Architecture
Four Go services separate routing, business workflows, identity and money.
Tokamak runs four Go services, PostgreSQL and Redis, with separate customer and platform web apps. The documentation site uses Next.js and Fumadocs. The Rust CLI runs on the customer's machine and connects tools to the API.
Service ownership
| Service | API port | Responsibility |
|---|---|---|
| Gateway | 8080 | Public API ingress, identity/permission checks through auth, route policy and signed internal delegation. |
| Core | 8090 | Organizations, teams, model/provider routing, usage limits, usage records and settlement coordination. |
| Auth | 8092 | Identities, sessions, invitations, API keys, service credentials and the authoritative RBAC store. |
| Billing | 8093 | Organization wallets, reservations, grants, debt, append-only ledger, payments, receipts and recovery. |
The base Compose topology publishes the gateway while keeping core/auth/billing private. Customer/admin/docs and selected infrastructure have their own host ports. Development overrides can deliberately expose additional services. Metrics listeners are separate: core9091, gateway9092, auth9093 and billing9094.
Request lifecycle
- A client supplies an inference credential, model and supported dialect.
- The gateway asks auth to resolve identity and authorize the route, then delegates the request to its owning service using signed claims.
- Core resolves the model/provider, checks traffic limits (concurrency and request/token rates per scope, and any upstream-429 cooldown), evaluates applicable budgets and coordinates credit admission when billing is authoritative for the payer.
- Core forwards the provider-native request. It substitutes the upstream model ID and requests usage inclusion for streaming Chat Completions; it does not implement a client tool loop.
- Usage is recorded and reservations are finalized through the budget and billing systems. Settlement is idempotent; usage cost and actual wallet effects remain separate facts.
Gateway routes have explicit service ownership; billing requests do not fall through to core by default. Core uses separate authenticated internal billing operations for admission, settlement and organization lifecycle.
Organization and credential context
A browser's active organization controls customer management pages. An existing API key's immutable organization/payer binding controls its billing attribution. Switching the browser cannot move that binding. Optional personal default-team attribution also stays fixed and is checked against live authority.
An organization can contain several teams, nested up to five levels deep; a key still attributes to exactly one team. Team budgets can share usage capacity, but a team does not own an independent prepaid wallet. Personal organizations use the same ledger model as shared organizations.
Authorization boundary
Auth owns RBAC for platform, organization and team scopes. Platform standing does not grant tenant-internal authority. Core and gateway consume verified authorization rather than maintaining competing role stores. Membership changes propagate to auth through an outbox, so cross-service visibility can be asynchronous.
The fixed roles are owner, admin and member, plus organization-only billing_admin. Custom-role creation is disabled. Reading a roster, managing membership, inspecting usage and moving money are distinct permissions.
Deployment dependencies
- Provider credentials and a published compatible model are needed for inference.
- Production login, gateway delegation keys and service credentials require operator configuration.
- Invitation email requires SMTP settings and the correct customer-app origin.
- Card purchases require configured payment credentials, webhooks, fees and organization activation.
- Usage retention, logs, media storage and request-data handling depend on deployment policy.
See Configuration, Upgrading, Organizations and Access control.