# DocuVault — Project Retrospective

*A living document updated after each milestone. Lessons feed forward into future planning.*

---

## Milestone: v0.2 — UI Overhaul and Optimization

**Shipped:** 2026-06-17
**Phases:** 4 (8–11) | **Plans:** 33 | **Duration:** 10 days (2026-06-07 → 2026-06-17)
**Git:** 198 commits, 236 files changed, +39,557 / −6,288 lines

### What Was Built

- Backend monolith decomposition — three router monoliths (934L, 852L, 825L) split into focused sub-packages with zero URL or behavior changes; shared schemas extracted to `api/schemas.py`
- Frontend client decomposition — `client.js` (635L) → 7 domain modules + barrel re-export; 35+ consumer files unchanged
- Admin panel rearchitecture — standalone `/admin/*` route subtree; `AdminLayout.vue`; `AdminSidebar.vue` with 5 nav links; 5 deep-linkable views; `to.matched.some()` auth guard fix; `GET /api/admin/overview` aggregate endpoint
- UX interaction layer — `EmptyState.vue`, skeleton loaders, keyboard shortcuts (`/`, `U`, `N`, `Escape`), `OsDragOverlay.vue`, Pinia toast store + `ToastContainer.vue`, `BreadcrumbBar.vue`, drag-to-move with Teleport dropdowns, `AppIcon.vue` (66 SVG instances centralized)
- Responsive design + visual polish — hamburger sidebar drawer (below `lg`), adaptive document list columns, 36px touch targets, scrollable modals, `@tailwindcss/forms` baseline, consistent Tailwind-only spacing/typography/focus-visible/hover states
- Bundle optimization — all admin routes lazy-loaded; dead code deleted; bundle −81 kB (−30.6%) from baseline

### What Worked

- **Wave parallelization** — executing independent plans in parallel (e.g., CODE-01/02/03/04 in Phase 8 Wave 2) dramatically reduced wall-clock time; the wave structure in PLAN.md made this trivial to execute
- **Barrel re-export pattern** — decomposing `client.js` with a barrel kept all 35+ consumer files unchanged; zero regressions, zero migration cost
- **Foundation-then-wire order** — building `EmptyState.vue`, `BreadcrumbBar.vue`, `AppIcon.vue`, and the toast store as isolated components in Phase 10 Wave 0 before wiring them in Wave 1 kept each step reviewable and testable
- **Teleport for dropdowns** — solving viewport-edge clipping with `Teleport to="body"` + `getBoundingClientRect()` was the right call; future virtual scrolling is now unblocked
- **UAT gap closure plans** — having dedicated plans (10-13, 11-07) for UAT gaps rather than patching in-flight kept the execution clean and the gap closure auditable

### What Was Inefficient

- **Phase 8 progress table not updated** — the ROADMAP progress table showed "4/8 In Progress" for Phase 8 even after completion, discovered at milestone close. Progress table updates should be part of the plan execution checklist.
- **Admin auth guard bug caught late** — the `to.meta.requiresAdmin` → `to.matched.some()` fix is a security-relevant change that wasn't caught until Phase 9. Nested route guards should be explicitly tested in Phase scaffolding.
- **11-07 mobile toolbar gap** — the mobile compact toolbar fix was a UAT gap rather than planned; the RESP-02 success criterion should have been clearer about the 550px threshold from the start.
- **Multiple SUMMARY.md formats** — some phase summaries used `**One-liner:**` and some used `## One-liner`; extracting them required heuristic grep patterns. A consistent frontmatter schema would help.

### Patterns Established

- **Sub-router NO-prefix rule** — `APIRouter()` in sub-packages must carry no `prefix`; the parent `include_router(sub, prefix=...)` propagates. This is now in CLAUDE.md.
- **FastAPI 0.128+ empty-path restriction** — `@router.get("")` on a sub-router with empty include prefix raises `FastAPIError`; root routes must be registered on the parent aggregator directly.
- **`to.matched.some()` for Vue Router 4 meta inheritance** — Vue Router 4 does not propagate `meta` to children automatically; direct `to.meta` checks are a security regression.
- **AdminLayout as route component, not App.vue branch** — router resolves `AdminLayout` as the `/admin` component; its `<router-view>` renders children. `App.vue` needs no layout branching logic.
- **Lazy-load all non-critical routes** — admin views and other non-initial-path routes should always be lazy-loaded by default; synchronous imports for non-critical routes are a bundle regression.

### Key Lessons

1. **Verify test coverage includes nested route behavior.** The `to.matched.some()` fix was a security-relevant change that required a specific negative test (non-admin navigating directly to `/admin/users`). Add nested-route auth tests to the scaffolding checklist for any phase that touches routing.
2. **Write success criteria with explicit thresholds.** "Mobile responsive" in RESP-02 should have said "toolbar fits without horizontal scrolling at 375px and 550px" rather than leaving it implicit. Explicit viewport thresholds eliminate UAT guesswork.
3. **Archive progress table state in the phase summary.** The ROADMAP progress table is read by the milestone close process; phases should update it as part of the "plan complete" ritual, not leave it for the orchestrator to discover at close.
4. **Barrel re-export is the zero-friction decomposition pattern.** When splitting a large module, start with the barrel and establish the public API first. Consumer files never change; the decomposition is invisible to callers.

### Cost Observations

- Model: Claude Sonnet 4.6 throughout
- No haiku or opus usage in v0.2
- Notable: wave parallelization (3–5 independent plans per wave) was the primary efficiency lever; sequential execution of the same work would have taken ~2–3x longer

---

## Cross-Milestone Trends

### Process Evolution

| Milestone | Duration | Phases | Key Process Change |
|-----------|----------|--------|--------------------|
| v0.1 | ~16 days (2026-05-21→2026-06-06) | 11 (1–7.4) | Feature-first; security gates added mid-stream |
| v0.2 | 10 days (2026-06-07→2026-06-17) | 4 (8–11) | Quality-first; wave parallelization; milestone audit before close |

### Cumulative Quality

| Milestone | Tests at close | Notes |
|-----------|---------------|-------|
| v0.1 | 347 | 1 pre-existing failure (missing module) |
| v0.2 | 277 | Reduction reflects dead test file deletion; coverage per line improved |

### Top Lessons (Verified Across Milestones)

1. **Security gates must run before phase advance, not as a post-close checklist.** Both milestones had late-discovered security issues (v0.1: IDOR stubs, v0.2: auth guard). Bake the security agent into the plan execution ritual.
2. **Explicit success criteria with measurable thresholds eliminate UAT gaps.** Vague criteria ("responsive") always produce UAT gap closure plans. Precise criteria ("at 375px and 550px viewport") do not.
3. **Milestone audits before archival are worth the overhead.** The v0.2 audit caught stale artifacts and the esbuild CVE before the milestone was tagged. Running the audit as a prerequisite rather than a post-mortem saves remediation cost.