# processmaker/nayra architecture

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

- Interactive diagram: https://gitdiagram.com/processmaker/nayra
- Repository: https://github.com/processmaker/nayra

## Overview

##### Main Components
- BPMN Definition Loader/Repository: Represented by the BpmnDocument class (found in src/ProcessMaker/Nayra/Storage) which is responsible for loading BPMN definition files and instantiating process models.
- Process Engine: The engine (in src/ProcessMaker/Nayra/Engine) that creates execution instances, runs tokens to the next state, and coordinates the process execution.
- BPMN Models and Domain Objects: A large portion of the project resides in the BPMN subdirectory (e.g., Models, Traits, and individual BPMN elements like activities, gateways, events, transitions). These classes encapsulate the definition and behavior of BPMN elements (activities, start/end events, gateways, etc.).
- Contracts and Interfaces: The project defines a set of interfaces (in src/ProcessMaker/Nayra/Contracts) that enforce architectural boundaries and allow for dependency injection and abstraction (e.g., for BPMN elements, engine behaviors, repositories, and storage).
- Data Storage and Repository: Components to create and manage process data (e.g., DataStore from the repository and ExecutionInstance classes).
- Event and Token Management: Classes and traits that handle token passing, event propagation, and transitions (as seen in directories like src/ProcessMaker/Nayra/Bpmn/Events and the many traits for transitions and states).

##### Relationships and Interactions
- The BPMN Document Loader reads a BPMN file (e.g., “ParallelGateway.bpmn”) and creates a BPMN model. This model includes various BPMN elements (activities, gateways, events) that are defined using the Models and Traits.
- Once loaded, the BPMN Document is used to retrieve a specific process by its identifier, and then the Engine (using methods like createExecutionInstance() and runToNextState()) creates and manages the state of the process.
- The Engine interacts with other components (such as data storage/repository and token management modules) as it propagates tokens through the process based on BPMN semantics.
- All these components are aligned through the use of defined interfaces in the Contracts directories, ensuring that the implementation stays modular, replaceable, and testable.
- There is also an event bus and error handling layer (shown by the existence of Exceptions and Event-related classes) that enable robust process control and logging of discrete events.

##### Architectural Patterns and Design Principles
- Modularity and Abstraction: The system is divided using interfaces (contracts) and separate namespaces for BPMN definitions, engine logic, and storage.
- Separation of Concerns: The design clearly distinguishes the responsibilities of loading process definitions (BpmnDocument), executing processes (Engine), and modeling BPMN components (Models/Traits under BPMN).
- Extensibility: By relying on interfaces and traits, the engine is designed for adaptability, making it easier to add new BPMN elements and behavior without impacting the core execution logic.
- Testability: The comprehensive tests directory indicates the importance of unit and feature tests for each component, which is an important consideration in design documentation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% BPMN Definition & Repository
    subgraph "BPMN Definition & Repository"
        A["BPMN Document Loader<br/>(Loads and parses BPMN files)"]
    end

    %% Process Engine
    subgraph "Process Execution Engine"
        B["Process Engine<br/>(Manages execution and state transitions)"]
    end

    %% BPMN Domain Models
    subgraph "BPMN Domain Model"
        C["BPMN Models & Domain Objects<br/>(Defines BPMN elements and behavior)"]
    end

    %% Data Storage & Repository
    subgraph "Data Management"
        D["Data Storage & Repository<br/>(Manages process instances and data)"]
    end

    %% Contracts & Interfaces
    subgraph "Contracts & Interfaces"
        F["Contracts & Interfaces<br/>(Defines abstractions)"]
    end

    %% Token & Event Management
    subgraph "Token & Event Management"
        E1["Event Management<br/>(Manages process events)"]
        subgraph "Token Management"
            E2["Token Trait<br/>(Provides token functionality)"]
            E3["Token Model<br/>(Represents a token)"]
        end
    end

    %% Connections between components
    A -->|"loadsBPMNmodel"| B
    B -->|"createsInstance"| D
    B -->|"managesElements"| C
    B -->|"triggersEvents"| E1
    B -->|"handlesTokens"| E2
    B -->|"adheresTo"| F
    C -->|"implementsContracts"| F
    E2 -->|"reliesOn"| E3

    %% Styling
    classDef loader fill:#AEDFF7,stroke:#1B6CA8,stroke-width:2px;
    classDef engine fill:#FFF2CC,stroke:#E1C699,stroke-width:2px;
    classDef models fill:#CFF0CC,stroke:#8BC34A,stroke-width:2px;
    classDef storage fill:#F7D6AE,stroke:#FF9800,stroke-width:2px;
    classDef contracts fill:#E2D1F9,stroke:#9C27B0,stroke-width:2px;
    classDef events fill:#F3C6F7,stroke:#E91E63,stroke-width:2px;

    class A loader;
    class B engine;
    class C models;
    class D storage;
    class F contracts;
    class E1 events;
    class E2 events;
    class E3 events;

    %% Click Events
    click A "https://github.com/processmaker/nayra/blob/release-2025-spring/src/ProcessMaker/Nayra/Storage/BpmnDocument.php"
    click B "https://github.com/processmaker/nayra/tree/release-2025-spring/src/ProcessMaker/Nayra/Engine/"
    click C "https://github.com/processmaker/nayra/tree/release-2025-spring/src/ProcessMaker/Nayra/Bpmn/Models/"
    click D "https://github.com/processmaker/nayra/tree/release-2025-spring/src/ProcessMaker/Nayra/Storage/"
    click F "https://github.com/processmaker/nayra/tree/release-2025-spring/src/ProcessMaker/Nayra/Contracts/"
    click E1 "https://github.com/processmaker/nayra/tree/release-2025-spring/src/ProcessMaker/Nayra/Bpmn/Events/"
    click E2 "https://github.com/processmaker/nayra/blob/release-2025-spring/src/ProcessMaker/Nayra/Bpmn/TokenTrait.php"
    click E3 "https://github.com/processmaker/nayra/blob/release-2025-spring/src/ProcessMaker/Nayra/Bpmn/Models/Token.php"
```
