kite/.planning/codebase/STRUCTURE.md

<!-- refreshed: 2026-06-02 -->
# Codebase Structure

**Analysis Date:** 2026-06-02

## Directory Layout

```
document_scanner/               # Repo root
├── backend/                    # FastAPI Python backend
│   ├── main.py                 # App factory, middleware, router registration
│   ├── config.py               # Pydantic Settings (all env vars)
│   ├── celery_app.py           # Celery factory, task routing, beat schedule
│   ├── alembic.ini             # Alembic migration config
│   ├── requirements.txt        # Pinned Python dependencies
│   ├── Dockerfile              # Backend container image
│   ├── pytest.ini              # pytest config
│   ├── api/                    # HTTP route handlers (thin — no business logic)
│   │   ├── auth.py             # /api/auth/* — register, login, TOTP, refresh
│   │   ├── documents.py        # /api/documents/* — upload, confirm, list, stream
│   │   ├── folders.py          # /api/folders/* — CRUD + document move
│   │   ├── shares.py           # /api/shares/* — share grants and revocation
│   │   ├── cloud.py            # /api/cloud/* + /api/users/me/default-storage
│   │   ├── admin.py            # /api/admin/* — user management, quota, AI config
│   │   ├── audit.py            # /api/admin/audit-log — viewer + CSV export
│   │   └── topics.py           # /api/topics/* — CRUD topics + suggest
│   ├── services/               # Business logic (no FastAPI coupling)
│   │   ├── auth.py             # Argon2, JWT, refresh tokens, TOTP, HIBP
│   │   ├── audit.py            # write_audit_log() helper
│   │   ├── classifier.py       # AI classification orchestration
│   │   ├── extractor.py        # PDF/DOCX/image/text extraction
│   │   ├── storage.py          # ORM document queries + topic resolution
│   │   ├── cloud_cache.py      # TTL-cached cloud folder listing
│   │   └── email.py            # Email composition helpers
│   ├── storage/                # Pluggable object storage backends
│   │   ├── base.py             # StorageBackend ABC
│   │   ├── __init__.py         # Factory: get_storage_backend(), get_storage_backend_for_document()
│   │   ├── minio_backend.py    # MinIO/S3 implementation (primary)
│   │   ├── google_drive_backend.py
│   │   ├── onedrive_backend.py
│   │   ├── nextcloud_backend.py
│   │   ├── webdav_backend.py
│   │   ├── cloud_utils.py      # HKDF encryption/decryption, URL validation
│   │   └── exceptions.py       # CloudConnectionError
│   ├── ai/                     # Pluggable AI classification providers
│   │   ├── base.py             # AIProvider ABC + ClassificationResult dataclass
│   │   ├── __init__.py         # Factory: get_provider()
│   │   ├── ollama_provider.py
│   │   ├── openai_provider.py
│   │   ├── anthropic_provider.py
│   │   ├── lmstudio_provider.py
│   │   └── utils.py            # Shared AI utilities
│   ├── db/                     # Database layer
│   │   ├── models.py           # SQLAlchemy ORM — 11 tables, all UUID PKs
│   │   └── session.py          # Async engine + AsyncSessionLocal factory
│   ├── deps/                   # FastAPI dependency injection
│   │   ├── auth.py             # get_current_user, get_current_admin, get_regular_user
│   │   ├── db.py               # get_db (per-request AsyncSession)
│   │   └── utils.py            # get_client_ip
│   ├── tasks/                  # Celery async task modules
│   │   ├── document_tasks.py   # extract_and_classify, cleanup_abandoned_uploads
│   │   ├── email_tasks.py      # send_reset_email, send_security_alert_email
│   │   └── audit_tasks.py      # audit_log_daily_export (nightly Celery beat)
│   ├── migrations/             # Alembic migration scripts
│   │   ├── versions/
│   │   │   ├── 0001_initial_schema.py
│   │   │   ├── 0002_add_backup_codes_and_password_must_change.py
│   │   │   ├── 0003_multi_user_isolation.py
│   │   │   └── 0004_phase4_pdf_open_mode_tsvector.py
│   │   └── env.py              # Alembic async migration runner
│   ├── tests/                  # Backend test suite (pytest + httpx)
│   │   ├── conftest.py         # Shared fixtures (async engine, client, users)
│   │   ├── test_auth_api.py
│   │   ├── test_documents.py
│   │   ├── test_folders.py
│   │   ├── test_shares.py
│   │   ├── test_cloud.py
│   │   ├── test_admin_api.py
│   │   ├── test_audit.py
│   │   ├── test_quota.py
│   │   ├── test_security.py
│   │   └── ...                 # 28 test files total
│   └── data/                   # Static data files (topic seed data etc.)
│
├── frontend/                   # Vue 3 SPA
│   ├── src/
│   │   ├── main.js             # Vue app mount, Pinia + Router registration
│   │   ├── App.vue             # Root component — layout switcher (auth vs app)
│   │   ├── style.css           # Global Tailwind CSS entry
│   │   ├── api/
│   │   │   └── client.js       # fetch wrapper, Bearer injection, 401→refresh→retry
│   │   ├── stores/             # Pinia state stores
│   │   │   ├── auth.js         # accessToken (memory), user, quota, refresh
│   │   │   ├── documents.js    # documents list, upload flow, search/sort
│   │   │   ├── folders.js      # folder tree, breadcrumb, rootFolders
│   │   │   ├── topics.js       # topics list CRUD
│   │   │   └── cloudConnections.js  # cloud connection list
│   │   ├── router/
│   │   │   └── index.js        # Routes + beforeEach auth guard (silent refresh)
│   │   ├── layouts/
│   │   │   └── AuthLayout.vue  # Centered card layout for login/register pages
│   │   ├── views/              # Page-level components (one per route)
│   │   │   ├── FileManagerView.vue      # / and /folders/:id — unified file manager
│   │   │   ├── DocumentView.vue         # /document/:id — document detail + preview
│   │   │   ├── TopicsView.vue           # /topics — topic management
│   │   │   ├── SettingsView.vue         # /settings — user settings + TOTP
│   │   │   ├── AdminView.vue            # /admin — admin panel (users, audit log)
│   │   │   ├── SharedView.vue           # /shared — documents shared with me
│   │   │   ├── CloudStorageView.vue     # /cloud — cloud connections overview
│   │   │   ├── CloudFolderView.vue      # /cloud/:provider/:folderId — cloud folder browser
│   │   │   └── auth/                   # Auth flow pages
│   │   │       ├── LoginView.vue
│   │   │       ├── RegisterView.vue
│   │   │       ├── PasswordResetView.vue
│   │   │       └── NewPasswordView.vue
│   │   ├── components/         # Reusable UI components
│   │   │   ├── storage/
│   │   │   │   └── StorageBrowser.vue  # Core file manager widget (local + cloud modes)
│   │   │   ├── layout/
│   │   │   │   ├── AppSidebar.vue      # Navigation sidebar with folder tree + quota bar
│   │   │   │   └── QuotaBar.vue        # Storage quota progress bar
│   │   │   ├── documents/
│   │   │   │   └── DocumentCard.vue    # Single document row in file manager
│   │   │   ├── folders/
│   │   │   │   ├── FolderTreeItem.vue  # Recursive sidebar folder tree node
│   │   │   │   └── FolderDeleteModal.vue
│   │   │   ├── cloud/
│   │   │   │   ├── CloudProviderTreeItem.vue
│   │   │   │   └── CloudFolderTreeItem.vue
│   │   │   ├── sharing/
│   │   │   │   └── ShareModal.vue      # Share document with another user
│   │   │   ├── upload/
│   │   │   │   └── DropZone.vue        # Drag-and-drop file upload zone
│   │   │   ├── auth/                   # Auth form components
│   │   │   ├── admin/                  # Admin panel sub-components
│   │   │   ├── settings/               # Settings page sub-components
│   │   │   ├── topics/                 # Topic chip/badge components
│   │   │   └── ui/                     # Generic UI primitives (TreeItem.vue, etc.)
│   │   └── utils/                      # Frontend utility functions
│   ├── index.html              # Vite HTML entry
│   ├── vite.config.js          # Vite config (proxy /api → :8000)
│   ├── tailwind.config.js      # Tailwind CSS config
│   ├── vitest.config.js        # Vitest test config
│   └── package.json            # npm dependencies
│
├── docker/
│   └── postgres/
│       └── initdb.d/           # PostgreSQL init scripts (DB user + role setup)
│
├── docker-compose.yml          # All services: postgres, minio, redis, backend,
│                               #   celery-worker, celery-beat, frontend
├── .env.example                # Documented env var template (safe to commit)
├── .env                        # Local secrets (gitignored)
├── CLAUDE.md                   # Project instructions for Claude agents
├── SECURITY.md                 # Security audit findings and mitigations
└── .planning/                  # GSD workflow planning artifacts
    ├── ROADMAP.md
    ├── REQUIREMENTS.md
    ├── STATE.md
    ├── PROJECT.md
    └── codebase/               # Codebase map (this directory)
```

## Directory Purposes

**`backend/api/`:**
- Purpose: HTTP endpoint handlers — thin layer only. No business logic.
- Contains: One module per resource (`auth.py`, `documents.py`, `folders.py`, etc.)
- Key files: `backend/api/documents.py` (presigned upload flow), `backend/api/auth.py` (JWT issuance)

**`backend/services/`:**
- Purpose: Business logic decoupled from FastAPI. Functions are pure async Python.
- Contains: `auth.py` (crypto, TOTP, HIBP), `classifier.py` (AI orchestration), `extractor.py` (text extraction), `storage.py` (ORM queries), `audit.py` (audit log writer), `cloud_cache.py` (TTL cache), `email.py` (email helpers)
- Rule: No module in `services/` may import from `fastapi` or `api/`

**`backend/storage/`:**
- Purpose: All object storage interaction behind the `StorageBackend` ABC
- Contains: `base.py` (interface), factory `__init__.py`, one file per backend, `cloud_utils.py` (HKDF encrypt/decrypt), `exceptions.py`
- Key invariant: `get_storage_backend_for_document()` is the only place cloud credentials are decrypted

**`backend/ai/`:**
- Purpose: AI classification providers behind the `AIProvider` ABC
- Contains: `base.py` (interface + `ClassificationResult`), factory `__init__.py`, one file per provider
- Selected per-user via `users.ai_provider` + `users.ai_model` DB columns

**`backend/db/`:**
- Purpose: ORM schema and session management
- Contains: `models.py` (11 tables, all UUID PKs, full index declarations), `session.py` (async engine, `AsyncSessionLocal`)
- Note: Two DB users — `docuvault_app` (DML only, used at runtime) and `docuvault_migrate` (DDL, used by Alembic only)

**`backend/deps/`:**
- Purpose: FastAPI `Depends()` callables — shared dependency injection
- Contains: `get_db` (per-request session), `get_current_user`, `get_current_admin`, `get_regular_user`, `get_client_ip`

**`backend/tasks/`:**
- Purpose: Celery task definitions for async background work
- Contains: `document_tasks.py` (extraction + classification + cleanup), `email_tasks.py` (password reset + security alerts), `audit_tasks.py` (nightly CSV export)

**`backend/migrations/versions/`:**
- Purpose: Alembic migration history
- Contains: Sequentially numbered migration scripts (`0001_` → `0004_`)
- Generated: Manually reviewed, never auto-generated and committed directly

**`backend/tests/`:**
- Purpose: pytest test suite using `httpx.AsyncClient` with real PostgreSQL
- Contains: 28 test files covering all endpoints, security invariants, and services
- Key files: `conftest.py` (shared fixtures), `test_security.py` (IDOR, admin block, CSRF tests)

**`frontend/src/stores/`:**
- Purpose: Pinia stores — application state + API calls
- Contains: `auth.js`, `documents.js`, `folders.js`, `topics.js`, `cloudConnections.js`
- Rule: Stores are the only place `api/client.js` is called from. Views do not call `api/` directly.

**`frontend/src/api/`:**
- Purpose: Thin HTTP client wrapper
- Contains: `client.js` — all `fetch()` calls, Bearer header injection, 401→refresh→retry logic, all exported API functions
- Rule: No business logic here — purely request/response translation

**`frontend/src/views/`:**
- Purpose: Route-level page components
- Contains: One `.vue` file per route. Views wire stores to components via event delegation.
- Key file: `FileManagerView.vue` — root view, delegates to `StorageBrowser` component

**`frontend/src/components/storage/`:**
- Purpose: Reusable file manager widget
- Contains: `StorageBrowser.vue` — unified listing component for local folder mode and cloud folder mode

**`frontend/src/components/layout/`:**
- Purpose: Persistent app shell
- Contains: `AppSidebar.vue` (navigation, folder tree, cloud links, quota bar), `QuotaBar.vue` (storage progress)

## Key File Locations

**Entry Points:**
- `backend/main.py`: FastAPI app — start here for any backend investigation
- `backend/celery_app.py`: Celery factory — start here for task routing investigation
- `frontend/src/main.js`: Vue app mount
- `frontend/src/router/index.js`: All routes + auth guard

**Configuration:**
- `backend/config.py`: All env vars with defaults (Pydantic Settings)
- `.env.example`: Documented env var template
- `docker-compose.yml`: Full service topology with env var wiring
- `frontend/vite.config.js`: Dev proxy config (`/api` → `:8000`)

**Core Logic:**
- `backend/db/models.py`: Full ORM schema — reference for all table structures
- `backend/services/auth.py`: JWT, Argon2, TOTP, HIBP — all auth primitives
- `backend/storage/__init__.py`: Storage backend factory — entry point for understanding storage routing
- `backend/storage/cloud_utils.py`: HKDF credential encryption/decryption

**Testing:**
- `backend/tests/conftest.py`: Test fixtures — DB setup, user creation, auth helpers
- `backend/tests/test_security.py`: Security invariant tests (IDOR, admin block, CSRF, timing)

## Naming Conventions

**Backend files:**
- Modules: `snake_case.py`
- One module per resource/concern in `api/` (matches the resource noun: `documents.py`, `folders.py`)
- One module per backend in `storage/` (`{provider}_backend.py`)
- One module per provider in `ai/` (`{provider}_provider.py`)

**Frontend files:**
- Vue components: `PascalCase.vue`
- Stores: `camelCase.js` matching the resource noun (`documents.js`, `folders.js`)
- Views: `{Name}View.vue` pattern

**Database:**
- All tables: `snake_case` plural (`users`, `refresh_tokens`, `cloud_connections`)
- All PKs: UUID type
- FKs: `{table_singular}_id` pattern (`user_id`, `folder_id`, `document_id`)

## Where to Add New Code

**New API endpoint (new resource):**
- Create `backend/api/{resource}.py` with `APIRouter(prefix="/api/{resource}")`
- Add service logic to `backend/services/{resource}.py` (or extend existing service)
- Register router in `backend/main.py` with `app.include_router()`
- Add corresponding `export function {action}{Resource}()` calls to `frontend/src/api/client.js`

**New Vue page (new route):**
- Create `frontend/src/views/{Name}View.vue`
- Add route to `frontend/src/router/index.js`
- If it needs auth: add `meta: { requiresAuth: true }` (or `requiresAdmin: true`)

**New Pinia store:**
- Create `frontend/src/stores/{resource}.js` using Composition API pattern (`defineStore('name', () => { ... })`)
- Export named: `export const use{Resource}Store`

**New storage backend:**
- Implement `StorageBackend` ABC from `backend/storage/base.py`
- Create `backend/storage/{provider}_backend.py`
- Add lazy import branch in `get_storage_backend_for_document()` in `backend/storage/__init__.py`

**New AI provider:**
- Implement `AIProvider` ABC from `backend/ai/base.py`
- Create `backend/ai/{provider}_provider.py`
- Register in `backend/ai/__init__.py` factory

**New Celery task:**
- Add task function to appropriate `backend/tasks/*.py` module
- Decorate with `@celery_app.task(name="tasks.{module}.{task_name}")`
- If periodic: add to `celery_app.conf.beat_schedule` in `backend/celery_app.py`

**New DB table:**
- Add ORM model class to `backend/db/models.py` extending `Base`
- Create new Alembic migration: `alembic revision --autogenerate -m "description"`
- Review and test the generated migration before committing

**New tests:**
- Backend: add `backend/tests/test_{resource}.py`
- Use fixtures from `backend/tests/conftest.py` (async session, auth client, test users)
- Security invariant tests belong in `backend/tests/test_security.py`

## Special Directories

**`.planning/`:**
- Purpose: GSD workflow planning artifacts (roadmap, requirements, phase plans, codebase maps)
- Generated: Partially (codebase maps regenerated by mapper agents)
- Committed: Yes

**`backend/data/`:**
- Purpose: Static data files (topic seed data, fixture CSVs)
- Generated: No
- Committed: Yes

**`frontend/dist/`:**
- Purpose: Vite production build output
- Generated: Yes (`npm run build`)
- Committed: No (gitignored)

**`backend/migrations/versions/`:**
- Purpose: Alembic migration history — one file per schema change
- Generated: Via `alembic revision` then manually reviewed
- Committed: Yes — each migration is a permanent historical artifact

**`.claude/worktrees/`:**
- Purpose: Isolated git worktrees used by Claude Code agent subprocesses
- Generated: Yes (by `/gsd:execute-phase` and related commands)
- Committed: No

---

*Structure analysis: 2026-06-02*