# nestjs/workflows architecture

> Architecture diagram of the GitHub repository nestjs/workflows, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nestjs/workflows
- Repository: https://github.com/nestjs/workflows

## Overview

This is a NestJS durable-workflows module. Applications define workflows and use the client to start, signal, inspect, and manage instances; background workers claim instances, replay journaled async execution, and persist progress so runs can survive restarts. The package also provides schedules, timers, retries, compensations, child workflows, lifecycle events, payload codecs, and in-memory, MySQL, and PostgreSQL storage options. The map reflects documented capabilities and indexed references; unsampled implementation details are represented at their enclosing directory where appropriate.

Main entry points: [`lib/storage/workflow.storage.ts`](https://github.com/nestjs/workflows/blob/master/lib/storage/workflow.storage.ts) (Storage registry), [`lib/services/workflow-execution.service.ts`](https://github.com/nestjs/workflows/blob/master/lib/services/workflow-execution.service.ts) (Journaled execution), [`lib/services/workflow-client.service.ts`](https://github.com/nestjs/workflows/blob/master/lib/services/workflow-client.service.ts) (Workflow client), [`lib/services/workflow-worker.service.ts`](https://github.com/nestjs/workflows/blob/master/lib/services/workflow-worker.service.ts) (Background worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Workflow API"]
  node_definitions["Workflow definitions"]
  node_client["Workflow client"]
  node_registry["Workflow registry"]
end

subgraph group_runtime["Execution runtime"]
  node_worker["Background worker"]
  node_execution["Journaled execution"]
  node_leased["Leased worker core<br/>[leased-worker.ts]"]
  node_retry["Retry policies<br/>[retry.ts]"]
end

subgraph group_durability["Persistence"]
  node_storage["Storage registry"]
  node_encoded["Encoded store"]
  node_memory[("In-memory store")]
  node_mysql[("MySQL store")]
  node_postgres[("PostgreSQL store")]
  node_codecs["Payload codecs<br/>[payload-codecs.ts]"]
end

subgraph group_extensions["Scheduling and events"]
  node_schedules["Schedule service"]
  node_scheduler["Schedule engine<br/>[scheduler.ts]"]
  node_cqrs["Workflow event routes"]
  node_events["Lifecycle events"]
end

subgraph group_foundation["Core utilities"]
  node_clock["Clock<br/>[clock.ts]"]
  node_instance["Instance construction"]
  node_duration["Duration parsing<br/>[duration.ts]"]
  node_normalization["JSON normalization<br/>[normalize.util.ts]"]
end

node_application(("Nest application"))

node_application -->|"defines workflows"| node_definitions
node_application -->|"starts and manages"| node_client
node_worker -->|"runs executions"| node_execution
node_worker -->|"emits events"| node_events
node_worker -->|"uses leases"| node_leased
node_execution -->|"resolves retries"| node_retry
node_client -->|"constructs instances"| node_instance
node_instance -->|"normalizes input"| node_normalization
node_instance -->|"parses timeouts"| node_duration
node_execution -->|"parses durations"| node_duration
node_storage -->|"wraps store"| node_encoded
node_storage -->|"defaults to"| node_memory
node_storage -->|"configures codecs"| node_codecs
node_encoded -->|"encodes payloads"| node_codecs
node_mysql -->|"registers store"| node_storage
node_postgres -->|"registers store"| node_storage
node_schedules -->|"uses scheduler"| node_scheduler
node_schedules -->|"starts scheduled runs"| node_client
node_cqrs -->|"routes workflow events"| node_definitions
node_client -->|"uses clock"| node_clock
node_execution -->|"reads time"| node_clock
node_application -.->|"may select"| node_mysql
node_application -.->|"may select"| node_postgres

click node_definitions "https://github.com/nestjs/workflows/blob/master/lib/decorators/workflow.decorator.ts"
click node_client "https://github.com/nestjs/workflows/blob/master/lib/services/workflow-client.service.ts"
click node_registry "https://github.com/nestjs/workflows/blob/master/lib/services/workflow-registry.service.ts"
click node_worker "https://github.com/nestjs/workflows/blob/master/lib/services/workflow-worker.service.ts"
click node_execution "https://github.com/nestjs/workflows/blob/master/lib/services/workflow-execution.service.ts"
click node_leased "https://github.com/nestjs/workflows/blob/master/lib/core/workers/leased-worker.ts"
click node_retry "https://github.com/nestjs/workflows/blob/master/lib/core/retries/retry.ts"
click node_storage "https://github.com/nestjs/workflows/blob/master/lib/storage/workflow.storage.ts"
click node_encoded "https://github.com/nestjs/workflows/blob/master/lib/storage/encoded-workflow.store.ts"
click node_memory "https://github.com/nestjs/workflows/blob/master/lib/stores/in-memory-workflow.store.ts"
click node_mysql "https://github.com/nestjs/workflows/blob/master/lib/mysql/mysql-workflow.store.ts"
click node_postgres "https://github.com/nestjs/workflows/blob/master/lib/postgres/postgres-workflow.store.ts"
click node_codecs "https://github.com/nestjs/workflows/blob/master/lib/core/codecs/payload-codecs.ts"
click node_schedules "https://github.com/nestjs/workflows/blob/master/lib/services/workflow-schedules.service.ts"
click node_scheduler "https://github.com/nestjs/workflows/blob/master/lib/core/scheduling/scheduler.ts"
click node_cqrs "https://github.com/nestjs/workflows/blob/master/lib/cqrs/workflows-cqrs.module.ts"
click node_events "https://github.com/nestjs/workflows/blob/master/lib/events/workflow-events.service.ts"
click node_clock "https://github.com/nestjs/workflows/blob/master/lib/core/time/clock.ts"
click node_instance "https://github.com/nestjs/workflows/blob/master/lib/utils/new-instance.util.ts"
click node_duration "https://github.com/nestjs/workflows/blob/master/lib/core/time/duration.ts"
click node_normalization "https://github.com/nestjs/workflows/blob/master/lib/utils/normalize.util.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_definitions,node_client,node_registry toneBlue
class node_worker,node_execution,node_leased,node_retry toneAmber
class node_storage,node_encoded,node_memory,node_mysql,node_postgres,node_codecs toneMint
class node_schedules,node_scheduler,node_cqrs,node_events toneRose
class node_clock,node_instance,node_duration,node_normalization,node_application toneIndigo
```

## Components

### Workflow API

- [Workflow definitions](https://github.com/nestjs/workflows/blob/master/lib/decorators/workflow.decorator.ts): `lib/decorators/workflow.decorator.ts`
- [Workflow client](https://github.com/nestjs/workflows/blob/master/lib/services/workflow-client.service.ts): `lib/services/workflow-client.service.ts`
- [Workflow registry](https://github.com/nestjs/workflows/blob/master/lib/services/workflow-registry.service.ts): `lib/services/workflow-registry.service.ts`

### Execution runtime

- [Background worker](https://github.com/nestjs/workflows/blob/master/lib/services/workflow-worker.service.ts): `lib/services/workflow-worker.service.ts`
- [Journaled execution](https://github.com/nestjs/workflows/blob/master/lib/services/workflow-execution.service.ts): `lib/services/workflow-execution.service.ts`
- [Leased worker core](https://github.com/nestjs/workflows/blob/master/lib/core/workers/leased-worker.ts): `lib/core/workers/leased-worker.ts`
- [Retry policies](https://github.com/nestjs/workflows/blob/master/lib/core/retries/retry.ts): `lib/core/retries/retry.ts`

### Persistence

- [Storage registry](https://github.com/nestjs/workflows/blob/master/lib/storage/workflow.storage.ts): `lib/storage/workflow.storage.ts`
- [Encoded store](https://github.com/nestjs/workflows/blob/master/lib/storage/encoded-workflow.store.ts): `lib/storage/encoded-workflow.store.ts`
- [In-memory store](https://github.com/nestjs/workflows/blob/master/lib/stores/in-memory-workflow.store.ts): `lib/stores/in-memory-workflow.store.ts`
- [MySQL store](https://github.com/nestjs/workflows/blob/master/lib/mysql/mysql-workflow.store.ts): `lib/mysql/mysql-workflow.store.ts`
- [PostgreSQL store](https://github.com/nestjs/workflows/blob/master/lib/postgres/postgres-workflow.store.ts): `lib/postgres/postgres-workflow.store.ts`
- [Payload codecs](https://github.com/nestjs/workflows/blob/master/lib/core/codecs/payload-codecs.ts): `lib/core/codecs/payload-codecs.ts`

### Scheduling and events

- [Schedule service](https://github.com/nestjs/workflows/blob/master/lib/services/workflow-schedules.service.ts): `lib/services/workflow-schedules.service.ts`
- [Schedule engine](https://github.com/nestjs/workflows/blob/master/lib/core/scheduling/scheduler.ts): `lib/core/scheduling/scheduler.ts`
- [Workflow event routes](https://github.com/nestjs/workflows/blob/master/lib/cqrs/workflows-cqrs.module.ts): `lib/cqrs/workflows-cqrs.module.ts`
- [Lifecycle events](https://github.com/nestjs/workflows/blob/master/lib/events/workflow-events.service.ts): `lib/events/workflow-events.service.ts`

### Core utilities

- [Clock](https://github.com/nestjs/workflows/blob/master/lib/core/time/clock.ts): `lib/core/time/clock.ts`
- [Instance construction](https://github.com/nestjs/workflows/blob/master/lib/utils/new-instance.util.ts): `lib/utils/new-instance.util.ts`
- [Duration parsing](https://github.com/nestjs/workflows/blob/master/lib/core/time/duration.ts): `lib/core/time/duration.ts`
- [JSON normalization](https://github.com/nestjs/workflows/blob/master/lib/utils/normalize.util.ts): `lib/utils/normalize.util.ts`

### Other components

- **Nest application**

## Connections

- Nest application → Workflow definitions: defines workflows (evidence: `README.md`)
- Nest application → Workflow client: starts and manages (evidence: `README.md`)
- Background worker → Journaled execution: runs executions (evidence: `lib/services/workflow-worker.service.ts`)
- Background worker → Lifecycle events: emits events (evidence: `lib/services/workflow-worker.service.ts`)
- Background worker → Leased worker core: uses leases (evidence: `lib/services/workflow-worker.service.ts`)
- Journaled execution → Retry policies: resolves retries (evidence: `lib/services/workflow-execution.service.ts`)
- Workflow client → Instance construction: constructs instances (evidence: `lib/services/workflow-client.service.ts`)
- Instance construction → JSON normalization: normalizes input (evidence: `lib/utils/new-instance.util.ts`)
- Instance construction → Duration parsing: parses timeouts (evidence: `lib/utils/new-instance.util.ts`)
- Journaled execution → Duration parsing: parses durations (evidence: `lib/services/workflow-execution.service.ts`)
- Storage registry → Encoded store: wraps store (evidence: `lib/storage/workflow.storage.ts`)
- Storage registry → In-memory store: defaults to (evidence: `lib/storage/workflow.storage.ts`)
- Storage registry → Payload codecs: configures codecs (evidence: `lib/storage/workflow.storage.ts`)
- Encoded store → Payload codecs: encodes payloads (evidence: `lib/storage/encoded-workflow.store.ts`)
- MySQL store → Storage registry: registers store (evidence: `lib/mysql/mysql-workflow.store.ts`)
- PostgreSQL store → Storage registry: registers store (evidence: `lib/postgres/postgres-workflow.store.ts`)
- Schedule service → Schedule engine: uses scheduler (evidence: `lib/services/workflow-schedules.service.ts`)
- Schedule service → Workflow client: starts scheduled runs (evidence: `lib/services/workflow-schedules.service.ts`)
- Workflow event routes → Workflow definitions: routes workflow events
- Workflow client → Clock: uses clock (evidence: `lib/services/workflow-client.service.ts`)
- Journaled execution → Clock: reads time (evidence: `lib/services/workflow-execution.service.ts`)
- Nest application → MySQL store: may select (evidence: `README.md`)
- Nest application → PostgreSQL store: may select (evidence: `README.md`)
