Files
faunosteo/docs/development/WORKSPACE.md
T
bchanot 8673475293 chore(workspace): move the app to apps/app under a pnpm workspace (step 2)
144 files moved with git mv (pure renames). Root package.json delegates
dev/typecheck/test:run/lint/build to the packages; Node 24 LTS and
pnpm 10.13.1 pinned (.nvmrc, .node-version, engines, packageManager,
root devDependency, engine-strict). Dockerfile builds @faunosteo/app on
node:24-alpine and copies apps/app/dist; nginx and runtime config
unchanged. CI workflow for Gitea Actions. packages/ reserved (README only).
Docs synced: WORKSPACE.md, CLAUDE.md, README, DEPLOY, CHANGELOG, plan.
271/271 tests, typecheck, lint, build green from the root.
2026-10-08 21:51:13 +02:00

5.9 KiB

Workspace

Status: plan Step 2, 2026-10-08. The repository is a pnpm workspace. The private application was moved under apps/app with git mv (history kept) and runs exactly as before; nothing else was extracted.

1. Structure

faunosteo/
├─ apps/
│  └─ app/                    @faunosteo/app — Vite + React private application (the current app)
│     ├─ src/ public/ tests/ scripts/ index.html
│     ├─ vite.config.ts vitest.config.ts tsconfig*.json eslint.config.js
│     └─ package.json         app dependencies and scripts
├─ packages/                  shared code, empty on purpose (see packages/README.md)
├─ docker/                    nginx.conf, entrypoint.sh (unchanged)
├─ docs/                      conventions, audit, development plan
├─ logos/                     brand sources
├─ .gitea/workflows/ci.yml    CI (Gitea Actions)
├─ Dockerfile                 builds apps/app, serves it with nginx (unchanged runtime)
├─ docker-compose.yml .env.example
├─ package.json               workspace root: scripts, engines, packageManager
├─ pnpm-workspace.yaml        apps/*, packages/*, approved build scripts
├─ pnpm-lock.yaml             single lockfile for the whole workspace
├─ .nvmrc .node-version       Node 24
└─ .npmrc                     supply-chain guard, engine-strict

Future units, created only by the step that needs them:

Path Role Created at
apps/public-web SSR public site (landing, practitioner profiles, search) plan Step 22
apps/worker Node job runner (emails, expiry, calendar sync, imports) plan Step 19
packages/* shared domain, anatomy, pdf, i18n, supabase, config, ui see packages/README.md
supabase/ migrations, functions, seed, tests plan Step 3

2. Why this layout now

  • Root commands stay one word (pnpm test:run) and delegate with pnpm -r; a developer never needs to cd.
  • Docker builds one filtered package (pnpm --filter @faunosteo/app build) and copies apps/app/dist; adding public-web or worker later is a second stage, not a rewrite of the Dockerfile.
  • The lockfile was already v9 (workspace-capable); it now has one importer per package.
  • Moving 144 files while the app is small costs one commit; doing it after packages and a second app exist would not.

Alternatives weighed in FRONTEND_ARCHITECTURE.md §2 (app kept at root, single Next.js app): rejected.

3. Node and pnpm

Tool Version Declared in
Node 24 (LTS) .nvmrc, .node-version, package.json engines.node >=22.12 <25, Dockerfile node:24-alpine, CI node-version-file
pnpm 10.13.1 package.json packageManager, engines.pnpm >=10.13 <11, root devDependencies.pnpm (so node_modules/.bin/pnpm exists for the root scripts), Dockerfile corepack prepare pnpm@10.13.1

Why Node 24: Node 20 reached end-of-life on 2026-04-30, the development host already runs 24, and every check of Steps 1 and 2 ran on 24.21.0. Why pnpm 10.x and not 11: pnpm 11 requires Node ≥ 22.13 and rewrites the lockfile; 10.13.1 is the version the Dockerfile was validated with (BLK-005). engine-strict=true in .npmrc makes pnpm install refuse a wrong Node, so the mismatch is visible at the first command instead of in a test.

Bootstrapping without a global install:

corepack enable          # once per machine; picks pnpm@10.13.1 from package.json
pnpm install             # or: corepack pnpm install

If corepack enable cannot write to the Node bin directory, every command also works as corepack pnpm <cmd>.

4. Commands (from the root)

Command Does
pnpm install installs the whole workspace from the lockfile
pnpm dev Vite dev server of apps/app on :5173
pnpm preview serves apps/app/dist on :4173
pnpm typecheck tsc --noEmit in every package
pnpm test:run vitest once in every package
pnpm test vitest watch for apps/app
pnpm lint ESLint, 0 warnings, in every package
pnpm build typecheck + Vite build in every package
pnpm check typecheck, test:run, lint, build in sequence (what CI runs)
pnpm format Prettier on the whole repository
pnpm scaffold:species legacy species scaffold (slated for removal)

Package-scoped: pnpm --filter @faunosteo/app <script>.

5. Conventions

  • A package has name @faunosteo/<name>, private: true for apps, its own tsconfig.json, tests under tests/ (apps) or beside sources (packages).
  • Dependencies are declared where they are used (apps/app/package.json); the root holds only repository tooling (Prettier, pnpm).
  • Build scripts of dependencies run only for packages listed in pnpm-workspace.yaml onlyBuiltDependencies.
  • Commit scopes gain app, workspace, ci (see CLAUDE.md).

6. Manual validation procedure (Step 2)

  1. From a clean clone, Node 24 active: pnpm install completes with no "Ignored build scripts" warning.
  2. pnpm typecheck, pnpm test:run (271 tests), pnpm lint, pnpm build all exit 0; apps/app/dist/ contains index.html, env.js, pathology-editor.html, species/equine/{Horse.svg,Horse_head.svg,pathologies.json}.
  3. pnpm dev, then in the browser: / (home), /new (form, species defaults to Cheval), /editor (SVG loads, click a hinge, a hip, a spine zone, the head trigger; pickers open; findings picker lists the zone), export the PDF, go back to / and import it; /svg-editor loads a project SVG; /pathology-editor.html loads the pre-wired horse. Behaviour must match CHARACTERIZATION_REPORT.md.
  4. grep -rn "/home/\|/Users/" apps/app/tests returns nothing (no machine-specific path; fixtures resolve from import.meta.url).
  5. docker build -t faunosteo . then docker compose up and curl -sI http://127.0.0.1:8080/ returns 200, /env.js carries window.__APP_CONFIG__.