docs(okf): write overview, architecture, decisions and roadmap

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:18:32 +02:00
1 parent 987a5efba1
commit 557ac1985b
20 files changed
+750 -16

No files matched your search

+45
View File
@@ -0,0 +1,45 @@
---
type: Service
title: Chapter service
description: One small Go binary whose health behavior is set by the MODE env var; every life chapter runs it.
tags: [architecture, go, k3s]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
# Behavior
| `MODE` | Runs as | `/healthz` (liveness) | `/ready` (readiness) | Resulting state |
|---|---|---|---|---|
| `healthy` | Deployment | 200 | 200 | Running, Ready |
| `not-ready` | Deployment | 200 | 503 | Running, NotReady |
| `crash` | Deployment | n/a | n/a | Exits on start: CrashLoopBackOff |
| `complete` | Job | n/a | n/a | Prints a line, exits 0: Completed |
`CHAPTER` env var names the chapter. Used in logs only.
# Endpoints
- `GET /healthz` - liveness.
- `GET /ready` - readiness, depends on `MODE`.
- `POST /fall` - responds 202, then `os.Exit(1)`. The kubelet restarts the container and increments `restartCount`.
# Kubernetes details
- Each chapter gets a Deployment (1 replica) and a Service `chapter-{name}`.
- Services set `publishNotReadyAddresses: true`, otherwise a NotReady chapter
has no endpoints and the gateway cannot push it.
- Label every pod `cv.noelsabia.dev/chapter: {name}`. The gateway uses it to map pods to chapters.
- Tight resource limits on every chapter (for example 10m CPU, 16Mi memory).
Crashing chapters back off on Kubernetes' default schedule, which caps at 5 minutes.
- Completed Jobs keep no `ttlSecondsAfterFinished`, so they stay visible as Completed.
- A CrashLoopBackOff chapter cannot be pushed; it is already down. The UI shows its lesson card instead.
# Manifests
Plain YAML, one file per chapter, applied with `kubectl apply -k` (kustomize is
built into kubectl). Copy-paste per chapter is fine at this size.
# Size
About 50 lines of Go, standard library only.
+37
View File
@@ -0,0 +1,37 @@
---
type: Pipeline
title: Delivery
description: Gitea Actions on the home server scan, build, push to the Gitea registry, deploy with kubectl, and version with release-please.
tags: [architecture, ci, gitea, release-please]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
# Pipeline
```
push to main ─► Gitea Actions (runner on the home server)
├─ go test ./...
├─ snyk test
├─ build images: gateway (with Nuxt), chapter
├─ push to the Gitea container registry
└─ kubectl apply -k deploy/
─► release-please (Gitea variant) opens a release PR; merging it tags the version
```
# Details
- **Commits:** Conventional Commits. `feat:` bumps minor, `fix:` bumps patch,
`docs:` and `chore:` do not release.
- **Image tags:** the git SHA, so every deploy is traceable.
- **Registry pull:** k3s needs an `imagePullSecret` for the Gitea registry,
or `/etc/rancher/k3s/registries.yaml` if the registry is plain HTTP.
- **Runner permissions:** a kubeconfig for a ServiceAccount that can only
manage resources in `cv`.
- **Jobs are immutable:** changing a completed chapter's Job spec needs a
delete before apply. Rare, since finished chapters do not change.
- **Snyk:** needs a `SNYK_TOKEN` secret in Gitea.
# Later
- k6 as a release gate needs a staging target. See [open questions](/decisions/open-questions.md).
+48
View File
@@ -0,0 +1,48 @@
---
type: Frontend
title: Frontend
description: Nuxt site generated to static files and served by the gateway, with three audience layers fed by one SSE stream.
tags: [architecture, nuxt, design]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
# Build
`nuxt generate` produces static, prerendered files. A multi-stage Docker build
runs it in a Node stage and copies the output into the gateway's Go stage for
`go:embed`. No Node process runs in the cluster.
# Layers
| Layer | Audience | Content | Needs live cluster |
|---|---|---|---|
| 0: First screen | HR | Name, role, contact, PDF CV download | No |
| 1: Life map | Non-technical | Chapters in plain words, "Push this chapter", story cards | Yes, degrades to static |
| 2: Dev view | Developers | Raw SSE events in a `<pre>` | Yes |
# Content
Chapter text (title, dates, story, setback, recovery, lesson) lives in the
Nuxt repo as one data file. The key is the chapter name, the same value as the
pod label `cv.noelsabia.dev/chapter`. The gateway knows nothing about stories.
# Behavior without the live stream
If `/api/events` fails, the life map renders from the data file with a small
"live cluster offline" note. No error page.
# Plain-word states
| State | Shown as |
|---|---|
| Completed | finished |
| Running, Ready | active |
| Running, NotReady | unfinished |
| CrashLoopBackOff | failed, lesson learned |
| Restarting after a push | recovering |
# Design
Terminal feel, navy `#1A3D64` and white, logo with a "broken pieces" look.
Drafted with Stitch prompts.
+48
View File
@@ -0,0 +1,48 @@
---
type: Service
title: Gateway
description: The only public service; serves the static site, streams chapter states over SSE, and forwards rate-limited knockdowns.
tags: [architecture, go, security]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
# Routes
| Route | Does |
|---|---|
| `GET /` and static paths | Serves the Nuxt build, embedded with `go:embed` |
| `GET /api/events` | SSE stream: full state on connect, then each change |
| `POST /api/fall/{chapter}` | Allowlist, cooldown, rate limit, then calls the chapter's `/fall` |
# Reading cluster state
- v1 polls `list pods` and `list events` in `cv` every 2 seconds and diffs the result.
At about 10 pods this is cheap. Upgrade path: a client-go informer.
- Recovery times come from the pod's Ready condition `lastTransitionTime`,
so they are exact even though polling is not.
- Dependency: `k8s.io/client-go`. It authenticates through the in-cluster ServiceAccount.
# SSE event shape
```json
{"chapter": "example", "phase": "Running", "ready": true, "restarts": 3, "event": "recovered", "seconds": 4.2}
```
The same stream feeds the life map and the developer view.
# Limits
- **Per-chapter cooldown:** a `map[string]time.Time` behind a mutex. Default 30 seconds.
- **Global limit:** `golang.org/x/time/rate`, for example 1 fall per second with burst 3.
- Knockdowns are shared state on purpose: every viewer sees "someone just knocked down X".
# Cloudflare Tunnel and SSE
- Send `Content-Type: text/event-stream` and flush after every message.
- Send a comment line (`: ping`) every 30 seconds so idle connections are not closed.
# RBAC
ServiceAccount `gateway` in `cv`, Role with `get/list/watch` on `pods`,
`events` and `jobs`. No create, delete or patch.
+8
View File
@@ -0,0 +1,8 @@
# Architecture
* [System](system.md) - All runtime components of the v1 site and how a request and a knockdown flow through them.
* [Chapter service](chapter-service.md) - One small Go binary whose health behavior is set by the MODE env var; every life chapter runs it.
* [Gateway](gateway.md) - The only public service; serves the static site, streams chapter states over SSE, and forwards rate-limited knockdowns.
* [Frontend](frontend.md) - Nuxt site generated to static files and served by the gateway, with three audience layers fed by one SSE stream.
* [Delivery](delivery.md) - Gitea Actions on the home server scan, build, push to the Gitea registry, deploy with kubectl, and version with release-please.
* [In-browser language model](language-model.md) - A tiny language model trained by Noel that runs entirely in the visitor's browser and shows its internals live.
+40
View File
@@ -0,0 +1,40 @@
---
type: Project
title: In-browser language model
description: A tiny language model trained by Noel that runs entirely in the visitor's browser and shows its internals live.
tags: [architecture, ml, typescript, learning]
status: draft
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
# Goal
A from-scratch learning project on the same domain: a small transformer whose
attention patterns, next-token probabilities and temperature are visible and
adjustable in the browser.
# Architecture
No backend. A `/lm` page in the Nuxt build plus a weights file, both served
statically by the [gateway](/architecture/gateway.md). It adds nothing to the cluster.
# Plan
| Step | What | Guide |
|---|---|---|
| Base model | About 5M parameters, layers written by hand, trained with PyTorch on TinyStories with word-piece tokens | Karpathy "Zero to Hero", llama2.c |
| Browser inference | Forward pass in plain TypeScript | llama2.c |
| Visuals | Attention heatmaps, next-token probabilities, temperature slider | |
| Chat | Fine-tune at 15-30M parameters on simple dialogues in a fixed user/bot format | |
| Own engine | Replace PyTorch gradients with Noel's own autograd | micrograd |
# Expectations
- TinyStories gives coherent short stories. Grimm gives stylish nonsense.
- The chat handles greetings and small talk, not knowledge questions or long conversations.
# Constraints
- **Download size:** 5M parameters in fp32 is about 20 MB, 30M is about 120 MB.
Ship int8 weights (about 4× smaller) and load them lazily.
- **PyTorch is new tooling** and needs Noel's approval under the stack rule.
+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).