TFM Checkpoints — Zero Trust Temporary Access System

Monorepo for a temporary-access control system: QR-checkpoint delivery routes, real-time updates, and Authentik (OIDC/JWT) as the identity provider.

Directory	What it is
backend/	FastAPI + SQLite (WAL) API — auth, QR checkpoints, WebSockets
frontend/	React + Vite PWA — admin/client/delivery dashboards, QR scanner, live tracking
docs/	Shared contract: IMPLEMENTATION.md (human-readable API/WS reference), openapi.json (machine-readable spec), AUTHENTIK_SETUP.md (IdP one-time setup)
docker-compose.yml	Orchestrates the api, web and bundled Authentik services
project-plan-backend.md	Original backend plan this implementation follows
project-plan-frontend.md	Frontend plan (PWA) this implementation follows

Repo layout

.
├── backend/            # FastAPI app (app/, tests/, Dockerfile, requirements, pytest.ini)
├── frontend/           # React + Vite PWA (src/, Dockerfile, nginx.conf)
├── docs/               # API contract, implementation notes, Authentik setup guide
├── docker-compose.yml  # api (8836) + web (8837) + Authentik (8838) services
├── .env.example        # shared env template (compose loads .env from the repo root)
├── Makefile            # common dev commands
└── README.md

Quick start

cp .env.example .env        # set AUTHENTIK_SECRET_KEY / AUTHENTIK_BOOTSTRAP_* first
docker compose up --build -d
curl http://localhost:8836/healthz   # {"status":"ok"} — API
open http://localhost:8837           # web app (nginx proxies /api and /ws)
open http://localhost:8838           # Authentik admin UI

The compose stack runs: api (8836), web (8837, nginx serving the PWA and reverse-proxying /api + /ws same-origin — no CORS), and the bundled Authentik 2026.5 IdP (8838/9443, with its own postgres + redis + worker). On first Authentik start it bootstraps the admin user from AUTHENTIK_BOOTSTRAP_*.

One-time IdP configuration is required before anyone can log in: groups (Admin/Cliente/Repartidor), the OIDC provider/application (slug tfm), and the installation_id claim mapping. Follow docs/AUTHENTIK_SETUP.md, then put the provider's client ID into AUTHENTIK_CLIENT_ID in .env.

The web container gets its OIDC config at container start via envsubst (see frontend/docker-entrypoint.d/30-tfm-config.sh); the backend validates JWTs against AUTHENTIK_ISSUER / AUTHENTIK_JWKS_URL (in-network URL).

For front-end developers

• Read first: docs/IMPLEMENTATION.md — exact REST payloads, WebSocket protocol, scan status codes, and the adjustments made to the original plan.
• Typed clients: generate them from docs/openapi.json with cd frontend && npm run codegen (openapi-typescript → src/api/schema.d.ts). Regenerate the spec with make openapi whenever the API changes.
• Dev setup: see frontend/README.md. In dev, the Vite server proxies /api and /ws to the backend on port 8836 — no CORS, no absolute VITE_API_URL / VITE_WS_URL.

Common commands

make api        # build + run the whole stack (api, web, Authentik) with docker compose
make web        # build + run only the frontend (nginx on port 8837)
make test       # backend test suite (needs ../.venv or an active venv)
make openapi    # regenerate docs/openapi.json from the running API code

See backend/README.md for backend-specific details and frontend/README.md for the frontend.