The repository tree

One pnpm workspace (TypeScript), Go services and Python services beside it. The rule that names every package: where the code runs, or what it declares (ARCHITECTURE.md §2). The tree is the contract; when this skill and the linter disagree, the linter wins (§17).

The map

Rules that matter

1. Apps hold no product code. apps/api/src/main.ts boots a server and serves the installed modules. If you are writing behaviour in an app, it belongs in a module.
2. Feature code in packages/ is a defect. If the code names a product subject (trace, monitor, invite), it is a module.
3. One subject, one owning module. modules/catalogue.json maps every subject to exactly one module. Another module reaches the subject through the owner's *Api and contract only (§3). modules/README.md prints that map with each module's tables and peers, and every module has its own README.md (ownership skill).
4. The prefix tells you the graph. Nothing browser-* in a server graph; no process* package in a web graph (§2). A contract imports the light @langwatch/module core, plus only the portable surfaces §2 names (config and secret handles, errors, the span vocabulary, @langwatch/eventing/tables); never a runtime.
5. Generated lists are never edited. The module list each app carries (process halves in apps/{api,worker,tasks}/src/process-modules.generated.ts; browser halves in apps/ui/src/browser-modules.generated.ts) is written by pnpm generate:modules from the catalogue. Add a module by editing modules/catalogue.json, then run the generator.
6. Shared browser code has three homes, no kits. Component: the design system. Pure domain logic: the owner's contract. Data: the owner's <name>-client (§3.4). A *-browser-kit package is a deleted spelling.
7. A package named by a module has four suffixes: @langwatch/<f>-contract, -process, -browser, -client. Enterprise ones carry enterprise- in the name (@langwatch/enterprise-billing-process).
8. A portable library both halves import sits inside the owning module (modules/analytics/filters exists; the record also names modules/trace/query-language, not in the tree yet), never in packages/ (§2). It is the one sanctioned folder beside the four halves, specs/ and adrs/.

Placement test

Ask in order. Stop at the first yes.

If no row fits, that is a design question. Do not invent a folder: ask.

Worked example: modules/monitor

The smallest full module. Read it before inventing a layout.

modules/monitor/
├── adrs/  specs/
├── contract/src/    monitor.api.ts  monitor.errors.ts  monitor.trpc.ts  index.ts
├── process/src/     monitor.module.ts  index.ts  app/  services/  repositories/
│                    rules/  transport/
└── browser/src/     monitor.web.ts  model/  behavior/  ui/{elements,blocks,sections}

Its catalogue entry is one line of data: id: "monitor", root: "modules/monitor", classification: "core", subjects: ["monitor"]. modules/organization owns seven subjects (group, invite, membership, organization, team, ...), so one module may own several subjects. modules/automation adds eventing/, channels/ and migrations/ to process/src/; add a folder only when the module has that kind of thing.

Traps

• Reading dist/ or *.generated.ts as source. Both are outputs. Fix the catalogue or the source, regenerate.
• A new folder under a module root. The root holds the four halves, a module-owned portable library, specs/ and adrs/ only. The folder grammar is packages/oxlint-rules/grammar/feature-layout-policy.mjs; the linter refuses a stray folder (see the linting skill).
• A folder that keeps growing. Past the source-folder-shape budget it is grouped into features/<concern>/, one level only (§3.4). The number is the policy's (FOLDER_BUDGET in its source), not this skill's.
• A second config.ts or a dev-only branch in an app. The same main.ts runs on a laptop, in CI and in production; only the parsed environment differs.
• Putting a table or a query in a module that does not own the subject. Owning a table means owning every query against it; another module reads it only through a declared share (ownership skill).
• A utils/, lib/, helpers/, domain/ folder. Deleted spellings. Pure decisions go in rules/; behaviour in services/.
• Naming a package *-web. Today that means an internal console under apps/*-web; module browser halves are *-browser.

Links

• dev/docs/ARCHITECTURE.md §1 (the product), §2 (package family), §3 (a module), §3.4 (browser half, no kits), §16 (names in flight), §18 (Nx runs the tasks).
• The generated pages: modules/README.md, packages/README.md, apps/README.md, the enterprise/ indexes and one per module; ownership reads them, readmes maintains them.
• The module skills: module for anatomy, module-client for clients, browser-module for the browser half.
• Process composition and what a module may demand (peers, config, stores, entitlements): the module-dependencies and process-composition skills. Not taught here.