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

# 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

3.4 KiB Raw Blame History