Skip to content

Development

Layout

backend/    FastAPI application, Alembic migrations, tests, admin CLI
frontend/   React + Vite + TypeScript single-page app
scripts/    Operations helpers (backup, load test)
docs/       This documentation (MkDocs Material)

Backend

cd backend
python3 -m venv .venv
.venv/bin/pip install -r requirements-dev.txt

export ANNOTRAIN_DATABASE_URL=sqlite:///./annotrain.db   # local development uses SQLite
export ANNOTRAIN_STORAGE_DIR=./data/storage
export ANNOTRAIN_ADMIN_TOKEN=dev-token

.venv/bin/alembic upgrade head
.venv/bin/python -m app.cli seed-demo --count 40
.venv/bin/uvicorn app.main:app --reload --port 8000

Interactive API documentation is at http://localhost:8000/api/docs.

Tests

cd backend
.venv/bin/python -m pytest

The suite covers the public annotation loop, assignment, undo, consensus, exports, visibility rules and checks that the Alembic migration matches the models.

Configuration

All settings are environment variables prefixed with ANNOTRAIN_:

Variable Default Purpose
ANNOTRAIN_DATABASE_URL sqlite:///./annotrain.db SQLAlchemy URL; production uses postgresql+psycopg://…
ANNOTRAIN_STORAGE_DIR ./data/storage Originals and web derivatives
ANNOTRAIN_ADMIN_TOKEN (unset, admin API disabled) Value of the X-Admin-Token header
ANNOTRAIN_CORS_ORIGINS [] JSON list of allowed origins (not needed behind the proxy)
ANNOTRAIN_WEB_MAX_SIDE 1600 Longest side of the browser image
ANNOTRAIN_WEB_QUALITY 85 JPEG quality of the browser image

Database changes

Change app/models.py, then generate and review a migration:

.venv/bin/alembic revision --autogenerate -m "describe the change"

Frontend

cd frontend
npm install
npm run dev      # http://localhost:5173, proxies /api to localhost:8000
npm test         # unit tests for the sync queue and annotation session
npm run build    # type-check + production build

How the annotation screen stays fast

  • The next images are prefetched, so answering advances instantly.
  • Answers are written by a small sync queue: strictly in order, retried with back-off when the connection drops, and persisted in the browser so a reload does not lose them.
  • Every annotation has a client-generated id, which makes retries idempotent, and Undo revokes the exact annotation (the server keeps the history and only marks it revoked).

Documentation

pip install -r requirements-docs.txt
mkdocs serve -a localhost:8123

Pushing to main redeploys the public documentation on Cloudflare Pages.

Load test

backend/.venv/bin/python scripts/loadtest.py --base-url https://annotrain.cmaslard.xyz --project bt-2026 --users 40

Simulates concurrent contributors annotating at a human pace and reports latency percentiles and errors. Run it against a test project, not the class project: it writes real annotations.