Skip to content

0028. Dashboard as a static SPA on the API's origin

  • Status: Accepted
  • Date: 2026-11-08

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.

  • apps/dashboard is a React + Vite single-page application. It talks to the backend only through surfaces/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 all image 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 api actions (ADR 0019)
    /mcp API 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/ses API 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).

  • The dashboard cannot use an internal endpoint; anything it needs is an api action 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.