Skip to content
Skills Library
Programming · Learning & explanation

module

/module

What a LangWatch module is and how to start one: the four packages (contract, process, browser, client), modules/catalogue.json, pnpm generate:modules, the specs/ and adrs/ folders, the dependency direction between halves, and what another module may import. Use when someone says 'new module', 'add a module', 'where does this feature live', 'which half does this go in', 'module anatomy', 'install a module', 'can I import from another module', 'split this out of X', or opens modules/<name>/.

Repository
langwatch ↗
Licence
Apache-2.0
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

What a LangWatch module is and how to start one: the four packages (contract, process, browser, client), modules/catalogue.json, pnpm generate:modules, the specs/ and adrs/ folders, the dependency direction between halves, and what another module may import. Use when someone says 'new module', 'add a module', 'where does this feature live', 'which half does this go in', 'module anatomy', 'install a module', 'can I import from another module', 'split this out of X', or opens modules/<name>/.

Triggers from the description

new moduleadd a modulewhere does this feature livewhich half does this go inmodule anatomyinstall a modulecan I import from another modulesplit this out of X
Original author description

What a LangWatch module is and how to start one: the four packages (contract, process, browser, client), modules/catalogue.json, pnpm generate:modules, the specs/ and adrs/ folders, the dependency direction between halves, and what another module may import. Use when someone says 'new module', 'add a module', 'where does this feature live', 'which half does this go in', 'module anatomy', 'install a module', 'can I import from another module', 'split this out of X', or opens modules/<name>/.

How it works

  1. Rules that matter
  2. Worked example: monitor (minimal)
  3. New module checklist
  4. Traps
  5. Not here
Original SKILL.md headings · 111 lines, 841 words
SKILL.md preview
---
name: module
description: "What a LangWatch module is and how to start one: the four packages (contract, process, browser, client), modules/catalogue.json, pnpm generate:modules, the specs/ and adrs/ folders, the dependency direction between halves, and what another module may import. Use when someone says 'new module', 'add a module', 'where does this feature live', 'which half does this go in', 'module anatomy', 'install a module', 'can I import from another module', 'split this out of X', or opens modules/<name>/."
user-invocable: true
---

# 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.

| Rule                                                                                    | Record       |
| --------------------------------------------------------------------------------------- | ------------ |
| Dependency direction: apps -> process/browser -> contract, never sideways               | §3           |
| Others import only your contract and call your `*Api` token (plus the surfaces above)   | §3, §7       |
| One owner per subject, mapped in `modules/catalogue.json`                               | §3           |
| Install by catalogue entry + `pnpm generate:modules`; never hand-edit a generated list  | §1, §5       |
| Specs first, error paths included                                                       | CLAUDE.md    |
| Decisions in `adrs/` with a README row; comments five lines max                         | CLAUDE.md    |
| Package names, `private`, source-resolved `main`: copy `modules/monitor/*/package.json` | (convention) |
| Process exports the installer and transports only (`process-module`)                    | §3.2         |
| Browser exports `./declaration` only                                                    | §3.4         |
| Past 30 source files, group into `features/<concern>/`, one level                       | §3.4         |

## Worked example: monitor (minimal)

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

| Step | File                                           | What it shows                                         |
| ---- | ---------------------------------------------- | ----------------------------------------------------- |
| 1    | `modules/catalogue.json` (entry `"monitor"`)   | id, root, `classification`, `subjects`                |
| 2    | `contract/src/monitor.api.ts`                  | the `MonitorApi` interface and token                  |
| 3    | `contract/src/monitor.errors.ts`               | `HandledError` subclasses                             |
| 4    | `contract/src/monitor.trpc.ts`                 | every procedure declared once                         |
| 5    | `process/src/monitor.module.ts`                | the installer: repositories, module class, transports |
| 5a   | `process/src/app/monitor.app.ts`               | the module class, `MonitorModule` (§3.2)              |
| 6    | `process/src/transport/monitor.{rest,trpc}.ts` | permission and handler per route                      |
| 7    | `process/src/repositories/`                    | interface, `prisma/`, `memory/`, registry             |
| 8    | `process/src/services/monitor.service.ts`      | behaviour over the repository                         |

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`.

Versions

The database has no other skills named module.

Database snapshot: 13.11.2026 · package version 147c8d048fc0 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100repo-tree
    Where a thing lives in the LangWatch tree and what each top-level folder is for. Use when someone says 'where does this go', 'which package', 'new package', 'is this a module or a package', 'apps vs modules vs packages vs services vs tools', 'what is a generated module list',…
  • 100ownership
    Where a change belongs in LangWatch: find the owning module of a subject, table or route from the generated READMEs (modules/README.md and each module page), refuse an edit that reaches into another module, and name the *Api operation to call or the new operation to ask for. Use…
  • 100add-module
    Creates a new module in this solution with its project, database schema, registration, migrations resource and test project, and its contracts project once another module needs one. Use when asked for a new module or bounded context, including in a solution that has no modules yet.
  • 100architecture
    This skill should be used when the user asks to "map the architecture", "show module dependencies", "analyze coupling", "dependency graph", "how are modules connected", "module boundaries", or mentions keywords related to architectural analysis and dependency mapping.
  • 95module-scaffold
    Use when creating a brand new module file in modules/ for a new tool category. Generates the boilerplate with correct array prefix, install_module_<name>() function, and ensures it integrates with install.sh, profiles, and MCP server. Triggers on "new module", "add a module for…
  • 100module-boundary-review
    Evidence-based review of module/package/service boundaries using measured coupling (fan-in, fan-out, instability, import cycles) plus git co-change history. Use when deciding where code should live, before adding a cross-module dependency, when a change keeps touching several…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.