Design 62: name ADR 0481 accepted, and say the page reaches OkiOki only over the bus
mesh/merge-gate head 993c7def3ae3 merged into trunk a2918df0aab2 — pass: the change touches no module of the mesh's graph
mesh/repo-check head 993c7def3ae3 merged into trunk a2918df0aab2 — pass: its merge-check.sh passed
mesh/delivery delivered

The review of hq#453 after its merge found the design calling ADR 0481 proposed, and the operator's rule (the page uses the bus and makes no OkiOki call, 2026-10-21) only implied. A document crosses the bus in parts, as scanner.document does.
This commit is contained in:
jochen
2026-10-21 12:32:31 +02:00
parent a2918df0aa
commit 993c7def3a
@@ -14,7 +14,7 @@ decisions:
**A web page on the private network where the operator, signed in with Keycloak, sees the business's income and
expenses as the bookkeeping service holds them now, and what is still to do per quarter. The `okioki` module that
talks to the service moves, whole, from the laptop to the home server, and the page, `okioki-web`, runs beside it.
Bookkeeping data stays on hardware the operator owns.** (ADR 0481, proposed and not in force.)
Bookkeeping data stays on hardware the operator owns.** (ADR 0481, accepted.)
**Acceptance.** The operator, signed in on a machine of the mesh, opens the page's internal name and sees income and
expenses per month and per quarter, the same period a year before beside them, including an invoice made in the
@@ -29,7 +29,7 @@ the operator's browser (a machine of the mesh)
│ HTTP through the route proxy's internal name, signed in with Keycloak
▼
okioki-web — renders the pages on the server, keeps no bookkeeping data
│ bookkeeping.summary · bookkeeping.todo · bookkeeping.documents · bookkeeping.transactions · bookkeeping.document
│ over the bus (NATS): bookkeeping.summary · bookkeeping.todo · bookkeeping.documents · bookkeeping.transactions · bookkeeping.document
▼
okioki — the one session with the bookkeeping service, on the home server
│ HTTPS, the service's own web API, as its web app calls it
@@ -39,14 +39,15 @@ the bookkeeping service (OkiOki)
`okioki` claims the seat `bookkeeping`, held once for the mesh, and serves the verbs the page calls beside the tools
it has (`okioki_todo`, `okioki_link`, …). `okioki-web` claims `bookkeeping-web` with `open` and `status`, and calls
only `bookkeeping` verbs, never a module's own tool, as the print and scan page calls only seats (ADR 0479 §1). Both
are Go, and both live in the `okioki` repository.
only `bookkeeping` verbs, over the bus, never a module's own tool, as the print and scan page calls only seats (ADR 0479 §1).
`okioki-web` opens no connection to the bookkeeping service and holds none of its secrets or settings: only `okioki`
holds the service's password and session (ADR 0481 §1, §7). Both are Go, and both live in the `okioki` repository.
## 2. Where it runs
Both modules run on the home server, which is always on and is the operator's own hardware (ADR 0481 §1). The
laptop sleeps and travels, so a page there would be away whenever the laptop is. `okioki` runs once: the service
password is sealed on the home server alone, given once at its desk prompt, and the laptop's `okioki` is retired on
password is sealed on the home server for `okioki` alone, given once at its desk prompt, and the laptop's `okioki` is retired on
the operator's Approve once the home server's answers.
Uploading no longer reads a folder on the laptop. `okioki_upload` takes a scan from the scanner's bucket by its key,
@@ -68,7 +69,8 @@ default, so nobody is let in until the operator names themself. Nothing about th
documents and transactions, so the page does no bookkeeping arithmetic of its own.
- **To-do.** Open payments and documents per quarter, as `okioki_todo` reads them.
- **Documents and transactions.** Searchable lists for a period; a document opens as the file the service keeps,
streamed through `bookkeeping.document`.
streamed through `bookkeeping.document` over the bus in numbered parts, as `scanner.document` answers (part, parts,
size, SHA-256, data): `okioki` fetches the file from the service, and the page never follows the service's own link.
The page only reads: it calls no verb that changes the service, and keeps no copy (ADR 0481 §4). Keeping the history in a database of the mesh's own is the own
bookkeeping research (issue 1457), and a decision of its own.