Repository navigation
0030 spotcraft user pool
Status: accepted · Implementation: done · Date: 2026-11-19 · Supersedes: 0017
From LibreLifts ADR 0039. Partly supersedes 0015: the API no longer keeps accounts; the rest stands. Partly supersedes 0016: the session is a bearer token in secure storage (local storage in the web build), and the limit on new guests is the pool's; the rest stands. Partly supersedes 0021: Postgres for development and tests comes from
spotcraft dev, not the repository's Compose file, and the tests no longer run on PGlite; Postgres 18 stands. Spotcraft 0.6, @kodentuzo/spotkit 0.1.0. The API isn't deployed yet: it goes to the LibreVitalis instance later.
The API kept LibreBars' accounts itself, with Better Auth's anonymous accounts in its own
auth schema (0015, 0016,
0017), on a Postgres the repository ran with Docker Compose and, in
tests, on PGlite (0021).
The API will run on Spotcraft, which hosts the owner's apps. Since 0.6, a Spotcraft instance
has one user pool for every app on it: Better Auth with guests, bearer tokens and signed JWTs,
reached at /_spotcraft/auth on every app's domain. Each app gets a schema of its own,
app_<slug>, in the instance's database, may point foreign keys at the pool's auth.users,
and has its migrations run from an image label before a new version starts. spotcraft dev
runs the same stack locally, one per repository. LibreLifts made the same move first.
-
Every account is a guest of the instance's user pool. The app makes its guest there,
never the API. The API keeps no accounts and no sessions:
@kodentuzo/spotkitchecks the pool's token on each request and gives the account's id. -
The app sends the pool's session token as
Authorization: Bearer …, to the pool and to the API, on every platform. On a phone it's in the device's secure storage; in the temporary web build, in local storage. No cookies cross between sites. -
The pool is at the API's own address,
<API>/_spotcraft/auth, so the app needs one address. On Spotcraft, Caddy answers that path; locally the API passes it on to the stack's pool. -
The personal tables are in the API's schema,
app_librebars_api, and everyuser_idpoints atauth.userswithon delete cascade: deleting a guest in the pool deletes their data. -
Migrations start again from one that creates today's tables in that schema. A small
runner applies drizzle-kit's files, because Drizzle's own migrator first tries to create a
schema, which the API's role may not. The image's
dev.spotcraft.migratelabel runs it. -
Development and tests use
spotcraft dev: its Postgres and its pool, with the settings it writes to.env. The repository's Compose file and the in-process Postgres go. The API's tests make real guests in the pool. - The API has an image, built and checked in CI.
- The API has no account code to keep secure, and no Better Auth to pin; the pool does.
- Running the API's tests needs Docker and
spotcraft dev, in CI too. - The limit on new guests is the pool's, per address, and works with any number of API instances.
- Guests made by the old API aren't carried over. None exist outside developers' machines: the API was never deployed.
- Signing up, signing in and turning a guest into a full account are the pool's to add.
Generated from docs/ on dev. Edit the docs there; changes made on the wiki are overwritten.
- Development
- Workflow
-
Decisions
- 0001 Decisions are recorded
- 0002 Apache License 2.0
- 0003 Changes land on dev by fast-forward; main is the last release
- 0004 Conventional Commits, Keep a Changelog and Semantic Versioning
- 0005 docs/ is for developers and is mirrored to the wiki
- 0006 LibreBars is a free workout log for calisthenics
- 0007 The tracker is an iOS and Android app; its web build stays until the store release
- 0008 LibreBars is an app and a crowd-sourced open database
- 0009 The database is ODbL, media is CC BY-SA, and neither can be closed later
- 0010 A hosted API with a free tier is the paid product
- 0011 The workspace is app, web and api, with engine, ui, data and contracts
- 0012 The engine is small pure functions, in the style of date-fns
- 0013 Web and app share a Tailwind theme, not components
- 0014 Postgres is the source of truth for all data
- 0015 The API is Fastify, and it owns LibreBars accounts
- 0016 Every install is a guest account, made in the background
- 0017 Accounts use Better Auth
- 0018 The on-device database is SQLite with Drizzle, on every platform
- 0019 Sync is our own push and pull
- 0020 The app says it backs up, and backup can be turned off
- 0021 Postgres 18, run with Docker Compose and tested on two databases
- 0022 expo-sqlite is patched so the web build reuses one buffer
- 0023 Seed data is TypeScript modules in packages/data, with permanent ids
- 0024 The first tables
- 0025 One TanStack Start app is the website, on GitHub Pages
- 0026 The catalog reaches the app as a snapshot plus updates, and the website through the API
- 0027 The app's first components are its own
- 0028 The theme comes from Spotstrap, with shadcn's colour names
- 0029 The app's own components take their classes from Spotstrap's recipes
- 0030 Accounts are guests of Spotcraft's user pool, and the API runs on Spotcraft's contract