Skip to content

0011 workspace layout

github-actions[bot] edited this page Nov 18, 2026 · 5 revisions

The workspace is app, web and api, with engine, ui, data and contracts

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.

Context

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.

Decision

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.
  • engine and ui import nothing from the workspace. Neither reads storage or the network.
  • data and contracts import 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.md with 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.

Consequences

  • 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.

LibreBars

Clone this wiki locally