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,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