# nishgpt/chain-executor architecture

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

- Interactive diagram: https://gitdiagram.com/nishgpt/chain-executor
- Repository: https://github.com/nishgpt/chain-executor

## Overview

##### Project type and purpose
- This is a Java library (“chain-executor”) that provides a simplified linear workflow engine. It lets clients define named chains of processing stages and execute them sequentially against a context object.
- Key features: stage-based execution, chain registry, factory‐based executor resolution, robust error handling.

##### File structure
- Top-level: pom.xml (Maven module), src/main/java/com/github/nishgpt/chainexecutor.
- Packages:
- chainexecutor – contains StageExecutionManager (orchestrator)
- chainexecutor/exceptions – custom exception and error codes
- chainexecutor/models/execution – executor interfaces, factory, request, context, keys
- chainexecutor/models/stage – chain, registry, identifier, status, stage interface
- No UI or external service modules; purely a library.

##### Insights from the README
- Describes architecture: StageChain → executed by StageExecutionManager, executors created via StageExecutorFactory, errors via ChainExecutorException/ErrorCode.
- No persistence or messaging; focus on in‐memory chaining and execution.

a. Components
1. Client Code (defines chains & invokes execution)
2. StageChainRegistry (holds mappings: ChainID → StageChain)
3. StageChain (directed linear graph of Stage instances)
4. StageExecutionManager (orchestrates execution flow)
5. StageExecutorFactory (resolves a StageExecutor for each Stage)
6. StageExecutor implementations (concrete processing steps)
7. ExecutionContext (carries metadata & results)
8. Exceptions/ErrorCode (error handling subsystem)
b. Relationships & flow
1. Client registers one or more StageChains in StageChainRegistry under a ChainIdentifier.
2. Client invokes StageExecutionManager.execute(chainId, ExecutionContext).
3. ExecutionManager queries StageChainRegistry for the StageChain.
4. For each Stage in the chain:
– Build a StageExecutorKey (Stage + auxiliary key)
– Request StageExecutorFactory.create(key)
– Call executor.execute(ExecutionContext)
– Update ExecutionContext and evaluate StageStatus
– On failure, throw ChainExecutorException with ErrorCode; manager handles retry or abort.
5. Manager advances to the next stage in StageChain.forwardChainMappings.
c. Architectural patterns
- Chain of Responsibility / Pipeline pattern for stages.
- Factory pattern for dynamic discovery & instantiation of executors.
- Registry for central chain management & integrity validation (detects loops, broken links).
d. Technologies
- Java 8+, Maven.
- No external frameworks; uses Java interfaces and annotations (for executor discovery).

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Client"
        Client["Client Code"]:::extension
    end

    subgraph "Registry"
        Registry["StageChainRegistry"]:::core
        Identifier["StageChainIdentifier"]:::core
        Chain["StageChain"]:::core
    end

    subgraph "Core Engine"
        Manager["StageExecutionManager"]:::core
        Factory["StageExecutorFactory"]:::core
    end

    subgraph "Execution Model"
        Request["StageExecutionRequest"]:::core
        AuxKey["ExecutorAuxiliaryKey"]:::core
        ExecutorKey["StageExecutorKey"]:::core
        Context["ExecutionContext"]:::core
        ExecutorIfc["StageExecutor"]:::core
    end

    subgraph "Error Handling"
        Exception["ChainExecutorException"]:::error
        ErrorCode["ErrorCode"]:::error
    end

    Client -->|"registerChain(ChainID, StageChain)"| Registry
    Client -->|"execute(chainId, ExecutionContext)"| Manager
    Manager -->|"getChain(ChainID)"| Registry
    Registry -->|"returns StageChain"| Manager
    Manager -->|"build ExecutorKey"| Request
    Manager -->|"attach AuxKey"| AuxKey
    Manager -->|"createExecutor(key)"| Factory
    Factory -->|"returns Executor"| ExecutorIfc
    ExecutorIfc -->|"execute(context)"| Manager
    Manager -->|"update Context"| Context
    Manager -.->|"retry/abort"| Manager
    Manager -->|"on failure throw"| Exception
    Exception -->|"uses"| ErrorCode

    click Registry "https://github.com/nishgpt/chain-executor/blob/main/src/main/java/com/github/nishgpt/chainexecutor/models/stage/StageChainRegistry.java"
    click Chain "https://github.com/nishgpt/chain-executor/blob/main/src/main/java/com/github/nishgpt/chainexecutor/models/stage/StageChain.java"
    click Identifier "https://github.com/nishgpt/chain-executor/blob/main/src/main/java/com/github/nishgpt/chainexecutor/models/stage/StageChainIdentifier.java"
    click Manager "https://github.com/nishgpt/chain-executor/blob/main/src/main/java/com/github/nishgpt/chainexecutor/StageExecutionManager.java"
    click Factory "https://github.com/nishgpt/chain-executor/blob/main/src/main/java/com/github/nishgpt/chainexecutor/models/execution/StageExecutorFactory.java"
    click ExecutorIfc "https://github.com/nishgpt/chain-executor/blob/main/src/main/java/com/github/nishgpt/chainexecutor/models/execution/StageExecutor.java"
    click Context "https://github.com/nishgpt/chain-executor/blob/main/src/main/java/com/github/nishgpt/chainexecutor/models/execution/ExecutionContext.java"
    click Request "https://github.com/nishgpt/chain-executor/blob/main/src/main/java/com/github/nishgpt/chainexecutor/models/execution/StageExecutionRequest.java"
    click AuxKey "https://github.com/nishgpt/chain-executor/blob/main/src/main/java/com/github/nishgpt/chainexecutor/models/execution/ExecutorAuxiliaryKey.java"
    click ExecutorKey "https://github.com/nishgpt/chain-executor/blob/main/src/main/java/com/github/nishgpt/chainexecutor/models/execution/StageExecutorKey.java"
    click Exception "https://github.com/nishgpt/chain-executor/blob/main/src/main/java/com/github/nishgpt/chainexecutor/exceptions/ChainExecutorException.java"
    click ErrorCode "https://github.com/nishgpt/chain-executor/blob/main/src/main/java/com/github/nishgpt/chainexecutor/exceptions/ErrorCode.java"

    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef extension fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef error fill:#FFA500,stroke:#000,stroke-width:1px;
```
