docs: add original planning brief

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Noel SabiaandClaude Opus 5.5 committed 2026-10-11 14:21:20 +02:00
1 parent 557ac1985b
commit 957a386b58
1 file changed
+133
+133
View File
@@ -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.