kite/.planning/codebase/STACK.md

# Technology Stack

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

## Languages

**Primary:**
- Python 3.12 — backend API, services, Celery tasks, storage backends
- JavaScript (ES Modules, ES2022+) — Vue 3 frontend SPA

**Secondary:**
- SQL — PostgreSQL schema via Alembic migrations (`backend/migrations/`)
- HTML/CSS — Vue SFC templates, Tailwind utility classes

## Runtime

**Backend:**
- CPython 3.12 (pinned: `FROM python:3.12-slim` in `backend/Dockerfile`)
- ASGI server: Uvicorn `>=0.29` with `[standard]` extras
- Entry point: `backend/main.py` — `uvicorn main:app`

**Frontend:**
- Node.js 20 (pinned: `FROM node:20-alpine` in `frontend/Dockerfile`)
- Dev server: Vite 5 on port 5173, proxies `/api` → `http://backend:8000`
- Entry point: `frontend/index.html` → `frontend/src/main.js`

**Package Manager:**
- Backend: `pip` — `backend/requirements.txt`; no lockfile (floating `>=` ranges used throughout — see CONCERNS.md)
- Frontend: `npm` — lockfile: `frontend/package-lock.json`

## Frameworks

### Backend Core

| Package | Version | Purpose |
|---|---|---|
| `fastapi` | `>=0.111` | Async REST API framework — `backend/main.py` |
| `uvicorn[standard]` | `>=0.29` | ASGI server |
| `pydantic` | `>=2.0` with `[email]` | Request/response validation |
| `pydantic-settings` | `>=2.2` | Environment-based config — `backend/config.py` |
| `python-multipart` | `>=0.0.27` | Multipart file upload parsing |

### ORM / Database

| Package | Version | Purpose |
|---|---|---|
| `sqlalchemy[asyncio]` | `>=2.0.49` | Async ORM — `backend/db/session.py`, `backend/db/models.py` |
| `psycopg[binary]` | `>=3.3.4` | psycopg v3 async PostgreSQL driver |
| `alembic` | `>=1.18.4` | Schema migrations — `backend/migrations/` |
| `aiosqlite` | `>=0.20.0` | SQLite async driver (test isolation only) |

### Background Tasks

| Package | Version | Purpose |
|---|---|---|
| `celery[redis]` | `>=5.5.0` | Async task queue — `backend/celery_app.py` |
| `redis` | `>=4.6.0` | Redis async client; Celery broker + result backend + JTI token store |

### Auth / Security

| Package | Version | Purpose |
|---|---|---|
| `PyJWT` | `>=2.8.0` | JWT access token creation and verification — `backend/services/auth.py` |
| `pwdlib[argon2]` | `>=0.2.1` | Argon2id password hashing |
| `pyotp` | `>=2.9.0` | TOTP provisioning and verification (2FA) |
| `cryptography` | `>=41.0.0` | HKDF per-user key derivation; Fernet encryption for cloud credentials |
| `slowapi` | `>=0.1.9` | Rate limiting middleware on auth endpoints |
| `httpx` | `>=0.27` | Async HTTP client (HIBP k-anonymity checks, OneDrive Graph API) |

### Document Processing

| Package | Version | Purpose |
|---|---|---|
| `PyMuPDF` | `>=1.26.7` | PDF text extraction — `backend/services/extractor.py` |
| `python-docx` | `>=1.1` | DOCX text extraction — `backend/services/extractor.py` |
| `pytesseract` | `>=0.3` | OCR for image files — `backend/services/extractor.py` |
| `Pillow` | `>=10.3` | Image loading for OCR pipeline |
| `aiofiles` | `>=23.2` | Async file I/O |

### AI Classification

| Package | Version | Purpose |
|---|---|---|
| `anthropic` | `>=0.26` | Anthropic Claude SDK — `backend/ai/anthropic_provider.py` |
| `openai` | `>=1.30` | OpenAI SDK; also used as shim for Ollama and LM Studio — `backend/ai/openai_provider.py` |

### Cloud Storage SDKs

| Package | Version | Purpose |
|---|---|---|
| `minio` | `>=7.2.20` | MinIO/S3 object storage SDK — `backend/storage/minio_backend.py` |
| `google-auth-oauthlib` | `>=1.3.1` | Google OAuth2 flow — `backend/storage/google_drive_backend.py` |
| `google-api-python-client` | `>=2.196.0` | Google Drive v3 API — `backend/storage/google_drive_backend.py` |
| `msal` | `>=1.36.0` | Microsoft Auth Library for OneDrive — `backend/storage/onedrive_backend.py` |
| `webdavclient3` | `>=3.14.7` | Generic WebDAV + Nextcloud — `backend/storage/webdav_backend.py` |
| `cachetools` | `>=5.3.0` | Cloud connection caching — `backend/services/cloud_cache.py` |

### Frontend

| Package | Version | Purpose |
|---|---|---|
| `vue` | `^3.4.0` | UI framework (Options API) — `frontend/src/` |
| `vue-router` | `^4.3.0` | Client-side routing — `frontend/src/router/` |
| `pinia` | `^2.1.0` | State management (JWT access token stored in memory only) — `frontend/src/stores/` |
| `qrcode` | `^1.5.4` | TOTP QR code generation for 2FA enrollment UI |
| `tailwindcss` | `^3.4.0` | Utility-first CSS — `frontend/tailwind.config.js` |

### Frontend Dev / Build

| Tool | Version | Purpose |
|---|---|---|
| `vite` | `^5.2.0` | Dev server and bundler — `frontend/vite.config.js` |
| `@vitejs/plugin-vue` | `^5.0.0` | Vue SFC compilation |
| `postcss` | `^8.4.0` | CSS processing — `frontend/postcss.config.js` |
| `autoprefixer` | `^10.4.0` | CSS vendor prefixing |

### Testing

| Tool | Version | Purpose |
|---|---|---|
| `pytest` | `>=8.2` | Backend test runner — `backend/pytest.ini` |
| `pytest-asyncio` | `>=1.3.0` | Async test support (`asyncio_mode = auto`) |
| `vitest` | `^4.1.7` | Frontend test runner — `frontend/vitest.config.js` |
| `@vue/test-utils` | `^2.4.10` | Vue component test utilities |
| `happy-dom` | `^20.9.0` | DOM environment for Vitest |

## Infrastructure

### Docker Compose Services (`docker-compose.yml`)

| Service | Image | Port(s) | Notes |
|---|---|---|---|
| `postgres` | `postgres:17-alpine` | internal | Persistent `postgres_data` volume |
| `minio` | `minio/minio:latest` | `9000`, `9001` | S3-compatible object store; persistent `minio_data` volume |
| `redis` | `redis:7-alpine` | internal | Password-protected; Celery broker + JTI revocation store |
| `backend` | Built from `./backend` | `8000` | Hot-reload via volume mount; depends on postgres, minio, redis |
| `celery-worker` | Built from `./backend` | — | Processes `documents` queue |
| `celery-beat` | Built from `./backend` | — | Periodic task scheduler |
| `frontend` | Built from `./frontend` | `5173` | Vite dev server; proxies `/api` → `backend:8000` |

### Database Role Separation

- `docuvault_app` — DML only (SELECT/INSERT/UPDATE/DELETE); used by FastAPI app
- `docuvault_migrate` — DDL; used by Alembic migrations only
- Init script: `docker/postgres/initdb.d/01-init-users.sql`

### System Dependencies (backend Docker image)

Installed via `apt-get` in `backend/Dockerfile`:
- `tesseract-ocr` — OCR binary for `pytesseract`
- `libgl1`, `libglib2.0-0` — shared libraries required by PyMuPDF

## Configuration

**Environment variables** are the single source of truth, read by `pydantic-settings` in `backend/config.py`.

Required for core operation:
- `DATABASE_URL` — psycopg v3 async DSN for app user
- `DATABASE_MIGRATE_URL` — psycopg v3 DSN for migrate user
- `MINIO_ENDPOINT`, `MINIO_ACCESS_KEY`, `MINIO_SECRET_KEY`, `MINIO_BUCKET`
- `REDIS_URL` — used by both FastAPI (JTI store) and Celery
- `SECRET_KEY` — JWT signing secret
- `CLOUD_CREDS_KEY` — 32-byte master key for HKDF cloud credential encryption

Optional:
- `SMTP_HOST/PORT/USER/PASSWORD/FROM` — transactional email
- `GOOGLE_CLIENT_ID/SECRET`, `ONEDRIVE_CLIENT_ID/SECRET` — OAuth cloud storage
- `ADMIN_EMAIL`, `ADMIN_PASSWORD` — bootstrap admin account
- `SYSTEM_PROMPT`, `DEFAULT_AI_PROVIDER`, `DEFAULT_AI_MODEL` — AI defaults
- `CORS_ORIGINS`, `FRONTEND_URL`, `BACKEND_URL`

## Platform Requirements

**Development:**
- Docker + Docker Compose (preferred), or
- Python 3.12, Node.js 20 plus running PostgreSQL 17, MinIO, Redis instances locally

**Production:**
- Containerised via Docker Compose; no cloud-native manifests or reverse-proxy config detected in repo

---

*Stack analysis: 2026-06-02*