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¶
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:
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¶
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.