Architecture

StackShip starts as four independently deployed Workers in one pnpm/Turborepo monorepo.

Request flow

The dashboard calls the API with credentialed cross-origin requests. Both origins are subdomains of the same site, so Better Auth can keep its default same-site cookie posture.

The API owns the Better Auth handler at /api/auth. OAuth login and consent routes redirect to dashboard screens while preserving Better Auth’s signed OAuth query. The MCP Worker publishes RFC 9728 protected-resource metadata, points clients to the API authorization server, and verifies JWT access tokens against the API’s JWKS.

Data plane

PlanetScale PostgreSQL is reached from the API through the Cloudflare Hyperdrive binding 397048f06dbc43c1a921c92258384a40. Drizzle owns application and Better Auth schema. Application traffic uses a least-privileged PlanetScale role; schema migrations use a separate direct administrative connection.

The identity Hyperdrive configuration has query caching disabled. Hyperdrive does not expose a supported per-query cache hint, and Better Auth owns its SQL, so sessions, permissions, organizations, and identity reads need the cache-disabled connection. When product reads can tolerate staleness, add a second cache-enabled Hyperdrive configuration and route only those reads through it.

R2 is the object plane for state-related artifacts, plans, run logs, and exports. Workers Analytics Engine is for high-cardinality operational events, while PostHog is reserved for product behavior and funnels.

Failure posture

Public health and version endpoints do not require the database. Authentication and protected product operations fail closed when Hyperdrive or required secrets are absent. The MCP endpoint never falls back to anonymous access.