From e37a1d579840ab813837c49e2d3380590131caa6 Mon Sep 17 00:00:00 2001 From: Fredrik Johansson Date: Tue, 21 Jul 2026 05:27:52 +0200 Subject: [PATCH] README: document the new module layout, drop the dead-endpoint note MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The known-rough-edge section described POST /api/receipts as still present but scheduled for removal — the refactor already removed it. Replaced with a table of what each file now owns. Co-Authored-By: Claude Sonnet 5 --- README.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2573c47..e4fbf61 100644 --- a/README.md +++ b/README.md @@ -86,9 +86,20 @@ curl https://trace.dev.xplwd.com/api/v1/public/projects/goonk/latest Full producer onboarding — registering a project, per-project tokens, the exact CI step shape, and the deploy-host responsibilities above — is in [`docs/INTEGRATING_PROJECTS.md`](docs/INTEGRATING_PROJECTS.md). `keep/scripts/deploy.sh` is the reference deploy-host implementation of the second `curl` above: after `docker compose up -d`, it polls the app's own embedded build identity until healthy, then submits exactly this receipt — opt-in per project via a `.trace-meta` marker file, never assumed. -### A known rough edge +## Code layout -`POST /api/receipts` (Basic Auth, no `/v1`, no bearer token) still exists in `src/server.mjs` as a leftover from before the v1 events API was built. It writes to a `receipts` table nothing else ever reads from — dead code, not a second real API. Use `/api/v1/events` for everything; the old path is scheduled for removal, not a documented feature. +`src/server.mjs` is composition only — open the database, build each route module, wire the dispatch order, listen. Everything else lives by concern: + +| File | Owns | +|---|---| +| `src/db.mjs` | Schema and migrations for the incident notebook (`openDb()`) | +| `src/views.mjs` | Pure HTML/Markdown rendering — no database or network access | +| `src/style.mjs` | The one shared stylesheet every page links to | +| `src/http-utils.mjs` | `form()`/`redirect()` request helpers | +| `src/routes/incidents.mjs` | The private notebook, the Git inbox, publish/unpublish — auth-gated once at the top | +| `src/routes/public-failures.mjs` | The read-only `/api/v1/public/failures*` projection | +| `src/receipts.mjs` | The deployment-receipts ledger and `/events` | +| `src/gitea.mjs` | Gitea-API-based commit scanning, no checkout needed | ## Configuration reference