API Server Architecture

The API server is a Python FastAPI application located at server/. It exposes two HTTP surfaces: the OpenAI-compatible inference API (/v1/*) and the A2A JSON-RPC control plane (/a2a).

The server is the single point of contact between the webapp (and external API callers) and all backing infrastructure: the database, the provider integrations, the Actor executor, and the billing system.

Directory structure

server/
├── app/
│   ├── main.py              # FastAPI app setup, middleware, lifespan
│   ├── routers/
│   │   ├── v1/              # OpenAI-compatible routes
│   │   │   ├── chat.py      # POST /v1/chat/completions
│   │   │   └── models.py    # GET /v1/models
│   │   └── a2a/             # A2A control plane router
│   ├── services/
│   │   ├── inference.py     # Request routing to providers / actors
│   │   ├── actors.py        # Actor management (CRUD, deploy)
│   │   ├── billing.py       # Credit deduction, Stripe integration
│   │   └── usage.py         # Usage recording
│   ├── models/              # SQLAlchemy ORM models
│   ├── schemas/             # Pydantic request/response schemas
│   └── dependencies/        # FastAPI dependency injection (auth, DB)
├── alembic/                 # Database migrations
└── tests/                   # Server tests (pytest)

Request flow for inference

1. POST /v1/chat/completions hits the chat router.
2. Auth dependency validates the ct_live_ key and resolves the namespace.
3. Namespace is checked to confirm the requested model is deployed.
4. If the model is a provider model, the request is forwarded to the upstream provider via the inference service.
5. If the model is an Actor, the Actor YAML is retrieved and the cleveractors-core executor runs the graph.
6. The response is streamed back to the caller.
7. Token counts are recorded asynchronously to the usage store.
8. Credits are deducted from the wallet asynchronously.

Coming soon

Database schema diagram and a deeper walkthrough of the A2A router dispatch mechanism are being added.