# dieg0r01/simpletaskbalancer architecture

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

- Interactive diagram: https://gitdiagram.com/dieg0r01/simpletaskbalancer
- Repository: https://github.com/dieg0r01/simpletaskbalancer

## Overview

##### Project type and purpose
- This is a distributed Java application implementing the Master–Worker pattern.
- Purpose: receive CPU-intensive tasks from clients, enqueue and balance them across worker nodes, execute in parallel, then return results.

##### File structure
- Top-level scripts: compile.sh, run-client.sh, run-master.sh, run-worker.sh – drive compilation and launch of each component.
- src/main/java/com/taskbalancer:
- client/Client.java – client entry point
- master/Master.java, LoadBalancer.java, TaskQueue.java, WorkerRegistry.java, WorkerInfo.java – master side modules
- worker/Worker.java, TaskExecutor.java – worker node modules
- common/Task.java, Message.java, Result.java, SerializationUtils.java – shared message and task definitions
- tasks/… – concrete TaskHandler implementations (e.g., FactorizeTask, PrimeTestTask, MatrixMultTask, etc.)

##### README for additional insights
- Communication over TCP sockets with simple JSON messages.
- Concurrency via java.util.concurrent: ExecutorService pools, BlockingQueue for the master’s task queue, ScheduledExecutorService for heartbeats/timeouts.
- Balance strategy: least-loaded by default, fallback round-robin or queue wait.
- Workers send periodic heartbeats; master monitors and handles disconnects/retries.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client(s)" 
        direction TB
        ClientApp["Client Application"]:::client
    end

    %% Master Layer
    subgraph "Master Node" 
        direction TB
        MasterEntry["Master"]:::master
        Acceptor["Acceptor Pool\n(ServerSocket handlers)"]:::master
        Queue["Task Queue\n(BlockingQueue<Task>)"]:::queue
        Assigner["Assigner Pool\n(Task dispatch threads)"]:::master
        LoadBalancerModule["Load Balancer\n(least‐loaded algorithm)"]:::master
        Registry["Worker Registry &\nHeartbeat Monitor"]:::master
        WorkerMeta["WorkerInfo Metadata"]:::master
    end

    %% Worker Layer
    subgraph "Worker Node" 
        direction TB
        WorkerEntry["Worker"]:::worker
        TaskExec["Task Executor\n(ExecutorService pool)"]:::worker
        HeartbeatSend["Heartbeat Sender"]:::worker
    end

    %% Common Library
    subgraph "Common Library" 
        direction TB
        TaskDef["Task"]:::common
        MessageDef["Message"]:::common
        ResultDef["Result"]:::common
        Serialization["SerializationUtils"]:::common
        TasksSub["TaskHandler &\nImplementations"]:::common
    end

    %% Top‐level Scripts
    subgraph "Scripts" 
        direction TB
        Compile["compile.sh"]:::scripts
        RunClient["run-client.sh"]:::scripts
        RunMaster["run-master.sh"]:::scripts
        RunWorker["run-worker.sh"]:::scripts
    end

    %% Connections
    ClientApp -->|"submit Task JSON"| MasterEntry
    MasterEntry --> Acceptor
    Acceptor --> Queue
    Queue --> Assigner
    Assigner -->|"select Worker via"| LoadBalancerModule
    LoadBalancerModule --> Registry
    Registry --> WorkerMeta
    LoadBalancerModule -->|"assign Task JSON"| WorkerEntry
    WorkerEntry --> TaskExec
    TaskExec -->|"execute TaskHandler"| TasksSub
    WorkerEntry -->|"return Result JSON"| MasterEntry
    MasterEntry -->|"send Result"| ClientApp
    Registry -- "heartbeat ↔" --> WorkerEntry
    TaskDef --- MessageDef
    MessageDef --- ResultDef
    MessageDef --- Serialization
    TasksSub --- TaskDef

    %% Click Events
    click ClientApp "https://github.com/dieg0r01/simpletaskbalancer/blob/main/src/main/java/com/taskbalancer/client/Client.java"
    click MasterEntry "https://github.com/dieg0r01/simpletaskbalancer/blob/main/src/main/java/com/taskbalancer/master/Master.java"
    click LoadBalancerModule "https://github.com/dieg0r01/simpletaskbalancer/blob/main/src/main/java/com/taskbalancer/master/LoadBalancer.java"
    click Queue "https://github.com/dieg0r01/simpletaskbalancer/blob/main/src/main/java/com/taskbalancer/master/TaskQueue.java"
    click Registry "https://github.com/dieg0r01/simpletaskbalancer/blob/main/src/main/java/com/taskbalancer/master/WorkerRegistry.java"
    click WorkerMeta "https://github.com/dieg0r01/simpletaskbalancer/blob/main/src/main/java/com/taskbalancer/master/WorkerInfo.java"
    click WorkerEntry "https://github.com/dieg0r01/simpletaskbalancer/blob/main/src/main/java/com/taskbalancer/worker/Worker.java"
    click TaskExec "https://github.com/dieg0r01/simpletaskbalancer/blob/main/src/main/java/com/taskbalancer/worker/TaskExecutor.java"
    click TaskDef "https://github.com/dieg0r01/simpletaskbalancer/blob/main/src/main/java/com/taskbalancer/common/Task.java"
    click MessageDef "https://github.com/dieg0r01/simpletaskbalancer/blob/main/src/main/java/com/taskbalancer/common/Message.java"
    click ResultDef "https://github.com/dieg0r01/simpletaskbalancer/blob/main/src/main/java/com/taskbalancer/common/Result.java"
    click Serialization "https://github.com/dieg0r01/simpletaskbalancer/blob/main/src/main/java/com/taskbalancer/common/SerializationUtils.java"
    click TasksSub "https://github.com/dieg0r01/simpletaskbalancer/tree/main/src/main/java/com/taskbalancer/tasks"
    click Compile "https://github.com/dieg0r01/simpletaskbalancer/blob/main/compile.sh"
    click RunClient "https://github.com/dieg0r01/simpletaskbalancer/blob/main/run-client.sh"
    click RunMaster "https://github.com/dieg0r01/simpletaskbalancer/blob/main/run-master.sh"
    click RunWorker "https://github.com/dieg0r01/simpletaskbalancer/blob/main/run-worker.sh"

    %% Styles
    classDef client fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef master fill:#1E90FF,stroke:#333,stroke-width:1px;
    classDef worker fill:#32CD32,stroke:#333,stroke-width:1px;
    classDef common fill:#D3D3D3,stroke:#333,stroke-width:1px;
    classDef queue fill:#87CEEB,stroke:#333,stroke-width:1px;
    classDef scripts fill:#FFFFE0,stroke:#333,stroke-width:1px;
```
