docs(okf): write overview, architecture, decisions and roadmap
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
987a5efba1
commit
557ac1985b
20 files changed
+750
-16
No files matched your search
@@ -0,0 +1,25 @@
|
||||
---
|
||||
type: Decision
|
||||
title: Accept home-server downtime in v1
|
||||
description: v1 serves everything from the home server; if it is down, the whole site is down.
|
||||
tags: [decision, availability]
|
||||
status: stable
|
||||
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
|
||||
verified: { by: human:noel, at: 2026-10-11T12:15:30Z }
|
||||
---
|
||||
|
||||
# Decision
|
||||
|
||||
Accept the risk. No off-box hosting, no snapshot persistence in v1.
|
||||
|
||||
# Why
|
||||
|
||||
- Off-box hosting (Cloudflare Pages, GitHub Pages) is new tooling and needs approval.
|
||||
- A snapshot fallback only helps when the server is up but the gateway is not,
|
||||
which the static Nuxt data file already covers.
|
||||
- If the server is down, visitors see Cloudflare's error page. HR may hit it.
|
||||
|
||||
# Revisit when
|
||||
|
||||
The CV is actively sent to employers, or downtime is noticed in practice.
|
||||
The fix is hosting the static first screen off-box.
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
type: Decision
|
||||
title: Knowledge bundle lives in knowledge/
|
||||
description: The OKF bundle sits in a subdirectory, not at the repository root.
|
||||
tags: [decision, okf]
|
||||
status: stable
|
||||
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
|
||||
---
|
||||
|
||||
# Decision
|
||||
|
||||
The OKF v0.2 bundle lives in `knowledge/`.
|
||||
|
||||
# Why
|
||||
|
||||
OKF requires frontmatter in every non-reserved `.md` file in the bundle. The
|
||||
repo root will hold files like `README.md` and release-please's `CHANGELOG.md`
|
||||
that have none, which would make a root-level bundle non-conformant.
|
||||
@@ -0,0 +1,24 @@
|
||||
---
|
||||
type: Decision
|
||||
title: CI/CD on Gitea Actions
|
||||
description: The existing Gitea instance and runner on the home server build, scan, deploy and version the project.
|
||||
tags: [decision, ci, gitea, release-please]
|
||||
status: stable
|
||||
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
|
||||
verified: { by: human:noel, at: 2026-10-11T12:15:30Z }
|
||||
---
|
||||
|
||||
# Decision
|
||||
|
||||
Use Gitea Actions with the runner already on the home server, the Gitea
|
||||
container registry, and the Gitea variant of the release-please action.
|
||||
|
||||
# Why
|
||||
|
||||
- GitHub Actions cannot reach the k3s API behind the tunnel. The local runner can.
|
||||
- No new tooling: Gitea, its runner and its registry already exist.
|
||||
- No GitOps agent (Flux, Argo) needed.
|
||||
|
||||
# Details
|
||||
|
||||
See [delivery](/architecture/delivery.md).
|
||||
@@ -0,0 +1,11 @@
|
||||
# Decisions
|
||||
|
||||
* [v1 scope](v1-scope.md) - What the first public version keeps and what moves to later phases.
|
||||
* [Accept home-server downtime in v1](accept-downtime-v1.md) - v1 serves everything from the home server; if it is down, the whole site is down.
|
||||
* [Static Nuxt served by the gateway](static-nuxt-in-gateway.md) - Nuxt is generated to static files and embedded in the gateway image instead of running as its own pod.
|
||||
* [CI/CD on Gitea Actions](ci-on-gitea.md) - The existing Gitea instance and runner on the home server build, scan, deploy and version the project.
|
||||
* [Knowledge bundle lives in knowledge/](bundle-in-subdirectory.md) - The OKF bundle sits in a subdirectory, not at the repository root.
|
||||
|
||||
# Open
|
||||
|
||||
* [Open questions](open-questions.md) - Decisions still to make, with the release that needs each answer.
|
||||
@@ -0,0 +1,19 @@
|
||||
---
|
||||
type: Open Questions
|
||||
title: Open questions
|
||||
description: Decisions still to make, with the release that needs each answer.
|
||||
tags: [decision, open]
|
||||
status: draft
|
||||
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
|
||||
---
|
||||
|
||||
| Question | Needed by | Default if nobody decides |
|
||||
|---|---|---|
|
||||
| Final chapter list and the state of each chapter | 0.2.0 (placeholders), 1.0.0 (final) | Three placeholder chapters: one completed, one active, one failed |
|
||||
| Story card text per chapter | 1.0.0 | None, Noel writes it |
|
||||
| Life map visual form: timeline, graph or map | 0.7.0 | Vertical timeline |
|
||||
| Which Gitea release-please action, exact name | 0.1.0 | None, Noel names it |
|
||||
| Staging for k6 in CI: namespace or separate cluster | 1.2.0 | Namespace `cv-staging` on the same cluster |
|
||||
| MCP scope: read-only or read plus `/fall` | 1.1.0 | Read plus `/fall`, same limits as visitors |
|
||||
| Approve PyTorch for the language model | 1.5.0 | None, needs Noel |
|
||||
| Approve NumPy (or similar) for the own autograd engine | 1.13.0 | None, needs Noel |
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
type: Decision
|
||||
title: Static Nuxt served by the gateway
|
||||
description: Nuxt is generated to static files and embedded in the gateway image instead of running as its own pod.
|
||||
tags: [decision, nuxt, go]
|
||||
status: stable
|
||||
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
|
||||
---
|
||||
|
||||
# Decision
|
||||
|
||||
Build with `nuxt generate`, embed the output in the gateway with `go:embed`.
|
||||
|
||||
# Why
|
||||
|
||||
- One less Deployment, no Node runtime in the cluster.
|
||||
- One public service, same origin for the site and `/api`, so no CORS.
|
||||
- The life map can still render from its data file when the live stream fails.
|
||||
|
||||
# Cost
|
||||
|
||||
Frontend and gateway release together in one image.
|
||||
|
||||
# Revisit when
|
||||
|
||||
The site needs server-side rendering per request.
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
type: Decision
|
||||
title: v1 scope
|
||||
description: What the first public version keeps and what moves to later phases.
|
||||
tags: [decision, scope, roadmap]
|
||||
status: stable
|
||||
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
|
||||
---
|
||||
|
||||
# Keep in v1
|
||||
|
||||
- First screen: name, role, contact, PDF CV. Never gated behind interaction.
|
||||
- Life map with plain-word states and a "Push this chapter" button.
|
||||
- Story cards with real recovery seconds, lesson cards for failed chapters.
|
||||
- Live states: Completed, Ready, NotReady, CrashLoopBackOff, restart counts.
|
||||
- Gateway: SSE plus `/fall` with per-chapter cooldown and global rate limit.
|
||||
- "Someone just knocked down X" messages. Free, the SSE stream carries them.
|
||||
- Dev view: the raw event stream in a `<pre>`. Also free.
|
||||
- CI: Snyk, build, deploy, release-please.
|
||||
|
||||
# Cut from v1
|
||||
|
||||
| Cut | Why | Where it went |
|
||||
|---|---|---|
|
||||
| Separate Nuxt pod | Static build served by the gateway is simpler | [Decision](/decisions/static-nuxt-in-gateway.md) |
|
||||
| Snapshot persistence, offline banner | Downtime accepted for v1 | [Decision](/decisions/accept-downtime-v1.md) |
|
||||
| MCP endpoint | Cheap to add later, reuses `/fall` | Phase 2 |
|
||||
| k6 as a CI gate | Needs a staging target first | Phase 2 |
|
||||
| Full kubectl-style terminal (YAML, probes) | The raw stream covers it | Phase 2 |
|
||||
| Interactive k6, HPA demo, latency graph | Most work and most abuse risk | Phase 3 |
|
||||
| Rolling update as "pivot" | Nothing triggers it yet | Not planned |
|
||||
| client-go informer | Polling every 2 seconds is enough at about 10 pods | When polling falls short |
|
||||
Reference in new issue
Block a user