# yasir2000/bpmninja architecture

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

- Interactive diagram: https://gitdiagram.com/yasir2000/bpmninja
- Repository: https://github.com/yasir2000/bpmninja

## Overview

BPMNinja is a Rust BPMN 2.0 workflow engine with a REST server, persistence backends, a Tauri desktop UI, and an external-task client. The principal workflow is BPMN XML parsing and validation, deployment/model checking, process execution, and interaction through API/UI or service-task workers, with state and history persisted. The graph also preserves timer/message handling, monitoring, archived history, and desktop push updates. Several subsystem links reflect README documentation; unsampled implementation details are not asserted beyond those documented relationships.

Main entry points: [`engine-server/src/server/mod.rs`](https://github.com/yasir2000/bpmninja/blob/main/engine-server/src/server/mod.rs) (REST API server), [`desktop-tauri/src/App.tsx`](https://github.com/yasir2000/bpmninja/blob/main/desktop-tauri/src/App.tsx) (Operations UI), [`engine-core/src/engine/mod.rs`](https://github.com/yasir2000/bpmninja/blob/main/engine-core/src/engine/mod.rs) (Workflow engine), [`engine-core/src/engine/executor/mod.rs`](https://github.com/yasir2000/bpmninja/blob/main/engine-core/src/engine/executor/mod.rs) (Token executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["Model and deploy"]
  node_bpmn["BPMN parser<br/>[parser.rs]"]
  node_collab["Collaboration metadata<br/>[collaboration.rs]"]
  node_modelcheck["Deploy model check<br/>[model_check.rs]"]
end

subgraph group_runtime["Workflow runtime"]
  node_engine["Workflow engine<br/>[mod.rs]"]
  node_executor["Token executor<br/>[mod.rs]"]
  node_events["Events and boundaries"]
  node_service["Service tasks<br/>[service_task.rs]"]
  node_timers["Timer scheduler<br/>[timer_processor.rs]"]
end

subgraph group_storage["Persistence and history"]
  node_history["Instance history<br/>[mod.rs]"]
  node_memory[("Memory persistence<br/>[lib.rs]")]
  node_nats[("NATS persistence<br/>[client.rs]")]
end

subgraph group_api["API and workers"]
  node_server["REST API server<br/>[mod.rs]"]
  node_taskclient["Task client"]
  node_agent["Sample worker<br/>[main.rs]"]
end

subgraph group_ui["Desktop operations"]
  node_desktopbridge["Desktop bridge<br/>[sse_consumer.rs]"]
  node_desktop["Operations UI<br/>[App.tsx]"]
  node_modeler["BPMN modeler<br/>[ModelerPage.tsx]"]
  node_instances["Instance tracking<br/>[InstancesPage.tsx]"]
  node_tasks["User tasks"]
  node_monitoring["Monitoring and logs<br/>[MonitoringPage.tsx]"]
  node_archiveui["History search<br/>[HistoryPage.tsx]"]
end

node_operator(("Workflow operator"))
node_worker(("External worker"))

node_operator -->|"models processes"| node_modeler
node_modeler -.->|"deploys definitions"| node_server
node_server -.->|"parses deployments"| node_bpmn
node_bpmn -->|"parses collaboration"| node_collab
node_server -->|"checks deployments"| node_modelcheck
node_server -.->|"routes workflow API"| node_engine
node_engine -->|"executes tokens"| node_executor
node_executor -->|"handles event work"| node_events
node_executor -->|"runs service tasks"| node_service
node_engine -.->|"schedules timers"| node_timers
node_engine -->|"records lifecycle"| node_history
node_engine -.->|"persists state"| node_memory
node_engine -.->|"persists state"| node_nats
node_worker -->|"processes work"| node_taskclient
node_taskclient -.->|"fetches and locks"| node_server
node_agent -.->|"requests tasks"| node_server
node_operator -->|"operates workflows"| node_desktop
node_desktop -->|"opens modeler"| node_modeler
node_desktop -->|"opens instances"| node_instances
node_desktop -->|"opens tasks"| node_tasks
node_desktop -->|"opens monitoring"| node_monitoring
node_desktop -->|"opens history"| node_archiveui
node_server -.->|"streams SSE updates"| node_desktopbridge
node_desktopbridge -->|"emits UI events"| node_desktop
node_server -.->|"serves archived history"| node_archiveui

click node_bpmn "https://github.com/yasir2000/bpmninja/blob/main/bpmn-parser/src/parser.rs"
click node_collab "https://github.com/yasir2000/bpmninja/blob/main/bpmn-parser/src/collaboration.rs"
click node_modelcheck "https://github.com/yasir2000/bpmninja/blob/main/engine-server/src/server/model_check.rs"
click node_engine "https://github.com/yasir2000/bpmninja/blob/main/engine-core/src/engine/mod.rs"
click node_executor "https://github.com/yasir2000/bpmninja/blob/main/engine-core/src/engine/executor/mod.rs"
click node_events "https://github.com/yasir2000/bpmninja/blob/main/engine-core/src/engine/event_subprocess.rs"
click node_service "https://github.com/yasir2000/bpmninja/blob/main/engine-core/src/engine/service_task.rs"
click node_timers "https://github.com/yasir2000/bpmninja/blob/main/engine-core/src/engine/timer_processor.rs"
click node_history "https://github.com/yasir2000/bpmninja/blob/main/engine-core/src/history/mod.rs"
click node_memory "https://github.com/yasir2000/bpmninja/blob/main/persistence-memory/src/lib.rs"
click node_nats "https://github.com/yasir2000/bpmninja/blob/main/persistence-nats/src/client.rs"
click node_server "https://github.com/yasir2000/bpmninja/blob/main/engine-server/src/server/mod.rs"
click node_taskclient "https://github.com/yasir2000/bpmninja/blob/main/bpmn-ninja-external-task-client/src/ExternalTaskClient.ts"
click node_agent "https://github.com/yasir2000/bpmninja/blob/main/agent-orchestrator/src/main.rs"
click node_desktopbridge "https://github.com/yasir2000/bpmninja/blob/main/desktop-tauri/src-tauri/src/sse_consumer.rs"
click node_desktop "https://github.com/yasir2000/bpmninja/blob/main/desktop-tauri/src/App.tsx"
click node_modeler "https://github.com/yasir2000/bpmninja/blob/main/desktop-tauri/src/features/modeler/ModelerPage.tsx"
click node_instances "https://github.com/yasir2000/bpmninja/blob/main/desktop-tauri/src/features/instances/InstancesPage.tsx"
click node_tasks "https://github.com/yasir2000/bpmninja/blob/main/desktop-tauri/src/features/tasks/PendingTasksPage.tsx"
click node_monitoring "https://github.com/yasir2000/bpmninja/blob/main/desktop-tauri/src/features/monitoring/MonitoringPage.tsx"
click node_archiveui "https://github.com/yasir2000/bpmninja/blob/main/desktop-tauri/src/features/history/HistoryPage.tsx"

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_bpmn,node_collab,node_modelcheck toneBlue
class node_engine,node_executor,node_events,node_service,node_timers toneAmber
class node_history,node_memory,node_nats toneMint
class node_server,node_taskclient,node_agent,node_worker toneRose
class node_desktopbridge,node_desktop,node_modeler,node_instances,node_tasks,node_monitoring,node_archiveui,node_operator toneIndigo
```

## Components

### Model and deploy

- [BPMN parser](https://github.com/yasir2000/bpmninja/blob/main/bpmn-parser/src/parser.rs): `bpmn-parser/src/parser.rs`
- [Collaboration metadata](https://github.com/yasir2000/bpmninja/blob/main/bpmn-parser/src/collaboration.rs): `bpmn-parser/src/collaboration.rs`
- [Deploy model check](https://github.com/yasir2000/bpmninja/blob/main/engine-server/src/server/model_check.rs): `engine-server/src/server/model_check.rs`

### Workflow runtime

- [Workflow engine](https://github.com/yasir2000/bpmninja/blob/main/engine-core/src/engine/mod.rs): `engine-core/src/engine/mod.rs`
- [Token executor](https://github.com/yasir2000/bpmninja/blob/main/engine-core/src/engine/executor/mod.rs): `engine-core/src/engine/executor/mod.rs`
- [Events and boundaries](https://github.com/yasir2000/bpmninja/blob/main/engine-core/src/engine/event_subprocess.rs): `engine-core/src/engine/event_subprocess.rs`
- [Service tasks](https://github.com/yasir2000/bpmninja/blob/main/engine-core/src/engine/service_task.rs): `engine-core/src/engine/service_task.rs`
- [Timer scheduler](https://github.com/yasir2000/bpmninja/blob/main/engine-core/src/engine/timer_processor.rs): `engine-core/src/engine/timer_processor.rs`

### Persistence and history

- [Instance history](https://github.com/yasir2000/bpmninja/blob/main/engine-core/src/history/mod.rs): `engine-core/src/history/mod.rs`
- [Memory persistence](https://github.com/yasir2000/bpmninja/blob/main/persistence-memory/src/lib.rs): `persistence-memory/src/lib.rs`
- [NATS persistence](https://github.com/yasir2000/bpmninja/blob/main/persistence-nats/src/client.rs): `persistence-nats/src/client.rs`

### API and workers

- [REST API server](https://github.com/yasir2000/bpmninja/blob/main/engine-server/src/server/mod.rs): `engine-server/src/server/mod.rs`
- [Task client](https://github.com/yasir2000/bpmninja/blob/main/bpmn-ninja-external-task-client/src/ExternalTaskClient.ts): `bpmn-ninja-external-task-client/src/ExternalTaskClient.ts`
- [Sample worker](https://github.com/yasir2000/bpmninja/blob/main/agent-orchestrator/src/main.rs): `agent-orchestrator/src/main.rs`

### Desktop operations

- [Desktop bridge](https://github.com/yasir2000/bpmninja/blob/main/desktop-tauri/src-tauri/src/sse_consumer.rs): `desktop-tauri/src-tauri/src/sse_consumer.rs`
- [Operations UI](https://github.com/yasir2000/bpmninja/blob/main/desktop-tauri/src/App.tsx): `desktop-tauri/src/App.tsx`
- [BPMN modeler](https://github.com/yasir2000/bpmninja/blob/main/desktop-tauri/src/features/modeler/ModelerPage.tsx): `desktop-tauri/src/features/modeler/ModelerPage.tsx`
- [Instance tracking](https://github.com/yasir2000/bpmninja/blob/main/desktop-tauri/src/features/instances/InstancesPage.tsx): `desktop-tauri/src/features/instances/InstancesPage.tsx`
- [User tasks](https://github.com/yasir2000/bpmninja/blob/main/desktop-tauri/src/features/tasks/PendingTasksPage.tsx): `desktop-tauri/src/features/tasks/PendingTasksPage.tsx`
- [Monitoring and logs](https://github.com/yasir2000/bpmninja/blob/main/desktop-tauri/src/features/monitoring/MonitoringPage.tsx): `desktop-tauri/src/features/monitoring/MonitoringPage.tsx`
- [History search](https://github.com/yasir2000/bpmninja/blob/main/desktop-tauri/src/features/history/HistoryPage.tsx): `desktop-tauri/src/features/history/HistoryPage.tsx`

### Other components

- **Workflow operator**
- **External worker**

## Connections

- Workflow operator → BPMN modeler: models processes
- BPMN modeler → REST API server: deploys definitions
- REST API server → BPMN parser: parses deployments
- BPMN parser → Collaboration metadata: parses collaboration (evidence: `bpmn-parser/src/lib.rs`)
- REST API server → Deploy model check: checks deployments
- REST API server → Workflow engine: routes workflow API
- Workflow engine → Token executor: executes tokens (evidence: `engine-core/src/engine/mod.rs`)
- Token executor → Events and boundaries: handles event work (evidence: `engine-core/src/engine/executor/mod.rs`)
- Token executor → Service tasks: runs service tasks (evidence: `engine-core/src/engine/executor/mod.rs`)
- Workflow engine → Timer scheduler: schedules timers (evidence: `engine-core/src/engine/mod.rs`)
- Workflow engine → Instance history: records lifecycle (evidence: `engine-core/src/engine/executor/mod.rs`)
- Workflow engine → Memory persistence: persists state
- Workflow engine → NATS persistence: persists state
- External worker → Task client: processes work
- Task client → REST API server: fetches and locks
- Sample worker → REST API server: requests tasks
- Workflow operator → Operations UI: operates workflows
- Operations UI → BPMN modeler: opens modeler (evidence: `desktop-tauri/src/App.tsx`)
- Operations UI → Instance tracking: opens instances (evidence: `desktop-tauri/src/App.tsx`)
- Operations UI → User tasks: opens tasks (evidence: `desktop-tauri/src/App.tsx`)
- Operations UI → Monitoring and logs: opens monitoring (evidence: `desktop-tauri/src/App.tsx`)
- Operations UI → History search: opens history (evidence: `desktop-tauri/src/App.tsx`)
- REST API server → Desktop bridge: streams SSE updates
- Desktop bridge → Operations UI: emits UI events
- REST API server → History search: serves archived history
