Repository navigation
0001 decision records
Status: accepted · Implementation: done · Date: 2026-11-18
The format is the one LibreLifts uses (its ADR 0001), with two changes: implementation is only planned or done, and notes may be added to after the fact.
LibreBars starts from an empty repository. Its architecture and its way of working come from LibreLifts, a sibling project by the same maintainer, where each choice was written down as a record and then built. Copying the outcome without the reasons would lose the part that is hardest to get back: why things are the way they are, and what was given up.
Every decision that shapes the project gets a short record in docs/decisions/, written
before the decision is acted on.
- One file per decision, named
NNNN-kebab-title.md, numbered in order. - Front matter:
title,number,status,implementation,date,supersedes,superseded_by,notes. -
statusisacceptedorsuperseded.implementationisplannedordone. - Three sections: Context, Decision, Consequences. Consequences say what is given up, not only what is gained.
- A changed decision gets a new record that supersedes the old one. Old records are never
rewritten. Only their
status,superseded_byandnoteschange, andnotesonly gains facts: what was built, when, and where the build differed. - A record taken from LibreLifts is written again for LibreBars, with its own number, and its
notesname the LibreLifts record it came from. -
docs/decisions/README.mdlists every record with its status.
- A decision costs a few minutes of writing before any code.
- The history of why stays in the repository, next to the code. Superseded records stay too, so the folder also shows what was tried and dropped.
- The numbers here do not match LibreLifts' numbers. Someone comparing the two projects has to go through the notes.
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