docs(okf): move bundle to repo root and retire brief

The brief is fully captured in the bundle; it stays in git history.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Noel SabiaandClaude Opus 5.5 committed 2026-10-11 14:22:03 +02:00
1 parent 957a386b58
commit 64fef83314
22 files changed
+37 -153

No files matched your search

+59
View File
@@ -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).