ADR-002-a — Backend Development Stack

ADR-002-a — Backend Development Stack

Status

Accepted

Context

The backend runs inside Docker in both development and production. Versions must be pinned to guarantee reproducibility between both environments.

Decision

All backend dependencies are pinned to a semver range and managed via uv. pip is not used directly. Versions are declared in pyproject.toml (requires-python, dependencies) and locked to guarantee identical behavior across development and production Docker images. Commands run inside the container or via uv run.

Component	Pinned version	Notes
Python	>=3.13	requires-python in pyproject.toml
Django	>=5.2,<6.0	LTS. Async-capable.
Django REST Framework	>=3.15,<4.0	JSON-only, page-based pagination
djangorestframework-simplejwt	>=5.3,<6.0	JWT for local dev; Cognito in prod
psycopg	>=3.2,<4.0	psycopg3 (binary). Not psycopg2.
uvicorn	>=0.30,<1.0	ASGI server with --reload in dev
django-fsm-2	>=3.0,<4.0	FSM for Employee lifecycle
django-cors-headers	>=4.4,<5.0	CORS for local dev (localhost:4200)
python-dotenv	>=1.0,<2.0	.env file loading
django-csp	>=4.0,<5.0	Content Security Policy headers
whitenoise	>=6.8,<7.0	Static file serving in production
PostgreSQL	16-alpine	Pinned Docker image

Dev extras are excluded from the production image. pytest-django, pytest-cov, django-extensions, and ipython are installed only in the development/CI environment and are not included in the prod Docker image.

Consequences

• django-fsm-2 is a maintained fork of django-fsm; the API is identical but with Django 5+ support.
• Versions without an upper bound (pytest-*) are left uncapped per YAGNI — they only matter in CI and do not affect the prod image.
• Production uses the same Docker image (see [[adr-003-a-backend-prod-stack|ADR-003-a]]); the difference is DJANGO_SETTINGS_MODULE and the environment variables injected by App Runner.