For ingestion scaling decisions and the production upload pattern, see Document Ingestion Architecture.
- Framework: FastAPI
- Database: PostgreSQL (async via asyncpg)
- ORM: SQLAlchemy 2.0 (async)
- Auth: Authlib (Google OAuth), JWT in httpOnly cookie
- Rate limiting: slowapi
- Auth — Google OAuth, session cookie, logout
- Users —
GET /me; admin CRUD for users
- Python 3.14+
- PostgreSQL
- Docker (optional, for running PostgreSQL)
uv syncCopy .env.example to .env and set required variables:
cp .env.example .envRequired: POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, JWT_SECRET_KEY, SESSION_SECRET_KEY. Generate secrets with openssl rand -hex 32.
docker compose up -dalembic upgrade headuv run uvicorn app.main:app --reloadAPI: http://localhost:8000
Docs: http://localhost:8000/docs
| Command | Purpose |
|---|---|
uv sync |
Install dependencies (from pyproject.toml) |
uv run uvicorn app.main:app --reload |
Run API (dev) |
alembic upgrade head |
Apply migrations |
alembic revision --autogenerate -m "message" |
Create migration |
pytest |
Run tests |
pytest -n auto |
Run tests in parallel (pytest-xdist) |
pytest --drop-test-db |
Run tests and drop test DB after |
ruff check . |
Lint |
ruff format . |
Format |
See docs/commands.md for Docker, pre-commit, and more.
Interactive API docs: http://localhost:8000/docs
Tests use a separate DB ({postgres_db}_test). Migrations run automatically before tests.
pytest -v
pytest -n auto # Parallel execution (pytest-xdist)Unit, integration, E2E, security, and smoke tests. See docs/commands.md for Pytest commands.