A module

Record: dev/docs/ARCHITECTURE.md §3 (what a module is), §3.4 (browser half), §14 (worked examples). This skill teaches the shape and the traps. It does not restate the rulings: follow the links.

A module is an isolated microservice in one folder. Other code sees its contract and calls its *Api token. Beyond that, by surface (record §2, §7, §10.1): a browser reads its owner's data through the owner's <name>-client and lent tokens; a module may expose a portable library (analytics' filters); and a table another module owns is read only through a declared share (SHARED_PRISMA_TABLES, the ClickHouse table-ownership policy). An undeclared read is a defect.

modules/monitor/
├── adrs/        decisions (README.md index + NNN-slug.md)
├── specs/       Gherkin: the requirements (monitor-service.feature, ...)
├── contract/    @langwatch/monitor-contract   shared by everyone
├── process/     @langwatch/monitor-process    the half the api/worker install
├── browser/     @langwatch/monitor-browser    PRIVATE, the half the UI installs
└── client/      @langwatch/<name>-client      OPTIONAL: data others read in a browser

Enterprise modules mirror this exactly under enterprise/modules/ (§3, §11).

Rules that matter

Each rule lives in the record or CLAUDE.md; this table only points at it.

Worked example: monitor (minimal)

modules/monitor is the smallest complete module. Read it in this order:

For a module with eventing, channels and tasks read modules/automation. For a module with many transports and contract files read modules/organization. For a module with a client/ package read modules/dataset/client.

New module checklist

1. Spec first: modules/<name>/specs/<name>.feature.
2. Copy modules/monitor/{contract,process}/{package.json,tsconfig*.json,vitest*.ts} and rename. Add the browser half only if there is UI.
3. Write the contract (contract skill), then the process half (process-module skill).
4. Add the catalogue entry, run pnpm generate:modules, and pnpm sync:references (new workspace packages). Run pnpm generate:readmes and write the one-paragraph description above each new page's generated block (readmes skill).
5. Prove it with an installation test that boots the installed list over memory twins with bootInstalledProcess and testPeer (record §13; apps/api/src/__tests__/share-link-engine.integration.test.ts). monitor-installation.unit.test.ts still builds with the old createApp chain (withStores(memoryStores()) and .provide, §15); do not copy it. Annotate the installer PublishedProcessModule<name, Api, Config> so the class, repositories and generated database types stay out of the emitted declarations (process-module).
6. Scoped checks only, then pnpm --filter @langwatch/<name>-process typecheck.

Traps

• Reaching into a peer because the import resolves. Ask for an *Api operation instead; adding one is a design choice, so propose it.
• Putting a shared component or hook in a "kit" or shared browser package. Kits are deleted (§3.4, §15). Shared UI goes to packages/design-system, shared data to a <name>-client.
• A contract package.json naming a runtime (prisma-client, clickhouse-client, redis-client, the eventing runtime, group-queue, process-*). The manifests policy refuses it (§3). The one eventing import a contract may make is the plain-data subpath @langwatch/eventing/tables (§2; modules/data-retention/contract).
• A second feature.json or a hand-edited generated list. The catalogue is the one map.
• Old spellings are deleted (defineServerModule, *App classes, <f>.server.ts; §15). Write defineProcessModule, *Module and <f>.module.ts.
• Peer cycles. A module may not depend back on its dependent: every cycle is refused (§5, §17; the peer-cycles policy), bar the one ruled organization and identity pair. Cut from the reactor's side with a peer subscriber (§9), and cut or list no edge without asking Alex first (§5, 2026-10-05). The module-dependencies skill walks it.

Not here

What each module owns today, its peers and its doors: modules/README.md and the module's own README.md, generated from the code (ownership skill). Read them before the module's files.

What a module may demand of its process (peers, config, secrets, availability, entitlements; §3.3): module-dependencies. Composing a process (main.ts, boot(); §4, §5): process-composition.