# Backend Architecture (MVP)

## Stack

- FastAPI
- PostgreSQL + asyncpg
- Celery + Redis
- Jinja2 + HTMX-ready templates

## Execution flow

1. API receives a launch request and creates a job (`queued`).
2. API starts an ephemeral runner runtime (`docker` container or `k8s` pod/service) with mini FastAPI service.
3. API sends run payload directly to runner over HTTP (`/runs/*` endpoints).
4. Runner executes `ansible-playbook` or `molecule test`.
5. Main API monitors runner status with heartbeat/timeout and persists logs/status to DB.
6. WebSocket clients subscribe to `/ws/jobs/{job_id}` and `/ws/tests/{test_id}`; API proxies realtime logs from runner WS.

## Test runs (Molecule)

- Test launch endpoint supports playbook tests and role tests.
- Runtime creates dynamic ephemeral inventory based on requested host blueprint.
- Each test run is isolated in its own dynamic runner runtime.

## Security

- JWT access token + refresh token
- Password hash via `passlib`
- Password reset token flow

## Runtime modes

- `docker`: runner starts as ephemeral container over Docker socket.
- `k8s`: runner starts as ephemeral pod + ClusterIP service in configured namespace.