curo/kite
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: archive v0.2 milestone files

Browse Source 
Archive v0.2 (UI Overhaul and Optimization) to milestones/:
- milestones/v0.2-ROADMAP.md — full phase archive (Phases 8–11, 33 plans)
- milestones/v0.2-REQUIREMENTS.md — all 40 requirements marked complete
- milestones/v0.2-MILESTONE-AUDIT.md — audit artifact (passed, 40/40)
- MILESTONES.md — new living milestone index
- RETROSPECTIVE.md — new living retrospective with v0.2 section
- PROJECT.md — full evolution review: v0.2 requirements moved to Validated, 5 new Key Decisions added
- STATE.md — updated to milestone-complete status
- ROADMAP.md — v0.2 phases collapsed into <details> with progress table updated

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
curo1305
2026-06-17 14:26:19 +02:00
co-authored by Claude Sonnet 4.6
parent 2280b6f987
commit 475e519158
8 changed files with 573 additions and 250 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.planning/MILESTONES.md
+37
View File
@@ -0,0 +1,37 @@
# DocuVault — Milestones
## v0.2 — UI Overhaul and Optimization
**Shipped:** 2026-06-17
**Phases:** 8–11 (4 phases, 33 plans)
**Timeline:** 2026-06-07 → 2026-06-17 (10 days)
**Git range:** docs: define milestone v0.2 requirements → docs(milestone): mark v0.2 audit passed
**Files changed:** 236 files, +39,557 / −6,288 lines, 198 commits
### Delivered
Transformed the frontend from rough alpha to polished, production-quality web app. Three backend router monoliths decomposed into focused sub-packages; `client.js` decomposed into 7 domain modules. Admin panel moved to standalone `/admin/*` route subtree with correct auth guard. Full UX interaction layer (empty states, skeletons, keyboard shortcuts, OS drag-drop, toasts, breadcrumbs, drag-to-move). Mobile-responsive layout with hamburger sidebar drawer. Bundle reduced −81 kB (−30.6%) via lazy loading.
### Key Accomplishments
1. Backend monolith decomposition — `api/admin.py` (934L), `api/documents.py` (852L), `api/auth.py` (825L) split into focused sub-packages; shared schemas extracted to `api/schemas.py`
2. Frontend client decomposition — `client.js` (635L) → 7 domain modules + utils.js + barrel re-export; zero consumer churn across 35+ import sites
3. Admin panel rearchitecture — standalone `/admin/*` subtree, `AdminLayout.vue`, `AdminSidebar.vue`, 5 deep-linkable views, overview aggregate endpoint, `to.matched.some()` auth guard
4. 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)
5. Responsive design — hamburger sidebar drawer (below `lg`), adaptive document list columns, 36px touch targets, scrollable modals, `@tailwindcss/forms` baseline, Tailwind-only spacing/typography
6. Bundle optimization — all admin routes lazy-loaded; dead code deleted (`FolderRow.vue`, `AccountView.vue`, stale test files); final bundle −81 kB vs baseline
### Requirements
40/40 satisfied (100%). No known gaps.
### Archive
- Roadmap: `.planning/milestones/v0.2-ROADMAP.md`
- Requirements: `.planning/milestones/v0.2-REQUIREMENTS.md`
- Audit: `.planning/milestones/v0.2-MILESTONE-AUDIT.md`
- Phases: `.planning/phases/08-*/`, `09-*/`, `10-*/`, `11-*/`
---
*For project history prior to v0.2, see v0.1 milestone (not yet archived — v0.1 phases remain in `.planning/phases/01-*/` through `07.4-*/`).*
.planning/PROJECT.md
+33 -15
View File
@@ -8,17 +8,11 @@ DocuVault is a self-hosted, multi-user SaaS document management platform. Users
Every user's documents — and the credentials they use to store them — are inaccessible to everyone except that user, while the platform scales horizontally and supports pluggable storage backends. Every user's documents — and the credentials they use to store them — are inaccessible to everyone except that user, while the platform scales horizontally and supports pluggable storage backends.
## Current Milestone: v0.2 — UI Overhaul and Optimization ## Last Milestone: v0.2 — UI Overhaul and Optimization (shipped 2026-06-17)
**Goal:** Redesign the frontend into a polished, performant, and responsive interface, and overhaul both the backend and frontend codebase to senior-dev quality — minimal, DRY, readable code with no unnecessary comments. **Delivered:** Polished, production-quality frontend with mobile-responsive layout, full UX interaction layer, decomposed backend/frontend codebase, and standalone admin panel.
**Target features:** See `.planning/MILESTONES.md` and `.planning/milestones/v0.2-ROADMAP.md` for full archive.
- Visual redesign — refined Tailwind component system, consistent palette, typography, spacing
- UX & interaction improvements — drag-and-drop upload, keyboard shortcuts, empty states, loading skeletons
- Frontend performance — lazy loading, virtual scrolling, bundle size reduction, API response caching
- Responsive / mobile layout — adaptive layouts for phones/tablets, touch-friendly controls
- Proper admin panel — standalone admin interface with its own routes, layout, and nav (not tabs bolted onto the user app)
- Codebase quality overhaul — eliminate duplication, extract shared utilities, delete dead code, flatten unnecessary abstractions; comments only where code alone is insufficient
## Requirements ## Requirements
@@ -49,9 +43,29 @@ Every user's documents — and the credentials they use to store them — are in
- ✓ Celery retry backoff (30 s / 90 s / 270 s) on classification failure - ✓ Celery retry backoff (30 s / 90 s / 270 s) on classification failure
- ✓ Backend stateless — all state in PostgreSQL and MinIO - ✓ Backend stateless — all state in PostgreSQL and MinIO
### Active (v0.2 — this milestone) ### Validated (v0.2 — shipped 2026-06-17)
*Defined in REQUIREMENTS.md* - ✓ Backend monolith decomposition (api/admin/, api/documents/, api/auth/ sub-packages) — v0.2
- ✓ Frontend API client decomposition (7 domain modules + barrel re-export) — v0.2
- ✓ Admin panel standalone route subtree (/admin/*) with AdminLayout, AdminSidebar, 5 deep-linkable views — v0.2
- ✓ requiresAdmin guard via to.matched.some() — v0.2
- ✓ Admin overview aggregate endpoint (user count, storage, doc status, recent audit) — v0.2
- ✓ EmptyState.vue in all zero-content contexts — v0.2
- ✓ Skeleton loaders for all async-populated tables/lists/sidebars — v0.2
- ✓ Keyboard shortcuts: / (search), U (upload), N (new folder), Escape (close/clear) — v0.2
- ✓ OS drag-drop overlay (full-screen, file-type discriminated) — v0.2
- ✓ Toast notification system (auto-dismiss, stacking, non-blocking) — v0.2
- ✓ BreadcrumbBar.vue shared across all views — v0.2
- ✓ Drag-to-move document to folder with Teleport-based dropdowns — v0.2
- ✓ AppIcon.vue centralizing all SVG path data (66 instances) — v0.2
- ✓ Mobile-responsive layout: hamburger sidebar drawer (below lg), touch targets ≥36px — v0.2
- ✓ @tailwindcss/forms cross-browser form baseline — v0.2
- ✓ Consistent Tailwind-only spacing/typography/focus-visible/hover states — v0.2
- ✓ Bundle −81 kB (−30.6%) via lazy-loaded admin routes — v0.2
- ✓ Dead code deleted (FolderRow.vue, AccountView.vue, stale test files) — v0.2
- ✓ WHY-only comment policy enforced (CODE-09) — v0.2
### Active (next milestone — not yet defined)
### Out of Scope ### Out of Scope
@@ -65,10 +79,10 @@ Every user's documents — and the credentials they use to store them — are in
## Context ## Context
- **Current state**: v0.2 in progress — Phase 10 complete (2026-06-16). UX & Interaction layer ships: empty states, loading skeletons, keyboard shortcuts (/, U, N, Escape), OS drag-drop upload, toast notifications, BreadcrumbBar, AppIcon registry, drag-to-move, Teleport dropdowns. All 6 UAT gaps closed (plan 10-13): sidebar shimmer, search-at-root visibility, admin sidebar isolation, keyboard dispatch via matched.find(), Escape modifier, OS drop capture phase. 219 tests pass. Phase 11 (Visual Design, Responsive Layout & Cleanup) up next. - **Current state**: v0.2 shipped 2026-06-17. All 4 v0.2 phases complete: stack upgrade + decomposition (Phase 8), admin panel rearchitecture (Phase 9), UX interaction layer (Phase 10), visual design + responsive layout (Phase 11). 277 tests pass. Bundle −81 kB from baseline. App is mobile-responsive, keyboard-navigable, and fully polished. Ready for next milestone definition.
- **Tech stack**: FastAPI 0.136+ (Python 3.12), SQLAlchemy 2.0 async, Alembic, MinIO SDK; Vue 3 (Options API), Pinia, Vue Router 4, Vite, Tailwind CSS. - **Tech stack**: FastAPI 0.136+ (Python 3.12), SQLAlchemy 2.0 async, Alembic, MinIO SDK; Vue 3 (Options API), Pinia, Vue Router 4, Vite, Tailwind CSS.
- **Code quality**: v0.1 was built feature-first under time pressure. Both backend and frontend contain duplication, inconsistent patterns, and components that grew beyond their original scope. v0.2 addresses this systematically. - **Code quality**: v0.1 was built feature-first under time pressure. Both backend and frontend contain duplication, inconsistent patterns, and components that grew beyond their original scope. v0.2 addresses this systematically.
- **Admin panel**: Now a standalone /admin/* route subtree with AdminLayout as the route component, AdminSidebar with 5 nav links, and 5 dedicated view components. Old AdminView.vue and tab components deleted. Admin users are redirected to /admin on login; non-admin users are blocked from /admin/* by a correct to.matched.some() guard. - **Admin panel**: Standalone /admin/* route subtree with AdminLayout as the route component, AdminSidebar with 5 nav links, and 5 dedicated view components. AdminView.vue and legacy tab components deleted. Admin users redirect to /admin on login; non-admin blocked by to.matched.some() guard.
- **Privacy constraint**: Admin role is a platform operator, not a content viewer. Cloud credentials encrypted with per-user HKDF key; API keys encrypted with separate HKDF domain. Neither is ever in an API response. - **Privacy constraint**: Admin role is a platform operator, not a content viewer. Cloud credentials encrypted with per-user HKDF key; API keys encrypted with separate HKDF domain. Neither is ever in an API response.
## Constraints ## Constraints
@@ -101,7 +115,11 @@ Every user's documents — and the credentials they use to store them — are in
| Vite 6 upgrade | Resolved two moderate CVEs (CVE-2026-39363/39364) present in Vite 5; build time unchanged | Shipped Phase 8 (PERF-01) | | Vite 6 upgrade | Resolved two moderate CVEs (CVE-2026-39363/39364) present in Vite 5; build time unchanged | Shipped Phase 8 (PERF-01) |
| Admin login redirect (D-08) | Role check fires before router.push — admin → /admin, regular user → /; D-09 guard as belt-and-suspenders | Shipped Phase 9 | | Admin login redirect (D-08) | Role check fires before router.push — admin → /admin, regular user → /; D-09 guard as belt-and-suspenders | Shipped Phase 9 |
| Tailwind safelist with regex patterns | Dynamic color classes (sky=OneDrive, amber=admin audit badges) are tree-shaken without explicit safelist | Regex patterns cover all provider and event-type color families in tailwind.config.js | | Tailwind safelist with regex patterns | Dynamic color classes (sky=OneDrive, amber=admin audit badges) are tree-shaken without explicit safelist | Regex patterns cover all provider and event-type color families in tailwind.config.js |
| GET /api/admin/overview as dedicated endpoint | Aggregated stats (user count, storage, doc status, recent audit) served in one request to avoid N+1 on admin load | Shipped Phase 9 (09-01) | | GET /api/admin/overview as dedicated endpoint | Aggregated stats (user count, storage, doc status, recent audit) served in one request to avoid N+1 on admin load | ✓ Shipped Phase 9 (09-01) |
| AppIcon.vue SVG registry | 66 duplicate inline SVG blocks eliminated; single source of truth for all icon paths | ✓ Shipped Phase 10 (CODE-05) |
| Teleport + getBoundingClientRect for dropdowns | Viewport-edge clipping eliminated without complex position logic; prerequisite for virtual scrolling | ✓ Shipped Phase 10 (UX-13) |
| Admin routes lazy-loaded | All 5 admin views excluded from initial bundle; −81 kB (−30.6%) improvement | ✓ Shipped Phase 11 (PERF-03) |
| Vite 8 upgrade for npm audit | Closed high-severity esbuild CVE present in Vite 5/6; npm audit now clean | ✓ Shipped Phase 11 (11-07) |
## Evolution ## Evolution
@@ -123,4 +141,4 @@ Last updated: 2026-06-16
4. Update Context with current state 4. Update Context with current state
--- ---
*Last updated: 2026-06-13 — after Phase 9* *Last updated: 2026-06-17 — after v0.2 milestone*
.planning/RETROSPECTIVE.md
+80
View File
@@ -0,0 +1,80 @@
# 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.
.planning/ROADMAP.md
+30 -210
View File
@@ -522,220 +522,40 @@ Before any phase is marked complete, all three gates must pass:
--- ---
# DocuVault — v0.2 Roadmap ## Milestones
_Milestone: v0.2 — UI Overhaul and Optimization_ - ✅ **v0.2 — UI Overhaul and Optimization** — Phases 8–11 (shipped 2026-06-17)
_Started: 2026-06-07_
## v0.2 Phases <details>
<summary>✅ v0.2 — UI Overhaul and Optimization (Phases 8–11) — SHIPPED 2026-06-17</summary>
- [x] **Phase 8: Stack Upgrade & Backend Decomposition** — Dependency bumps land; all three backend router monoliths split into focused sub-packages; frontend API client decomposed into domain modules; shared Pydantic schemas extracted _(2026-06-12)_ - [x] Phase 8: Stack Upgrade & Backend Decomposition (8/8 plans) — completed 2026-06-12
- [x] **Phase 9: Admin Panel Rearchitecture** — Admin panel moves to `/admin/*` route subtree with its own layout, sidebar, and deep-linkable child routes; Tailwind safelist configured; redundant comments purged (completed 2026-06-12) - [x] Phase 9: Admin Panel Rearchitecture (5/5 plans) — completed 2026-06-13
- [x] **Phase 10: UX & Interaction** — Empty states, loading skeletons, keyboard shortcuts, drag-and-drop upload, toast notifications, breadcrumbs, and icon centralization land across the full UI (completed 2026-06-16) - [x] Phase 10: UX & Interaction (13/13 plans) — completed 2026-06-16
- [x] **Phase 11: Visual Design, Responsive Layout & Cleanup** — Consistent spacing, form styling, hover/focus states, and typography applied; mobile-responsive sidebar and layouts ship; dead code deleted; bundle measured (completed 2026-06-17) - [x] Phase 11: Visual Design, Responsive Layout & Cleanup (7/7 plans) — completed 2026-06-17
## Phase Details Full archive: `.planning/milestones/v0.2-ROADMAP.md`
### Phase 8: Stack Upgrade & Backend Decomposition </details>
**Goal**: The dependency stack is current, all three backend router monoliths are split into focused sub-packages with zero URL or behavior changes, and the frontend API client is decomposed into domain modules behind a re-export barrel — the entire change is invisible to consumers and tests. ## v0.2 + v0.1 Progress Table
**Depends on**: Phase 7.4 (last v0.1 phase)
**Requirements**: PERF-01, CODE-01, CODE-02, CODE-03, CODE-04, CODE-08
**Implementation notes:** | Phase | Milestone | Plans Complete | Status | Completed |
- Sub-routers in `api/admin/`, `api/documents/`, `api/auth/` must have NO prefix on their `APIRouter()` — the parent prefix propagates. Adding a prefix doubles the URL path. (PITFALLS.md §Pitfall 1) |-------|-----------|----------------|--------|-----------|
- Shared Pydantic models, constants, and helpers that span sub-modules go in a `shared.py` within each package — never duplicated across sub-routers. (PITFALLS.md §Pitfall 2 — prevents circular imports) | 8. Stack Upgrade & Backend Decomposition | v0.2 | 8/8 | Complete | 2026-06-12 |
- `client.js` decomposition uses the re-export barrel pattern: `client.js` re-exports everything from domain sub-files; zero changes to the 35+ consumer files. `request()` and `noRefreshPaths` stay in `client.js`; the three blob-download 401-retry duplicates are consolidated into a single `fetchWithRetry()` helper. (PITFALLS.md §Pitfall 5) | 9. Admin Panel Rearchitecture | v0.2 | 5/5 | Complete | 2026-06-13 |
- CODE-01, CODE-02, CODE-03 are independent (touch different files) and can be executed in parallel. CODE-04 is also independent of the backend work. | 10. UX & Interaction | v0.2 | 13/13 | Complete | 2026-06-16 |
| 11. Visual Design, Responsive Layout & Cleanup | v0.2 | 7/7 | Complete | 2026-06-17 |
**Success Criteria** (what must be TRUE): | 1. Infrastructure Foundation | v0.1 | 5/5 | Complete | 2026-05-22 |
1. `pytest -v` passes with zero failures immediately after the backend split — every existing API endpoint continues to respond on the same URL path | 2. Users & Authentication | v0.1 | 6/6 | Complete | 2026-06-01 |
2. `import * as api from '../api/client.js'` in any existing consumer file resolves all previously-exported names without modification to that consumer file | 3. Document Migration & Multi-User Isolation | v0.1 | 5/5 | Complete | 2026-05-25 |
3. No Pydantic model definition appears more than once across `api/admin/`, `api/documents/`, and `api/auth/` sub-packages — shared types live in a dedicated module | 4. Folders, Sharing, Quotas & Document UX | v0.1 | 9/9 | Complete | 2026-05-28 |
4. `PERF-01` packages are installed and `npm list` confirms `vue@^3.5.x`, `vite@^6.x`, `@vueuse/core@^14.x`, `sortablejs`, `@tailwindcss/forms`, `rollup-plugin-visualizer` are present | 5. Cloud Storage Backends | v0.1 | 12/12 | Complete | 2026-05-30 |
**Plans**: 8 plans (3 waves) | 6. Performance & Production Hardening | v0.1 | 6/6 | Complete | 2026-05-30 |
| 6.1. Close v1.0 audit gaps | v0.1 | 2/2 | Complete | 2026-05-30 |
**Wave 0** — Foundation (parallel) | 6.2. Close v1 sharing + cloud-delete + CSV export gaps | v0.1 | 5/5 | Complete | 2026-05-31 |
| 7. Redo and optimize LLM integration | v0.1 | 5/5 | Complete | 2026-06-05 |
- [x] 08-01-PLAN.md — CR-01/02/03 test stubs (3 xfail stubs in test_auth.py) + Wave 0 scaffolds for regression detection | 7.1. Security: session revocation on privilege change | v0.1 | 2/2 | Complete | 2026-06-08 |
- [x] 08-02-PLAN.md — `api/schemas.py` creation + `CloudConnectionOut` migration from admin.py (MUST precede admin split) | 7.2. Security: JTI claim + Redis access-token revocation | v0.1 | 3/3 | Complete | 2026-06-05 |
| 7.3. Security: ES256 algorithm upgrade | v0.1 | 3/3 | Complete | 2026-06-06 |
**Wave 1** *(blocked on Wave 0)* — Phase 7.1 completion (frontend only — backend already implemented) | 7.4. Security: token fingerprinting / token binding | v0.1 | 2/2 | Complete | 2026-06-06 |
- [x] 08-03-PLAN.md — `useToastStore` stub (`frontend/src/stores/toast.js`) + CR test promotion + SettingsAccountTab.vue + TotpEnrollment.vue inline toast replacement
**Wave 2** *(blocked on Wave 1)* — Backend decomposition + frontend (parallel)
- [x] 08-04-PLAN.md — Split `api/admin.py` → `api/admin/` package: users.py, quotas.py, ai.py, shared.py, __init__.py (CODE-01)
- [x] 08-05-PLAN.md — Split `api/documents.py` → `api/documents/` package: upload.py, crud.py, content.py, shared.py, __init__.py (CODE-02)
- [x] 08-06-PLAN.md — Split `api/auth.py` → `api/auth/` package: tokens.py, totp.py, password.py, sessions.py, shared.py, __init__.py (CODE-03)
- [x] 08-07-PLAN.md — Frontend `client.js` decomposition: utils.js + 7 domain modules + barrel rewrite (CODE-04)
- [x] 08-08-PLAN.md — PERF-01 dependency bump + tailwind/vite config wiring + requirements.txt exact pinning (PERF-01, D-17)
**Cross-cutting constraints:**
- Sub-routers MUST have NO prefix on `APIRouter()` — only package `__init__.py` carries the prefix (Plans 04, 05, 06)
- `api/schemas.py` must exist before admin split — `api/cloud.py` imports `CloudConnectionOut` from admin (Plan 02 before Plan 04)
- `request()` moves to `utils.js` for circular-import avoidance; `client.js` re-exports it — zero consumer changes (Plan 07)
- Every admin sub-module handler retains `Depends(get_current_admin)` explicitly — never omit (Plans 04)
---
### Phase 9: Admin Panel Rearchitecture
**Goal**: The admin interface is a standalone route subtree (`/admin/*`) with its own layout component and sidebar; each admin section is deep-linkable and browser-back-button works; the `requiresAdmin` navigation guard correctly protects all child routes; and the Tailwind safelist is configured so dynamic color classes render correctly in production builds.
**Depends on**: Phase 8
**Requirements**: ADMIN-08, ADMIN-09, ADMIN-10, ADMIN-11, ADMIN-12, CODE-06, CODE-09
**Implementation notes:**
- `AdminLayout.vue` is registered as the `/admin` route's component; its `<router-view />` renders child views. `App.vue` does NOT need a third `v-else-if` branch — it renders whatever component the router resolves to. (PITFALLS.md §Pitfall 4)
- The `beforeEach` guard must change from `to.meta.requiresAdmin` to `to.matched.some(r => r.meta.requiresAdmin)`. Vue Router 4 does not inherit `meta` from parent to children automatically. (PITFALLS.md §Pitfall 3)
- `App.vue` layout resolution reads `route.matched.find(r => r.meta.layout)?.meta.layout` — same `matched` walk as the guard. (ARCHITECTURE.md §Integration Point 2)
- `AdminLayout.vue` owns the `p-8 max-w-5xl mx-auto` content wrapper. Extracted tab-component-turned-views (`AdminUsersView.vue` etc.) must strip any top-level padding they inherited from `AdminView.vue` — double padding is the risk. (PITFALLS.md §Pitfall 9)
- Tailwind safelist covers `providerColor`, `providerBg`, `providerLabel` dynamic pattern families from `formatters.js`. (PITFALLS.md §Pitfall 14)
- CODE-09 (comment purge) applies to every file touched in this phase and retroactively to the backend sub-packages created in Phase 8.
**Success Criteria** (what must be TRUE):
1. Navigating directly to `/admin/users`, `/admin/quotas`, `/admin/ai`, and `/admin/audit` in a fresh browser tab loads the correct admin view with the admin sidebar — not the user app sidebar
2. A logged-in non-admin user who navigates to `/admin/users` is redirected to `/` by the `beforeEach` guard; the redirect happens even when the URL is entered directly
3. The browser back button moves from `/admin/audit` to `/admin/users` (or whichever path was previous) without a full page reload
4. `AdminView.vue` is deleted from the repository; no file imports it
5. A production build (`npm run build`) renders topic badge and provider chip colors correctly — no gray/invisible badges caused by purged dynamic Tailwind classes
**Plans**: 5 plans (4 waves)
**Wave 1** — Foundation (parallel)
- [x] 09-01-PLAN.md — Backend overview.py endpoint + 8 ADMIN-11 tests (overview aggregate query + security invariants)
- [x] 09-02-PLAN.md — Frontend AdminLayout + AdminSidebar + AdminOverviewView + getAdminOverview API client
**Wave 2** *(blocked on 09-02)*
- [x] 09-03-PLAN.md — Extract 4 admin tab components to standalone views (AdminUsersView, AdminQuotasView, AdminAiView, AdminAuditView)
**Wave 3** *(blocked on 09-01, 09-02, 09-03)*
- [x] 09-04-PLAN.md — Router rearchitecture (nested /admin + to.matched.some guard + D-08/D-09/D-10 redirects) + Tailwind safelist + LoginView admin redirect + delete AdminView.vue + 4 tab files
**Wave 4** *(blocked on 09-04)*
- [x] 09-05-PLAN.md — CODE-09 comment purge (Phase 9 files + retroactive Phase 8 backend sub-packages) + human checkpoint UAT
**UI hint**: yes
---
### Phase 10: UX & Interaction
**Goal**: The application communicates state clearly at every moment — empty contexts have purposeful empty states, loading transitions show structured skeletons, power users can operate keyboard-first, files can be dragged from the OS directly onto the browser, and every action produces an immediate toast confirmation.
**Depends on**: Phase 9
**Requirements**: UX-01, UX-02, UX-03, UX-04, UX-05, UX-06, UX-07, UX-08, UX-09, UX-10, UX-11, UX-12, UX-13, UX-14, CODE-05
**Implementation notes:**
- Global `keydown` listener must guard against active input elements before firing any shortcut. The check pattern is: `['INPUT','TEXTAREA','SELECT'].includes(document.activeElement?.tagName) || document.activeElement?.isContentEditable` → early return. Register in `mounted()`, remove in `beforeUnmount()`. (PITFALLS.md §Pitfall 12)
- Drag-and-drop upload (`UX-09`) detects `dataTransfer.types.includes('Files')` to distinguish file drags from element drags. The full-screen overlay must be attached at the `window`/`document` level, not inside `StorageBrowser`. (UX-09 requirement)
- Drag-to-move (`UX-11`) is already partially implemented in `StorageBrowser.vue`. This phase wires it end-to-end and adds the `ring-2 ring-inset ring-amber-300` drop highlight on valid folder targets.
- `DocumentCard.vue` drag must track `dragging` state to prevent the browser's `dragend`-then-`click` fire from navigating after a drag. Use a dedicated drag handle element where possible. (PITFALLS.md §Pitfall 6)
- All dropdown menus that risk viewport-edge clipping must use fixed positioning from `getBoundingClientRect()` or `<Teleport to="body">`. This is a prerequisite for virtual scrolling adoption if pursued later. (UX-13, PITFALLS.md §Pitfall 7)
- `AppIcon.vue` centralizes all SVG path data. Inline `<svg>` blocks are replaced with `<AppIcon name="..." class="..." />`. No duplicated path strings remain. (CODE-05)
- `UX-14`: the inline "New" folder button in `AppSidebar.vue` is removed; folder creation is accessible only from the file manager.
- A single shared `BreadcrumbBar.vue` component serves all view types — no per-view breadcrumb implementations. (UX-12)
**Success Criteria** (what must be TRUE):
1. Every zero-content context (root file list, folder, search with no results, shared-with-me, topics, audit log, cloud connections) shows a distinct `EmptyState.vue` — no plain "No items" text remains anywhere in the app
2. Pressing `/` focuses the search bar, `Escape` closes any open modal and clears active search, `U` triggers the file upload picker, and `N` starts the new-folder input — none of these fire when a text input has focus
3. Dragging files from the OS onto any part of the browser window (not just a drop zone) shows a full-screen overlay and uploads them on drop
4. Every upload, delete, share, revoke, and rename action produces a toast notification that auto-dismisses after 4 seconds and does not block interaction with the page
5. All views display a breadcrumb rendered by a single shared component; the breadcrumb reflects the full navigation path and updates on every route change
**Plans**: 12 plans (6 waves)
**Wave 0** — Foundation components + xfail test stubs (parallel)
- [x] 10-01-PLAN.md — AppIcon.vue + tests (CODE-05 foundation)
- [x] 10-02-PLAN.md — EmptyState.vue + tests (UX-01 foundation)
- [x] 10-03-PLAN.md — BreadcrumbBar.vue + tests (UX-12 foundation)
- [x] 10-04-PLAN.md — Toast store + ToastContainer.vue + App.vue mount + tests (UX-10 foundation)
- [x] 10-05-PLAN.md — Wave 0 xfail test stubs for UX-02..09, UX-11, UX-13, UX-14
**Wave 1** *(blocked on Wave 0 foundation components)* — Wire EmptyState, skeletons, BreadcrumbBar, UX-14, toast call sites (parallel)
- [x] 10-06-PLAN.md — StorageBrowser + FileManagerView + CloudFolderView wiring (skeleton, EmptyState, BreadcrumbBar swap, FolderBreadcrumb deletion, toast call sites) — UX-02, UX-01 (storage), UX-10 (file actions), UX-12 (file manager)
- [x] 10-07-PLAN.md — AppSidebar wiring (skeleton, EmptyState micro, UX-14 removal) — UX-03, UX-01 (sidebar), UX-14
- [x] 10-08-PLAN.md — Admin views + Settings + SharedView + CloudStorageView (skeleton, EmptyState, BreadcrumbBar static segments) — UX-04, UX-01 (remaining), UX-12 (admin)
**Wave 2** *(blocked on Wave 1)* — Keyboard shortcuts
- [x] 10-09-PLAN.md — Global keydown in App.vue + ref chain through FileManagerView/StorageBrowser/DropZone/SearchBar — UX-05, UX-06, UX-07, UX-08
**Wave 3** *(blocked on Wave 2)* — OS drag overlay
- [x] 10-10-PLAN.md — OsDragOverlay.vue + App.vue mount + FileManagerView.handleOsDrop — UX-09
**Wave 4** *(blocked on Waves 1-3)* — Drag-to-move completion + dropdown clipping fixes
- [x] 10-11-PLAN.md — Click-after-drag guard in StorageBrowser + Teleport-based folder picker (StorageBrowser, DocumentCard) + FolderRow three-dot menu — UX-11, UX-13
**Wave 5** *(blocked on Wave 4)* — SVG centralization across the codebase
- [x] 10-12-PLAN.md — Replace all inline `<svg>` blocks in ~29 files with `<AppIcon name="..." class="..." />` — CODE-05
**UI hint**: yes
---
### Phase 11: Visual Design, Responsive Layout & Cleanup
**Goal**: Every component uses the Tailwind spacing scale and typography system consistently, form elements have cross-browser baseline styling, interactive elements have consistent hover/focus states, the layout adapts cleanly to mobile viewports with a hamburger-toggled sidebar drawer, dead code is deleted, and bundle size is measured before and after.
**Depends on**: Phase 10
**Requirements**: VISUAL-01, VISUAL-02, VISUAL-03, VISUAL-04, RESP-01, RESP-02, RESP-03, RESP-04, RESP-05, CODE-07, PERF-02, PERF-03
**Implementation notes:**
- Sidebar responsive behavior: below `lg` (1024px) the sidebar is hidden; a hamburger button in a mobile-only header toggles a slide-in overlay drawer with `translate-x-0 / -translate-x-full` transition. Sidebar open/closed state lives in a Pinia store or `App.vue` ref — not in `AppSidebar`'s own `data()`. (PITFALLS.md §Pitfall 8)
- The admin layout needs the same responsive treatment as the user layout — admin sidebar hidden on mobile, hamburger shows the admin nav drawer. (RESP-05)
- All route components not on the critical render path must be lazy-loaded with `() => import(...)`. Admin views are explicitly lazy-loaded. (PERF-03)
- `PERF-02` requires two Vite bundle reports committed to `.planning/`: one measured before optimizations (taken at start of this phase) and one after all work is complete (taken at end).
- `CODE-07` dead-code deletion sweeps all unreferenced files, components, stores, and unused imports. Deletion happens after all other changes in this phase are complete — delete only what is confirmed unreferenced after all additions.
- `VISUAL-02` requires the `@tailwindcss/forms` plugin (already listed in PERF-01) to be configured in `tailwind.config.js`.
- `RESP-02`: `StorageBrowser`'s grid hides the Size column below `md` and Modified below `sm`. Icon, name, and actions are always visible.
- `RESP-03`: inline icon action buttons have minimum 36×36px touch target below `md`; storage row actions are visible without hover on touch devices.
- `RESP-04`: all modal dialogs are scrollable on viewports below 640px.
- UAT gap closure 11-07: below `sm`, StorageBrowser search/sort/new-folder collapse into compact icon controls so the toolbar fits below ~550px without horizontal scrolling.
**Success Criteria** (what must be TRUE):
1. At 375px viewport width, the app is fully usable: the sidebar is hidden, the hamburger opens an overlay drawer, the document list shows only icon/name/actions columns, and all touch targets are at least 36×36px
2. All form inputs, selects, textareas, checkboxes, and radio buttons have consistent cross-browser styling with no browser-default rendering differences visible between Chrome, Firefox, and Safari
3. Every button, card row, and interactive link has a visible `focus-visible:` ring and a distinct hover state; no interactive element is style-identical in focused and unfocused states
4. No arbitrary pixel value (`px-[13px]`, `style="margin: 5px"`, etc.) appears in any template; all spacing is from the Tailwind scale
5. Two bundle analysis reports are committed to `.planning/` — one baseline and one post-optimization; all non-initial-render routes are lazy-loaded and appear as separate chunks in the report
**Plans**: 11-01 through 11-07 complete
**UI hint**: yes
---
## v0.2 Progress Table
| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 8. Stack Upgrade & Backend Decomposition | 4/8 | In Progress| |
| 9. Admin Panel Rearchitecture | 5/5 | Complete | 2026-06-13 |
| 10. UX & Interaction | 13/13 | Complete | 2026-06-16 |
| 11. Visual Design, Responsive Layout & Cleanup | 7/7 | Complete | 2026-06-17 |
---
## Progress Table
| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. Infrastructure Foundation | 5/5 | Complete | 2026-05-22 |
| 2. Users & Authentication | 6/6 | Complete | 2026-06-01 |
| 3. Document Migration & Multi-User Isolation | 5/5 | Complete | 2026-05-25 |
| 4. Folders, Sharing, Quotas & Document UX | 9/9 | Complete | 2026-05-28 |
| 5. Cloud Storage Backends | 12/12 | Complete | 2026-05-30 |
| 6. Performance & Production Hardening | 6/6 | Complete | 2026-05-30 |
| 6.1. Close v1.0 audit gaps | 2/2 | Complete | 2026-05-30 |
| 6.2. Close v1 sharing + cloud-delete + CSV export gaps | 5/5 | Complete | 2026-05-31 |
| 7. Redo and optimize LLM integration | 5/5 | Complete | 2026-06-05 |
| 7.1. Security: session revocation on privilege change (CR-01..03) | 0/2 | Planned | — |
| 7.2. Security: JTI claim + Redis access-token revocation | 3/3 | Complete | 2026-06-05 |
| 7.3. Security: ES256 algorithm upgrade | 3/3 | Complete | 2026-06-06 |
| 7.4. Security: token fingerprinting / token binding | 2/2 | Complete | 2026-06-06 |
.planning/STATE.md
+22 -25
View File
@@ -1,32 +1,29 @@
--- ---
gsd_state_version: 1.0 gsd_state_version: 1.0
milestone: v0.2 milestone: v0.2
milestone_name: Phases milestone_name: UI Overhaul and Optimization
current_phase: 11 current_phase: 11
status: executing status: complete
last_updated: "2026-06-16T19:00:53.916Z" last_updated: "2026-06-17"
last_activity: 2026-06-16 -- Phase 11 execution started last_activity: 2026-06-17 -- v0.2 milestone archived
progress: progress:
total_phases: 4 total_phases: 4
completed_phases: 3 completed_phases: 4
total_plans: 32 total_plans: 33
completed_plans: 26 completed_plans: 33
percent: 75 percent: 100
--- ---
# Project State # Project State
**Project:** DocuVault **Project:** DocuVault
**Status:** Executing Phase 11 **Status:** v0.2 milestone complete — ready for next milestone
**Current Phase:** 11 **Last Updated:** 2026-06-17
**Last Updated:** 2026-06-16
## Current Position ## Current Position
Phase: 11 (visual-design-responsive-layout-cleanup) — EXECUTING Milestone v0.2 shipped 2026-06-17. All 4 phases complete, 40/40 requirements satisfied.
Plan: 1 of 6 Next action: `/gsd:new-milestone` to define v0.3
Status: Executing Phase 11
Last activity: 2026-06-16 -- Phase 11 execution started
## Phase Status ## Phase Status
@@ -34,17 +31,17 @@ Last activity: 2026-06-16 -- Phase 11 execution started
|-------|-------------|--------| |-------|-------------|--------|
| 8. Stack Upgrade & Backend Decomposition | PERF-01, CODE-01, CODE-02, CODE-03, CODE-04, CODE-08 | **Complete (8/8 plans)** | | 8. Stack Upgrade & Backend Decomposition | PERF-01, CODE-01, CODE-02, CODE-03, CODE-04, CODE-08 | **Complete (8/8 plans)** |
| 9. Admin Panel Rearchitecture | ADMIN-08..12, CODE-06, CODE-09 | **Complete (5/5 plans)** | | 9. Admin Panel Rearchitecture | ADMIN-08..12, CODE-06, CODE-09 | **Complete (5/5 plans)** |
| 10. UX & Interaction | UX-01..14, CODE-05 | **Complete (12/12 plans)** | | 10. UX & Interaction | UX-01..14, CODE-05 | **Complete (13/13 plans)** |
| 11. Visual Design, Responsive Layout & Cleanup | VISUAL-01..04, RESP-01..05, CODE-07, PERF-02, PERF-03 | **Planned (0/6 plans)** | | 11. Visual Design, Responsive Layout & Cleanup | VISUAL-01..04, RESP-01..05, CODE-07, PERF-02, PERF-03 | **Complete (7/7 plans)** |
## Performance Metrics ## Performance Metrics
| Metric | Value | | Metric | Value |
|---|---| |---|---|
| Phases complete | 3 / 4 | | Phases complete | 4 / 4 |
| Requirements mapped | 40 / 40 | | Requirements satisfied | 40 / 40 |
| Plans written | 96 | | Plans complete | 33 / 33 |
| Plans complete | 90 | | Tests at close | 277 |
## Accumulated Context ## Accumulated Context
@@ -67,8 +64,8 @@ Last activity: 2026-06-16 -- Phase 11 execution started
### Roadmap Evolution ### Roadmap Evolution
- v0.1 completed: all 7 foundation phases + security hardening (2026-06-06) - v0.1 completed: all 7 foundation phases + security hardening (2026-06-06)
- v0.2 started: UI overhaul, code quality, admin panel rearchitecture (2026-06-07) - v0.2 completed: UI overhaul, admin panel rearchitecture, responsive layout, codebase quality (2026-06-17)
- v0.2 roadmap defined: 4 phases, 40 requirements, phases 8–11 (2026-06-07) - v0.2 archived to `.planning/milestones/v0.2-ROADMAP.md`
### Open Questions ### Open Questions
@@ -84,7 +81,7 @@ _Updated at each phase transition._
| Field | Value | | Field | Value |
|---|---| |---|---|
| Last session | 2026-06-13 — Phase 9 complete; UAT 9/9 passed | | Last session | 2026-06-17 — v0.2 milestone archived |
| Next action | /gsd:execute-phase 11 plan 11-01 | | Next action | /gsd:new-milestone to define v0.3 |
| Pending decisions | None | | Pending decisions | None |
| Resume file | None | | Resume file | None |
.planning/milestones/v0.2-MILESTONE-AUDIT.md
+103
View File
@@ -0,0 +1,103 @@
---
milestone: v0.2
name: Phases
status: passed
audited_at: 2026-06-17
remediated_at: 2026-06-17
phase_count: 4
completed_phases: 4
requirements_total: 40
requirements_satisfied: 40
requirements_partial: 0
requirements_missing: 0
nyquist_compliant_phases: 4
nyquist_partial_phases: 0
integration_check:
status: passed
mode: inline_fallback
note: "gsd-integration-checker spawn failed in Codex runtime with child model resolution error; integration was checked inline from phase artifacts and source wiring."
blocking_gaps: []
---
# v0.2 Milestone Audit
## Verdict
Milestone v0.2 now has complete gate evidence across all four phases. The original audit found missing or stale closeout artifacts; those gaps were remediated on 2026-06-17.
Recommended route: archive/complete the milestone when ready.
## Audit Method
The workflow integration-checker subagent could not be spawned in this Codex runtime because child model resolution failed. The integration step was completed inline by cross-checking phase summaries, verification files, validation/security artifacts, requirements traceability, and source wiring.
## Phase Gate Summary
| Phase | Verification | Validation | UAT | Security | Audit result |
|---|---:|---:|---:|---:|---|
| 08 Stack Upgrade / Backend Decomposition | Passed, 6/6 | Complete | Complete | Verified | Complete |
| 09 Admin Panel Rearchitecture | Human needed, 5/5 | Complete | Complete | Verified | Acceptable with ADMIN-09 decision noted |
| 10 UX Interaction | Passed, 15/15 | Complete | Resolved | Verified | Complete |
| 11 Visual / Responsive Cleanup | Passed, 12/12 | Complete | Resolved | Complete | Complete |
## Blocking Gaps
All blocking gaps from the initial audit are resolved.
## Remediation Completed
1. Phase 08 verification was reconstructed in `08-VERIFICATION.md`.
2. Phase 10 security gate was reconstructed in `10-SECURITY.md`.
3. Phase 11 post-11-07 UAT/validation/verification closure was recorded in `11-UAT.md`, `11-VALIDATION.md`, and `11-VERIFICATION.md`.
4. `REQUIREMENTS.md` traceability was updated for all completed v0.2 requirements.
5. ADMIN-09 was aligned with the accepted Phase 09 D-06 decision: admin accounts are administration-only and no "Back to app" link is rendered.
6. `npm audit --audit-level=high` high-severity esbuild finding was closed by upgrading frontend Vite to `^8.0.16`.
## Requirement Coverage
| Phase | Requirements | Satisfied | Partial | Notes |
|---|---:|---:|---:|---|
| 08 | 6 | 6 | 0 | `08-VERIFICATION.md` now exists and verifies all Phase 8 v0.2 requirements |
| 09 | 7 | 7 | 0 | ADMIN-09 text now matches accepted D-06 admin-only decision |
| 10 | 15 | 15 | 0 | Verification passed; requirements traceability updated |
| 11 | 12 | 12 | 0 | Plan 11-07 mobile UAT closure is reflected in UAT, validation, and verification artifacts |
Strict audit score: 40/40 requirements satisfied, 0 partial, 0 missing.
## Integration Findings
The milestone's cross-phase wiring appears coherent:
- Phase 08 backend decomposition preserved route/module behavior according to summaries and green tests.
- Phase 08 frontend client barrel exports avoided consumer churn.
- Phase 09 admin routing uses the admin layout and matched-route guard pattern.
- Phase 10 shared UX components feed into Phase 11 responsive cleanup.
- `StorageBrowser.vue` remains the single shared file browser used by local and cloud file views.
Previously identified integration risks are resolved:
- Phase 08 now has the canonical verification artifact.
- Phase 10 now has the canonical security artifact.
- Phase 11 post-fix evidence loop is closed after plan 11-07.
- ADMIN-09 is explicitly aligned with decision D-06.
## Nyquist Review
| Phase | Nyquist status | Evidence |
|---|---|---|
| 08 | Compliant | `08-VALIDATION.md` marks `nyquist_compliant: true` |
| 09 | Compliant | `09-VALIDATION.md` marks `nyquist_compliant: true` |
| 10 | Compliant | `10-VALIDATION.md` marks `nyquist_compliant: true` |
| 11 | Compliant | `11-VALIDATION.md` marks `nyquist_compliant: true` after plan 11-07 closure |
## Remediation Checklist
1. [x] Run or reconstruct Phase 08 verification and create `08-VERIFICATION.md`.
2. [x] Run the Phase 10 security gate and create `10-SECURITY.md`.
3. [x] Re-run Phase 11 UAT/validation after plan 11-07 and update `11-UAT.md`, `11-VALIDATION.md`, and `11-VERIFICATION.md` as needed.
4. [x] Update `REQUIREMENTS.md` traceability once the above artifacts exist.
5. [x] Decide whether ADMIN-09 should remain a documented D-06 override or be edited to remove the "Back to app" requirement.
## Archive Decision
Milestone v0.2 is ready for archival/closeout from this audit's perspective.
.planning/milestones/v0.2-REQUIREMENTS.md
+114
View File
@@ -0,0 +1,114 @@
# DocuVault v0.2 Requirements — Archive
**Milestone:** v0.2 — UI Overhaul and Optimization
**Archived:** 2026-06-17
**Total requirements:** 40 — all satisfied
---
## CODE — Codebase Quality
- [x] **CODE-01**: Backend `api/admin.py` decomposed into `api/admin/` package — Phase 8, Complete
- [x] **CODE-02**: `api/documents.py` decomposed into `api/documents/` package — Phase 8, Complete
- [x] **CODE-03**: `api/auth.py` decomposed into `api/auth/` package — Phase 8, Complete
- [x] **CODE-04**: Frontend `api/client.js` decomposed into domain modules; barrel re-export — Phase 8, Complete
- [x] **CODE-05**: All inline SVG blocks replaced with `<AppIcon name="..." />`; path data centralized — Phase 10, Complete
- [x] **CODE-06**: Tailwind `safelist` configured for all dynamic class name patterns in `formatters.js` — Phase 9, Complete
- [x] **CODE-07**: All unreferenced files, components, stores, and unused imports deleted — Phase 11, Complete
- [x] **CODE-08**: No duplicated Pydantic model definitions; shared schemas in dedicated modules — Phase 8, Complete
- [x] **CODE-09**: No WHAT comments remain; WHY-only policy enforced across all touched files — Phase 9, Complete
## ADMIN — Admin Panel
- [x] **ADMIN-08**: Admin panel at `/admin/*`; `AdminLayout.vue` as route component; `AdminView.vue` deleted — Phase 9, Complete
- [x] **ADMIN-09**: Admin sidebar: Overview, Users, Quotas, AI Config, Audit Log. No "Back to app" link (D-06 decision) — Phase 9, Complete
- [x] **ADMIN-10**: Deep-linkable URLs (`/admin/users`, `/admin/quotas`, `/admin/ai`, `/admin/audit`); back button works — Phase 9, Complete
- [x] **ADMIN-11**: Admin overview page with user count, platform storage, doc status breakdown, last 10 audit entries — Phase 9, Complete
- [x] **ADMIN-12**: `to.matched.some(r => r.meta.requiresAdmin)` guard on all `/admin/*` routes — Phase 9, Complete
## UX — UX and Interaction
- [x] **UX-01**: `EmptyState.vue` in all zero-content contexts; no plain "No items" text remains — Phase 10, Complete
- [x] **UX-02**: `StorageBrowser` displays 5-col `animate-pulse` skeleton grid rows during loading — Phase 10, Complete
- [x] **UX-03**: Sidebar folder tree and topics list display skeleton placeholders during loading — Phase 10, Complete
- [x] **UX-04**: Admin user table and audit log table display skeleton table rows during loading — Phase 10, Complete
- [x] **UX-05**: Pressing `/` when no input is focused moves focus to the search bar — Phase 10, Complete
- [x] **UX-06**: Pressing `Escape` closes any open modal and clears active search — Phase 10, Complete
- [x] **UX-07**: Pressing `U` when no input is focused triggers the file upload picker — Phase 10, Complete
- [x] **UX-08**: Pressing `N` when no input is focused starts the new folder inline input — Phase 10, Complete
- [x] **UX-09**: OS drag-onto-browser shows full-screen overlay; releasing uploads files — Phase 10, Complete
- [x] **UX-10**: Toast notification system (auto-dismiss 4s, stacking, non-blocking) for upload/delete/share/rename — Phase 10, Complete
- [x] **UX-11**: Drag-to-move document onto folder row with `ring-2 ring-inset ring-amber-300` drop highlight — Phase 10, Complete
- [x] **UX-12**: Single shared `BreadcrumbBar.vue` across all views; updates on every route change — Phase 10, Complete
- [x] **UX-13**: All dropdowns use `Teleport + getBoundingClientRect`; no viewport-edge clipping — Phase 10, Complete
- [x] **UX-14**: Inline "New" folder button removed from `AppSidebar.vue`; folder creation in file manager only — Phase 10, Complete
## VISUAL — Visual Design
- [x] **VISUAL-01**: Consistent spacing scale; no arbitrary `px-[N]` values or inline `style` margins — Phase 11, Complete
- [x] **VISUAL-02**: `@tailwindcss/forms` plugin configured; cross-browser form element baseline styling — Phase 11, Complete
- [x] **VISUAL-03**: All interactive elements have consistent hover, `focus-visible:` rings, and active states — Phase 11, Complete
- [x] **VISUAL-04**: Consistent typography scale: one heading size per level, one body size, one label/caption size — Phase 11, Complete
## RESP — Responsive Layout
- [x] **RESP-01**: Sidebar hidden below `lg` (1024px); hamburger opens slide-in overlay drawer — Phase 11, Complete
- [x] **RESP-02**: Document list hides Size column below `md`, Modified below `sm`; compact icon toolbar below `sm` — Phase 11, Complete (11-07 gap closure)
- [x] **RESP-03**: Inline icon action buttons ≥36×36px touch target on viewports below `md` — Phase 11, Complete
- [x] **RESP-04**: All modal dialogs scrollable on viewports below 640px — Phase 11, Complete
- [x] **RESP-05**: Admin layout has same responsive behavior (hamburger, drawer) as user layout — Phase 11, Complete
## PERF — Performance and Stack
- [x] **PERF-01**: Frontend dependencies bumped: `vue@^3.5.0`, `vite@^8.0.16`, `@vueuse/core@^14.3.0`, `sortablejs`, `@tailwindcss/forms`, `rollup-plugin-visualizer` — Phase 8, Complete
- [x] **PERF-02**: Bundle baseline and post-optimization reports committed to `.planning/` — Phase 11, Complete (−81 kB / −30.6%)
- [x] **PERF-03**: All non-initial-render routes lazy-loaded; admin views explicitly lazy-loaded — Phase 11, Complete
---
## Traceability
| REQ-ID | Phase | Status |
|--------|-------|--------|
| PERF-01 | Phase 8 | ✓ Complete |
| CODE-01 | Phase 8 | ✓ Complete |
| CODE-02 | Phase 8 | ✓ Complete |
| CODE-03 | Phase 8 | ✓ Complete |
| CODE-04 | Phase 8 | ✓ Complete |
| CODE-08 | Phase 8 | ✓ Complete |
| ADMIN-08 | Phase 9 | ✓ Complete |
| ADMIN-09 | Phase 9 | ✓ Complete (D-06: admin-only, no Back-to-app) |
| ADMIN-10 | Phase 9 | ✓ Complete |
| ADMIN-11 | Phase 9 | ✓ Complete |
| ADMIN-12 | Phase 9 | ✓ Complete |
| CODE-06 | Phase 9 | ✓ Complete |
| CODE-09 | Phase 9 | ✓ Complete |
| UX-01 | Phase 10 | ✓ Complete |
| UX-02 | Phase 10 | ✓ Complete |
| UX-03 | Phase 10 | ✓ Complete |
| UX-04 | Phase 10 | ✓ Complete |
| UX-05 | Phase 10 | ✓ Complete |
| UX-06 | Phase 10 | ✓ Complete |
| UX-07 | Phase 10 | ✓ Complete |
| UX-08 | Phase 10 | ✓ Complete |
| UX-09 | Phase 10 | ✓ Complete |
| UX-10 | Phase 10 | ✓ Complete |
| UX-11 | Phase 10 | ✓ Complete |
| UX-12 | Phase 10 | ✓ Complete |
| UX-13 | Phase 10 | ✓ Complete |
| UX-14 | Phase 10 | ✓ Complete |
| CODE-05 | Phase 10 | ✓ Complete |
| VISUAL-01 | Phase 11 | ✓ Complete |
| VISUAL-02 | Phase 11 | ✓ Complete |
| VISUAL-03 | Phase 11 | ✓ Complete |
| VISUAL-04 | Phase 11 | ✓ Complete |
| RESP-01 | Phase 11 | ✓ Complete |
| RESP-02 | Phase 11 | ✓ Complete |
| RESP-03 | Phase 11 | ✓ Complete |
| RESP-04 | Phase 11 | ✓ Complete |
| RESP-05 | Phase 11 | ✓ Complete |
| CODE-07 | Phase 11 | ✓ Complete |
| PERF-02 | Phase 11 | ✓ Complete |
| PERF-03 | Phase 11 | ✓ Complete |
*All 40 requirements satisfied. Archive created 2026-06-17.*
.planning/milestones/v0.2-ROADMAP.md
+154
View File
@@ -0,0 +1,154 @@
# Milestone v0.2: UI Overhaul and Optimization
**Status:** ✅ SHIPPED 2026-06-17
**Phases:** 8–11
**Total Plans:** 33
## Overview
v0.2 transformed DocuVault from a feature-complete but rough alpha into a polished, production-quality web application. The milestone covered four areas: codebase quality (decomposing monolith routers, eliminating duplication, purging dead code), admin panel rearchitecture (standalone route subtree with deep-linkable views), UX & interaction (empty states, skeletons, keyboard shortcuts, OS drag-drop, toast notifications), and visual design with responsive layout (mobile sidebar, consistent spacing, form styling, bundle optimization).
## Phases
### Phase 8: Stack Upgrade & Backend Decomposition
**Goal**: The dependency stack is current, all three backend router monoliths are split into focused sub-packages with zero URL or behavior changes, and the frontend API client is decomposed into domain modules behind a re-export barrel — the entire change is invisible to consumers and tests.
**Depends on**: Phase 7.4 (last v0.1 phase)
**Requirements**: PERF-01, CODE-01, CODE-02, CODE-03, CODE-04, CODE-08
**Plans**: 8 plans (3 waves)
**Wave 0** — Foundation (parallel)
- [x] 08-01-PLAN.md — CR-01/02/03 test stubs (3 xfail stubs in test_auth.py) + Wave 0 scaffolds for regression detection
- [x] 08-02-PLAN.md — `api/schemas.py` creation + `CloudConnectionOut` migration from admin.py (MUST precede admin split)
**Wave 1** — Phase 7.1 completion (frontend only)
- [x] 08-03-PLAN.md — `useToastStore` stub + CR test promotion + SettingsAccountTab.vue + TotpEnrollment.vue inline toast replacement
**Wave 2** — Backend decomposition + frontend (parallel)
- [x] 08-04-PLAN.md — Split `api/admin.py` → `api/admin/` package (CODE-01)
- [x] 08-05-PLAN.md — Split `api/documents.py` → `api/documents/` package (CODE-02)
- [x] 08-06-PLAN.md — Split `api/auth.py` → `api/auth/` package (CODE-03)
- [x] 08-07-PLAN.md — Frontend `client.js` decomposition: utils.js + 7 domain modules + barrel rewrite (CODE-04)
- [x] 08-08-PLAN.md — PERF-01 dependency bump + tailwind/vite config wiring + requirements.txt exact pinning
**Completed:** 2026-06-12
---
### Phase 9: Admin Panel Rearchitecture
**Goal**: The admin interface is a standalone route subtree (`/admin/*`) with its own layout component and sidebar; each admin section is deep-linkable and browser-back-button works; the `requiresAdmin` navigation guard correctly protects all child routes; and the Tailwind safelist is configured so dynamic color classes render correctly in production builds.
**Depends on**: Phase 8
**Requirements**: ADMIN-08, ADMIN-09, ADMIN-10, ADMIN-11, ADMIN-12, CODE-06, CODE-09
**Plans**: 5 plans (4 waves)
**Wave 1** — Foundation (parallel)
- [x] 09-01-PLAN.md — Backend overview.py endpoint + 8 ADMIN-11 tests
- [x] 09-02-PLAN.md — Frontend AdminLayout + AdminSidebar + AdminOverviewView + getAdminOverview API client
**Wave 2**
- [x] 09-03-PLAN.md — Extract 4 admin tab components to standalone views
**Wave 3**
- [x] 09-04-PLAN.md — Router rearchitecture (nested /admin + to.matched.some guard) + Tailwind safelist + delete AdminView.vue
**Wave 4**
- [x] 09-05-PLAN.md — CODE-09 comment purge + human checkpoint UAT
**Completed:** 2026-06-13
---
### Phase 10: UX & Interaction
**Goal**: The application communicates state clearly at every moment — empty contexts have purposeful empty states, loading transitions show structured skeletons, power users can operate keyboard-first, files can be dragged from the OS directly onto the browser, and every action produces an immediate toast confirmation.
**Depends on**: Phase 9
**Requirements**: UX-01 through UX-14, CODE-05
**Plans**: 13 plans (6 waves)
**Wave 0** — Foundation components + xfail test stubs (parallel)
- [x] 10-01-PLAN.md — AppIcon.vue + tests (CODE-05 foundation)
- [x] 10-02-PLAN.md — EmptyState.vue + tests (UX-01 foundation)
- [x] 10-03-PLAN.md — BreadcrumbBar.vue + tests (UX-12 foundation)
- [x] 10-04-PLAN.md — Toast store + ToastContainer.vue + App.vue mount + tests (UX-10 foundation)
- [x] 10-05-PLAN.md — Wave 0 xfail test stubs for UX-02..09, UX-11, UX-13, UX-14
**Wave 1** — Wire EmptyState, skeletons, BreadcrumbBar (parallel)
- [x] 10-06-PLAN.md — StorageBrowser + FileManagerView + CloudFolderView wiring
- [x] 10-07-PLAN.md — AppSidebar wiring (skeleton, EmptyState, UX-14 removal)
- [x] 10-08-PLAN.md — Admin views + Settings + SharedView + CloudStorageView
**Wave 2** — Keyboard shortcuts
- [x] 10-09-PLAN.md — Global keydown in App.vue + ref chain through FileManagerView/StorageBrowser
**Wave 3** — OS drag overlay
- [x] 10-10-PLAN.md — OsDragOverlay.vue + App.vue mount + FileManagerView.handleOsDrop
**Wave 4** — Drag-to-move + dropdown clipping fixes
- [x] 10-11-PLAN.md — Click-after-drag guard + Teleport-based folder picker + FolderRow three-dot menu
**Wave 5** — SVG centralization
- [x] 10-12-PLAN.md — Replace all inline `<svg>` blocks with `<AppIcon name="..." />`
**UAT Gap Closure**
- [x] 10-13-PLAN.md — 6 UAT gaps closed: sidebar shimmer, search-at-root, admin sidebar isolation, keyboard dispatch fix, Escape modifier, OS drop capture phase
**Completed:** 2026-06-16
---
### Phase 11: Visual Design, Responsive Layout & Cleanup
**Goal**: Every component uses the Tailwind spacing scale and typography system consistently, form elements have cross-browser baseline styling, interactive elements have consistent hover/focus states, the layout adapts cleanly to mobile viewports with a hamburger-toggled sidebar drawer, dead code is deleted, and bundle size is measured before and after.
**Depends on**: Phase 10
**Requirements**: VISUAL-01 through VISUAL-04, RESP-01 through RESP-05, CODE-07, PERF-02, PERF-03
**Plans**: 7 plans (5 waves + 1 UAT gap closure)
- [x] 11-01-PLAN.md — Bundle baseline + Vite analyzer wiring + lazy-load admin routes (PERF-02, PERF-03)
- [x] 11-02-PLAN.md — Tailwind forms plugin + form element baseline styling (VISUAL-02)
- [x] 11-03-PLAN.md — Responsive shells and storage rows (RESP-01, RESP-02)
- [x] 11-04-PLAN.md — Mobile-safe modals and form baseline verification (RESP-04, RESP-05)
- [x] 11-05-PLAN.md — Visual consistency pass — typography, focus-visible, hover/active states (VISUAL-01, VISUAL-03, VISUAL-04, RESP-03)
- [x] 11-06-PLAN.md — Dead-code sweep + bundle final measurement (CODE-07, PERF-02 post-opt)
- [x] 11-07-PLAN.md — Mobile storage toolbar compact icon controls (RESP-02, RESP-03 gap closure)
**Completed:** 2026-06-17
---
## Milestone Summary
**Key Decisions:**
- Options API preserved in v0.2 refactor — Composition API migration is scope-creep for a UX milestone
- Admin panel as standalone route subtree — AdminView.vue as tabs-on-user-layout is architecturally wrong
- `client.js` barrel re-export pattern — zero consumer churn; all 35+ import sites stay unchanged
- Sub-routers carry NO prefix — parent `include_router` propagates prefix; sub-router with prefix causes double-segment URLs
- FastAPI 0.128+ empty-path restriction — `@router.get("")` on sub-router with empty include prefix raises FastAPIError
- `to.matched.some()` for requiresAdmin guard — Vue Router 4 does not inherit meta to children; direct `to.meta` check is a security regression
- Vite 6→8 upgrade — resolved moderate CVEs (CVE-2026-39363/39364); npm audit clean
- AdminLayout as route component, not App.vue branch — router resolves AdminLayout as /admin component; its router-view renders children
- Tailwind safelist with regex patterns — dynamic color classes (sky=OneDrive, amber=admin audit badges) are tree-shaken without safelist
**Issues Resolved:**
- Admin panel auth guard was checking `to.meta.requiresAdmin` directly (Vue Router 4 doesn't inherit meta to children) — fixed to `to.matched.some()`
- Three-dot dropdown menus clipped by scroll containers — fixed with Teleport + getBoundingClientRect positioning
- Admin views loaded synchronously — all lazy-loaded, reducing initial bundle by 81 kB (−30.6%)
- Inline SVG duplicated path data in 66 instances — centralized in AppIcon.vue
- Mobile toolbar overflow below 550px — compact icon controls added in 11-07
**Issues Deferred:**
- Virtual scrolling — quota cap (100 MB/user) limits lists to hundreds of items; v-for sufficient
- Dark mode — coherent color token system must exist first
- Folder reordering by drag — requires persistent `position` column in DB
- Composition API migration — separate milestone
**Technical Debt Incurred:**
- Options API retained throughout — intentional deferral; next milestone may begin Composition API migration
---
*For current project status, see .planning/ROADMAP.md*