docs: create roadmap (5 phases)

2026-05-21 20:53:28 +02:00
parent 7fac328a54
commit 3353387312
4 changed files with 313 additions and 2 deletions
@@ -0,0 +1,79 @@
+# DocuVault — Claude Code Guide
+
+## Project Overview
+
+DocuVault is a multi-user SaaS document management platform built on FastAPI (Python) + Vue 3. It handles document upload, text extraction (PDF/DOCX/image/text), AI-based topic classification, per-user isolated storage, folder organization, document sharing, and pluggable cloud storage backends (OneDrive, Google Drive, Nextcloud, WebDAV).
+
+**Current state:** Brownfield — single-user app is functional. Active milestone: migrating to multi-user, adding auth, PostgreSQL + MinIO, and cloud storage.
+
+## Stack
+
+- **Backend:** Python 3.12, FastAPI 0.136+, SQLAlchemy 2.0 async, psycopg v3, Alembic, MinIO SDK
+- **Frontend:** Vue 3 (Options API), Pinia, Vue Router 4, Vite, Tailwind CSS
+- **Infrastructure:** Docker Compose, PostgreSQL, MinIO (S3-compatible)
+- **Auth:** PyJWT 2.12+, pwdlib[argon2], pyotp (TOTP), cryptography (Fernet/HKDF)
+
+## Key Architectural Rules
+
+- JWT access token lives in **Pinia memory only** — never localStorage or sessionStorage
+- Refresh token is an **httpOnly; Secure; SameSite=Strict cookie** — never accessible to JavaScript
+- MinIO object keys are **UUID-based** (`{user_id}/{document_id}/{uuid4()}{ext}`) — human filenames in DB only
+- Cloud credentials encrypted with **HKDF per-user key derivation** — master key in env var only
+- Quota enforced atomically: **`UPDATE quotas SET used_bytes = used_bytes + $delta WHERE (used_bytes + $delta) <= limit_bytes RETURNING used_bytes`**
+- Admin endpoints **never return** document content, extracted text, or `credentials_enc`
+- Every document/folder endpoint asserts `resource.user_id == current_user.id`
+- All DB queries via ORM / parameterized statements — zero raw string interpolation
+
+## GSD Workflow
+
+This project uses the GSD (Get Shit Done) planning workflow. Planning artifacts live in `.planning/`.
+
+### Key files
+
+| File | Purpose |
+|---|---|
+| `.planning/ROADMAP.md` | 5-phase plan with success criteria |
+| `.planning/REQUIREMENTS.md` | 54 v1 requirements with REQ-IDs |
+| `.planning/STATE.md` | Current phase and completion status |
+| `.planning/PROJECT.md` | Project context and key decisions |
+| `.planning/research/SUMMARY.md` | Domain research synthesis |
+| `.planning/codebase/` | Codebase map (architecture, stack, concerns) |
+
+### Commands
+
+```
+/gsd:discuss-phase N   — gather context before planning a phase
+/gsd:plan-phase N      — create execution plan for a phase
+/gsd:execute-phase N   — execute the plan
+/gsd:verify-work N     — verify phase deliverables against requirements
+/gsd:progress          — check status and advance workflow
+```
+
+### Current phase: Not started — run `/gsd:discuss-phase 1` to begin
+
+## Development Setup
+
+```bash
+# Start all services
+docker compose up
+
+# Backend only (local dev)
+cd backend && uvicorn main:app --reload
+
+# Frontend only (local dev)
+cd frontend && npm run dev
+
+# Run backend tests
+cd backend && pytest -v
+```
+
+## Security Requirements (Non-Negotiable)
+
+- Rate limiting on all auth endpoints (login, register, password reset, TOTP)
+- Constant-time comparison for all token/code verification
+- CSRF protection on all state-changing endpoints
+- Content-Security-Policy headers on all responses
+- HaveIBeenPwned API check on registration and password change
+- TOTP replay prevention (mark used codes in DB within validity window)
+- Refresh token family revocation on token reuse detection
+- Admin impersonation is an explicit architectural exclusion — no endpoint or code path may exist