Backend guide

Persisted BYO backend

BYO means your server stores threads, comments, mention ids, and read markers. An in-memory map that disappears on restart is not the production shape. The reference app is examples/comments-nextjs.

Run the example

pnpm --filter @bootstrapware/comments-example dev

Open http://localhost:3014. Sign in as Ada (user_ada), Kai (user_kai), or Noor (user_noor) for tenant acme, resource type task, resource task_1842 (“Approve the launch checklist”). Sign in as Boa (user_boa) for tenant other with the same resource id. The session is an HttpOnly HMAC cookie bsw_comments_demo. A caller who is not a member gets not_found.

State file: COMMENTS_BYO_DATA_FILE, or .data/comments.json. Writes are serialized and renamed into place. App id inside the example is cma_demo. Workspace id is ws_demo. Environment is test.

Routes your adapter calls

• POST /api/session
• GET and POST /api/threads
• GET and POST /api/threads/:id/comments
• POST /api/threads/:id/resolve and /reopen
• GET and POST /api/threads/:id/read
• PATCH /api/comments/:id and POST { "action": "delete" }
• POST /api/purge
• GET /api/export

Mutations take operationId, max 80. The actor is the cookie user, not a body field named authorId. Mention allow-lists are the resource members. Replay of the same operation returns the stored result. Point createByoAdapter at these routes from the widget, or keep using the example HTML while you port the store to Postgres.

Live BYO still publishes app config so the widget can load empty state and limits. Discussion text does not go to comments.bootstrapware.co. See the adapter contract.

Related: BYO vs Hosted · Records · Modes