nest-process-docs

Business Process Documentation as Code for NestJS applications.

Status: early development (pre-release). Public API and PDS schema are not yet stable.

Where Swagger answers "what endpoints exist?", nest-process-docs answers "how does the system achieve a business goal?" — see RFC-0001 for the full design.

Quick start

npm install @nest-process-docs/core

import { defineProcess, ProcessStep, ProcessDocsModule } from '@nest-process-docs/core';

export const PlaceOrder = defineProcess({
  id: 'place-order',
  title: 'Place Order',
  actors: ['customer'],
});

@Controller('orders')
class OrdersController {
  @Post()
  @ProcessStep(PlaceOrder, { order: 10 })
  createOrder() { /* ... */ }
}

@Module({ imports: [ProcessDocsModule.forRoot()] })
class AppModule {}

curl http://localhost:3000/process-docs   # raw PDS JSON
open http://localhost:3000/process-docs/ui  # the documentation UI

See @nest-process-docs/core's README for the full walkthrough (multi-actor processes, non-API steps, decisions, validation), and @nest-process-docs/cli's README for generate/validate/serve.

You can also preview the docs offline, without running your NestJS app at all:

npx nest-process-docs generate --out process-docs.json
npx nest-process-docs serve --file process-docs.json

Already using @nestjs/swagger? One extra line in main.ts cross-references each API node with its real Swagger operation (summary, request body, responses) in the UI:

const document = SwaggerModule.createDocument(app, swaggerConfig);
SwaggerModule.setup('api', app, document);
ProcessDocsModule.attachSwaggerDocument(document); // new

Packages

| Package | Description | | --- | --- | | @nest-process-docs/core | defineProcess(), @ProcessStep(), ProcessDocsModule — the package you install | | @nest-process-docs/cli | generate/validate/serve against a running instance or an exported file | | @nest-process-docs/scanner | Discovery, reflection, validation, PDS assembly — core's internal engine | | @nest-process-docs/common | Shared PDS and validation types | | @nest-process-docs/ui | React documentation viewer — bundled into ProcessDocsModule (/process-docs/ui); also runs standalone via serve or its own dev server | | examples | A working sample NestJS app demonstrating real usage |

Development

npm install
npm run build   # build all packages
npm run test    # run all test suites
npm run lint
npm run typecheck

Each package also runs independently, e.g. npm run test --workspace=packages/core.

Running the example app

npm run build --workspace=packages/ui       # UI must be built at least once — core resolves its dist at runtime
npm run build --workspace=packages/examples
node packages/examples/dist/main.js         # serves /process-docs and /process-docs/ui on :3000

For UI development specifically (fast HMR instead of a full rebuild per change), run its Vite dev server against the example app instead:

npm run dev --workspace=packages/ui         # :5173, proxies /process-docs to :3000

What's implemented

• ✅ defineProcess(), @ProcessStep(), and the full validation ruleset (RFC-0001 §10)
• ✅ ProcessDocsModule — scans and validates on bootstrap, serves the PDS, never blocks app startup on a documentation bug
• ✅ CLI generate/validate/serve (offline file mode and live-proxy mode)
• ✅ UI — navigation, overview, a linear journey canvas, a Context Drawer per node type, and client-side search
• ✅ UI bundled into ProcessDocsModule, served automatically at /process-docs/ui — no CLI or separate dev server needed
• ✅ Swagger cross-referencing — API nodes resolve their swaggerOperationId; the Context Drawer lazily loads and renders the real summary, request body shape, and responses from the attached Swagger document

License

MIT