Concepts

Architecture

Web shell, API control plane, MCP server, deploy adapters, and where each runs.

Showly is a small set of services with hard, observable boundaries. This page is a tour of what each one does and how they connect.

Components

Web (apps/web) — Next.js App Router app. Renders the public marketing surface, /app workspace shell, /docs, and acts as the auth front end. Talks to the API via a server-side proxy so client components never see API tokens.

API (apps/api) — Fastify control plane. Owns the database, RBAC, audit log, pipeline orchestration, and tenant-aware reads/writes. Every mutation passes through this service.

MCP (apps/mcp) — MCP server exposing scoped tools (list_projects, list_sites, get_site_context, get_preview_status, get_deployment_logs, list_templates, create_change_plan, apply_site_patch, create_preview, run_checks, request_publish, create_site_from_template). Production publish and rollback are NOT MCP tools — they exist only in the web UI behind step-up MFA + approval. The MCP path to production is request_publish, which returns a webApprovalUrl deep link a human follows to approve and publish. Backed by the API; MCP itself is a thin authentication + tool-schema layer.

Status (apps/status) — Public status page service. Reads /status-page from the API and renders HTML.

Ops jobs (apps/ops-jobs) — Background workers: domain verification, preview cleanup, audit archive, dunning, restore drills, cost attribution.

Analytics ingest (apps/analytics-ingest) — Edge pixel + server-side ingest for the Showly Analytics package.

Forms gateway — Receives form submissions from deployed sites and forwards them to the API. Admin CLI — Operator tooling for support and maintenance tasks against the control plane. These are supporting utilities; production publish is owned by the web UI (behind step-up MFA + approval) and the API, not a separate gateway. See each app's README for details.

Trust boundaries

  ┌────────────────┐   browser
  │  apps/web      │◄──────────── user (cookie session)
  └──┬─────────────┘
     │  service token + bridged web session
     ▼
  ┌────────────────┐
  │  apps/api      │◄──── apps/mcp ◄──── agent (MCP token)
  └──┬─────────────┘
     │  Drizzle ORM
     ▼
  PostgreSQL  +  KMS-encrypted secrets

Three trust planes:

  1. Browser ↔ Web. Cookie session, server actions, server-side proxy. Web never trusts the browser for cross-tenant claims.
  2. Web ↔ API. Internal bearer token plus a _web session bridge_ secret so API can verify the cookie was issued by a trusted Web instance.
  3. Agent ↔ MCP ↔ API. Per-MCP-client token with explicit scopes. Every tool call audits with the client id and the action.

Data residency

The API treats the workspace (organization) as the residency boundary. Multi-region is a planned Iteration 7+ concern; today everything is in the primary region.

Deploy targets

Showly deploys _user_ sites (your application code) and _Showly itself_. Two adapter families:

  • cloud-run — primary target. Container build, Cloud Run revision, Cloud SQL connector if needed.
  • static-cdn — for SSG output. Uploads to Cloud Storage, fronts with a CDN.
  • (Roadmap) ecs-fargate, gke — see the Iteration 8 plan in the internal showly-platform repo (docs/showly-platform-iteration-plan.md).

Where to read next