Backend FastAPI Development

Use this skill when working on the Python backend in backend/ (API, import/export pipeline, DB interactions).

When to use

• Editing FastAPI routes under backend/app/api/
• Changing business logic under backend/app/services/
• Updating SQLAlchemy models under backend/app/models/
• Running black / pytest, or diagnosing failing backend tests
• Debugging /healthcheck, job progress, plugin management endpoints

Local dev (outside Docker)

Prereqs:

• Python 3.14+
• A running Postgres (or use docker compose dev stack for DB/Mattermost)

Workflow:

1. Create/activate venv (repo root):

- python3 -m venv .venv - source .venv/bin/activate

1. Install deps:

- cd backend && pip install -r requirements.txt

1. Apply migrations (repo root):

- alembic -c alembic.ini upgrade head

1. Run the backend:

- cd backend && uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Health check:

• curl http://localhost:8000/healthcheck (also available as /api/healthcheck)
• Expected JSON (per integration test): {"status": "ok"}

Recommended dev workflow (Docker full stack)

This repo’s default dev workflow is running the full compose stack (backend + frontend + db + mattermost + test-files).

• Create infra/.env.dev (dummy tokens are fine for local dev)
• Start stack:

- docker compose -f infra/docker-compose.dev.yml up --build -d

Common endpoints:

• Backend: http://localhost:8000/healthcheck
• Frontend: http://localhost:5173

Code quality

ALWAYS run before committing backend changes:

• Format: cd backend && black app alembic tests
• Tests: cd backend && pytest --cov=app --cov-report=term-missing

If you only need a quick signal:

• cd backend && pytest tests/unit

Debugging checklist

• If backend doesn’t start, migrations may still be running in the lifespan hook (don’t assume Uvicorn is “hung”).
• Check logs:

- docker compose -f infra/docker-compose.dev.yml logs -f backend

• If /healthcheck fails, look for:

- DB connection errors - Alembic migration errors - Exceptions during FastAPI lifespan startup

Related docs

• Developer workflow and testing: [docs/dev.md](../../../docs/dev.md)
• Backend overview + invariants: [backend/README.md](../../../backend/README.md)
• Healthcheck contract: [backend/tests/integration/testapihealthcheck.py](../../../backend/tests/integration/testapihealthcheck.py)