Reference backend (PR 1,5,7).

[Chriztiaan]

Write API PoC: foundation, auth and transaction batching

feat/base merges PRs #1, #5 and #7 into a single branch against main, plus the integration work that only became visible once the three sat together.

The result is a runnable demo end to end: a React/Vite todo app, an Express backend, an OpenAPI contract both sides generate types from, and persisters for Postgres, MySQL, MSSQL and MongoDB, with docker-compose bringing up Postgres, MongoDB and the PowerSync service.

The three focus areas

A template write path (#1). Moves the translation problem from the client to the server edge. Instead of every developer writing a bespoke uploadData that fetches CRUD ops, maps types, talks to a backend and classifies errors, the client sends raw CRUD data over the wire and a standard server-side stack handles it from there: a generated endpoint handler, a mapping layer from SQLite CRUD data to the source database's shape, and a persister per supported database. Defining the wire format in openapi.yaml means the handler and client types can be regenerated rather than reimplemented, including for other languages.

Auth on the write path (#5). The write endpoint is gated behind a bearer JWT: the backend verifies a token on every write, the frontend attaches one to every upload. Verification sits behind a single TokenVerifier interface (backend/src/auth/types.ts), so an adopter swaps one file to accept tokens from Supabase, Clerk or anything else. The demo reuses the same PowerSync token the client already fetches in fetchCredentials() rather than minting a second one, and verifies it against the backend's own public key. auth-verifiers.md walks through the swap for Supabase and Clerk.

Transaction batching (#7). The client previously uploaded one transaction per attempt, so a queue built up offline drained one round-trip at a time. The write endpoint now takes an ordered run of whole transactions from the head of the upload queue and applies each one in its own database transaction. A transaction is never split across batches. The response holds one result per transaction sent, in the same order and always the same length as the request, so the client never has to infer which transactions were applied. Transactions the batch never reached come back as not_attempted rather than being omitted. The client then completes once, at the last result that is success or fatal_error; completing a transaction also completes everything before it, so a retry resumes from the failure instead of re-uploading transactions that already committed.

For a batch to know where to stop, every failure is sorted into retryable (connection loss, deadlock, resource exhaustion: will upload again after a delay) or fatal (missing required field, constraint violation, malformed or out-of-range value, schema mismatch: the data can never be stored). Classification is per engine, in backend/src/persistance/<engine>/<engine>-errors.ts.

on_fatal_error controls what a fatal failure does to the rest of the batch. stop (the default) ends the batch there and reports everything after it as not_attempted. skip drops the failing transaction and carries on, so a queue blocked by a poison operation can still drain; its result still reports fatal_error with the classification, so the client can record what it discarded, or divert it to a dead-letter queue instead of throwing it away. skip covers fatal failures only. A retryable failure always ends the batch.

AI disclosure

This PR was created with the help of Claude Code. Help constitutes assistance in research, planning, and rough outline of implementation. Beyond having a hand in the implementation, I have also manually tested this work.