# Architecture

What runs where, what each part may do, and which repository holds it.

## The picture

![Buun Identity, the account portal, the gateway, the staff console and the products](https://developers.buungroup.com/diagrams/buun-identity-and-the-products-around-it.svg "themed")

## The parts

| Part | Host | Repository | Runs on |
|---|---|---|---|
| Identity Worker, the issuer | `id.buungroup.com` | `buun-group/buungroup-app`, `apps/identity` | Cloudflare Workers and D1 |
| Account portal | `account.buungroup.com` | `buun-group/buungroup-app`, `apps/account` | A static page on Workers |
| Developer docs, this site | `developers.buungroup.com` | `buun-group/buungroup-app`, `apps/developers` | A static site on Workers |
| MCP gateway | `mcp.buungroup.com` | `buun-group/buungroup-gateway` | Cloudflare Workers and D1 |
| Staff console | `staff.buungroup.com` | `buun-group/buungroup-staff` | Cloudflare Workers and D1 |

Shared code is published privately on GitHub Packages under `@buun-group`: `core` (products, scopes, roles, the client schema), `crypto` (Web Crypto helpers) and `ui` (the design system). A product installs them at a pinned version.

## Who may do what

| Part | May | Never |
|---|---|---|
| Identity Worker | Sign tokens, keep accounts, sessions, grants and hashed secrets | Show a page: the portal does that |
| Account portal | Call the issuer with the person's session | Hold a token for a product |
| Gateway | Check an agent's token, trade it for a product's, call the product | Pass the agent's token on, or log one |
| Staff console | Read and change through the issuer's `/admin` and the gateway's `/admin`, naming the member of staff | Reach a customer session or cookie |
| A product | Check tokens with the published keys, ask for the person's plan | Accept a token whose `aud` is not its own |

## Why it is built this way

| Decision | Why |
|---|---|
| ES256 access tokens with one audience, 15 minutes | A product checks a token without calling the issuer, and a token for one service opens nothing else |
| PKCE S256 for every client | A stolen code is useless without the verifier |
| Plans read live from `/oauth/plans` | A cancelled plan stops at once |
| Token exchange at the gateway (RFC 8693) | A person on a plan reaches the product through the gateway without a second sign-in, and the agent's token stays with the gateway |
| Tools reviewed by staff before an agent sees them | A product's tool description is text an agent obeys; a change waits for review again |

Source: https://developers.buungroup.com/architecture
