Files
OKF_CV_Website/roadmap.md
T

9.1 KiB

type, title, description, tags, status, generated
type title description tags status generated
Roadmap Roadmap Small releases in three phases, each a few days of work at most, each ending in something that runs.
roadmap
planning
stable
by at
claude-code/claude-opus-5-5 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 Tiny 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 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
0.9.0 Own tracker 1-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.

Everything runs on a 2 vCPU, 4 GB server shared with Gitea. Every release stays inside the memory budget.


Phase 1: Ship the CV

0.1.0 Chapter service

  • Go module with cmd/chapter: /healthz, /ready, /fall, behavior from MODE. See chapter service.
  • 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

  • 2 GB swap file, k3s installed with traefik and servicelb disabled and kubelet reservations. See server budget.
  • ResourceQuota (384Mi) and LimitRange on 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, resource limits and quotas.

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. Runner capacity 1, so builds never run in parallel.
  • 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 with NODE_OPTIONS=--max-old-space-size=512, 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.

0.9.0 Own tracker

  • Gateway middleware writing daily totals to SQLite (modernc.org/sqlite) on a local-path volume. See decision.
  • Count page views, PDF downloads and falls per chapter. No IPs, no cookies.
  • Gateway Deployment switches to strategy Recreate.
  • One test for the upsert and the bot filter.
  • Done when: a test visit, a PDF download and a fall each raise their count in the SQLite file.
  • Learn: SQLite, Go database/sql, HTTP middleware, privacy by design.

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 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 runs on Noel's own computer, not the server. 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, a few virtual users, 30 seconds max, 64Mi limit.
  • The server is shared with Gitea: if a run slows Gitea noticeably, cut this release.
  • 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), max 3 replicas, 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 on Noel's own computer. Check training time 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.