Skip to main content

alphaswarm-api

Catalog date: 2026-08-07.

alphaswarm-api is the consolidated API gateway and composition root for the AlphaSwarm platform. It preserves downstream route, authentication, tenancy, audit, and step-up semantics rather than becoming a second security authority.

Role​

  • Unified Entrypoint: Provides a single host for all platform REST and WebSocket APIs.
  • Service Routing: Mounts each platform boundary (FinOps, KB, Graph, Controller, MLOps, RL, Federation, Admin, the monolith, ...) either in-process or as an HTTP/WS proxy, chosen per boundary via ALPHASWARM_GW_<BOUNDARY>_MODE.
  • Schema Discovery: Aggregates OpenAPI specs from all registered services into a central catalog.
  • No auth/authz of its own: per alphaswarm_api/AGENTS.md, the gateway "must be invisible to correctness" — it never authenticates, authorizes, reads tenant state, or touches a database. It only stamps a correlation id, emits one structured access line, and applies CORS; auth, tenancy, audit, and step-up all happen in the leaf router or the downstream service, exactly as if the gateway were not there.

Architecture​

The gateway is built on FastAPI and uses httpx (plus the websockets library for WS) for high-performance async proxying between in_process and http_proxy boundary modes. It does not integrate with tenant_router or perform IAM scope resolution itself — those stay downstream in the leaf services.

Operations​

  • Health: GET /livez, GET /readyz, and compatibility GET /healthz.
  • Metrics: GET /metrics exposes request, 5xx-error, and latency series with route-template labels.
  • Logs: structured access events include request correlation and emit 5xx responses at error level without logging credentials.
  • Release: canonical manifests live under alphaswarm_devops/deployments/services/alphaswarm-api and are selected by the platform alphaswarm-api ApplicationSet.

Repository​