RoleForge/docs/architecture.md

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.