diff --git a/architecture/gateway.md b/architecture/gateway.md index 0b2c4a2..f0b9b8a 100644 --- a/architecture/gateway.md +++ b/architecture/gateway.md @@ -14,6 +14,7 @@ generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z } | `GET /` and static paths | Serves the Nuxt build, embedded with `go:embed` | | `GET /api/events` | SSE stream: full state on connect, then each change | | `POST /api/fall/{chapter}` | Allowlist, cooldown, rate limit, then calls the chapter's `/fall` | +| every route | Counted by the tracker | # Reading cluster state @@ -42,6 +43,22 @@ The same stream feeds the life map and the developer view. - Send `Content-Type: text/event-stream` and flush after every message. - Send a comment line (`: ping`) every 30 seconds so idle connections are not closed. +# Tracker + +Middleware that counts page views, PDF downloads and falls. See [decision](/decisions/own-tracker.md). + +```sql +CREATE TABLE counts (day TEXT, event TEXT, n INTEGER, PRIMARY KEY (day, event)); +-- event: 'view:/', 'pdf', 'fall:example', ... +INSERT INTO counts VALUES (?, ?, 1) ON CONFLICT DO UPDATE SET n = n + 1; +``` + +- Daily totals only. No IP addresses, no cookies, no personal data. +- Skip requests whose user agent looks like a bot. +- SQLite file on a small `local-path` volume. Deployment strategy `Recreate`, + so two gateway pods never write the file at the same time. +- Read the numbers with `sqlite3` or a small admin route later; no dashboard in v1. + # Resources 64Mi memory limit with `GOMEMLIMIT=50MiB`, 100m CPU. See [server budget](/architecture/server-budget.md). diff --git a/architecture/server-budget.md b/architecture/server-budget.md index f98051e..351ee06 100644 --- a/architecture/server-budget.md +++ b/architecture/server-budget.md @@ -33,9 +33,8 @@ Per workload inside `cv`: | Workload | Memory limit | CPU limit | |---|---|---| -| Gateway | 64Mi, `GOMEMLIMIT=50MiB` | 100m | +| Gateway, including the [tracker](/decisions/own-tracker.md) | 64Mi, `GOMEMLIMIT=50MiB` | 100m | | Each chapter (~10) | 16Mi, `GOMEMLIMIT=12MiB` | 10m | -| Analytics ([GoatCounter](/decisions/goatcounter-over-umami.md)) | 64Mi | 50m | Completed Jobs do not count against the quota. @@ -70,7 +69,7 @@ kubelet-arg: ``` Keep `metrics-server` and `local-storage`: the HPA demo needs the first, -analytics storage the second. Single-node k3s uses SQLite, not etcd; do not +the tracker's SQLite volume the second. Single-node k3s uses SQLite, not etcd; do not pass `--cluster-init`. # Swap diff --git a/architecture/system.md b/architecture/system.md index 800385b..ba39eac 100644 --- a/architecture/system.md +++ b/architecture/system.md @@ -12,12 +12,11 @@ generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z } | Component | Runs as | Job | |---|---|---| | Cloudflare Tunnel | `cloudflared` on the home server | Only way in from the internet. Points at the gateway. | -| [Gateway](/architecture/gateway.md) | 1 Deployment, Go | Serves the static site, streams states, forwards knockdowns. The only public service. | +| [Gateway](/architecture/gateway.md) | 1 Deployment, Go | Serves the static site, streams states, forwards knockdowns, counts visits into SQLite. The only public service. | | [Frontend](/architecture/frontend.md) | Static files inside the gateway image | Nuxt, built with `nuxt generate`. | | [Chapter service](/architecture/chapter-service.md) | One Deployment or Job per chapter | Behaves healthy, not-ready, crashing, or completed, set by env. | | [Delivery](/architecture/delivery.md) | Gitea Actions on the home server | Test, scan, build, push, deploy, version. | -| Analytics | 1 Deployment, GoatCounter (proposed) | Page views, PDF downloads, falls per chapter. See [decision](/decisions/goatcounter-over-umami.md). | Everything runs in one namespace: `cv`, capped at 384Mi memory in total, on a 2 vCPU, 4 GB server shared with Gitea. See [server budget](/architecture/server-budget.md). diff --git a/decisions/goatcounter-over-umami.md b/decisions/goatcounter-over-umami.md deleted file mode 100644 index 296f239..0000000 --- a/decisions/goatcounter-over-umami.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -type: Decision -title: GoatCounter over Umami for analytics -description: Proposed; GoatCounter gives cookie-free open source analytics in about 30 MB, where Umami needs Postgres and about 300-400 MB. -tags: [decision, analytics, resources] -status: draft -generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z } ---- - -# Proposal - -Self-host GoatCounter in namespace `cv` instead of Umami. Needs Noel's -approval as new tooling. - -# Why - -| | Umami | GoatCounter | -|---|---|---| -| Runtime | Node app | Single Go binary | -| Database | Postgres | SQLite file | -| Memory | ~300-400 MB with Postgres | ~30 MB | -| Cookie-free, no consent banner | Yes | Yes | -| Custom events | Yes | Yes | -| License | Open source | Open source | - -On a [4 GB shared server](/architecture/server-budget.md), Umami alone would -match the whole CV budget. - -# Track - -- Page views. -- PDF CV downloads. -- Falls per chapter. - -# Details - -One Deployment, 64Mi limit, SQLite on a small `local-path` volume. No backup: -losing analytics hurts nobody. diff --git a/decisions/index.md b/decisions/index.md index d09ba62..d73ae39 100644 --- a/decisions/index.md +++ b/decisions/index.md @@ -3,13 +3,10 @@ * [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. +* [Own analytics tracker on SQLite](own-tracker.md) - Analytics are counted by Noel's own code in the gateway and stored as daily totals in SQLite; no third-party tracker, no Postgres. * [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 at the repository root](bundle-at-root.md) - The repository root is the OKF bundle root; any other markdown file there needs frontmatter to stay conformant. -# Proposed - -* [GoatCounter over Umami for analytics](goatcounter-over-umami.md) - Proposed; GoatCounter gives cookie-free open source analytics in about 30 MB, where Umami needs Postgres and about 300-400 MB. - # Open * [Open questions](open-questions.md) - Decisions still to make, with the release that needs each answer. diff --git a/decisions/open-questions.md b/decisions/open-questions.md index 0d7a5f9..9c7dbaa 100644 --- a/decisions/open-questions.md +++ b/decisions/open-questions.md @@ -15,6 +15,5 @@ generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z } | 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 GoatCounter for analytics | 0.9.0 | None, needs Noel | | 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 | diff --git a/decisions/own-tracker.md b/decisions/own-tracker.md new file mode 100644 index 0000000..2b9552f --- /dev/null +++ b/decisions/own-tracker.md @@ -0,0 +1,36 @@ +--- +type: Decision +title: Own analytics tracker on SQLite +description: Analytics are counted by Noel's own code in the gateway and stored as daily totals in SQLite; no third-party tracker, no Postgres. +tags: [decision, analytics, sqlite, go] +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 + +Write the tracker as middleware in the [gateway](/architecture/gateway.md). +Store daily totals in SQLite via `modernc.org/sqlite` (pure Go, no cgo). +SQLite is approved tooling. + +# Why + +- The gateway already sees every page view, PDF download and fall. No + tracking script, nothing for ad blockers to block. +- About 5 MB of memory, no extra pod. GoatCounter would need ~30 MB, Umami + with Postgres ~300-400 MB, on a [4 GB shared server](/architecture/server-budget.md). +- A learning project: owning the code is the point. + +# Rejected + +| Option | Why not | +|---|---| +| Umami | Needs Postgres, ~300-400 MB | +| GoatCounter | Fine, but Noel wants his own | +| Postgres for the own tracker | ~40-60 MB for a table of counters | +| Cloudflare analytics only | Cannot count falls or PDF downloads | + +# Revisit when + +Noel wants to learn Postgres. The schema is plain SQL, so the move is small. diff --git a/log.md b/log.md index 958ed32..ecbcda3 100644 --- a/log.md +++ b/log.md @@ -1,7 +1,8 @@ # Update Log ## 2026-10-11 -* **Creation**: Added the [server and memory budget](/architecture/server-budget.md) from measured usage, and proposed [GoatCounter over Umami](/decisions/goatcounter-over-umami.md). +* **Update**: Replaced the GoatCounter proposal with Noel's [own tracker on SQLite](/decisions/own-tracker.md). +* **Creation**: Added the [server and memory budget](/architecture/server-budget.md) from measured usage, and proposed GoatCounter over Umami (since replaced by the [own tracker](/decisions/own-tracker.md)). * **Update**: Moved the bundle from `knowledge/` to the repository root and replaced the planning brief with this bundle. See [bundle at root](/decisions/bundle-at-root.md). * **Creation**: Wrote the [overview](/overview.md), [architecture](/architecture/), [decisions](/decisions/), [chapter states](/chapters/state-mapping.md) and [roadmap](/roadmap.md) from the planning conversation. * **Initialization**: Created the bundle [index](/index.md). diff --git a/roadmap.md b/roadmap.md index 6d12cc6..b38445d 100644 --- a/roadmap.md +++ b/roadmap.md @@ -25,7 +25,7 @@ generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z } | 0.6.0 | First screen | 2 | | 0.7.0 | Life map | 3 | | 0.8.0 | Story cards and dev view | 2 | -| 0.9.0 | Analytics | 1 | +| 0.9.0 | Own tracker | 1-2 | | 1.0.0 | Real content, launch | 2-3 | | 1.1.0 | MCP endpoint | 1 | | 1.2.0 | k6 release gate | 2 | @@ -117,11 +117,14 @@ stays inside the [memory budget](/architecture/server-budget.md). - Dev view: the raw stream in a `
`.
 - **Done when:** two browsers see each other's knockdowns live.
 
-## 0.9.0 Analytics
+## 0.9.0 Own tracker
 
-- GoatCounter in `cv`, 64Mi limit, SQLite on a `local-path` volume. Needs approval, see [decision](/decisions/goatcounter-over-umami.md).
-- Count page views, PDF downloads and falls per chapter.
-- **Done when:** a test visit, a PDF download and a fall all show up in GoatCounter.
+- Gateway middleware writing daily totals to SQLite (`modernc.org/sqlite`) on a `local-path` volume. See [decision](/decisions/own-tracker.md).
+- Count page views, PDF downloads and falls per chapter. No IPs, no cookies.
+- Gateway Deployment switches to strategy `Recreate`.
+- One test for the upsert and the bot filter.
+- **Done when:** a test visit, a PDF download and a fall each raise their count in the SQLite file.
+- **Learn:** SQLite, Go `database/sql`, HTTP middleware, privacy by design.
 
 ## 1.0.0 Real content and launch