Buun Group Developers
Pages

Architecture

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

Markdown

The picture

Buun Identity, the account portal, the gateway, the staff console and the productsBuun Identity, the account portal, the gateway, the staff console and the products

The parts

PartHostRepositoryRuns on
Identity Worker, the issuerid.buungroup.combuun-group/buungroup-app, apps/identityCloudflare Workers and D1
Account portalaccount.buungroup.combuun-group/buungroup-app, apps/accountA static page on Workers
Developer docs, this sitedevelopers.buungroup.combuun-group/buungroup-app, apps/developersA static site on Workers
MCP gatewaymcp.buungroup.combuun-group/buungroup-gatewayCloudflare Workers and D1
Staff consolestaff.buungroup.combuun-group/buungroup-staffCloudflare 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

PartMayNever
Identity WorkerSign tokens, keep accounts, sessions, grants and hashed secretsShow a page: the portal does that
Account portalCall the issuer with the person's sessionHold a token for a product
GatewayCheck an agent's token, trade it for a product's, call the productPass the agent's token on, or log one
Staff consoleRead and change through the issuer's /admin and the gateway's /admin, naming the member of staffReach a customer session or cookie
A productCheck tokens with the published keys, ask for the person's planAccept a token whose aud is not its own

Why it is built this way

DecisionWhy
ES256 access tokens with one audience, 15 minutesA product checks a token without calling the issuer, and a token for one service opens nothing else
PKCE S256 for every clientA stolen code is useless without the verifier
Plans read live from /oauth/plansA 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 themA product's tool description is text an agent obeys; a change waits for review again