# alibaba/smartengine architecture

> Architecture diagram of the GitHub repository alibaba/smartengine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alibaba/smartengine
- Repository: https://github.com/alibaba/smartengine

## Overview

##### Project Type and Purpose
- SmartEngine is an open-source, lightweight BPMN 2.0 business orchestration engine library/framework.
- It exposes CQRS-style APIs (command vs. query) to start/signal processes and query state, parses BPMN XML definitions, and drives execution via a Pluggable Virtual Machine (PVM) and behavior modules.
- It’s designed for microservice orchestration and traditional approval workflows, with extension points for storage, retry, parsing, delegation, and listeners.

a. API Layer (Commands & Queries)
- Packages: `service/command/*`, `service/query/*`
- Responsibility: expose operations (startProcess, signal, taskService, etc.) following CQRS.
b. Core Engine
- `SmartEngine` entry point under `engine/SmartEngine.java`
- Subcomponents:
- Configuration (`configuration/*`)
- BPMN Parser (`xml/parser/*`, `bpmn/assembly/*`)
- PVM Runtime (`pvm/*`)
- Behavior Implementations (`bpmn/behavior/*`, `engine/behavior/impl/*`)
- Context & Execution (`context/*`)
- Interceptors & Listeners (`interceptor/*`, `listener/*`)
c. Model & Instance
- `model/assembly/*`, `model/instance/*`: in-memory representations of definitions and runtime instances.
- Factories & Storage Interfaces (`instance/factory/*`, `instance/storage/*`)
d. Extension Points
- Annotation-driven extension binding (`extension/annotation`, `configuration/scanner/*`)
- Smart-specific extensions (`smart/*`)
e. Persistence Plugins
- Storage‐common (abstract interfaces / helpers)
- Storage-custom (in-memory, file, NoSQL, etc.)
- Storage-mysql (MyBatis + MySQL implementation)
- Retry-common, retry-custom, retry-mysql (retry extension points)
f. External Services
- Database (MySQL or other RDBMS via MyBatis)
- External microservices invoked through ServiceTaskBehavior
- Messaging or event systems via SendTask/ReceiveTaskBehavior

- Client → API Layer (CommandService, QueryService) → SmartEngine
- SmartEngine → BPMN XML Parser → ProcessDefinition model
- SmartEngine → ContextFactory → ExecutionContext
- ExecutionContext → PVM Runtime → Behavior modules → (ServiceTaskBehavior → External Service)
- PVM events/interceptors/listeners → Extension Points
- During execution: InstanceStorage & VariablePersister → Storage Plugins → (Database or Custom)
- Retry extension intercepts failed behaviors and schedules retry records via RetryStorage plugins

##### Architectural Patterns & Principles
- CQRS (separate command/query packages)
- Plugin architecture (interfaces + multiple implementations, discovered via annotation scanner)
- Strategy & Factory patterns (ConfigurationOption, InstanceFactory, PersisterSession)
- Behavior tree traversal (PVM + BehaviorImplementation classes)
- XML-driven configuration (BPMN 2.0, annotation scanning)

##### Essential Elements

- Configuration
- BPMN Parser
- PVM Runtime → Behavior Modules
- Context & Execution
- Interceptor / Listener

## Diagram (Mermaid)

```mermaid
flowchart TD
    ClientApplications["Client Applications"]:::external

    subgraph "API Layer"
        CommandServiceAPI["Command Services\n(service/command/*)"]:::api
        QueryServiceAPI["Query Services\n(service/query/*)"]:::api
    end

    subgraph "SmartEngine Core"
        SmartEngine["SmartEngine\n(engine/SmartEngine.java)"]:::core

        subgraph Configuration
            Configuration["Configuration\n(configuration/*)"]:::core
        end

        subgraph "XML Parser"
            XmlParser["XmlParserFacade\n(xml/parser)"]:::core
            BPMNAssembly["BPMN Assembly\n(bpmn/assembly/*)"]:::core
        end

        subgraph "PVM & Behaviors"
            PVM["PVM Runtime\n(pvm/*)"]:::core
            BehaviorImpl["Behavior Modules\n(behavior/impl & bpmn/behavior/*)"]:::core
        end

        subgraph "Context & Execution"
            Context["Context & Execution\n(context/*)"]:::core
            Interceptor["Interceptor Chain\n(interceptor/*)"]:::core
            Listener["Listener Aggregation\n(listener/*)"]:::core
        end
    end

    subgraph "Model & Instance"
        DefinitionModel["Definition Model\n(model/assembly/*)"]:::core
        RuntimeInstance["Runtime Instances\n(model/instance/*)"]:::core
        InstanceFactory["Instance Factories\n(instance/factory/*)"]:::core
        StorageInterface["Storage Interfaces\n(instance/storage/*)"]:::core
    end

    subgraph "Persistence Plugins"
        StorageCommon["Storage Common\n(persister/common)"]:::persistence
        StorageCustom["Storage Custom\n(persister/custom)"]:::persistence
        StorageMySQL["Storage MySQL\n(persister/database)"]:::persistence
    end

    subgraph "Retry Plugins"
        RetryCommon["Retry Common\n(retry/*)"]:::persistence
        RetryCustom["Retry Custom\npersister/custom"]:::persistence
        RetryMySQL["Retry MySQL\npersister/database"]:::persistence
    end

    subgraph "Extension Points"
        ExtAnnotation["Extension Annotations\n(extension/annotation)"]:::extension
        SimpleScanner["SimpleAnnotationScanner\n(extension/scanner/*)"]:::extension
        SmartExt["Smart Extensions\n(smart/*)"]:::extension
    end

    Database["MySQL Database"]:::external
    ExternalServices["External Microservices"]:::external

    ClientApplications -->|calls| CommandServiceAPI
    ClientApplications -->|queries| QueryServiceAPI

    CommandServiceAPI -->|invoke| SmartEngine
    QueryServiceAPI -->|invoke| SmartEngine

    SmartEngine -->|load config| Configuration
    SmartEngine -->|parse BPMN| XmlParser
    SmartEngine -->|assemble model| BPMNAssembly
    SmartEngine -->|create context| Context
    SmartEngine -->|setup interceptors| Interceptor
    SmartEngine -->|register listeners| Listener
    SmartEngine -->|start runtime| PVM

    PVM -->|execute behaviors| BehaviorImpl
    BehaviorImpl -->|call service tasks| ExternalServices

    Interceptor -->|on events| SimpleScanner
    Interceptor -->|retry failed| RetryCommon

    Context -->|create instance| InstanceFactory
    Context -->|persist state| StorageInterface

    InstanceFactory --> DefinitionModel
    InstanceFactory --> RuntimeInstance

    StorageInterface -->|persist| StorageCommon
    StorageInterface -->|persist| StorageCustom
    StorageInterface -->|persist| StorageMySQL

    RetryCommon -->|store retry record| RetryCustom
    RetryCommon -->|store retry record| RetryMySQL

    StorageMySQL --> Database
    RetryMySQL --> Database

    click CommandServiceAPI "https://github.com/alibaba/smartengine/tree/master/core/src/main/java/com/alibaba/smart/framework/engine/service/command"
    click QueryServiceAPI "https://github.com/alibaba/smartengine/tree/master/core/src/main/java/com/alibaba/smart/framework/engine/service/query"
    click SmartEngine "https://github.com/alibaba/smartengine/blob/master/core/src/main/java/com/alibaba/smart/framework/engine/SmartEngine.java"
    click Configuration "https://github.com/alibaba/smartengine/tree/master/core/src/main/java/com/alibaba/smart/framework/engine/configuration"
    click XmlParser "https://github.com/alibaba/smartengine/blob/master/core/src/main/java/com/alibaba/smart/framework/engine/xml/parser/XmlParserFacade.java"
    click BPMNAssembly "https://github.com/alibaba/smartengine/tree/master/core/src/main/java/com/alibaba/smart/framework/engine/bpmn/assembly"
    click PVM "https://github.com/alibaba/smartengine/tree/master/core/src/main/java/com/alibaba/smart/framework/engine/pvm"
    click BehaviorImpl "https://github.com/alibaba/smartengine/tree/master/core/src/main/java/com/alibaba/smart/framework/engine/behavior/impl"
    click Context "https://github.com/alibaba/smartengine/tree/master/core/src/main/java/com/alibaba/smart/framework/engine/context"
    click Interceptor "https://github.com/alibaba/smartengine/tree/master/core/src/main/java/com/alibaba/smart/framework/engine/interceptor"
    click Listener "https://github.com/alibaba/smartengine/tree/master/core/src/main/java/com/alibaba/smart/framework/engine/listener"
    click DefinitionModel "https://github.com/alibaba/smartengine/tree/master/core/src/main/java/com/alibaba/smart/framework/engine/model/assembly"
    click RuntimeInstance "https://github.com/alibaba/smartengine/tree/master/core/src/main/java/com/alibaba/smart/framework/engine/model/instance"
    click InstanceFactory "https://github.com/alibaba/smartengine/tree/master/core/src/main/java/com/alibaba/smart/framework/engine/instance/factory"
    click StorageInterface "https://github.com/alibaba/smartengine/tree/master/core/src/main/java/com/alibaba/smart/framework/engine/instance/storage"
    click ExtAnnotation "https://github.com/alibaba/smartengine/tree/master/core/src/main/java/com/alibaba/smart/framework/engine/extension/annotation"
    click SimpleScanner "https://github.com/alibaba/smartengine/blob/master/core/src/main/java/com/alibaba/smart/framework/engine/configuration/scanner/AnnotationScanner.java"
    click SmartExt "https://github.com/alibaba/smartengine/tree/master/core/src/main/java/com/alibaba/smart/framework/engine/smart"
    click StorageCommon "https://github.com/alibaba/smartengine/tree/master/extension/storage/storage-common/src/main/java/com/alibaba/smart/framework/engine/persister/common"
    click StorageCustom "https://github.com/alibaba/smartengine/tree/master/extension/storage/storage-custom/src/main/java/com/alibaba/smart/framework/engine/persister/custom"
    click StorageMySQL "https://github.com/alibaba/smartengine/tree/master/extension/storage/storage-mysql/src/main/java/com/alibaba/smart/framework/engine/persister/database"
    click RetryCommon "https://github.com/alibaba/smartengine/tree/master/extension/retry/retry-common/src/main/java/com/alibaba/smart/framework/engine/retry"
    click RetryCustom "https://github.com/alibaba/smartengine/tree/master/extension/retry/retry-custom/src/main/java/com/alibaba/smart/framework/engine/persister/custom"
    click RetryMySQL "https://github.com/alibaba/smartengine/tree/master/extension/retry/retry-mysql/src/main/java/com/alibaba/smart/framework/engine/persister/database"

    classDef api fill:#e0f7e9,stroke:#2ecc71,color:#2ecc71
    classDef core fill:#e0f3ff,stroke:#3498db,color:#3498db
    classDef persistence fill:#fff0e0,stroke:#e67e22,color:#e67e22
    classDef extension fill:#f5e0ff,stroke:#9b59b6,color:#9b59b6
    classDef external fill:#f0f0f0,stroke:#7f8c8d,color:#7f8c8d
```
