Comprehensive Issue Resolution Plan

Update 2026-04-25: This plan was authored before several structural moves on apps/web (notably the proxy.ts → middleware.ts rename and Pillar A help-content redirects to docs.fragjulia.de). File paths below may not match current state — this is a spot-check, not a full audit. Treat unannotated references as "state unverified since plan was written".

88 open issues across security, design, accessibility, bugs, and config. This plan organizes them into 7 sprints with clear dependencies and priority order.

Architecture Overview

• Monorepo: apps/web (Next.js 16 + App Router), apps/mobile (Expo), voice/ (LiveKit agent), packages/shared
• Stack: React 19, Supabase (auth + DB), Stripe (payments), Resend (email), Upstash Redis (rate limiting), LiveKit (voice), Tailwind v4
• Design system: V2 components in components/v2/ (Sage-Creme-Terracotta), legacy in components/ (Pine-Gold)
• Key files: proxy.ts (middleware), lib/ (rate-limit, stripe, hmac, sanitize, supabase, resend)

Update 2026-04-25: apps/web/proxy.ts no longer exists on main; the active middleware file is apps/web/middleware.ts, which imports updateSession from @/lib/supabase/middleware. This was the launch-audit-2026-04-04 finding #1 (CRITICAL), now resolved.

Sprint 0 — Foundation & Config (Days 1–2)

Unblock everything else. Fix build, config, and env var chaos first.

Action plan:

1. Delete next.config.mjs (empty/stale), consolidate into next.config.ts with security headers (X-Content-Type-Options, X-Frame-Options, Referrer-Policy), image domains, and redirects
2. Rename package to fragjulia-web in package.json
3. Audit all process.env.* usage across lib/ and app/api/ → create comprehensive .env.example
4. Fix Vercel 403 by verifying vercel.json output directory and root route
5. Audit CSS token files — consolidate fj-tokens.ts aliases, remove legacy Pine-Gold tokens, map everything to Tailwind v4 theme

Update 2026-04-25: The duplicate-config decision went the other way — apps/web/next.config.ts no longer exists, apps/web/next.config.mjs is the active config (with security headers, image domains, redirects, and Pillar A docs.fragjulia.de redirects). Sprint 0 action plan step 1 is inverted relative to current state.

Sprint 1 — Critical Security (Days 3–5)

These are exploitable vulnerabilities. Fix before any public traffic.

Action plan:

1. #26: Replace request.headers.get('host') with hardcoded NEXT_PUBLIC_SITE_URL or request.nextUrl.origin for redirect URI construction
2. #27: Add Supabase auth check (createClient → getUser()) at top of voice token route; return 401 if unauthenticated
3. #28: Move CRON_SECRET from query param to Authorization: Bearer <secret> header; update Vercel cron config
4. #29: Add strict CSP in next.config.ts headers — remove unsafe-inline (use nonces), remove unsafe-eval
5. #30: Change lib/rate-limit.ts Redis failure mode from "allow all" to "deny" (fail-closed); add logging
6. #31: Use Supabase .eq() / .ilike() parameterized methods instead of string interpolation
7. #54: Sanitize JSON-LD output with proper JSON escaping instead of dangerouslySetInnerHTML

Sprint 2 — Critical UX & Broken Routes (Days 5–7)

These break core user flows. Users literally can't navigate.

Action plan:

1. #65: Create app/lexikon/page.tsx — glossary/encyclopedia page for medical terms (placeholder with proper V2 layout, or full implementation if content data exists)
2. #66: Create app/breastfriend/chat/page.tsx — chat endpoint for breastfriend matching flow
3. #67: Modify chat page to allow anonymous access per DesignGUIDE "anonym" promise. Move auth gate to premium features only, not base chat
4. #68: Update V2 header nav to point "Wissen" to /lexikon (or temporary redirect to /faq until lexikon is built)
5. #69: Systematic migration — replace <AppHeader/> / <AppFooter/> with <V2Header/> / <V2Footer/> in these pages: /faq, /login, /registrieren, /datenschutz, /impressum, /nutzungsbedingungen, /profil, /community, /dokumente, /kliniken, /forschung, /magazin
6. #70: Remove duplicate button — keep single "Anmelden" (German) CTA
7. #75 + #48: Global find-and-replace for broken umlauts: Uberschrift→Überschrift, hinzufugen→hinzufügen, Zuruck→Zurück, Loschen→Löschen, Offnen→Öffnen, etc. across all .tsx files

Sprint 3 — DesignGUIDE Compliance (Days 8–12)

Align all pages with the V3 DesignGUIDE spec.

3a. Color & Layout (High Priority)

3b. Component Specs

3c. Page-Level Redesigns

Action plan:

• Work through V2 components first (3b) — these cascade to all pages
• Then tackle color/layout globals (3a)
• Then page-level redesigns (3c) last, since they depend on correct components

Sprint 4 — Medium Security + Data Integrity (Days 12–14)

Update 2026-04-25: Issue #64's "or proxy.ts" file alternate is stale — apps/web/proxy.ts no longer exists; the live file is apps/web/middleware.ts. The middleware logic itself still lives in lib/supabase/middleware.ts.

Action plan:

1. Env var validation (#33, #34, #61): Add runtime validation at module load — throw if STRIPE_PRICE_*, HMAC_SECRET, SUPABASE_SERVICE_ROLE_KEY are missing. Pattern: const X = process.env.X ?? (() => { throw new Error('Missing X') })()
2. Rate limiting (#32): Wrap public API routes (/api/kliniken, /api/studies, /api/newsletter/*) with checkRateLimit() from lib/rate-limit.ts
3. Email validation (#52, #53): Add proper email regex to login form (client-side), tighten lib/sanitize.ts regex to RFC 5322 subset
4. Newsletter tokens (#56): Add expires_at column to newsletter tokens table, validate on unsubscribe
5. Type safety (#63, #64): Replace as casts with Zod validation in email send route; replace string matching in middleware with error code checks
6. Resend naming (#58): Rename env var RESEND_API_KEY consistently, remove confusing fallback

Sprint 5 — SEO & Accessibility (Days 14–17)

5a. SEO

Action plan:

• Add export const metadata: Metadata = { title, description, openGraph } to every page.tsx that lacks it
• Standardize all privacy links to /datenschutz (not /datenschutz-info)
• Verify OG image and favicon against DesignGUIDE v3

5b. Accessibility (A11Y)

Action plan:

• Add aria-hidden="true" to all decorative <svg> icons
• Add <label htmlFor> associations to all form inputs
• Add aria-live="polite" to chat message container
• Add aria-expanded and aria-label to FAQ toggle buttons
• Add @media (prefers-reduced-motion: reduce) to disable transitions
• Add visible :focus-visible outline styles globally
• Add password requirements display on registration form

Sprint 6 — Remaining Polish (Days 17–19)

Action plan:

• Add 300ms debounce to kliniken search input with useEffect + timeout
• Replace index keys with stable IDs (data ID fields or generated keys)
• Audit cookie banner for DSGVO: must have reject-all, granular consent, no pre-checked boxes
• Wire up forschung toggle save/revoke handlers to Supabase
• Build interactive datenschutz dashboard per DesignGUIDE
• Regression check on all P0 fixes from #23

Dependency Graph

Sprint 0 (Config/Build)
    ↓
Sprint 1 (Security) ←── must complete before any public deployment
    ↓
Sprint 2 (Broken Routes) ←── unblocks user testing
    ↓
Sprint 3 (DesignGUIDE) ←── depends on V2 header/footer from Sprint 2 #69
    ↓
Sprint 4 (Data Integrity) ←── can run parallel with Sprint 3
    ↓
Sprint 5 (SEO + A11Y) ←── best done after pages are stable
    ↓
Sprint 6 (Polish) ←── final pass

Issue Cross-Reference by File

Key files touched by multiple issues (merge work to avoid conflicts):

Related Issue Groups

These issues share the same root cause and should be fixed together:

1. Env var validation (#33, #34, #61) — add runtime validation for all critical env vars
2. Email validation (#52, #53) — client + server side
3. Umlaut encoding (#48, #75) — global find/replace pass
4. Footer spec (#41, #77, #99) — single footer refactor
5. Chat accessibility (#46, #87) — single aria-live addition
6. CTA color (#42, #73) — single terracotta migration

Estimated Effort Summary

Top 5 Immediate Priorities (per user request)

1. #67 — Chat login wall breaks the core "anonym" promise → Sprint 2
2. #65 — /lexikon route missing (broken nav for every user) → Sprint 2
3. #69 — Migrate 12+ pages to V2 header/footer → Sprint 2
4. #73 — CTA buttons terracotta, not sage → Sprint 3
5. #75 — Fix broken umlauts → Sprint 2

These 5 should be tackled first within their respective sprints.

Ingested from repo-root PLAN.md on 2026-04-25 (#647).