Development Setup

Prerequisites

Tool	Minimum version
Python	3.11
Node.js	18
Docker + Docker Compose	24 / 2 (optional, for full-stack)

---

Backend

cd annotation-backend
python -m venv .venv

Linux / macOSWindows

source .venv/bin/activate

.venv\Scripts\activate

pip install -r requirements.txt

Copy the environment file and edit as needed:

Linux / macOSWindows

cp ../.env.example ../.env

copy .env.example .env

Run the development server (hot-reload enabled):

uvicorn app.main:app --reload

The API is available at http://localhost:8000 and Swagger UI at http://localhost:8000/docs.

Note

On first startup the backend applies Alembic migrations and creates the admin account from FIRST_ADMIN_USERNAME / FIRST_ADMIN_PASSWORD in .env.

---

Frontend

cd annotation_ui
npm install
npm start

The dev server runs at http://localhost:3721 and proxies /api/* requests to http://localhost:8000.

---

Full Stack with Docker (recommended)

Linux / macOSWindows

cp .env.example .env
docker compose up -d --build

copy .env.example .env
docker compose up -d --build

Service	URL
Frontend	http://localhost:3721
Backend API	http://localhost:8000
Swagger docs	http://localhost:8000/docs

Rebuild after code changes:

docker compose up -d --build

View logs:

docker compose logs -f backend
docker compose logs -f frontend