Architecture
What runs where, what each part may do, and which repository holds it.
The picture
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 |