scripts/avatar-e2e.sh read the DEV keys through `supabase status`, started the worker on the DEV network and let the suite write and purge on DEV. Port the V1-2 sandbox runner (`db-sandbox.sh avatar-e2e`: loopback gateway, worker in a 600 env file) and the guarded suite (fixed URL, container and key issuer, per-run accounts); refusals and the positive run proven under strace in .claude/audits/2026-11-02-avatar-e2e-sandbox-only.md.
8.1 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/core-wasm/ @faunosteo/core-wasm: the Rust core in the browser (runtime, ts-rs types, frozen N-1 reader)
├─ packages/supabase/ @faunosteo/supabase: typed client, generated types, PGlite SQL tests
├─ crates/ Rust workspace: core (contracts, rules, SVG, PDF, anatomical pipeline), wasm, worker
├─ 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/* |
core-wasm, supabase (i18n, config, ui planned; pdf deleted at R4.8, domain and anatomy at R5.7) |
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 (runtime, generated types, the N-1
reader, tests). Since R2 the application depends on it at runtime (the sheet
pages load the module lazily) and the core-wasm, app and supabase
suites refuse to run without a fresh pnpm wasm:build (BUILD_STAMP).
| supabase/ | migrations, functions, seed, tests | plan Step 3 |
2. Why this layout now
- Root commands stay one word (
pnpm test:run) and delegate withpnpm -r; a developer never needs tocd. - Docker builds one filtered package (
pnpm --filter @faunosteo/app build) and copiesapps/app/dist; addingpublic-weborworkerlater 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 |
= pnpm db:sandbox avatar-e2e: real-stack end-to-end of the avatar flow, worker container + packages/supabase/tests/e2e on the throwaway stack only (docs/development/STORAGE.md §6; needs pnpm db:sandbox up fresh and pnpm worker:image) |
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 standalonetsconfig.json(no root tsconfig), tests undertests/(apps and packages alike),vitestinnodeenvironment for packages. - Dependencies are declared where they are used (
apps/app/package.json); the root holds only repository tooling (Prettier forpnpm formatanddb:types, pnpm, the Supabase CLI). - Build scripts of dependencies run only for packages listed in
pnpm-workspace.yamlonlyBuiltDependencies. - Commit scopes gain
app,workspace,ci(see CLAUDE.md).
6. Manual validation procedure (Step 2)
- From a clean clone, Node 24 active:
pnpm installcompletes with no "Ignored build scripts" warning. pnpm typecheck,pnpm test:run(367 tests),pnpm lint,pnpm buildall exit 0;apps/app/dist/containsindex.html,env.js,favicon, logos (anatomy assets are bundled from the sheet seed, Step 5).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 inCHARACTERIZATION_REPORT.md(note of 2026-10-10).grep -rn "/home/\|/Users/" apps/app/testsreturns nothing (no machine-specific path; fixtures resolve fromimport.meta.url).docker build -t faunosteo .thendocker compose upandcurl -sI http://127.0.0.1:8080/returns 200,/env.jscarrieswindow.__APP_CONFIG__.