Architecture¶

Brama is one Rust process (axum) serving one HTTP listener. Its entire job is to turn an authenticated, alias-shaped model request into one provider HTTP call, paying with a credential it held for exactly that call. An alias resolves to exactly one route; when that route refuses the call, the refusal is what the caller receives.

The managed launcher uses the host's shared Skarbiec service for capability redemption. It does not start a private broker or a broker reaper. Startup reports the responding broker's PID and checks its state paths, then replaces the launcher with the gateway through exec. Stopping Brama does not stop Skarbiec.

The architecture material is split across two pages, both linked below: one for the ownership split and the trust boundaries, one for the runtime path a request takes and the state the process keeps.

Pages¶

• Ownership and boundaries — what Brama owns (routing, the credential seam, its own records, the shape of the route registry), what it deliberately is not, the rule enforced at every trust boundary from transport to vault listing, the two admin calls that write the registry, and the neighbouring services: Skarbiec, Stado, Jeden, Brama Desktop and Wisent Identity.
• Request path and state — the one listener and its two route sets, the flow from transport guard through caller identity to a single provider call, what an undeclared or unserviceable alias answers, the evidence rule separating /health from /readyz, and every file Brama writes on disk.

Where to go next¶

• What is Brama for the product framing that sits above this page.
• concepts/alias for aliases, the route registry document and its three known top-level fields.
• HTTP API for the request and response bodies named here, including GET /v1/aliases and the admin route calls.
• brama routes migrate for moving an existing registry file to the current shape without editing it by hand.
• Runbook for the operator response to each /readyz verdict.