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).
+7
View File
@@ -0,0 +1,7 @@
# Chapters
* [Chapter states](state-mapping.md) - How each Kubernetes primitive and state maps to a meaning in Noel's life story.
# Chapter list
Not written yet. One concept per chapter: dates, state, story, setback, recovery or lesson.
+30
View File
@@ -0,0 +1,30 @@
---
type: Reference
title: Chapter states
description: How each Kubernetes primitive and state maps to a meaning in Noel's life story.
tags: [chapters, k3s, narrative]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
# Mapping
| Kubernetes | Meaning | Example | Release |
|---|---|---|---|
| Job, Completed | Finished chapter | School, 42 piscine | v1 |
| Deployment, Running and Ready | Active, stable chapter | PreZero, Example | v1 |
| Running, NotReady | Exists, unfinished | Ongoing studies, thesis | v1 |
| CrashLoopBackOff | Failed and stayed failed | Abandoned projects | v1 |
| `restartCount` | Setbacks survived | "fell 3×, stood up 3×" | v1 |
| Replicas, HPA scale-up | Load carried, growth under pressure | Team lead, two businesses | Phase 3 |
| Rolling update | Pivot or reinvention | Career switch | Not planned yet |
Finished chapters are Jobs because they complete. Current chapters are
Deployments because they must stay alive.
# Narrative rules
- Every fall shows a story card: what went wrong and what got Noel back up.
- The recovery time shown is real, measured in seconds.
- Permanently failed chapters show a lesson card, not a recovery.
- Failures are labeled as lessons, never as bugs.
+25
View File
@@ -0,0 +1,25 @@
---
type: Decision
title: Accept home-server downtime in v1
description: v1 serves everything from the home server; if it is down, the whole site is down.
tags: [decision, availability]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
verified: { by: human:noel, at: 2026-10-11T12:15:30Z }
---
# Decision
Accept the risk. No off-box hosting, no snapshot persistence in v1.
# Why
- Off-box hosting (Cloudflare Pages, GitHub Pages) is new tooling and needs approval.
- A snapshot fallback only helps when the server is up but the gateway is not,
which the static Nuxt data file already covers.
- If the server is down, visitors see Cloudflare's error page. HR may hit it.
# Revisit when
The CV is actively sent to employers, or downtime is noticed in practice.
The fix is hosting the static first screen off-box.
@@ -0,0 +1,18 @@
---
type: Decision
title: Knowledge bundle lives in knowledge/
description: The OKF bundle sits in a subdirectory, not at the repository root.
tags: [decision, okf]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
# Decision
The OKF v0.2 bundle lives in `knowledge/`.
# Why
OKF requires frontmatter in every non-reserved `.md` file in the bundle. The
repo root will hold files like `README.md` and release-please's `CHANGELOG.md`
that have none, which would make a root-level bundle non-conformant.
+24
View File
@@ -0,0 +1,24 @@
---
type: Decision
title: CI/CD on Gitea Actions
description: The existing Gitea instance and runner on the home server build, scan, deploy and version the project.
tags: [decision, ci, gitea, release-please]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
verified: { by: human:noel, at: 2026-10-11T12:15:30Z }
---
# Decision
Use Gitea Actions with the runner already on the home server, the Gitea
container registry, and the Gitea variant of the release-please action.
# Why
- GitHub Actions cannot reach the k3s API behind the tunnel. The local runner can.
- No new tooling: Gitea, its runner and its registry already exist.
- No GitOps agent (Flux, Argo) needed.
# Details
See [delivery](/architecture/delivery.md).
+11
View File
@@ -0,0 +1,11 @@
# Decisions
* [v1 scope](v1-scope.md) - What the first public version keeps and what moves to later phases.
* [Accept home-server downtime in v1](accept-downtime-v1.md) - v1 serves everything from the home server; if it is down, the whole site is down.
* [Static Nuxt served by the gateway](static-nuxt-in-gateway.md) - Nuxt is generated to static files and embedded in the gateway image instead of running as its own pod.
* [CI/CD on Gitea Actions](ci-on-gitea.md) - The existing Gitea instance and runner on the home server build, scan, deploy and version the project.
* [Knowledge bundle lives in knowledge/](bundle-in-subdirectory.md) - The OKF bundle sits in a subdirectory, not at the repository root.
# Open
* [Open questions](open-questions.md) - Decisions still to make, with the release that needs each answer.
+19
View File
@@ -0,0 +1,19 @@
---
type: Open Questions
title: Open questions
description: Decisions still to make, with the release that needs each answer.
tags: [decision, open]
status: draft
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
| Question | Needed by | Default if nobody decides |
|---|---|---|
| Final chapter list and the state of each chapter | 0.2.0 (placeholders), 1.0.0 (final) | Three placeholder chapters: one completed, one active, one failed |
| Story card text per chapter | 1.0.0 | None, Noel writes it |
| Life map visual form: timeline, graph or map | 0.7.0 | Vertical timeline |
| Which Gitea release-please action, exact name | 0.1.0 | None, Noel names it |
| Staging for k6 in CI: namespace or separate cluster | 1.2.0 | Namespace `cv-staging` on the same cluster |
| MCP scope: read-only or read plus `/fall` | 1.1.0 | Read plus `/fall`, same limits as visitors |
| Approve PyTorch for the language model | 1.5.0 | None, needs Noel |
| Approve NumPy (or similar) for the own autograd engine | 1.13.0 | None, needs Noel |
@@ -0,0 +1,26 @@
---
type: Decision
title: Static Nuxt served by the gateway
description: Nuxt is generated to static files and embedded in the gateway image instead of running as its own pod.
tags: [decision, nuxt, go]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
# Decision
Build with `nuxt generate`, embed the output in the gateway with `go:embed`.
# Why
- One less Deployment, no Node runtime in the cluster.
- One public service, same origin for the site and `/api`, so no CORS.
- The life map can still render from its data file when the live stream fails.
# Cost
Frontend and gateway release together in one image.
# Revisit when
The site needs server-side rendering per request.
+32
View File
@@ -0,0 +1,32 @@
---
type: Decision
title: v1 scope
description: What the first public version keeps and what moves to later phases.
tags: [decision, scope, roadmap]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
# Keep in v1
- First screen: name, role, contact, PDF CV. Never gated behind interaction.
- Life map with plain-word states and a "Push this chapter" button.
- Story cards with real recovery seconds, lesson cards for failed chapters.
- Live states: Completed, Ready, NotReady, CrashLoopBackOff, restart counts.
- Gateway: SSE plus `/fall` with per-chapter cooldown and global rate limit.
- "Someone just knocked down X" messages. Free, the SSE stream carries them.
- Dev view: the raw event stream in a `<pre>`. Also free.
- CI: Snyk, build, deploy, release-please.
# Cut from v1
| Cut | Why | Where it went |
|---|---|---|
| Separate Nuxt pod | Static build served by the gateway is simpler | [Decision](/decisions/static-nuxt-in-gateway.md) |
| Snapshot persistence, offline banner | Downtime accepted for v1 | [Decision](/decisions/accept-downtime-v1.md) |
| MCP endpoint | Cheap to add later, reuses `/fall` | Phase 2 |
| k6 as a CI gate | Needs a staging target first | Phase 2 |
| Full kubectl-style terminal (YAML, probes) | The raw stream covers it | Phase 2 |
| Interactive k6, HPA demo, latency graph | Most work and most abuse risk | Phase 3 |
| Rolling update as "pivot" | Nothing triggers it yet | Not planned |
| client-go informer | Polling every 2 seconds is enough at about 10 pods | When polling falls short |
+8 -16
View File
@@ -2,22 +2,14 @@
okf_version: "0.2" okf_version: "0.2"
--- ---
# Project # Start here
* [Overview](overview.md) - Interactive CV on k3s: falling down and standing up again, shown live. * [Overview](overview.md) - A CV whose life chapters run as real Kubernetes workloads that visitors can knock down and watch recover.
* [Roadmap](roadmap.md) - What ships in v1, v2 and v3, including the in-browser language model. * [Roadmap](roadmap.md) - Small releases in three phases, each a few days of work at most, each ending in something that runs.
* [Update log](log.md) - History of changes to this bundle.
# Architecture # Drill down
* [System](architecture/system.md) - Cloudflare Tunnel, Go gateway serving the static Nuxt build, chapter services in namespace `cv`. * [Architecture](architecture/) - Components, services, frontend, delivery, and the in-browser language model.
* [Chapter service](architecture/chapter-service.md) - One Go image, health behavior set by `MODE`, knockdown via `/fall`. * [Decisions](decisions/) - What we chose, what we cut, and what is still open.
* [Gateway](architecture/gateway.md) - Only public API: SSE pod states and rate-limited `/fall`. * [Chapters](chapters/) - How Kubernetes states map to life chapters, and later one concept per chapter.
* [Delivery](architecture/delivery.md) - Gitea Actions: Snyk, build, Gitea registry, `kubectl apply -k`, release-please.
# Decisions
* [Decisions](decisions/) - Accepted trade-offs, such as v1 accepting home-server downtime.
# Chapters
* [Chapters](chapters/) - One concept per life chapter and its Kubernetes state.
+5
View File
@@ -0,0 +1,5 @@
# Update Log
## 2026-10-11
* **Creation**: Wrote the [overview](/overview.md), [architecture](/architecture/), [decisions](/decisions/), [chapter states](/chapters/state-mapping.md) and [roadmap](/roadmap.md) from the planning conversation.
* **Initialization**: Created the bundle [index](/index.md).
+63
View File
@@ -0,0 +1,63 @@
---
type: Overview
title: Interactive CV on k3s
description: A CV whose life chapters run as real Kubernetes workloads that visitors can knock down and watch recover.
tags: [overview, cv, k3s]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
# In one sentence
Noel's CV on the apex domain, where every life chapter is a workload on a
home k3s cluster: visitors push a chapter over and watch it stand up again.
The theme is **falling down and standing up again**.
# Two audiences, one page
| Audience | What they get |
|---|---|
| HR, 10 seconds | Name, role, contact, PDF CV. No interaction needed. |
| Non-technical visitor | A life map of chapters in plain words, a "Push this chapter" button, and a story card after every fall. |
| Developer | The raw live event stream from the cluster: pod states, restarts, recovery times. |
# The idea in pictures
| Kubernetes state | Life meaning |
|---|---|
| Job, Completed | Finished chapter (school, 42 piscine) |
| Deployment, Running and Ready | Active chapter |
| Running, NotReady | Exists but unfinished (studies, thesis) |
| CrashLoopBackOff | An attempt that failed and stayed failed, shown as a lesson |
| restartCount | Setbacks survived |
Full mapping: [chapter states](/chapters/state-mapping.md).
# How it works, high level
```
Visitor ─► Cloudflare Tunnel ─► Go gateway ─┬─ serves the Nuxt site (static files)
├─ streams live chapter states (SSE)
└─ forwards "push" to a chapter's /fall
│
chapter services in namespace `cv`
(one Go image, behavior set by env)
```
When a chapter is pushed, its process exits, Kubernetes restarts it, and the
page shows the real recovery time next to the story of how Noel recovered.
# Drill down
* [System architecture](/architecture/system.md) - every component and how they connect.
* [Roadmap](/roadmap.md) - small releases, each a few days of work.
* [Decisions](/decisions/) - what we chose and what we cut.
* [Open questions](/decisions/open-questions.md) - what is still undecided.
# Ground rules
- **Learning project, ship small.** Each release is a few days of work.
- **No tooling beyond the stack without Noel's approval.** The stack is Nuxt,
Go, k3s, Snyk, Gitea Actions, release-please, Cloudflare Tunnel, and k6.
- **Nobody gets Kubernetes API access.** Visitors and agents only talk to the gateway.
- **Failures are lessons, never bugs.**
+197
View File
@@ -0,0 +1,197 @@
---
type: Roadmap
title: Roadmap
description: Small releases in three phases, each a few days of work at most, each ending in something that runs.
tags: [roadmap, planning]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
# Overview
| Phase | Releases | Outcome |
|---|---|---|
| 1: Ship the CV | 0.1.0 - 1.0.0 | Public interactive CV on the apex domain |
| 2: Depth | 1.1.0 - 1.7.0 | MCP, k6 release gate, full dev terminal, in-browser language model |
| 3: Pressure and from scratch | 1.8.0 - 1.13.0 | Interactive load test with HPA, chat model, own autograd engine |
| Release | Name | Days |
|---|---|---|
| 0.1.0 | Chapter service | 1-2 |
| 0.2.0 | Chapters on k3s | 1-2 |
| 0.3.0 | Pipeline | 2 |
| 0.4.0 | Live states | 2-3 |
| 0.5.0 | Knockdown | 1-2 |
| 0.6.0 | First screen | 2 |
| 0.7.0 | Life map | 3 |
| 0.8.0 | Story cards and dev view | 2 |
| 1.0.0 | Real content, launch | 2-3 |
| 1.1.0 | MCP endpoint | 1 |
| 1.2.0 | k6 release gate | 2 |
| 1.3.0 | Dev terminal | 2 |
| 1.4.0 | LM: data and tokenizer | 2-3 |
| 1.5.0 | LM: model and training | 3 |
| 1.6.0 | LM: browser inference | 3 |
| 1.7.0 | LM: visuals | 2-3 |
| 1.8.0 | Interactive k6 | 3 |
| 1.9.0 | HPA demo | 2-3 |
| 1.10.0 | LM: bigger base model | 2-3 |
| 1.11.0 | LM: chat fine-tune | 3 |
| 1.12.0 | Own autograd engine | 3 |
| 1.13.0 | Train with own engine | 2-3 |
Each release is cut by release-please from `feat:` commits. A release is done
when its "done when" check passes on the real cluster, not locally.
---
# Phase 1: Ship the CV
## 0.1.0 Chapter service
- Go module with `cmd/chapter`: `/healthz`, `/ready`, `/fall`, behavior from `MODE`. See [chapter service](/architecture/chapter-service.md).
- Dockerfile, distroless or scratch base.
- One `go test` that checks `/ready` per `MODE`.
- release-please config, manifest and Gitea workflow, so this release is the first one it cuts.
- **Done when:** `docker run -e MODE=not-ready` answers 503 on `/ready`, and `POST /fall` ends the container with exit code 1.
- **Learn:** Go `net/http`, container basics, Conventional Commits.
## 0.2.0 Chapters on k3s
- Namespace `cv`, four placeholder chapters: one Job (`complete`), one each of `healthy`, `not-ready`, `crash`.
- Services with `publishNotReadyAddresses: true`, resource limits, pod label `cv.noelsabia.dev/chapter`.
- Registry pull from Gitea, `kubectl apply -k deploy/`.
- **Done when:** `kubectl get pods -n cv` shows Completed, Running 1/1, Running 0/1 and CrashLoopBackOff, and a `/fall` from a debug pod raises `restartCount`.
- **Learn:** Deployments, Jobs, probes, Services, kustomize.
## 0.3.0 Pipeline
- Gitea workflow: `go test`, `snyk test`, build and push images tagged with the git SHA, `kubectl apply -k`.
- Runner kubeconfig limited to namespace `cv`.
- **Done when:** a push to `main` deploys a new image without touching the server by hand.
- **Learn:** Gitea Actions, RBAC for CI, Snyk.
## 0.4.0 Live states
- `cmd/gateway`: polls pods and events every 2 seconds, streams changes on `GET /api/events` with a 30-second ping.
- ServiceAccount with read-only Role. Cloudflare Tunnel route to the gateway.
- A bare HTML page that prints the stream.
- **Done when:** the public URL shows a chapter going not-ready and back after `kubectl delete pod`.
- **Learn:** client-go, in-cluster auth, SSE, Cloudflare Tunnel.
## 0.5.0 Knockdown
- `POST /api/fall/{chapter}`: allowlist, 30-second per-chapter cooldown, global `rate.Limiter`.
- Recovery time from the Ready condition's `lastTransitionTime`.
- "fell" and "recovered" events with seconds in the stream.
- NetworkPolicy: only the gateway can reach chapter `/fall`.
- One test for the cooldown and limiter logic.
- **Done when:** a POST knocks a chapter over, a second POST within 30 seconds gets 429, and the stream shows the recovery seconds.
- **Learn:** rate limiting, NetworkPolicy, measuring with Kubernetes conditions.
## 0.6.0 First screen
- Nuxt project, `nuxt generate`, multi-stage Dockerfile that embeds the output in the gateway.
- Layer 0: name, role, contact, PDF CV download. Navy `#1A3D64` and white.
- **Done when:** the page loads and the PDF downloads with JavaScript disabled.
- **Learn:** Nuxt static generation, `go:embed`, multi-stage builds.
## 0.7.0 Life map
- Chapter data file in Nuxt keyed by chapter name.
- Life map (default: vertical timeline) with plain-word states from the stream and a "Push this chapter" button.
- Falls back to the data file with a "live cluster offline" note when the stream fails.
- **Done when:** a non-technical person can push a chapter and say what happened.
- **Learn:** Nuxt components, `EventSource`, degrading gracefully.
## 0.8.0 Story cards and dev view
- Story card on every fall with the measured seconds. Lesson card for CrashLoopBackOff chapters.
- "Someone just knocked down X" message when another visitor pushes.
- Dev view: the raw stream in a `<pre>`.
- **Done when:** two browsers see each other's knockdowns live.
## 1.0.0 Real content and launch
- Final chapter list, one manifest per chapter, story text, final PDF CV.
- Point the apex domain at the tunnel.
- One `knowledge/chapters/<name>.md` concept per chapter.
- **Done when:** someone from HR finds the PDF within 10 seconds, and the live map shows every real chapter.
---
# Phase 2: Depth
## 1.1.0 MCP endpoint
- MCP on the gateway: a tool to read states, a tool to push a chapter, same limits as visitors.
- The brief caps this at under 2 hours of work without AI. If it takes longer, drop it.
- **Done when:** an agent can list chapters and push one.
## 1.2.0 k6 release gate
- Namespace `cv-staging`, deploy there first in CI, run a fixed k6 script, fail the pipeline on the p95 threshold.
- Badge on the site: "p95 < X ms, last run".
- **Done when:** a deliberately slow build blocks the release.
## 1.3.0 Dev terminal
- kubectl-style view: events, probe results, restart history, YAML per chapter (read-only `get` through the gateway).
- **Done when:** a developer can inspect any chapter's state without the cluster.
## 1.4.0 LM: data and tokenizer
- TinyStories download, word-piece tokenizer written by hand, train/validation split.
- **Done when:** encode then decode round-trips the validation set.
## 1.5.0 LM: model and training
- About 5M-parameter transformer, layers written by hand, gradients from PyTorch (needs approval).
- Training run on the home server CPU, checkpoint saved.
- **Done when:** samples read like short simple stories.
## 1.6.0 LM: browser inference
- Export int8 weights, forward pass in plain TypeScript on `/lm`.
- **Done when:** TypeScript logits match PyTorch logits within a small tolerance for the same input.
## 1.7.0 LM: visuals
- Attention heatmaps per head, next-token probability bars, temperature slider.
- **Done when:** moving the slider visibly changes the probability bars and the generated text.
---
# Phase 3: Pressure and from scratch
## 1.8.0 Interactive k6
- Fixed k6 script run as a Job with the `grafana/k6` image, capped virtual users and duration.
- One run at a time across the site. No visitor-supplied parameters.
- The gateway needs `create` on Jobs for this, the first write permission it gets. Limit it to this one Job template.
- **Done when:** a second visitor sees "a test is already running".
## 1.9.0 HPA demo
- HPA on one chapter using metrics-server (ships with k3s), live replica count and latency graph during a k6 run.
- **Done when:** replicas go up during a run and back down after.
## 1.10.0 LM: bigger base model
- Retrain the base model at 15-30M parameters. Check training time on the CPU first.
- **Done when:** samples are clearly better than the 5M model.
## 1.11.0 LM: chat fine-tune
- Fine-tune on simple dialogues in a fixed user/bot format.
- **Done when:** it answers greetings and small talk in the browser.
## 1.12.0 Own autograd engine
- Tensor autograd written by Noel, likely on NumPy (needs approval).
- **Done when:** gradients match PyTorch on a small model.
## 1.13.0 Train with own engine
- Train the 5M model with the own engine instead of PyTorch.
- **Done when:** loss curves roughly match the PyTorch run.