Backend Stack

Backend Stack

Decisions: [[adr-002-a-backend-dev-stack]], [[adr-003-a-backend-prod-stack]]. Dependency manager: uv — never pip directly.

Dependencies (backend/pyproject.toml)

Package	Version	Role
Python	>=3.13	Runtime
Django	>=5.2,<6.0	Framework
djangorestframework	>=3.15,<4.0	REST API
djangorestframework-simplejwt	>=5.3,<6.0	JWT auth (dev)
psycopg (v3, binary)	>=3.2,<4.0	PostgreSQL driver
uvicorn	>=0.30,<1.0	ASGI server
django-fsm-2	>=3.0,<4.0	FSM lifecycle for Employee
django-cors-headers	>=4.4,<5.0	CORS (local dev)
django-csp	>=4.0,<5.0	Content Security Policy headers
whitenoise	>=6.8,<7.0	Static file serving
python-dotenv	>=1.0,<2.0	.env loading

Dev-only: pytest-django, pytest-cov, django-extensions, ipython.

Installed Apps (config/settings/base.py)

apps.users          # Custom User model, auth endpoints
apps.api            # Employee model (with FSM mixin), OrgUnit, Position
apps.fsm            # EmployeeFSMMixin, EmployeeTransitionLog, signals
apps.audit_log      # Read-only REST viewset for transition logs
apps.assignments    # Assignment model + FSM + AssignmentTransitionLog
apps.business_rules # BusinessRule catalogue + evaluation engine
apps.offer          # Hours Ledger (employee supply side)
apps.demand         # Coverage (position demand side)
apps.tags           # TagCatalog, EmployeeTag, PositionTag, TagChangeLog

Architecture: [[adr-017-audit-trail-architecture]] (FSM write side / audit read side split).

Settings

Module	When	Key differences
config/settings/base.py	Base (shared)	DB, middleware, DRF config, JWT, CORS
config/settings/local.py	DEBUG=True (dev)	Inherits base; relaxes CSP/cookies
config/settings/production.py	DEBUG=False (prod)	App Runner; Cognito auth class

Environment variables: [[adr-006-environment-variables]].

DRF Configuration (base.py)

Setting	Value
Default renderer	JSONRenderer only
Default authentication	CookieJWTAuthentication (dev)
Pagination	CoverisPagination — page-based, COVERIS_PAGE_SIZE env var (default 25)
Default throttle rates	anon: 100/h, user: 1000/h
Auth-specific throttle rates	login: 5/h, token_refresh: 20/h, logout: 20/h

Auth implementation: [[auth|stack/auth]]. API conventions: [[api-conventions|stack/api-conventions]].