---
title: "Architecture"
description: "The initial production topology and service boundaries."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.stackship.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

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

| Workspace | Runtime | Domain |
| --- | --- | --- |
| `apps/web` | Next.js 16 through OpenNext | `stackship.run` |
| `apps/api` | Hono | `api.stackship.run` |
| `apps/mcp` | Hono and the MCP TypeScript SDK | `mcp.stackship.run` |
| `apps/docs` | Nimbus on Astro | `docs.stackship.run` |

## 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.

Source: https://docs.stackship.run/architecture/index.mdx