Architecture overview

Status: scaffold, 2026-10-10. This page describes the shape the four repositories are set up for. Details are decided in the ADRs; what is still open is in Open items.

System context

flowchart LR
  student[Student PC]
  teacher[Teacher / admin]
  public[Visitors]

  subgraph cf[Cloudflare]
    dns[DNS + WAF]
    tunnel[Tunnel]
  end

  subgraph vercel[Vercel]
    landing[ceooflittlepeople.com]
    docs[docs.coipe.app]
    web[coipe.app and org.coipe.app]
  end

  subgraph home[Home cluster k3s]
    api[apps/api]
    db[(PostgreSQL)]
    obj[(Garage S3)]
  end

  public --> dns --> landing
  student --> dns --> web
  teacher --> dns --> web
  web -- /api --> tunnel --> api
  api --> db
  api --> obj

FIGDiagram · source controlled

Repositories

Repository	Contents	Deploys to
`fuisl/coipe`	`apps/web` (Next.js), `apps/api` (Fastify), `packages/contract`, `packages/design-tokens`, `packages/ui`	Vercel (web), GHCR image → home cluster (api)
`fuisl/ceo-of-little-people`	Company landing page	Vercel
`fuisl/coipe-infra`	Flux, Kustomize and SOPS for the home cluster, plus edge configuration	The home cluster via Flux
`fuisl/coipe-docs`	This handbook and its site, ADRs, design source	Vercel

See ADR-001.

Hostnames

Host	Serves
`ceooflittlepeople.com`	Company landing page
`coipe.app`	The app for individuals and families
`{org}.coipe.app`	The app for a school, with its branding
`{any app host}/api/*`	The API, same-origin (ADR-006)
`admin.coipe.app`	Builder admin (later), behind Cloudflare Access
`docs.coipe.app`	This handbook
`staging.coipe.app`, `{org}--staging.coipe.app`	Staging, one level deep

Reserved slugs that no organization may take: www, api, admin, assets, staging, auth, docs, status, mail, help, and anything containing --.

Runtime shape

Web: Next.js App Router. Resolves the organization from the Host header.
API: one Fastify process, a modular monolith (ADR-002). A worker for background jobs runs from the same image when it's needed.
Data: PostgreSQL 17 under CloudNativePG; every tenant-owned row carries org_id (ADR-005). Object storage on Garage.
Cluster: k3s on two always-on home nodes with UPS, reached only through Cloudflare Tunnel (ADR-003), managed by Flux (ADR-004).

Phases

Phase	Scope
0 · Pilot launch (2026-10-19)	Node A only. Web, API, PostgreSQL with nightly backups off the node, Cloudflare Tunnel, landing and docs on Vercel
1 · During the pilot	Node B joins: database replica, Garage with two copies, a second tunnel connector, staging, uptime monitoring and error tracking
2 · After funding	GitHub organization, managed PostgreSQL, payments and e-invoices, SSO, tablet apps