From 957a386b58799596b56e47be6749cf7d47301bfb Mon Sep 17 00:00:00 2001 From: Noel Sabia Date: Sun, 11 Oct 2026 14:21:20 +0200 Subject: [PATCH] docs: add original planning brief Co-Authored-By: Claude Opus 5.5 --- brief.md | 133 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 brief.md diff --git a/brief.md b/brief.md new file mode 100644 index 0000000..18d7de0 --- /dev/null +++ b/brief.md @@ -0,0 +1,133 @@ +# Interactive CV on k3s: Planning Brief + +Handoff document for further planning. Owner: Noel Sabia. + +## 1. Goal + +A creative, interactive CV on the apex of Noel's main domain. It must work for two audiences: + +- **Non-technical HR:** understandable without any coding knowledge. +- **Programmers:** real infrastructure, inspectable, technically credible. + +Core life lesson: **falling down and standing up again.** It is shown live on a k3s cluster running on Noel's home server. + +## 2. Fixed constraints (already decided) + +| Area | Decision | +|---|---| +| Frontend | Nuxt | +| Backend | Multiple Go microservices | +| Orchestration | k3s on home server (Ryzen 5, 24 GB RAM) | +| Security | Snyk | +| Delivery | CI/CD pipeline, release-please for versioning | +| Exposure | Cloudflare Tunnel | +| Design | Drafted with Stitch prompts. Terminal/IT feel, usable by non-IT visitors. | +| Brand | Navy #1A3D64 and white. Logo has a "broken pieces" look, which fits the fall/recover theme. | +| AI access | MCP-ready, so agents can read states and trigger a fall. Only include it if it is doable in under 2 hours without AI. Keep it minimal. | +| Tooling rule | **Any tooling beyond this stack needs Noel's approval before it enters the spec.** k6 is approved by Noel. | + +## 3. Core concept + +- Each life chapter runs as its own microservice or workload in k3s. +- Some chapters stay unhealthy on purpose. +- Visitors interactively knock chapters down and watch Kubernetes bring them back up. +- k6 load testing is integrated on the side. + +### Kubernetes state to life meaning + +| K8s primitive / state | Meaning | Example use | +|---|---|---| +| `Job` → Completed | Finished chapter | School, 42 piscine | +| `Deployment` → Running + Ready | Active, stable chapter | PreZero, Example | +| Running, **NotReady** (readiness fails on purpose) | Exists, unfinished | Ongoing studies, thesis | +| `CrashLoopBackOff` (permanent) | Attempt that failed and stayed failed | Abandoned projects, dead ends | +| `restartCount` | Setbacks survived | "fell 3×, stood up 3×" | +| Replicas / HPA scale-up | Load carried, growth under pressure | Team lead, two businesses in parallel | +| Rolling update / new revision | Pivot or reinvention | Career switch, new role | + +Key structural choice: finished chapters run as **Jobs** (they complete), and current chapters run as **Deployments** (they must stay alive). + +## 4. Audience layers (one data source, different rendering) + +| Layer | Audience | Content | +|---|---|---| +| 0: First screen | HR, 10-second skim | Name, role, contact, **static PDF CV download**. Never gated behind interaction. | +| 1: Life map | Non-technical | Timeline or graph of chapters. States in plain words ("recovering", "unfinished", "failed, lesson learned"). A "Push this chapter" button. | +| 2: Terminal | Developers | kubectl-style view: events, probes, restart history, YAML per chapter, live k6 results | + +## 5. Architecture + +``` +Visitor ─► Cloudflare Tunnel ─► Nuxt + │ SSE/WebSocket (state) + ▼ + Go gateway (only public API) + ├─ watch: read-only informer on namespace `cv` + ├─ actions: allowlisted, rate-limited + └─ MCP endpoint (same actions, same limits) + │ + ┌────────────────────┼────────────────────┐ + chapter-svc (Go) chapter-svc (Go) k6 Job (on demand) + /healthz /ready /fall +``` + +- **One Go chapter-service template.** Its health behavior is set by env config: `healthy`, `not-ready` or `crash`. +- **Knockdown via `/fall` on the service itself.** The process exits or fails its liveness probe, and the kubelet restarts it. This needs no delete permission on the cluster. +- **Gateway ServiceAccount:** scoped to namespace `cv`, read-only `get/list/watch` on pods, events and jobs. + +## 6. Non-negotiable rules + +- No visitor or agent gets Kubernetes API access. Everything goes through the gateway. +- Per-chapter cooldown and a global rate limit, so one visitor cannot hold everything down. +- Shared cluster state is a feature. Show messages like "someone just knocked down Example". +- Offline fallback: the gateway persists the last known state, and Nuxt renders a static snapshot with a "live cluster offline" banner. HR never sees an error page. +- Permanently unhealthy services get resource limits and a long backoff, so they don't waste CPU. + +## 7. Narrative layer + +- Every fall triggers a story card: what went wrong in that chapter and what got Noel back up. +- The time to recover is real measured seconds, shown next to the story. +- Permanently failed chapters show a "lesson" card instead of a recovery. +- Failures must be labeled explicitly as lessons, never as bugs. + +## 8. k6 integration + +| Use | Implementation | Visitor sees | +|---|---|---| +| Real engineering | k6 in CI against staging. Performance thresholds gate release-please releases. | Badge: "p95 < X ms, last run" | +| Interactive pressure test | Predefined script run as a k8s `Job` with the `grafana/k6` image. Capped VUs and duration, one run at a time across the whole site. | HPA scales replicas up and down live, with a latency graph | +| Dev layer | Raw k6 summary streamed to the terminal view | Full metrics | + +- HPA uses metrics-server, which ships with k3s by default. No extra tooling. +- No k6 operator; a plain Job is enough. The operator would be extra tooling and needs approval. +- Never allow visitor-defined k6 scripts or parameters. That would turn the site into a DoS tool against the home server. + +## 9. Build order + +1. Go chapter-service template with `/healthz`, `/ready` and `/fall`, configured by env. +2. Manifests for all chapters (Jobs plus Deployments), with states set through config. +3. Go gateway: informer, SSE, allowlisted actions, rate limits, snapshot persistence. +4. Nuxt Layer 0, plus Layer 1 life map and story cards. +5. Layer 2 terminal view. +6. k6: first as a CI gate, then as the bounded interactive Job, then the HPA demo. +7. MCP endpoint on the gateway, reusing the action allowlist. + +## 10. Risks + +| Risk | Mitigation | +|---|---| +| HR confusion | Layer 0 is conventional and complete on its own. The interactive part is optional. | +| Spectacle without substance | Every state change links to a story card | +| Home server downtime | Snapshot fallback, plus Layer 0 served statically | +| Abuse | Cooldowns, global k6 lock, no raw cluster exposure | +| "Unhealthy" read as incompetence | Failures labeled as lessons | + +## 11. Open decisions + +- Final chapter list and the state assigned to each chapter (completed, active, unfinished, permanently failed). +- Story card content per chapter: the setback and the recovery. +- Life map visual form: timeline, graph or map. +- Where state snapshots persist: file, ConfigMap or a database. Any new database needs approval. +- Staging environment for k6 in CI: a separate namespace or a separate cluster. +- Scope of the MCP endpoint: read-only, or read plus `/fall`. +- Whether Layer 0 is served by Nuxt or as a fully static page outside the cluster for maximum uptime. \ No newline at end of file