Choco Route Architecture Audit
Context
An architecture audit of cho-co/web (Next.js 15 App Router) identified critical structural debt that will compound when data fetching is added. The audit was formalised into SRS-010 (9 requirements) and BUNDLE-E (2 TASKSETs) in choco-hq.Key Findings
Critical Issues
- 4 duplicate layouts — factory/, dashboard/, docs/, search/ all render identical FactoryNav + main structure. Causes sidebar unmount/remount on cross-section navigation.
- Zero error boundaries — No error.tsx anywhere. Runtime errors show blank page in production.
- Zero loading states — No loading.tsx anywhere. When server-side data fetching arrives, users will see blank screens.
High Issues
- /docs redirect conflict — next.config.ts redirects /docs → /factory (307) but docs/page.tsx exists with full UI. Dead code.
- Middleware public route gap — /factory not in public routes. Unauthenticated users hit unnecessary auth wall before reaching the factory landing page.
- Dark mode fragility — @media (prefers-color-scheme: dark) targets specific class selectors. Doesn’t compose with Tailwind utility-first approach.
Medium Issues
- p-8 padding duplicated across 15+ page files (layout concern, not page concern).
- StatCard empty state — ”—” for both loading and no-data. No visual distinction.
- Missing generateStaticParams on dynamic routes using generateMetadata.
Solution Architecture
SRS-010 defines 9 formal requirements (REQ-010-001 through REQ-010-009) with acceptance criteria and verification methods. BUNDLE-E: THE FACTORY FLOOR PLAN contains two TASKSETs:- E1 — Route Consolidation: Create (app)/ route group with single layout, move sections, delete duplicates, add error/loading boundaries, fix redirect and middleware.
- E2 — Visual & Runtime Polish: CSS custom property dark mode, StatCard skeleton states, generateStaticParams stubs.
Cross-References
- SRS-004 (Factory IA) — Route URLs must comply with REQ-004-001 canonical room mapping. SRS-010 is a technical complement, not a replacement.
- BUNDLE-A through BUNDLE-D — All allocated. BUNDLE-E is next available.
Agent Operations
- Architecture audit performed manually and documented as structured input.
- SRS-010 authored following SRS-009 pattern (YAML code blocks, SHALL language, AC/VER traceability).
- BUNDLE-E authored following BUNDLE-A pattern (TASKSET headers, file-level changes, verification checklists).
- Master index (SRS-000) updated with SRS-010 entry and hierarchy tree extended to include SRS-008/009/010.
Cross-Project Trail
| Repo | File | Purpose |
|---|---|---|
| choco-hq | docs/SRS-010-ROUTE-ARCHITECTURE.md | Formal requirements |
| choco-hq | docs/BUNDLE-E-ROUTE-CONSOLIDATION.md | Implementation blueprint |
| choco-hq | docs/SRS-000-MASTER-INDEX.md | Updated with SRS-010 |
| atlas | learnings/2026-03-17-choco-route-architecture-audit.md | This file |
| so1-content | findings/2026-03-17-choco-route-architecture-srs010.md | Session findings |
| veritas | reference/choco-route-architecture-srs010.md | Reference pointer |
| ariel | baselines/2026-03-17-choco-route-srs010.md | Frozen baseline |
| traceo-ai | docs/choco-route-srs010-trace.md | Traceability record |