# modcluster/mod_cluster architecture

> Architecture diagram of the GitHub repository modcluster/mod_cluster, 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/modcluster/mod_cluster
- Repository: https://github.com/modcluster/mod_cluster

## Overview

##### Project Type and Purpose
- mod_cluster is an intelligent load balancer that sits between a reverse proxy (either Apache HTTP Server or an Undertow-based Java proxy) and a pool of application servers. It dynamically adjusts worker configurations by relaying server-side load metrics and lifecycle events back to the reverse proxy.
- The README emphasizes its use in web server load balancing, detailing integration with various servlet containers (like Tomcat) and the provision of dynamic configuration based on server feedback.

##### Analysis of the File Structure
- Key modules are clearly divided. The main directories are:
- core: Contains container-independent core concepts—this is where the business logic, core services, logging, configuration, and communication protocols for mod_cluster are implemented.
- container: Contains submodules that implement container-specific integrations. Inside this directory:
- spi: Defines the Service Provider Interface (SPI) that provides abstraction and extension points for container integrations without binding to any specific web container.
- tomcat-9.0, tomcat-10.1, and tomcat-11.0: These are the different container-specific implementations for various versions of Apache Tomcat. They include integration classes, listener implementations, connector configurations, and tests.
- load-spi: Provides SPI interfaces and classes for load metric computation. It defines how different load metrics are measured and how these metrics are exposed (often via MBeans).
- Other folders like bom, code-coverage, and dist provide project’s build, assembly, and reporting setup.
- The presence of Maven settings (pom.xml in each module and mvnw) confirms that the project uses Maven’s multi-module project strategy.

##### Main Components
a. mod_cluster Core (Business Logic):
- “Core” module (found in /core) as the central component responsible for core load-balancing logic, configuration management, logging, and inter-component communication.
- Components such as the ModClusterService, configuration builders, and logging/communication utilities.
b. Container Integration Modules:
- /container directory and its submodules using components for:
– A generic SPI layer (which defines connectors, event handlers, and contextual API for container interactions).
– Specific implementations for Tomcat versions (9, 10.1, 11.0) showcasing how each integrates mod_cluster within the container lifecycle (e.g., via listeners, connectors, and event handlers).
- That these modules extend the core functionality by adapting mod_cluster’s capabilities to the specifics of the underlying web server.
c. Load Metric SPI:
- /load-spi module that provides interfaces (e.g., LoadMetric, LoadMetricMBean) and factories for computing load-balancing factors.
- How these metrics feed into the core’s decision-making process.
d. External Dependencies:
- Although not explicitly part of the project’s code tree, the README describes two kinds of reverse proxies:
– Native Apache HTTP Server module.
– Undertow-based Java implementation.
- As external components that interact (via a controlled communication channel) with mod_cluster.
e. Integration with JMX/MBeans:
- Some packages (e.g., within Tomcat modules) contain classes to support JMX (Java Management Extensions) that allow monitoring and management of load metrics.

##### Relationships and Interactions
- Maven build and assembly as peripheral elements (for build management and code coverage) if desired, but focus primarily on runtime architectural elements.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% External Reverse Proxies
    subgraph "External Reverse Proxies"
        A1("Apache HTTP Reverse Proxy"):::external
        A2("Undertow Java Proxy"):::external
    end

    %% Core Load Balancer
    Core("Core Load Balancer"):::core

    %% Container Integration Modules
    subgraph "Container Integrations"
        SPI("Container SPI"):::integration
        T9("Tomcat 9.x Integration"):::integration
        T10("Tomcat 10.1 Integration"):::integration
        T11("Tomcat 11.0 Integration"):::integration
    end

    %% Load Metric SPI Module
    LM("Load Metric SPI"):::load

    %% Relationships
    A1 -->|"sendsConfig"| Core
    A2 -->|"sendsConfig"| Core
    Core -->|"pushesConfig"| SPI
    SPI -->|"integratesWith"| T9
    SPI -->|"integratesWith"| T10
    SPI -->|"integratesWith"| T11
    T9 -->|"reportsMetrics"| Core
    T10 -->|"reportsMetrics"| Core
    T11 -->|"reportsMetrics"| Core
    LM -->|"suppliesMetrics"| Core

    %% Click Events
    click Core "https://github.com/modcluster/mod_cluster/tree/main//core"
    click SPI "https://github.com/modcluster/mod_cluster/tree/main//container/spi"
    click T9 "https://github.com/modcluster/mod_cluster/blob/main//container/tomcat-9.0"
    click T10 "https://github.com/modcluster/mod_cluster/blob/main//container/tomcat-10.1"
    click T11 "https://github.com/modcluster/mod_cluster/blob/main//container/tomcat-11.0"
    click LM "https://github.com/modcluster/mod_cluster/tree/main//load-spi"

    %% Styles
    classDef external fill:#FFF8DC,stroke:#DAA520,stroke-width:2px;
    classDef core fill:#ADD8E6,stroke:#00008B,stroke-width:2px;
    classDef integration fill:#90EE90,stroke:#006400,stroke-width:2px;
    classDef load fill:#FFDEAD,stroke:#CD853F,stroke-width:2px;
```
