Skip to content

Latest commit

 

History

History
415 lines (304 loc) · 14.2 KB

IMPLEMENTATION.md

File metadata and controls

415 lines (304 loc) · 14.2 KB

Implementation Plan

Last updated: 2026-02-15


Overview

This document outlines the phased implementation plan for Running Red. The approach is backend-first POC — prove the core functionality works locally before styling and deployment.

Status Key:

  • [ ] = Not started
  • [~] = In progress
  • [x] = Done

Phase 0: Documentation ✅

Goal: Establish project direction, document all decisions, create foundation for implementation.

  • Create comprehensive documentation suite
  • Archive old Payload-era docs
  • Update CLAUDE.md
  • Clean up repository (remove monorepo scaffolding)

Completion Criteria:

  • All documentation files exist and are consistent
  • Single source of truth established for each topic
  • No code exists yet (documentation-first approach validated)

Status: ✅ Complete


Phase 1: Database & API Layer ✅

Goal: Working backend with database, API routes, and image processing. Testable via curl/Postman (no UI).

1.1 Project Setup ✅

  • Initialize Next.js 16 project with TypeScript strict mode
  • Configure basic directory structure (see CONVENTIONS.md)
  • Set up ESLint, Prettier configs (encode conventions in tooling)
  • Create .env.example and .env.local with required variables
  • Verify npm run dev works

1.2 Database Setup (Railway Postgres) ✅

  • Create Railway Postgres instance
  • Get connection string, add to .env.local
  • Create initial schema migration:
    • comic_pages table
    • about_page table
    • links_page table
    • site_settings table
  • Run migration, verify tables exist
  • Seed database with default data (site settings, about page, empty links)
  • Create lib/db.ts (Postgres client)
  • Create lib/types.ts (TypeScript types matching schema)

1.3 Cloudflare R2 Setup ✅

  • Create Cloudflare R2 bucket
  • Generate API credentials (access key, secret key)
  • Add R2 config to .env.local
  • Create lib/r2.ts (R2 upload/download utilities)
  • Test upload/download manually (via Node script or API route)

1.4 Image Processing ✅

  • Install Sharp (npm install sharp)
  • Create lib/image.ts:
    • Function to resize/convert to WebP (desktop: 1200px, mobile: 800px)
    • Function to generate blur placeholder (base64)
  • Test locally (upload PNG, get WebP variants + blur hash)

1.5 API Routes ✅

  • Create /api/admin/comics route:
    • GET - List all comics (including drafts)
    • POST - Create new comic page (upload image, process, save to DB)
  • Create /api/admin/comics/[id] route:
    • GET - Fetch single comic page
    • PUT - Update comic page (with optional image replacement)
    • DELETE - Delete comic page
  • Create /api/admin/about route (GET/PUT for about page singleton)
  • Create /api/admin/links route (GET/PUT for links array)
  • Create /api/admin/settings route (GET/PUT for site settings)
  • Create /api/comics route (GET - public, published pages only)

1.6 Testing (No UI Yet) ✅

  • Test all API routes with curl or Postman
  • Verify image upload → Sharp processing → R2 upload works
  • Verify database CRUD operations work
  • Verify published vs draft filtering works

Completion Criteria:

  • ✅ Railway Postgres is set up and accessible
  • ✅ R2 bucket is set up and images can be uploaded
  • ✅ All API routes respond correctly (test with curl)
  • ✅ Image processing pipeline works (PNG → WebP variants + blur)
  • ✅ Can create/read/update/delete comics via API

Estimated Time: 2-3 days


Phase 2: Admin Interface ✅

Goal: Ren can upload comic pages and edit content via admin UI. Test locally (no deployment yet).

2.1 Authentication ✅

  • Create lib/auth.ts (HMAC-signed session tokens — email/password checked against env vars)
  • Create /admin/login page (login form)
  • Create proxy.ts (protect /admin/* routes, redirect to login if not authenticated)
  • Store session in HTTP-only cookie
  • Test: can't access /admin without logging in

2.2 Admin Layout ✅

  • Create /admin/layout.tsx:
    • Check authentication
    • Simple header with "Running Red Admin" + logout button
    • Navigation: Dashboard, Comics, About, Links, Settings
  • Create /admin/page.tsx (dashboard with stats and quick actions)

2.3 Comic Pages Management ✅

  • Create /admin/comics/page.tsx:
    • Table listing all comics (page #, title, status, publish date, actions)
    • "Add New Page" button
  • Create /admin/comics/new/page.tsx:
    • Form with all fields (see PRODUCT.md)
    • Inline file input for image upload (FormData submission)
    • Content warnings checkboxes (multiselect)
    • On submit: POST to /api/admin/comics
    • Redirect to /admin/comics on success
  • Create /admin/comics/[slug]/page.tsx:
    • Server component fetches comic by slug, passes to client form
    • "Replace Image" option
    • On submit: PUT to /api/admin/comics/[id]

2.4 Static Content Management ✅

  • Create /admin/about/page.tsx:
    • Server component fetches data, passes to AboutForm client component
    • Form with 4 markdown textareas (About Me, About Comic, Content Warnings, Update Schedule)
    • On submit: PUT to /api/admin/about
  • Create /admin/links/page.tsx:
    • Server component fetches data, passes to LinksForm client component
    • Editable list of links (add/remove/reorder)
    • On submit: PUT to /api/admin/links
  • Create /admin/settings/page.tsx:
    • Server component fetches data, passes to SettingsForm client component
    • Form for site title, description, social image upload
    • On submit: PUT to /api/admin/settings

2.5 Image Upload UI — Skipped

Image upload is handled inline within the comic create/edit forms (file input + FormData submission). A dedicated upload component with a separate API route, progress indicators, and pre-submission processing was deemed unnecessary for now — Ren uploads once a week. If the UX becomes a pain point, revisit this.

2.6 Testing (Still Local)

  • Log in as admin
  • Upload a test comic page (with image)
  • Verify image appears in R2 bucket
  • Verify metadata saved to database
  • Edit the comic page, replace image
  • Edit About page, Links page, Site Settings
  • Verify all changes persist

Completion Criteria:

  • ✅ Ren can log into /admin
  • ✅ Ren can create/edit/delete comic pages
  • ✅ Ren can upload images (processed to WebP, stored in R2)
  • ✅ Ren can edit About, Links, Site Settings
  • ✅ Admin UI is functional (styling can be basic for now)

Estimated Time: 3-4 days


Phase 3: Public Website + Theming ✅

Goal: Readers can view comic pages and navigate. Custom visual design from Ren. All public pages query the database directly via Server Components (no public API routes needed).

3.1 Theme & Layout ✅

  • Set up Ren's color palette in globals.css via @theme inline (Tailwind v4)
    • Base: #141E16, gradient: #2E351B → #4D1713, buttons: #100302/#BA9449/#891313
  • Background image (public/images/bg-flowers.png) layered over gradient
  • Create (public) route group with own layout (header + footer)
  • SiteHeader.tsx — gold nav links (Home, About, Archive, Links)
  • SiteFooter.tsx — copyright + RSS link
  • Semi-transparent backdrop (bg-base/60 backdrop-blur-sm) on content areas

3.2 Comic Components ✅

  • ComicImage.tsx — <picture> with desktop/mobile WebP, blur placeholder, cache-busting (?v=updatedAt)
  • ComicNav.tsx — First/Prev/Next/Last buttons with keyboard arrow navigation
  • ContentWarning.tsx — blur overlay with warning list + reveal button
  • ComicPageView.tsx — shared layout composing image, nav, commentary, date

3.3 Comic Pages ✅

  • Home page (/) — Server Component, queries DB for latest published page
  • Comic route (/comic/[slug]) — ISR (1h), generateStaticParams, prev/next navigation
  • Next-page image prefetching via <link rel="prefetch">
  • Custom 404 for missing/unpublished comics

3.4 Supporting Pages ✅

  • About (/about) — 4 sections from about_page table
  • Archive (/archive) — chronological list of published pages
  • Links (/links) — external links from links_page table

3.5 RSS & SEO ✅

  • RSS feed (/rss.xml) — RSS 2.0, last 50 published pages
  • Title template in root layout (%s - Running Red)
  • RSS autodiscovery link
  • Per-page generateMetadata on comic pages

Completion Criteria:

  • ✅ Home page displays latest comic with Ren's custom theme
  • ✅ Readers can navigate between comics (buttons + keyboard)
  • ✅ Content warning system works (blur + reveal)
  • ✅ About, Archive, Links pages render from DB
  • ✅ RSS feed generates valid XML
  • ✅ Image cache-busting and prefetching in place
  • ✅ npm run build, npm run lint, typecheck all pass

Status: ✅ Complete


Phase 4: Polish & Accessibility

Goal: Responsive layout, accessibility, performance optimization. (Visual theming was done in Phase 3.)

4.1 Responsive Layout

  • Test on mobile (phone, tablet)
  • Test on desktop (various screen sizes)
  • Ensure all pages are mobile-friendly
  • Fix any responsive issues

4.3 Admin UI Polish

  • Improve admin forms (better spacing, labels, help text)
  • Add loading states (spinners, disabled buttons)
  • Add success/error messages (toasts or inline)
  • Add confirmation modals (delete actions)

4.4 Public Site Polish

  • Improve comic page layout (centered, max-width, spacing)
  • Improve navigation UI (buttons, hover states)
  • Add loading states (blur placeholder, skeleton screens)
  • Add error states (404 page, error boundaries)

4.5 Accessibility

  • Semantic HTML (<main>, <nav>, <article>)
  • Alt text on all images (admin enforces this)
  • Keyboard navigation works everywhere
  • Focus states visible
  • Color contrast meets WCAG AA (4.5:1)
  • Screen reader test (content warnings announced)

4.6 Performance Optimization

  • Run Lighthouse audit (target >90 all categories)
  • Optimize images (verify WebP, srcset working)
  • Minimize client-side JS (check bundle size)
  • Add preloading for adjacent pages (on hover)
  • Test on 4G (comic page <2s load time)

4.7 Error Handling

  • Add error.tsx at route level (comic pages, admin pages)
  • Add not-found.tsx for 404s
  • Test error scenarios (database down, R2 down, invalid data)
  • Friendly error messages for users

4.8 Final Testing

  • Test all user flows (reader, admin)
  • Test on multiple browsers (Chrome, Firefox, Safari, mobile)
  • Test on multiple devices (phone, tablet, desktop)
  • Test with real data (Ren uploads multiple pages)

Completion Criteria:

  • ✅ Site looks professional and clean
  • ✅ Responsive on all devices
  • ✅ Accessible (WCAG AA)
  • ✅ Performant (Lighthouse >90)
  • ✅ All error cases handled gracefully

Estimated Time: 2-3 days


Phase 5: Deployment

Goal: Deploy to production, point domain, monitor, go live.

5.1 Pre-Deployment Checklist

  • Review all environment variables (production values)
  • Verify Railway Postgres is production-ready (not hobby tier)
  • Verify R2 bucket is configured correctly
  • Run full test suite locally one more time

5.2 Vercel Deployment

  • Connect repo to Vercel (if not already)
  • Configure environment variables in Vercel dashboard:
    • DATABASE_URL (Railway connection string)
    • R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, R2_BUCKET, R2_ENDPOINT
    • ADMIN_EMAIL, ADMIN_PASSWORD (or auth secret)
  • Deploy to preview URL
  • Test preview deployment thoroughly

5.3 Domain Configuration

  • Point running.red to Vercel (A record or CNAME)
  • Verify domain works
  • Verify SSL certificate (HTTPS)

5.4 Production Testing

  • Test on production domain
  • Verify admin login works
  • Upload a test comic via admin
  • Verify it appears on public site
  • Test all pages (home, about, archive, links, RSS)

5.5 Monitoring & Cleanup

  • Set up error monitoring (Vercel logs, or Sentry if needed)
  • Monitor for errors/issues
  • Remove test data (if any)
  • Hand off to Ren (walkthrough admin UI)

5.6 Documentation Update

  • Update all docs to reflect production state
  • Update README with live URLs
  • Document any production-specific setup
  • Mark all phases as complete

Completion Criteria:

  • ✅ Site is live at running.red
  • ✅ Admin works at /admin
  • ✅ Ren can upload comics independently
  • ✅ Monitoring is in place
  • ✅ All docs updated

Estimated Time: 1-2 days


Future Enhancements (Not in MVP)

Deferred to post-launch:

  • Comments system (Giscus or similar)
  • Page version history (view older versions of updated pages)
  • Search (search comics by title, commentary)
  • Chapters (grouping pages into chapters)
  • Scheduled publishing (cron job to auto-publish)
  • Analytics dashboard in admin
  • Email notifications (new page published)
  • Patreon integration (early access)

Timeline Estimate

Phase Estimated Time Status
Phase 0: Documentation 1 day ✅ Done
Phase 1: Database & API 2-3 days ✅ Done
Phase 2: Admin Interface 3-4 days ✅ Done
Phase 3: Public Website + Theming 3-4 days ✅ Done
Phase 4: Polish & Accessibility 2-3 days 🔲 Not started
Phase 5: Deployment 1-2 days 🔲 Not started
Total 12-17 days —

Note: Backend-first approach de-risks early (prove core functionality works before building UI).


Checkpoints

After each phase, review:

  • Does the implementation match the documentation?
  • Do docs need to be updated?
  • Are there any blockers or open questions?
  • Is the quality acceptable (code, UX, performance)?

No phase is complete until docs are updated and functionality is tested.


Related Docs