docs: README and server placeholder

README covers how the pieces fit: the storage interface, the inverted
frequency join, the gate's three refinements, and the checks that guard
each one.

server/ holds a README only. Steps 1-3 give a fully working offline app with
no server at all, and that is the version that gets used first.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
MechaCat02
2026-09-08 19:13:53 +02:00
parent 21dfc43ae1
commit f73582913b
2 changed files with 184 additions and 0 deletions

25
server/README.md Normal file
View File

@@ -0,0 +1,25 @@
# server/ — not in this pass
PORT.md steps 46 land here: the sync API, the tutor SSE endpoint, and the
Docker Compose deployment beside the Pi's existing Postgres and Caddy.
Nothing here yet, on purpose. Steps 13 give a fully working offline app with
no server at all, and that is the version that gets used first.
What is already shaped for it:
- every syncable table carries `updated_at`, and seeded rows are pinned to 0
(see `app/src/db/writes.ts`) — the artifact's clobbering bug cannot be
expressed;
- `change_seq` is deliberately absent: it is server-assigned and arrives with
the sync layer;
- the dictionary is fetched by URL from `app/src/domain/dictionary.ts`, so
per-band deltas can come from the Pi instead of the bundle by changing a base
URL;
- the tutor goes through one `Sample` function
(`app/src/domain/stub-tutor.ts`). The real endpoint implements the same
contract — `onText` receives cumulative text, and an aborted turn stops
billing — so only that file changes.
When the SSE endpoint lands, Caddy needs `flush_interval -1` on the proxy or
the stream buffers and the tutor appears to hang.