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:
1 parent
957a386b58
commit
64fef83314
22 files changed
+37
-153
No files matched your search
@@ -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.
|
||||
@@ -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).
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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