# DocuVault v0.2 — Requirements

**Milestone:** v0.2 — UI Overhaul and Optimization
**Created:** 2026-06-07
**Total requirements:** 40

---

## Quality Mandate (applies to all phases)

Every line of code written or modified in v0.2 must be:

- **Minimal:** smallest amount of code that correctly solves the problem. No speculative abstractions.
- **DRY:** if the same logic exists twice, extract it. Duplication is a defect.
- **Readable:** names things accurately. A reader should understand intent without comments.
- **No redundant comments:** comments exist only where the *why* is non-obvious. Never explain what the code does.
- **No dead code:** unreferenced files, components, or functions are deleted — not commented out.

---

## CODE — Codebase Quality

- [ ] **CODE-01**: Backend `api/admin.py` (934L) decomposed into `api/admin/` package with `users.py`, `quotas.py`, `ai.py`; `__init__.py` aggregates sub-routers under the existing `/api/admin` prefix. No URL changes, no behavior changes, all tests stay green.
- [ ] **CODE-02**: `api/documents.py` (852L) decomposed into focused sub-modules (upload flow, content proxy, document CRUD, search/listing) within `api/documents/` package. Prefix and behavior unchanged.
- [ ] **CODE-03**: `api/auth.py` (825L) decomposed into focused sub-modules (login/tokens, TOTP, password management, session management) within `api/auth/` package. Prefix and behavior unchanged.
- [ ] **CODE-04**: Frontend `api/client.js` (635L) decomposed into domain modules (`documents.js`, `auth.js`, `admin.js`, `folders.js`, `shares.js`, `cloud.js`, `topics.js`); `client.js` becomes the HTTP transport layer and re-export barrel. Zero changes to any of the 35+ consumer files.
- [ ] **CODE-05**: All inline SVG blocks (~66 instances) replaced with `<AppIcon name="..." class="..." />`; all icon path data centralized in `components/ui/AppIcon.vue`. No duplicated path strings.
- [ ] **CODE-06**: Tailwind `safelist` configured for all dynamic class name patterns in `formatters.js` (provider colors, backgrounds, badge text). Production builds render topic and provider colors correctly.
- [ ] **CODE-07**: All unreferenced files, components, stores, and unused imports deleted. No dead code retained.
- [ ] **CODE-08**: No duplicated Pydantic model definitions or shared validators across router files. Shared schemas extracted to dedicated modules.
- [ ] **CODE-09**: No comment in any file describes what the code does. Comments exist only where intent or constraint would not be obvious to a competent reader.

---

## ADMIN — Admin Panel

- [ ] **ADMIN-08**: Admin panel moved to `/admin/*` route subtree with `AdminLayout.vue` as the route component. `AdminLayout` has its own sidebar with admin-specific nav only — no user quota bar, no folder tree, no topic list. `AdminView.vue` is deleted.
- [ ] **ADMIN-09**: Admin sidebar nav links (in order): Overview, Users, Quotas, AI Config, Audit Log. "Back to app" link at the bottom returns to `/`.
- [ ] **ADMIN-10**: Each admin section is its own deep-linkable URL (`/admin/users`, `/admin/quotas`, `/admin/ai`, `/admin/audit`). Browser back button works within the admin section.
- [ ] **ADMIN-11**: Admin overview page (`/admin`) shows: total registered user count, total platform storage in use, document status breakdown (processing/ready/failed), last 10 audit log entries. Requires new backend aggregate query endpoints.
- [ ] **ADMIN-12**: `requiresAdmin` guard enforced for all `/admin/*` child routes via `to.matched.some(r => r.meta.requiresAdmin)`. No admin child route is accessible to non-admin users.

---

## UX — UX and Interaction

- [ ] **UX-01**: Every zero-content context shows a contextually distinct empty state using a shared `EmptyState.vue` component (headline, subtext, optional CTA). Applied to: root file list, individual folder, search with no results, shared-with-me, topics list, audit log, cloud connections. No plain "No items" text remains.
- [ ] **UX-02**: Document list (`StorageBrowser`) displays 5-col skeleton grid rows during loading (matching actual grid layout, `animate-pulse`). "Loading..." text removed.
- [ ] **UX-03**: Sidebar folder tree and topics list display skeleton placeholder items during loading. "Loading..." text removed.
- [ ] **UX-04**: Admin user table and audit log table display skeleton table rows during loading.
- [ ] **UX-05**: Pressing `/` when no input is focused moves keyboard focus to the search bar.
- [ ] **UX-06**: Pressing `Escape` closes any open modal (`ShareModal`, `FolderDeleteModal`, `DocumentPreviewModal`) and clears active search. Handled at the overlay level, not only inside inputs.
- [ ] **UX-07**: Pressing `U` when no input is focused triggers the file upload picker.
- [ ] **UX-08**: Pressing `N` when no input is focused starts the new folder inline input in the file manager.
- [ ] **UX-09**: Dragging files from the OS anywhere onto the browser window shows a full-screen drop overlay. Releasing uploads the files via the existing upload flow. Only activates when `dataTransfer.types` includes `'Files'`.
- [ ] **UX-10**: Toast notification system shows transient messages (auto-dismiss 4 seconds, manual dismiss on click) for: upload complete, upload error, document deleted, share revoked, rename successful. Toasts stack vertically and do not block interaction.
- [ ] **UX-11**: Drag-to-move a document onto a folder row in `StorageBrowser` works correctly end-to-end. Drop highlight (`ring-2 ring-inset ring-amber-300`) renders on valid folder targets. "Move to folder" button remains as non-drag alternative.
- [ ] **UX-12**: All views display a breadcrumb reflecting the full current navigation path. Examples: `Folders › Reports › Q1`, `Cloud › Google Drive › Projects`, `Admin › Users`, `Settings › Account`, `Folders › Reports › document.pdf`. Breadcrumb updates on navigation. A single shared breadcrumb component is used across all view types — no per-view implementations.
- [ ] **UX-13**: All dropdown menus and modal dialogs render their full content within the viewport. No text or interactive element is clipped by a viewport edge or sibling element. Dropdowns that risk edge-clipping use fixed positioning computed from `getBoundingClientRect()` or `<Teleport to="body">`.
- [ ] **UX-14**: The inline "New" button next to the Folders section header in `AppSidebar.vue` is removed. Folder creation accessible only from within the file manager view.

---

## VISUAL — Visual Design

- [ ] **VISUAL-01**: Consistent spacing scale across all components using Tailwind utilities only. No arbitrary `px-[13px]` values or inline `style` margins.
- [ ] **VISUAL-02**: All form elements (inputs, selects, textareas, checkboxes, radio buttons) have consistent cross-browser baseline styling via `@tailwindcss/forms` plugin.
- [ ] **VISUAL-03**: All interactive elements (buttons, links, card rows) have consistent hover states, `focus-visible:` rings, and active states.
- [ ] **VISUAL-04**: Typography scale is consistent: one heading size per level, one body size, one label/caption size. No per-component font-size overrides.

---

## RESP — Responsive Layout

- [ ] **RESP-01**: Sidebar hidden below `lg` (1024px). Hamburger button in mobile-only header toggles a slide-in overlay drawer. Overlay closes on nav tap or backdrop tap.
- [ ] **RESP-02**: Document list hides Size column below `md` (768px) and Modified column below `sm` (640px). Icon, name, and actions always visible.
- [ ] **RESP-03**: Inline icon action buttons have minimum 36×36px touch target on viewports below `md`.
- [ ] **RESP-04**: All modal dialogs are scrollable on viewports below 640px. No modal content overflows the screen.
- [ ] **RESP-05**: Admin layout has the same responsive behavior as the user layout: admin sidebar hidden on mobile, hamburger shows admin nav drawer.

---

## PERF — Performance and Stack

- [ ] **PERF-01**: Frontend dependencies bumped/added: `vue@^3.5.0`, `vite@^6.4.3`, `@vueuse/core@^14.3.0`, `@vueuse/integrations@^14.3.0`, `sortablejs@^1.15.7`, `@tailwindcss/forms@^0.5.11`. Dev: `rollup-plugin-visualizer@^7.0.1`, `@types/sortablejs`.
- [ ] **PERF-02**: Bundle baseline measured with `rollup-plugin-visualizer` before optimizations begin. Second measurement taken after all refactoring is complete. Both reports committed to `.planning/`.
- [ ] **PERF-03**: All non-initial-render route components are lazy-loaded. Admin views explicitly lazy-loaded. No synchronous import for routes not on the critical render path.

---

## Future (deferred)

- Virtual scrolling — quota cap (100 MB/user) limits lists to hundreds of items; `v-for` is sufficient. Revisit with server-side pagination.
- Dark mode — coherent color token system must exist first.
- Folder reordering by drag — requires persistent `position` column in DB.
- Multi-select with batch operations — low frequency in a personal vault.

## Out of Scope

- Composition API migration — refactor within Options API; Composition API is a separate milestone.
- Component library switch (shadcn-vue, PrimeVue) — stay with Tailwind.
- SSO, billing, group roles — v0.x exclusions unchanged from v0.1.
- Document annotation or in-app editing — not planned.

---

## Traceability

| REQ-ID | Phase | Plan |
|--------|-------|------|
| PERF-01 | Phase 8 | Pending |
| CODE-01 | Phase 8 | Pending |
| CODE-02 | Phase 8 | Pending |
| CODE-03 | Phase 8 | Pending |
| CODE-04 | Phase 8 | Pending |
| CODE-08 | Phase 8 | Pending |
| ADMIN-08 | Phase 9 | Pending |
| ADMIN-09 | Phase 9 | Pending |
| ADMIN-10 | Phase 9 | Pending |
| ADMIN-11 | Phase 9 | Pending |
| ADMIN-12 | Phase 9 | Pending |
| CODE-06 | Phase 9 | Pending |
| CODE-09 | Phase 9 | Pending |
| UX-01 | Phase 10 | Pending |
| UX-02 | Phase 10 | Pending |
| UX-03 | Phase 10 | Pending |
| UX-04 | Phase 10 | Pending |
| UX-05 | Phase 10 | Pending |
| UX-06 | Phase 10 | Pending |
| UX-07 | Phase 10 | Pending |
| UX-08 | Phase 10 | Pending |
| UX-09 | Phase 10 | Pending |
| UX-10 | Phase 10 | Pending |
| UX-11 | Phase 10 | Pending |
| UX-12 | Phase 10 | Pending |
| UX-13 | Phase 10 | Pending |
| UX-14 | Phase 10 | Pending |
| CODE-05 | Phase 10 | Pending |
| VISUAL-01 | Phase 11 | Pending |
| VISUAL-02 | Phase 11 | Pending |
| VISUAL-03 | Phase 11 | Pending |
| VISUAL-04 | Phase 11 | Pending |
| RESP-01 | Phase 11 | Pending |
| RESP-02 | Phase 11 | Pending |
| RESP-03 | Phase 11 | Pending |
| RESP-04 | Phase 11 | Pending |
| RESP-05 | Phase 11 | Pending |
| CODE-07 | Phase 11 | Pending |
| PERF-02 | Phase 11 | Pending |
| PERF-03 | Phase 11 | Pending |
