Repository navigation
0005 docs and wiki
Status: accepted · Implementation: done · Date: 2026-11-18
From LibreLifts ADR 0011. As built, 2026-11-18: scripts/wiki.ts and the workflow exist, and the local build writes 30 pages. The wiki has no first page yet, so nothing has been published and this stays planned. First publish 2026-11-18, when the foundation landed on dev: the wiki already had a first page, and the workflow succeeded.
LibreBars has two kinds of reader. People who want the app need to know what it does; that is the website's job (0025). People who work on it need the decisions, the workflow and how to run it. Those documents are reviewed and versioned with the code, but a folder of Markdown files is awkward to browse.
-
docs/is developer documentation: the decision records, the workflow and how to set up and run the project. Text for people who use the product goes on the website. docs/is the only place the docs are edited.-
The GitHub wiki is a generated mirror of
docs/.scripts/wiki.tsturns the folder into wiki pages, with links rewritten, a sidebar, and each record's front matter shown as a status line..github/workflows/wiki.ymlpublishes it on every push todevthat touches the docs. -
The script fails on a link between docs that does not resolve, and it is a step of
pnpm check, so the link check runs on every pull request.
- The docs can be browsed and searched on the wiki, and still change only through commits.
- An edit made on the wiki in the browser is overwritten by the next publish.
- Wiki commits are made by the GitHub Actions bot in the wiki's own repository. They are not signed and are not part of the project's history.
- The wiki has to exist before the workflow can push to it: its first page is created by hand, once.
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