2.7 KiB
2.7 KiB
type, title, description, tags, status, generated
| type | title | description | tags | status | generated | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Architecture | System architecture | All runtime components of the v1 site and how a request and a knockdown flow through them. |
|
stable |
|
Components
| Component | Runs as | Job |
|---|---|---|
| Cloudflare Tunnel | cloudflared on the home server |
Only way in from the internet. Points at the gateway. |
| Gateway | 1 Deployment, Go | Serves the static site, streams states, forwards knockdowns, counts visits into SQLite. The only public service. |
| Frontend | Static files inside the gateway image | Nuxt, built with nuxt generate. |
| Chapter service | One Deployment or Job per chapter | Behaves healthy, not-ready, crashing, or completed, set by env. |
| Delivery | Gitea Actions on the home server | Test, scan, build, push, deploy, version. |
Everything runs in one namespace: cv, capped at 384Mi memory in total, on a
2 vCPU, 4 GB server shared with Gitea. See server budget.
Images
Two images from one Go module:
cmd/gateway → image `gateway` (includes the Nuxt build)
cmd/chapter → image `chapter`
Flow: page load
- Visitor opens the apex domain. Cloudflare Tunnel forwards to the gateway Service.
- Gateway returns prerendered Nuxt HTML. The first screen works without JavaScript.
- The page opens
GET /api/events(SSE) and receives the current state of every chapter, then every change.
Flow: knockdown
- Visitor clicks "Push this chapter":
POST /api/fall/{chapter}. - Gateway checks the allowlist, the per-chapter cooldown, and the global rate limit.
- Gateway calls
http://chapter-{chapter}.cv.svc/fallover cluster DNS. - The chapter process exits. The kubelet restarts it,
restartCountgoes up. - Gateway sees the pod go not-ready, then ready again, and pushes both changes over SSE.
- Recovery time = Ready condition
lastTransitionTimeminus the fall time. - The page shows the story card with the measured seconds.
No step needs write access to the Kubernetes API.
Security boundaries
- Only the gateway is reachable from outside.
- Gateway ServiceAccount:
get/list/watchon pods, events and jobs incv. Nothing else. /fallis unauthenticated inside the cluster. A NetworkPolicy (supported natively by k3s) restricts it to the gateway.- No visitor-supplied input reaches the cluster except a chapter name checked against an allowlist.
Accepted risk
If the home server is down, the whole site is down. See accept downtime in v1.