CapTown FaaS Core

Core backend service for queue-first orchestration.

Responsibilities

• Inbound queue intake and JWT/session normalization
• Router with strict order policy
• Subsystem worker orchestration
• Internal system API adapters and storage abstraction
• Sender queue and response dispatch
• Audit and lifecycle cleanup operations
• Sender correlation endpoints (/responses/{message_id} and /operations/{operation_id})

Processing rules

• All operator/client business processing must enter through the queue-first ingress contract (POST /ingest).
• Direct HTTP routes in this service are for read-only lookup, runtime visibility, and artifact retrieval after queued work has updated runtime state.
• Treat work as queue-backed work units with observable status transitions, not as one global transaction.
• Use local transactions only where one concrete storage boundary needs atomicity. See ../../documentation/queue/queue-runtime.md.

Structure

• src/capetown_faas_core/ application package
• ingress/ producer intake and validation
• queue/ inbound, subsystem, and sender queues
• router/ routing policy and dispatch
• workers/ subsystem worker templates
• adapters/ system API + storage adapters
• systems/ five system API implementations
• operations/ audit/cleanup/telemetry primitives

Development

cd services/capetown-faas-core
uv sync
Copy

Start this service only through the automation stack:

uv run --with fastapi==0.115.14 --with uvicorn==0.37.0 --with pydantic==2.11.7 --with starlette==0.46.0 python scripts/automation.py up --start-stack
Copy

Health check:

• GET /health

Contracts:

• documentation/contracts/capetown-faas-core.md
• POST /contracts

Statistics auth requirement

• statistics login requires the live statistics auth path to be configured and reachable.
• There is no session-store fallback credential path for statistics in this service.