Platform

What it is#

The platform is three HTTP services and a web console, kept as workspaces of one Bun repository: one install, one lockfile, one CI run and one release line. A command line client, the CLI (platformctl), ships from the same repository. Each service's spec is normative. When a platform page and a spec disagree, the spec wins.

The CLI is a client of the same contracts, run from an operator's or developer's machine. The two of them read those contracts in one place, the client workspace (packages/client), and each of them keeps the way it shows an answer and the way it speaks to a service.

How the processes talk#

browser ──▶ Console ──▶ Gateway ──▶ Data ──▶ PostgreSQL
                │           │            │
                │           │            └──▶ Access (access context)
                │           └───────────────▶ Access (login and decisions)
                └──────────────────────────▶ Access (login and administration)

The four processes are separate deployments that talk only over HTTP. No workspace imports another's source.

• The gateway fails closed: when Access gives no answer, the request is refused.
• Data verifies the gateway's signature, then asks Access for the caller's access context.
• The browser reaches the console on its own address. The console signs the caller in against Access directly and reads workspace data through the gateway.
• The gateway may be the only public service of a deployment: it serves the names of the deployment, and the request of a browser to the console or to the issuer of the tokens is a request to the gateway (front door).

A request, end to end#

Follow one browser request for /ws/{workspaceId}/v1/me, the request the quickstart sends:

1. The gateway matches the request to a route. The caller has no session yet, so the gateway redirects the browser to Access to log in.
2. Access sends the browser on to the tenant's identity provider. After the provider signs the caller in, Access maps the external identity to a principal and issues its own token to the gateway, which keeps a server-side session.
3. The gateway asks Access for a decision: may this principal use this workspace on this route? Anything but an explicit answer is treated as an outage, never a pass.
4. The gateway forwards the request to Data with signed x-gateway-* identity headers.
5. Data verifies the signature with the gateway's public key from its bindings, asks Access for the principal's access context, and answers with the principal, tenant and workspace as JSON.

The atlas draws the whole platform on one page and walks several requests across it.

Services at a glance#

Find your way#