Files
OKF_CV_Website/brief.md
T
2026-10-11 14:21:20 +02:00

133 lines
7.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.