# 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.