kite/.planning/PROJECT.md

# DocuVault

## What This Is

DocuVault is a self-hosted, multi-user SaaS document management platform. Users upload documents (PDF, DOCX, images, text), which are automatically text-extracted and classified by AI into user-defined topics. Each user has isolated, quota-enforced storage, can organize documents in folders, connect external cloud storage backends (OneDrive, Google Drive, Nextcloud, etc.), and share documents with other users by handle. A privacy-first admin model gives administrators platform control without any access to user document content.

## Core Value

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

**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.

**Target features:**
- 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

### Validated (v0.1 — shipped 2026-06-06)

- ✓ Document upload and text extraction (PDF, DOCX, image, plain text)
- ✓ AI-based topic classification via configurable provider
- ✓ Multiple AI provider support (Anthropic, OpenAI, GenericOpenAI-compat, Ollama, LMStudio)
- ✓ Topic CRUD management (per-user namespace)
- ✓ Docker containerization (Compose) with PostgreSQL + MinIO
- ✓ User registration with email/password (Argon2id, strength enforcement, HaveIBeenPwned check)
- ✓ JWT session management (ES256 asymmetric, 15 min access token, 16h/30d refresh, token fingerprinting, JTI revocation)
- ✓ TOTP 2FA with backup codes; session revocation on privilege change
- ✓ Admin: create, deactivate, reset password, assign AI provider per user
- ✓ Admin cannot access user documents or cloud credentials
- ✓ Per-user isolated storage with 100 MB free-tier quota (atomic enforcement)
- ✓ Folder creation, rename, delete, move documents between folders
- ✓ Document sharing by handle (view/edit permission, revocable, no recipient quota charge)
- ✓ "Shared with me" virtual folder
- ✓ Cloud storage backends: OneDrive, Google Drive, Nextcloud, WebDAV (HKDF-encrypted credentials)
- ✓ PDF in-browser preview (proxied, no presigned URL exposure)
- ✓ Full-text search and sorting on document list
- ✓ Audit log (metadata only): logins, uploads, deletes, shares, quota changes
- ✓ Admin audit log viewer with date/user/action filters and CSV export
- ✓ Structured JSON logging (structlog + correlation IDs)
- ✓ Container hardening (non-root user, read-only filesystem, dropped capabilities)
- ✓ AI provider settings in `system_settings` DB table (HKDF-encrypted API keys)
- ✓ Celery retry backoff (30 s / 90 s / 270 s) on classification failure
- ✓ Backend stateless — all state in PostgreSQL and MinIO

### Active (v0.2 — this milestone)

*Defined in REQUIREMENTS.md*

### Out of Scope

- Subscription billing / payment processing — future milestone (quota table designed for it)
- SSO (Microsoft, Google, Apple) — future; auth layer designed for extension
- Keycloak / SAML / OAuth enterprise federation — future
- Group admin roles — future; groups table seeded in schema
- Document annotation or in-app editing — not planned
- Mobile native app — not planned (responsive web only in v0.2)
- Public document sharing (unauthenticated link) — not planned for v0.x

## Context

- **Current state**: v0.2 in progress — Phase 8 complete (2026-06-12). Backend routers decomposed into focused sub-packages, frontend API client decomposed into domain modules, Vite 6 shipped, CVEs resolved. Phase 9 (Admin Panel Rearchitecture) up next.
- **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.
- **Admin panel**: AdminView.vue currently renders admin functionality as tabs appended to the main user layout. This is architecturally wrong — the admin interface needs its own route subtree, layout component, and nav.
- **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

- **Tech stack**: FastAPI (Python) + Vue 3 — keep existing stack, no framework switch
- **Database**: PostgreSQL (Alembic-managed schema, 5 migrations completed)
- **Object storage**: MinIO (S3-compatible, Docker-native)
- **Auth**: Argon2id passwords, ES256 JWT, TOTP 2FA (pyotp), HKDF key derivation
- **Deployment**: Docker Compose (primary deployment target, must remain so)
- **No rewrites**: Refactor, don't rewrite. Preserve all existing functionality and test coverage.

## Key Decisions

| Decision | Rationale | Outcome |
|---|---|---|
| PostgreSQL + MinIO over flat files | Multi-user quotas + horizontal scaling require shared, consistent state | Shipped in v0.1 Phase 1 |
| Cloud storage adapter pattern | Mirrors AI provider pattern — consistent, extensible | Shipped in v0.1 Phase 5 |
| Privacy-first admin model | SaaS legal/trust requirement | Admin queries exclude document content; cloud creds encrypted with user-scoped key |
| Admin controls AI config, not users | Prevents cost overruns and model misuse | AI provider assignment stored per-user in DB, configurable by admin only |
| 100 MB free tier | Baseline for future subscription tiers | Quota table has `limit_bytes` column admin can override |
| TOTP 2FA before SSO | State-of-the-art security without third-party dependency | Via pyotp (RFC 6238), shipped v0.1 Phase 2 |
| ES256 over HS256 for JWT | Leaked public key cannot forge tokens; asymmetric signing | Shipped v0.1 Phase 7.3 |
| Token fingerprinting (fgp claim) | Limits stolen access token replay to original device context | HMAC of User-Agent + Accept-Language, shipped v0.1 Phase 7.4 |
| JTI claim + Redis revocation | Closes 15-min window where revoked session's access token stays valid | Shipped v0.1 Phase 7.2 |
| Options API preserved in v0.2 refactor | Composition API migration is scope-creep for a UX milestone; refactor within Options API | Decision logged to prevent scope drift |
| Admin panel as standalone route subtree | AdminView.vue as tabs-on-user-layout is an architectural mistake | v0.2 introduces /admin/* routes with own layout |
| `client.js` barrel re-export pattern | Zero consumer churn — all 35+ import sites stay unchanged; domain modules hidden behind barrel | Shipped Phase 8 (CODE-04) |
| Sub-routers carry NO prefix | Parent `include_router(sub, prefix=...)` propagates; sub-router with own prefix causes double-segment URLs | Discovered during Phase 8 backend decomposition |
| FastAPI 0.128+ empty-path restriction | `@router.get("")` on a sub-router with empty include prefix raises `FastAPIError` — register root routes on parent aggregator directly | Discovered Phase 8; affects all future sub-router patterns |
| Vite 6 upgrade | Resolved two moderate CVEs (CVE-2026-39363/39364) present in Vite 5; build time unchanged | Shipped Phase 8 (PERF-01) |

## Evolution

This document evolves at phase transitions and milestone boundaries.

**After each phase transition** (via `/gsd-transition`):
1. Requirements invalidated? → Move to Out of Scope with reason
2. Requirements validated? → Move to Validated with phase reference
3. New requirements emerged? → Add to Active
4. Decisions to log? → Add to Key Decisions
5. "What This Is" still accurate? → Update if drifted

**After each milestone** (via `/gsd:complete-milestone`):
1. Full review of all sections
2. Core Value check — still the right priority?
3. Audit Out of Scope — reasons still valid?
4. Update Context with current state

---
*Last updated: 2026-06-12 — after Phase 8*