--- type: Architecture title: System architecture description: All runtime components of the v1 site and how a request and a knockdown flow through them. tags: [architecture, kubernetes, go, nuxt] status: stable generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z } --- # Components | Component | Runs as | Job | |---|---|---| | Caddy (reverse proxy) | Terraform-installed, on the home server | Only way in from the internet. TLS automatic via ACME. Points at the gateway. | | [Gateway](/architecture/gateway.md) | 1 Deployment, Go | Serves the static site, streams states, forwards knockdowns, counts visits into SQLite. The only public service. | | [Frontend](/architecture/frontend.md) | Static files inside the gateway image | Nuxt, built with `nuxt generate`. | | [Chapter service](/architecture/chapter-service.md) | One Deployment or Job per chapter | Behaves healthy, not-ready, crashing, or completed, set by env. | | [Delivery](/architecture/delivery.md) | Gitea Actions on the home server | Test, scan, build, push, deploy, version. | | FreeLens | Noel's laptop | Admin UI for the cluster over an SSH tunnel. Not part of the public site. | Everything runs in one namespace: `cv`, capped at 384Mi memory in total, on a 2 vCPU, 4 GB server shared with Gitea. A machine with more RAM is planned before 0.3.0, because the kubeadm control plane costs more than k3s did. See [server budget](/architecture/server-budget.md). # Images Two images from one Go module: ``` cmd/gateway → image `gateway` (includes the Nuxt build) cmd/chapter → image `chapter` ``` # Flow: page load 1. Visitor opens the apex domain. DNS points at the home server. Caddy (automatic HTTPS) forwards to the gateway Service. 2. Gateway returns prerendered Nuxt HTML. The first screen works without JavaScript. 3. The page opens `GET /api/events` (SSE) and receives the current state of every chapter, then every change. # Flow: knockdown 1. Visitor clicks "Push this chapter": `POST /api/fall/{chapter}`. 2. Gateway checks the allowlist, the per-chapter cooldown, and the global rate limit. 3. Gateway calls `http://chapter-{chapter}.cv.svc/fall` over cluster DNS. 4. The chapter process exits. The kubelet restarts it, `restartCount` goes up. 5. Gateway sees the pod go not-ready, then ready again, and pushes both changes over SSE. 6. Recovery time = Ready condition `lastTransitionTime` minus the fall time. 7. The page shows the story card with the measured seconds. No visitor-facing step needs write access to the Kubernetes API. # Security boundaries - Only the gateway is reachable from outside. - Gateway ServiceAccount: `get/list/watch` on pods, events and jobs in `cv`. Nothing else. - `/fall` is unauthenticated inside the cluster. A NetworkPolicy (Calico) restricts it to the gateway. - No visitor-supplied input reaches the cluster except a chapter name checked against an allowlist. - Only Noel holds a kubeconfig. The API server listens on localhost; FreeLens reaches it through an SSH tunnel. See [FreeLens](/decisions/freelens-admin-ui.md). # Accepted risk If the home server is down, the whole site is down. See [accept downtime in v1](/decisions/accept-downtime-v1.md).