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,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).
|
||||||
@@ -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.
|
||||||
@@ -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.
|
||||||
@@ -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.
|
||||||
@@ -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).
|
||||||
@@ -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.
|
||||||
@@ -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.
|
||||||
@@ -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
@@ -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.
|
|
||||||
@@ -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).
|
||||||
@@ -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.**
|
||||||
@@ -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.
|
||||||
Reference in new issue
Block a user