9.7 KiB
9.7 KiB
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_settingsDB 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 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.
- 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: 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.
- 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) |
| 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 |
| 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) |
Evolution
This document evolves at phase transitions and milestone boundaries.
Last updated: 2026-06-16
After each phase transition (via /gsd-transition):
- Requirements invalidated? → Move to Out of Scope with reason
- Requirements validated? → Move to Validated with phase reference
- New requirements emerged? → Add to Active
- Decisions to log? → Add to Key Decisions
- "What This Is" still accurate? → Update if drifted
After each milestone (via /gsd:complete-milestone):
- Full review of all sections
- Core Value check — still the right priority?
- Audit Out of Scope — reasons still valid?
- Update Context with current state
Last updated: 2026-06-13 — after Phase 9