0028. Dashboard as a static SPA on the API's origin
- Status: Accepted
- Date: 2026-11-08
Context
Section titled “Context”The dashboard framework and hosting were open. The dashboard must use the same API as users and AI assistants (ADR 0005), add no fixed cost, and avoid CORS and cross-site cookies.
Decision
Section titled “Decision”-
apps/dashboardis a React + Vite single-page application. It talks to the backend only throughsurfaces/api-client, the client generated from OpenAPI (ADR 0018). -
On Cloudflare it is served as Workers static assets on the app domain. In containers it is served from S3 and CloudFront, or by the
allimage for small installations. -
Same-origin routing on the app domain:
Path Goes to Purpose /api/auth/*API Better Auth routes: sign-in, sessions, OAuth authorization (ADR 0025) /api/*API apiactions (ADR 0019)/mcpAPI MCP /.well-known/*API reserved for the API: OAuth discovery metadata for MCP (RFC 9728 protected resource, RFC 8414 authorization server) /in/*API endpoint: inbound webhooks/provider-events/sesAPI endpoint: SES event receiver/u/*API endpoint: unsubscribe (GET shows a page, POST unsubscribes, ADR 0024)everything else SPA dashboard -
Click redirects (
/c/*) are served by the tracker on the separate tracking domain, never on the app domain (ADR 0020).
Consequences
Section titled “Consequences”- The dashboard cannot use an internal endpoint; anything it needs is an
apiaction with parity.
Amendment (2026-11-18, ADR 0040): surfaces/api-client also has a hand-written auth module beside the generated client, for the /api/auth/* routes, which are not in OpenAPI. It names no Better Auth type, has no runtime dependencies like the rest of the package (api-client-no-npm), and the dashboard signs in only through it.
Amendment (2026-11-18, ADR 0033, ADR 0035): /approvals/* (the send approval pages and their view and decision endpoints) and /operator/* (the operator endpoints) also go to the API. The Worker’s list of the API’s paths is isApiPath in apps/workers/src/dashboard.ts, tested against every route the API mounts; every other path is the dashboard’s.