docs(okf): write overview, architecture, decisions and roadmap
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
987a5efba1
commit
557ac1985b
20 files changed
+750
-16
No files matched your search
@@ -0,0 +1,59 @@
|
||||
---
|
||||
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, k3s, go, nuxt]
|
||||
status: stable
|
||||
generated: { by: claude-code/claude-opus-5-5, at: 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](/architecture/gateway.md) | 1 Deployment, Go | Serves the static site, streams states, forwards knockdowns. 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. |
|
||||
|
||||
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](/decisions/accept-downtime-v1.md).
|
||||
Reference in new issue
Block a user