# nitorcreations/nflow architecture

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

- Interactive diagram: https://gitdiagram.com/nitorcreations/nflow
- Repository: https://github.com/nitorcreations/nflow

## Overview

##### Main components
- nFlow Engine (nflow-engine): This is the core engine handling workflow definition, state machine logic, database operations (with many sub-packages for configuration, DAO, workflow execution, exception handling, and internal utilities). It is the heart of the orchestration system.
- Workflow Executor/Dispatcher: Within the engine you have components for executing workflows (e.g., dispatchers, state processors, lifecycle management).
- Database Layer: Since nFlow relies heavily on relational databases for atomic state updates and locking, include connections to multiple supported databases (PostgreSQL, MySQL/MariaDB, Oracle, SQL Server, DB2, and even H2 as demo).
- REST APIs and External Interfaces:
- nflow-rest-api-common, nflow-rest-api-jax-rs, and nflow-rest-api-spring-web expose the workflow and administrative functions over REST.
- nflow-server-common may contain shared server-side logic and static UI assets.
- Web UI / Explorer (nflow-explorer): A separate module providing visualization, configuration, and interactive documentation of workflows.
- Deployment Modules/Containers:
- nflow-jetty and nflow-netty: Provide embeddable web servers for running the engine in different container technologies.
- nflow-perf-test and nflow-tests: Indicate testing and load/performance testing framework for the engine.
- Examples (nflow-examples): Show how to integrate nFlow in different project setups (e.g., Spring Boot, full-stack examples with Maven and Gradle).

##### Relationships and Data Flow
- The engine module interfaces with the database layer for transactional state updates.
- The workflow dispatcher (inside the engine) takes in workflow definitions (which are coded as Java) and processes life cycle states.
- The REST API modules read from and write to the engine components, exposing workflows externally.
- The embeddable servers (Jetty, Netty) provide the HTTP container for REST and UI calls to the engine.
- Example projects illustrate how a client application embeds the engine and invokes the workflow definitions.

##### Architectural Patterns and Design Principles
- Integration via Microservices-like separation: Although nFlow is a library, its separate modules (REST, engine, server integrations) suggest a loose coupling where the core engine can be embedded into different container environments.
- Fault Tolerance & Recovery: Highlight the designs around atomic state updates, exception handling, and recovery mechanisms in the engine.
- Dependency Injection & Modular Configuration: The engine uses Guice (see the ‘guice’ directories in nflow-engine) for dependency management.
- Database Abstraction and Multi-dialect Support: The database packages show how different database configurations are handled.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Workflow Orchestration Layer
    subgraph "Core Workflow Orchestration Layer"
        nflowEngine["nFlow Engine"]:::engine
        workflowExec["Workflow Executor/Dispatcher"]:::executor
        dbLayer["Database Layer ((Relational DBs))"]:::database
    end

    nflowEngine -->|"manages"| workflowExec
    workflowExec -->|"atomic update"| dbLayer

    %% External Interfaces Layer
    subgraph "External Interfaces"
        commonRest["Common REST API"]:::rest
        jaxrsRest["JAX-RS REST API"]:::rest
        springRest["Spring Web REST API"]:::rest
        explorer["nFlow Explorer UI"]:::ui
    end

    commonRest -->|"calls"| nflowEngine
    jaxrsRest -->|"calls"| nflowEngine
    springRest -->|"calls"| nflowEngine
    explorer -->|"interacts"| commonRest

    %% Deployment Containers Layer
    subgraph "Deployment Containers"
        jetty["Jetty Container Integration"]:::container
        netty["Netty Container Integration"]:::container
    end

    jetty -->|"hosts"| commonRest
    netty -->|"hosts"| commonRest

    %% Support Modules Layer
    subgraph "Support Modules"
        perfTest["Performance Testing"]:::support
        additionalTests["Additional Tests"]:::support
        examples["Examples Module"]:::support
        sharedServer["Shared Server (Assets)"]:::support
        metrics["Metrics & Health Checks"]:::support
    end

    examples -->|"embeds"| nflowEngine
    sharedServer -->|"serves assets to"| explorer
    metrics -->|"monitors"| nflowEngine

    %% Click Events
    click nflowEngine "https://github.com/nitorcreations/nflow/tree/master/nflow-engine"
    click workflowExec "https://github.com/nitorcreations/nflow/tree/master/nflow-engine/src/main/java/io/nflow/engine/internal/executor"
    click dbLayer "https://github.com/nitorcreations/nflow/tree/master/nflow-engine/src/main/java/io/nflow/engine/config/db"
    click commonRest "https://github.com/nitorcreations/nflow/tree/master/nflow-rest-api-common"
    click jaxrsRest "https://github.com/nitorcreations/nflow/tree/master/nflow-rest-api-jax-rs"
    click springRest "https://github.com/nitorcreations/nflow/tree/master/nflow-rest-api-spring-web"
    click explorer "https://github.com/nitorcreations/nflow/tree/master/nflow-explorer"
    click jetty "https://github.com/nitorcreations/nflow/tree/master/nflow-jetty"
    click netty "https://github.com/nitorcreations/nflow/tree/master/nflow-netty"
    click perfTest "https://github.com/nitorcreations/nflow/tree/master/nflow-perf-test"
    click additionalTests "https://github.com/nitorcreations/nflow/tree/master/nflow-tests"
    click examples "https://github.com/nitorcreations/nflow/tree/master/nflow-examples"
    click sharedServer "https://github.com/nitorcreations/nflow/tree/master/nflow-server-common"
    click metrics "https://github.com/nitorcreations/nflow/tree/master/nflow-metrics"

    %% Styles
    classDef engine fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef executor fill:#FFCC80,stroke:#FB8C00,stroke-width:2px;
    classDef database fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef rest fill:#D1C4E9,stroke:#7B1FA2,stroke-width:2px;
    classDef ui fill:#F8BBD0,stroke:#C2185B,stroke-width:2px;
    classDef container fill:#FFE0B2,stroke:#F57C00,stroke-width:2px;
    classDef support fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px;
```
