Teddy Hospital X-Ray Application

Monorepo for a Teddy Hospital X-Ray workflow:

• backend/: FastAPI + TypeScript-compatible API contract (OpenAPI via /docs)
• frontend/: SvelteKit + TypeScript web app
• nginx/: reverse proxy template (/api -> backend, / -> frontend)
• tests/: backend pytest suite
• docker/: Dockerfiles for dev/prod

Quick Start (Local)

Backend

cd backend
cp .env.example .env
python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
uvicorn app.main:app --reload --port 8000

Frontend

cd frontend
cp .env.example .env
npm install
npm run dev -- --port 3000

Frontend expects PUBLIC_BACKEND_URL in frontend/.env. Default example points to http://localhost:8000.

Tests

Backend (pytest)

cd backend
pip install -r requirements-dev.txt
cd ..
pytest

Frontend (Playwright)

cd frontend
npm install
npx playwright install --with-deps chromium
npm run test:e2e

Docker

Development

cp .env.example .env
cp backend/.env.example backend/.env
docker compose -f compose.dev.yaml up --build

Host-network development compose is the only supported dev setup.

• Backend: http://localhost:8000
• Frontend: http://localhost:3000
• Runner: connect an external real runner to http://127.0.0.1:8000

If you need the old local mock runner setup, use:

docker compose -f compose.dev-dummy.yaml up --build

The runner package lives in ./runner with sources under ./runner/src/runner. It can be installed independently (for example on a GPU machine) with pip install ./runner. It exposes tbk-runner --workflow dummy. For the chroma workflow, install additional dependencies with pip install -r runner/requirements-chroma.txt and run with tbk-runner --workflow chroma.

The dummy workflow polls /api/worker/jobs/next, waits 5 seconds per case, performs a simple image manipulation, and submits the result back to /api/worker/jobs/{case_id}/results.

Optional runner env vars:

• RUNNER_POLL_SECONDS (default 2)
• RUNNER_HTTP_TIMEOUT_SECONDS (default 30)

Chroma workflow VLM settings are passed explicitly via runner CLI options:

• --vlm-server
• --vlm-server-key (optional)
• --vlm-model-name

Production

cp .env.example .env
cp backend/.env.example backend/.env
docker compose -f compose.prod.yaml up --build -d

Nginx exposes:

• HTTP :80
• HTTPS :443

Upload limit is set to 100MB.

Feature Coverage

• Shared-password JWT auth
• QR batch generation and PDF download
• Case upload with metadata + QR content
• Worker job polling/submission protocol
• Review decisions: confirm, retry, cancel
• Storage abstraction with providers:
  • Local filesystem (default)
  • Seafile
• Fracture API/UI no-op flow
• Carousel with autoplay/manual controls

API Docs

FastAPI autogenerated OpenAPI:

• Swagger UI: http://localhost:8000/docs
• OpenAPI JSON: http://localhost:8000/openapi.json