Files
OKF_CV_Website/knowledge/architecture/system.md
T

2.5 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.
architecture
k3s
go
nuxt
stable
by at
claude-code/claude-opus-5-5 2026-10-11T12:15:30Z

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

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. Cloudflare Tunnel 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 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 (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.