Overview
The services, the front door and the shared stack that Chelabase runs on.
Chelabase is a control plane for Postgres databases, built on Neon's storage stack. Every database runs as a Neon compute backed by a shared pageserver, safekeeper and object store; the control plane creates, branches, resets and deletes them, and gives apps a typed data API in front of them.
This section describes how the parts fit together. For how to use them, start with the Introduction.
Repository layout
apps/studio the web app (the only user-facing app)
apps/docs this documentation site
services/ gateway, orchestrator, worker, rest, auth, realtime, identity, init
tools/cli the `chelabase` binary (dev bootstrap, token minting, type generation)
tools/bench-data-api the data API benchmark harness
crates/ shared Rust libraries
packages/ shared TypeScript packages (client, management-client, design, neon-e2e)
openapi/ the generated OpenAPI documents
infra/compose/ Docker Compose: metadata Postgres, NATS JetStream, Valkey, the identity service, Mailpit, Neon storage
infra/neon/ Neon image pins and build scriptsWorkflow (setup, worktrees, the live queue, tests, commits) is in CONTRIBUTING.md.
The Rust workspace holds the control plane; a pnpm workspace holds Studio, this site and the TypeScript packages. Tooling is proto, moon and just.
The services
| Service | Role | Page |
|---|---|---|
| Gateway | Pingora front door on :8000: authenticates every request and routes it | Gateway |
| Orchestrator | The Management API (/v1), the metadata store and the internal listener | Orchestrator and worker |
| Worker | Runs the jobs: provisions computes, resets, bootstraps the data API, reconciles | Orchestrator and worker |
| Rest | The data API engine: turns a JSON query into SQL and runs it | Data API |
| Auth | Sign-in backend for Studio and for app users; signs member and app-user tokens | Studio, App users |
| Identity | Holds every account (Studio members and each project's app users), internal only | Identity service |
| Realtime | Live rows and presence over a WebSocket | Realtime |
| Studio | The web app | Studio |
NATS JetStream carries the jobs, a metadata Postgres holds the control plane's own state, Valkey backs the proxy's cache invalidation and realtime's tickets, and Mailpit catches local email.
How a request travels
All API traffic enters through the gateway. It checks the credential (a member access token for the Management API, a data API key for the data API), then calls the owning service with a short-lived internal identity token. Services never see the client's own credential, and they trust only the gateway's token. Postgres connections do not go through the gateway: they reach each database through Neon's proxy.
client ──HTTP──▶ gateway ──identity token──▶ orchestrator | auth | rest | realtime
client ──Postgres wire / SQL over HTTP──▶ Neon proxy ──▶ compute ◀── pageserver, safekeepersThe docs app
This site is apps/docs in the same repository: Fumadocs on TanStack Start, prerendered to static files. The API reference pages are generated from the OpenAPI documents in openapi/ (see API generation), and TypeScript samples are type-checked at build time with twoslash. just workbench up --with docs serves it on the stack's docs host (http://docs.chelabase.localhost:8000 on main), reached through the gateway.