# limbo-io/fluxion architecture

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

- Interactive diagram: https://gitdiagram.com/limbo-io/fluxion
- Repository: https://github.com/limbo-io/fluxion

## Overview

##### Project type and purpose
- Fluxion is a full-stack, distributed task scheduling platform composed of three primary logical layers:
a. Broker (fluxion-server) – the control plane that maintains cluster membership, scheduling logic, and task dispatch.
b. Worker (fluxion-worker) – the execution plane where tasks/jobs actually run.
c. Console/API (fluxion-server-start) – a RESTful façade for operators to manage tasks, workflows, triggers, etc.
- It uses a relational database (via JPA + Flyway) for persistent state and a custom RPC layer (fluxion-remote) for inter-node communication.

##### File structure
- Top-level modules:
- fluxion-common – shared utilities (thread pools, JSON, hashing, reflection).
- fluxion-remote – RPC framework (core abstractions, Netty transport, optional Vert.x).
- fluxion-server – Broker logic, broken into “core” (CQRS services, scheduling, broker tasks, DAOs) and “start” (SpringBoot application, controllers, converters, API layer).
- fluxion-worker – Worker logic (“core”), a demo application, and a Spring-Boot starter for easy integration.
- fluxion-test – unit/integration tests.
- Pattern indications:
- CQRS (infrastructure/cqrs), DAG-based workflows (infrastructure/dag), plugin RPC transport, repository/command/query packages.
- Modular separation (API vs core), clear service/DAO layering.

##### README for additional insights
- Scheduling types (fixed rate, fixed delay, cron).
- Load-balancing strategies (random, round robin, LRU, LFU, consistent hash, manual).
- Node-filtering (tags, executors, capacity).
- Execution types (single job vs workflow DAG), task types (normal vs broadcast).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client/Console"
        ConsoleApp["Console/CLI"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        API["API Layer\nfluxion-server-start"]:::api
        Flyway["DB Migrations (Flyway)"]:::infra
    end

    %% Broker Core Layer
    subgraph "Broker Core"
        BrokerCore["Broker Core\n(CQRS, Scheduling, Workflow)\nfluxion-server-core"]:::core
        DAO["Persistence Layer\n(JPA Repositories)"]:::core
        InfraFrameworks["Infrastructure\n(CQRS & DAG)"]:::core
    end

    %% RPC Layer
    subgraph "RPC Layer (fluxion-remote)"
        RC["Core API/DTOs/Clients/Servers"]:::rpc
        NT["Netty Transport Plugin"]:::rpc
    end

    %% Worker Layer
    subgraph "Worker Layer"
        WorkerCore["Worker Core\n(Execution, Heartbeat)\nfluxion-worker-core"]:::core
        WorkerDemo["Worker Demo App"]:::core
        WorkerStarter["Worker Spring-Boot Starter"]:::core
    end

    %% Shared Utilities and Tests
    Common["Shared Utilities\nfluxion-common"]:::infra
    UnitTests["Unit & Integration Tests"]:::infra

    %% Database
    DB["Relational DB (MySQL)"]:::db

    %% Data Flows
    ConsoleApp -->|"REST call"| API
    API -->|"Flyway migrations at startup"| Flyway
    Flyway --> DB
    API -->|"RPC client calls"| RC
    RC -->|uses plugin| NT
    RC -->|"dispatch & heartbeats"| BrokerCore
    BrokerCore -->|"reads/writes"| DAO
    BrokerCore -->|"CQRS & DAG services"| InfraFrameworks
    DAO --> DB
    BrokerCore -->|"dispatch tasks via RPC"| RC
    RC -->|"deliver task"| WorkerCore
    WorkerCore -->|"heartbeat & notifications"| RC
    WorkerCore -->|"persist logs"| DB

    %% Shared Utilities & Tests
    BrokerCore --> Common
    WorkerCore --> Common
    API --> Common
    UnitTests -.-> API
    UnitTests -.-> BrokerCore
    UnitTests -.-> WorkerCore

    %% Click Events
    click Common "https://github.com/limbo-io/fluxion/tree/master/fluxion-common/src/main/java/io/fluxion/common"
    click RC "https://github.com/limbo-io/fluxion/tree/master/fluxion-remote/fluxion-remote-core/src/main/java/io/fluxion/remote/core"
    click NT "https://github.com/limbo-io/fluxion/tree/master/fluxion-remote/fluxion-remote-netty/src/main/java/io/fluxion/remote/netty"
    click BrokerCore "https://github.com/limbo-io/fluxion/tree/master/fluxion-server/fluxion-server-core/src/main/java/io/fluxion/server/core"
    click DAO "https://github.com/limbo-io/fluxion/tree/master/fluxion-server/fluxion-server-core/src/main/java/io/fluxion/server/infrastructure/dao"
    click InfraFrameworks "https://github.com/limbo-io/fluxion/tree/master/fluxion-server/fluxion-server-core/src/main/java/io/fluxion/server/infrastructure"
    click API "https://github.com/limbo-io/fluxion/tree/master/fluxion-server/fluxion-server-start/src/main/java/io/fluxion/server/start"
    click Flyway "https://github.com/limbo-io/fluxion/blob/master/fluxion-server/fluxion-server-start/src/main/resources/db/migration/V20250101__init.sql"
    click WorkerCore "https://github.com/limbo-io/fluxion/tree/master/fluxion-worker/fluxion-worker-core/src/main/java/io/fluxion/worker/core"
    click WorkerDemo "https://github.com/limbo-io/fluxion/tree/master/fluxion-worker/fluxion-worker-demo/src/main/java/io/fluxion/worker/demo"
    click WorkerStarter "https://github.com/limbo-io/fluxion/tree/master/fluxion-worker/fluxion-worker-spring-boot-starter/src/main/java/io/fluxion/worker/spring/starter"
    click UnitTests "https://github.com/limbo-io/fluxion/tree/master/fluxion-test/src/test/java/io/fluxion/test"

    %% Styling
    classDef frontend fill:#D0E6FF,stroke:#3399FF,color:#000;
    classDef api fill:#CCE5FF,stroke:#66B2FF,color:#000;
    classDef core fill:#B3CDE3,stroke:#6497B1,color:#000;
    classDef rpc fill:#FFF2B2,stroke:#FFD633,color:#000;
    classDef db fill:#DFFFE0,stroke:#66CC66,color:#000;
    classDef infra fill:#FFE6CC,stroke:#FFB366,color:#000;
```
