# sartography/spiffworkflow architecture

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

- Interactive diagram: https://gitdiagram.com/sartography/spiffworkflow
- Repository: https://github.com/sartography/spiffworkflow

## Overview

SpiffWorkflow is a Python workflow engine: users supply BPMN diagrams, DMN decision tables, or programmatic workflow specifications; the engine builds executable specifications, runs tasks, and exposes workflow state. BPMN parsing and event/task modeling, DMN evaluation, and code-defined workflows are distinct product stages. Serialization provides a persistence boundary. The graph reflects README capabilities and relationships listed in the SOURCE INDEX; unsampled runtime wiring is omitted where it cannot be verified.

Main entry points: [`SpiffWorkflow/bpmn/parser/BpmnParser.py`](https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/bpmn/parser/BpmnParser.py) (BPMN parser), [`SpiffWorkflow/workflow.py`](https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/workflow.py) (Workflow runtime), [`SpiffWorkflow/dmn/parser/BpmnDmnParser.py`](https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/dmn/parser/BpmnDmnParser.py) (BPMN-DMN parser), [`SpiffWorkflow/dmn/specs/model.py`](https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/dmn/specs/model.py) (Decision model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Workflow execution"]
  node_workflow_spec["Workflow specification<br/>[WorkflowSpec.py]"]
  node_task_specs["Task specifications<br/>[base.py]"]
  node_workflow["Workflow runtime<br/>[workflow.py]"]
  node_task["Task state<br/>[task.py]"]
  node_task_util["Task traversal<br/>[task.py]"]
end

subgraph group_bpmn["BPMN processing"]
  node_bpmn_parser["BPMN parser<br/>[BpmnParser.py]"]
  node_bpmn_task_parser["Task parsing<br/>[TaskParser.py]"]
  node_event_parser["Event parsing<br/>[event_parsers.py]"]
  node_bpmn_specs["BPMN specifications"]
  node_bpmn_workflow["BPMN workflow<br/>[workflow.py]"]
  node_camunda_parser["Camunda parser<br/>[CamundaParser.py]"]
  node_spiff_parser["Spiff parser"]
end

subgraph group_decisions["Decision processing"]
  node_dmn_parser["DMN parser<br/>[DMNParser.py]"]
  node_bpmn_dmn_parser["BPMN-DMN parser<br/>[BpmnDmnParser.py]"]
  node_dmn_model["Decision model<br/>[model.py]"]
  node_dmn_engine["DMN engine<br/>[DMNEngine.py]"]
  node_script_engine["Python script engine<br/>[python_engine.py]"]
end

subgraph group_persistence["Serialization and extensions"]
  node_serializer["Workflow serializers"]
  node_bpmn_serializer["BPMN serializers"]
  node_dmn_serializer["DMN serializer<br/>[task_spec.py]"]
end

node_user(("Workflow author"))
node_bpmn_input["BPMN diagram"]
node_dmn_input["DMN table"]
node_code_input["Python workflow"]

node_user -->|"authors"| node_bpmn_input
node_user -->|"authors"| node_dmn_input
node_user -->|"defines"| node_code_input
node_bpmn_input -->|"parses"| node_bpmn_parser
node_bpmn_parser -->|"uses"| node_bpmn_task_parser
node_bpmn_parser -->|"uses"| node_event_parser
node_bpmn_parser -->|"builds"| node_bpmn_specs
node_bpmn_parser -.->|"produces"| node_bpmn_workflow
node_dmn_input -->|"parses"| node_dmn_parser
node_dmn_parser -->|"builds"| node_dmn_model
node_bpmn_dmn_parser -->|"uses"| node_bpmn_parser
node_bpmn_dmn_parser -->|"uses"| node_dmn_parser
node_bpmn_dmn_parser -->|"uses"| node_dmn_engine
node_dmn_model -->|"evaluated by"| node_dmn_engine
node_dmn_engine -.->|"evaluates expressions"| node_script_engine
node_code_input -->|"defines"| node_workflow_spec
node_workflow_spec -->|"connects"| node_task_specs
node_workflow -->|"uses"| node_workflow_spec
node_workflow -->|"runs"| node_task
node_task -->|"executes"| node_task_specs
node_workflow -->|"traverses"| node_task_util
node_workflow -->|"serializes through"| node_serializer
node_bpmn_specs -.->|"serialized by"| node_bpmn_serializer
node_dmn_model -->|"serialized by"| node_dmn_serializer
node_camunda_parser -->|"extends"| node_bpmn_parser
node_spiff_parser -->|"extends"| node_event_parser

click node_bpmn_parser "https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/bpmn/parser/BpmnParser.py"
click node_bpmn_task_parser "https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/bpmn/parser/TaskParser.py"
click node_event_parser "https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/bpmn/parser/event_parsers.py"
click node_bpmn_specs "https://github.com/sartography/spiffworkflow/tree/main/SpiffWorkflow/bpmn/specs"
click node_bpmn_workflow "https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/bpmn/workflow.py"
click node_camunda_parser "https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/camunda/parser/CamundaParser.py"
click node_spiff_parser "https://github.com/sartography/spiffworkflow/tree/main/SpiffWorkflow/spiff/parser"
click node_dmn_parser "https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/dmn/parser/DMNParser.py"
click node_bpmn_dmn_parser "https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/dmn/parser/BpmnDmnParser.py"
click node_dmn_model "https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/dmn/specs/model.py"
click node_dmn_engine "https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/dmn/engine/DMNEngine.py"
click node_script_engine "https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/bpmn/script_engine/python_engine.py"
click node_workflow_spec "https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/specs/WorkflowSpec.py"
click node_task_specs "https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/specs/base.py"
click node_workflow "https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/workflow.py"
click node_task "https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/task.py"
click node_task_util "https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/util/task.py"
click node_serializer "https://github.com/sartography/spiffworkflow/tree/main/SpiffWorkflow/serializer"
click node_bpmn_serializer "https://github.com/sartography/spiffworkflow/tree/main/SpiffWorkflow/bpmn/serializer"
click node_dmn_serializer "https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/dmn/serializer/task_spec.py"

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_workflow_spec,node_task_specs,node_workflow,node_task,node_task_util toneBlue
class node_bpmn_parser,node_bpmn_task_parser,node_event_parser,node_bpmn_specs,node_bpmn_workflow,node_camunda_parser,node_spiff_parser toneAmber
class node_dmn_parser,node_bpmn_dmn_parser,node_dmn_model,node_dmn_engine,node_script_engine toneMint
class node_serializer,node_bpmn_serializer,node_dmn_serializer toneRose
class node_user,node_bpmn_input,node_dmn_input,node_code_input toneIndigo
```

## Components

### Workflow execution

- [Workflow specification](https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/specs/WorkflowSpec.py): `SpiffWorkflow/specs/WorkflowSpec.py`
- [Task specifications](https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/specs/base.py): `SpiffWorkflow/specs/base.py`
- [Workflow runtime](https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/workflow.py): `SpiffWorkflow/workflow.py`
- [Task state](https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/task.py): `SpiffWorkflow/task.py`
- [Task traversal](https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/util/task.py): `SpiffWorkflow/util/task.py`

### BPMN processing

- [BPMN parser](https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/bpmn/parser/BpmnParser.py): `SpiffWorkflow/bpmn/parser/BpmnParser.py`
- [Task parsing](https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/bpmn/parser/TaskParser.py): `SpiffWorkflow/bpmn/parser/TaskParser.py`
- [Event parsing](https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/bpmn/parser/event_parsers.py): `SpiffWorkflow/bpmn/parser/event_parsers.py`
- [BPMN specifications](https://github.com/sartography/spiffworkflow/tree/main/SpiffWorkflow/bpmn/specs): `SpiffWorkflow/bpmn/specs`
- [BPMN workflow](https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/bpmn/workflow.py): `SpiffWorkflow/bpmn/workflow.py`
- [Camunda parser](https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/camunda/parser/CamundaParser.py): `SpiffWorkflow/camunda/parser/CamundaParser.py`
- [Spiff parser](https://github.com/sartography/spiffworkflow/tree/main/SpiffWorkflow/spiff/parser): `SpiffWorkflow/spiff/parser`

### Decision processing

- [DMN parser](https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/dmn/parser/DMNParser.py): `SpiffWorkflow/dmn/parser/DMNParser.py`
- [BPMN-DMN parser](https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/dmn/parser/BpmnDmnParser.py): `SpiffWorkflow/dmn/parser/BpmnDmnParser.py`
- [Decision model](https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/dmn/specs/model.py): `SpiffWorkflow/dmn/specs/model.py`
- [DMN engine](https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/dmn/engine/DMNEngine.py): `SpiffWorkflow/dmn/engine/DMNEngine.py`
- [Python script engine](https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/bpmn/script_engine/python_engine.py): `SpiffWorkflow/bpmn/script_engine/python_engine.py`

### Serialization and extensions

- [Workflow serializers](https://github.com/sartography/spiffworkflow/tree/main/SpiffWorkflow/serializer): `SpiffWorkflow/serializer`
- [BPMN serializers](https://github.com/sartography/spiffworkflow/tree/main/SpiffWorkflow/bpmn/serializer): `SpiffWorkflow/bpmn/serializer`
- [DMN serializer](https://github.com/sartography/spiffworkflow/blob/main/SpiffWorkflow/dmn/serializer/task_spec.py): `SpiffWorkflow/dmn/serializer/task_spec.py`

### Other components

- **Workflow author**
- **BPMN diagram**
- **DMN table**
- **Python workflow**

## Connections

- Workflow author → BPMN diagram: authors
- Workflow author → DMN table: authors
- Workflow author → Python workflow: defines
- BPMN diagram → BPMN parser: parses
- BPMN parser → Task parsing: uses (evidence: `SpiffWorkflow/bpmn/parser/BpmnParser.py`)
- BPMN parser → Event parsing: uses (evidence: `SpiffWorkflow/bpmn/parser/BpmnParser.py`)
- BPMN parser → BPMN specifications: builds (evidence: `SpiffWorkflow/bpmn/parser/BpmnParser.py`)
- BPMN parser → BPMN workflow: produces
- DMN table → DMN parser: parses
- DMN parser → Decision model: builds (evidence: `SpiffWorkflow/dmn/parser/DMNParser.py`)
- BPMN-DMN parser → BPMN parser: uses (evidence: `SpiffWorkflow/dmn/parser/BpmnDmnParser.py`)
- BPMN-DMN parser → DMN parser: uses (evidence: `SpiffWorkflow/dmn/parser/BpmnDmnParser.py`)
- BPMN-DMN parser → DMN engine: uses (evidence: `SpiffWorkflow/dmn/parser/BpmnDmnParser.py`)
- Decision model → DMN engine: evaluated by (evidence: `SpiffWorkflow/dmn/engine/DMNEngine.py`)
- DMN engine → Python script engine: evaluates expressions
- Python workflow → Workflow specification: defines
- Workflow specification → Task specifications: connects (evidence: `SpiffWorkflow/specs/WorkflowSpec.py`)
- Workflow runtime → Workflow specification: uses (evidence: `SpiffWorkflow/workflow.py`)
- Workflow runtime → Task state: runs (evidence: `SpiffWorkflow/workflow.py`)
- Task state → Task specifications: executes (evidence: `SpiffWorkflow/task.py`)
- Workflow runtime → Task traversal: traverses (evidence: `SpiffWorkflow/workflow.py`)
- Workflow runtime → Workflow serializers: serializes through (evidence: `SpiffWorkflow/workflow.py`)
- BPMN specifications → BPMN serializers: serialized by (evidence: `SpiffWorkflow/bpmn/serializer/helpers/spec.py`)
- Decision model → DMN serializer: serialized by (evidence: `SpiffWorkflow/dmn/serializer/task_spec.py`)
- Camunda parser → BPMN parser: extends (evidence: `SpiffWorkflow/camunda/parser/CamundaParser.py`)
- Spiff parser → Event parsing: extends (evidence: `SpiffWorkflow/spiff/parser/event_parsers.py`)