Files
faunosteo/docs/development/WORKSPACE.md
T
bchanot e633169a00 fix(workspace): LAN exposure via host firewall — the Supabase CLI forces 0.0.0.0, so PostgreSQL / Studio / raw Mailpit close by UFW rules on the LAN interface; gateway reduced to Mailpit behind basic auth on 54325
Owner run: the CLI prints 'All services bind to 0.0.0.0' and ignored the
rootless daemon's default address; the gateway could not share 54321/54324
with 0.0.0.0 listeners. Now: Kong serves the API directly; the DEV gateway
serves only Mailpit with basic auth on <DEV host>:54325; ENVIRONMENTS.md §3
gives the exact UFW rules (interface-scoped deny on 54322-54324, two cases
by current UFW state), rollback and impact; dev:net-check proves the
allowed surfaces from a distinct Docker network (5/5 OK) and prints the
refusal checks to run from another device, since a rootless container's
traffic to the host is delivered locally and cannot see the LAN firewall.
LRN-053 corrects LRN-052.
2026-10-13 23:01:19 +02:00

7.7 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/domain/           @faunosteo/domain: canonical anatomical sheet document (Zod) + integrity rules
├─ packages/supabase/         @faunosteo/supabase: typed client, generated types, PGlite SQL tests
├─ supabase/                  Supabase CLI config, migrations, seed, pgTAP tests (docs/development/SUPABASE.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
crates/worker Rust job runner (avatars at R1, then emails, expiry, calendar sync, imports) — created at R0, replaces the planned apps/worker R0 (2026-10-12)
packages/* shared domain, anatomy, pdf, i18n, supabase, config, ui see packages/README.md

Rust workspace (plan R0, docs/development/RUST.md): Cargo.toml at the root with crates/core (library), crates/wasm (browser facade, built into packages/core-wasm/pkg) and crates/worker (binary). Every cargo command runs on the native toolchain of the development machine (pnpm rust:check, pnpm wasm:build; user-level rustup, channel of rust-toolchain.toml) or, for a reproducible run, through the builder image (:docker variants); the pnpm workspace gains packages/core-wasm (loader, generated types, proofs), whose tests skip with a notice when the module has not been built. | 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 http://<FAUNOSTEO_DEV_HOST>:5173, wired to the local Supabase stack by the DEV origin (scripts/dev.sh, ENVIRONMENTS.md)
pnpm dev:offline the same server without backend (local tool only)
pnpm dev:gateway / dev:gateway:stop the DEV gateway: Mailpit behind basic auth on the LAN address, port 54325 (ENVIRONMENTS.md §3)
pnpm dev:net-check allowed surfaces probed from a distinct Docker network; refusal checks printed for another device
pnpm supabase <args> / pnpm db:* the Supabase CLI with the DEV origin exported (scripts/supabase.sh)
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 (the Node gate)
pnpm check:all the whole pre-merge gate: native Rust check, types drift, wasm build, pnpm check, application and worker images (docs/development/RUST.md §4; no CI runs it yet)
pnpm e2e:avatar real-stack end-to-end of the avatar flow: worker container against the local Supabase stack + packages/supabase/tests/e2e (docs/development/STORAGE.md §6; needs pnpm db:start)
pnpm format Prettier on the whole repository

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

5. Conventions

  • A package has name @faunosteo/<name>, private: true, its own standalone tsconfig.json (no root tsconfig), tests under tests/ (apps and packages alike), vitest in node environment for 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 (367 tests), pnpm lint, pnpm build all exit 0; apps/app/dist/ contains index.html, env.js, favicon, logos (anatomy assets are bundled from the sheet seed, Step 5).
  3. pnpm dev, then in the browser: / (home), /new (form, species defaults to Cheval), /editor (the bundled sheet renders, 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, then import an older v2 PDF. Behaviour must match the suites listed in CHARACTERIZATION_REPORT.md (note of 2026-10-10).
  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__.