Repository navigation
0011 workspace layout
Status: accepted · Implementation: done · Date: 2026-11-18
From LibreLifts ADR 0020. Stack as pinned there on 2026-11-18: Node 26, pnpm 12, Biome, Vitest, Expo 58, TanStack Start, Fastify 5, Drizzle 1.0 release candidate, Postgres 18. As built, 2026-11-18: the four packages exist. The three apps do not yet, so this stays planned. apps/app was added on 2026-11-18; the website and the API are still to come. apps/api was added on 2026-11-18; the website is still to come. Built 2026-11-18: apps/web was the last of the three apps and four packages.
LibreBars has an app, a website and an API, and code that more than one of them needs.
LibreLifts arrived at a layout for exactly this after trying another: a package called core
collected whatever had no other home, and was replaced by packages whose names say what
belongs in them.
One pnpm workspace with three apps and four packages, each with one job:
| Path | What it is |
|---|---|
apps/app |
The Expo app: the tracker (0007). |
apps/web |
The website (0025). |
apps/api |
The Fastify API (0015). |
packages/engine |
The rules of the log, as pure functions (0012). |
packages/ui |
The look shared by web and app (0013). |
packages/data |
Seed and reference data (0023). |
packages/contracts |
The shapes of the API's requests and responses, shared by api, web and app. |
- Apps import packages; packages never import apps, and apps do not import each other.
-
engineanduiimport nothing from the workspace. Neither reads storage or the network. dataandcontractsimport nothing from the workspace either.- Packages are consumed as TypeScript source, with no build step of their own. Node runs TypeScript directly; the apps' bundlers compile it.
- A folder is added when the first thing that belongs in it is built, not before.
-
Each app has its own
AGENTS.mdwith the rules that apply only there. - Packages are named
@librebars/<name>. - The workspace holds back packages published very recently, through pnpm's release-age setting. A package that is needed sooner is listed as an exception, by exact version.
- Where something belongs is answered by the name of the package.
- A rule that only the engine and the interface share has no package. If one appears, it gets a package with a name that says what it holds.
- With no build step, a package cannot be published to a registry as it is. Nothing needs that yet.
- A new dependency can be blocked for a few days by the release-age hold. That is the point of it.
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