curo1305
80 lines
3.4 KiB
Markdown
80 lines
3.4 KiB
Markdown
# 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
|