# chengchen/leadership-consul architecture

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

- Interactive diagram: https://gitdiagram.com/chengchen/leadership-consul
- Repository: https://github.com/chengchen/leadership-consul

## Overview

##### Project type and purpose
- This is a Java library (“open-source tool”) that provides leader-election functionality on top of Consul (with an alternative HTTP-only variant).
- Its core offering is a `Gambler` abstraction that emits leadership events (`elected`, `revoked`, etc.) by interacting with Consul’s session and key-value APIs.

##### File structure
- Top-level build files: Gradle wrappers and `build.gradle`.
- `src/main/java/net/kinguin/leadership/core`: core interfaces and abstractions (e.g., `Member`, `ElectionMessage`, `AbstractClusterFactory`).
- `src/main/java/net/kinguin/leadership/consul`: Consul-based implementation, with subpackages for configuration (`config`), election (`election`), factory (`factory`), and operations (`operation`).
- `src/main/java/net/kinguin/leadership/http`: HTTP-only fallback client implementation.
- Tests mirror that structure, plus a `docker-compose.yml` to spin up Consul for integration tests.

##### README for additional insights
- Usage examples show how `SimpleClusterFactory` builds a `Gambler` that “asObservable” emits events.
- A Spring integration example wires in `SessionConsulClient` and `KeyValueConsulClient` beans.

##### Main components and their relationships
a. Core library (package “core”)
- Interfaces / data models: `Member`, `ElectionMessage`, `ElectionState`, `ClusterConfiguration`
- Factory abstraction: `AbstractClusterFactory` → produces `Gambler` instances
b. Consul implementation (package “consul”)
- Clients: `SessionConsulClient`, `KeyValueConsulClient`
- Operations: `CreateSession`, `UpkeepSession` (manage TTL/session refresh)
- Cluster factory: `SimpleConsulClusterFactory` uses clients + operations to instantiate a `ConsulMember`
c. HTTP-only implementation (package “http”)
- `HttpMember`, `HttpMemberProperties`, `ElectionResponse` (for environments that proxy Consul HTTP themselves)
d. External service
- Consul agent (on TCP 8500) – provides HTTP APIs for sessions and KV store
e. Consumers
- Application code subscribes to the `Observable` returned by `Gambler.asObservable()` to react to leadership events

##### Essential architectural elements to capture
- Core vs. implementation modules
- Factory → Member → Client → External Consul
- Reactive event stream returning to the user’s application
- Configuration inputs (`ClusterConfiguration`, Spring-style properties)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application
    YourApp["Your Application"]:::app

    %% Core Abstractions
    subgraph "Core Abstractions"
        direction TB
        Member["Member"]:::core
        ElectionMessage["ElectionMessage"]:::core
        ElectionState["ElectionState"]:::core
        DummyMember["DummyMember"]:::core
        AbstractClusterFactory["AbstractClusterFactory"]:::factory
    end

    %% Consul Implementation
    subgraph "Consul Implementation"
        direction TB
        SimpleConsulClusterFactory["SimpleConsulClusterFactory"]:::consul
        ConsulMember["ConsulMember"]:::consul
        CreateSession["CreateSession"]:::consul
        UpkeepSession["UpkeepSession"]:::consul
        SessionConsulClient["SessionConsulClient"]:::consul
        KeyValueConsulClient["KeyValueConsulClient"]:::consul
    end

    %% HTTP Implementation
    subgraph "HTTP Implementation"
        direction TB
        HttpMemberProperties["HttpMemberProperties"]:::http
        HttpMember["HttpMember"]:::http
        ElectionResponse["ElectionResponse"]:::http
    end

    %% External Services
    ConsulAgent["Consul Agent\n(TCP 8500)"]:::external
    HTTPProxy["Consul HTTP Endpoint"]:::external

    %% Relationships
    YourApp -->|uses| AbstractClusterFactory
    AbstractClusterFactory -->|produces| SimpleConsulClusterFactory
    AbstractClusterFactory -->|produces| HttpMember

    SimpleConsulClusterFactory -->|instantiates| ConsulMember
    ConsulMember -->|calls| SessionConsulClient
    ConsulMember -->|calls| KeyValueConsulClient
    SessionConsulClient -->|uses| CreateSession
    SessionConsulClient -->|uses| UpkeepSession
    CreateSession -->|HTTP API| ConsulAgent
    UpkeepSession -->|HTTP API| ConsulAgent
    KeyValueConsulClient -->|HTTP API| ConsulAgent

    HttpMemberProperties -->|configures| HttpMember
    HttpMember -->|HTTP API| HTTPProxy

    ConsulMember -->|emits events| ElectionMessage
    HttpMember -->|emits events| ElectionMessage
    ElectionMessage -->|stream| YourApp

    %% Click Events
    click Member "https://github.com/chengchen/leadership-consul/blob/master/src/main/java/net/kinguin/leadership/core/Member.java"
    click ElectionMessage "https://github.com/chengchen/leadership-consul/blob/master/src/main/java/net/kinguin/leadership/core/ElectionMessage.java"
    click ElectionState "https://github.com/chengchen/leadership-consul/blob/master/src/main/java/net/kinguin/leadership/core/ElectionState.java"
    click DummyMember "https://github.com/chengchen/leadership-consul/blob/master/src/main/java/net/kinguin/leadership/core/DummyMember.java"
    click AbstractClusterFactory "https://github.com/chengchen/leadership-consul/blob/master/src/main/java/net/kinguin/leadership/core/factory/AbstractClusterFactory.java"
    click SimpleConsulClusterFactory "https://github.com/chengchen/leadership-consul/blob/master/src/main/java/net/kinguin/leadership/consul/factory/SimpleConsulClusterFactory.java"
    click CreateSession "https://github.com/chengchen/leadership-consul/blob/master/src/main/java/net/kinguin/leadership/consul/operation/CreateSession.java"
    click UpkeepSession "https://github.com/chengchen/leadership-consul/blob/master/src/main/java/net/kinguin/leadership/consul/operation/UpkeepSession.java"
    click ConsulMember "https://github.com/chengchen/leadership-consul/blob/master/src/main/java/net/kinguin/leadership/consul/election/ConsulMember.java"
    click HttpMember "https://github.com/chengchen/leadership-consul/blob/master/src/main/java/net/kinguin/leadership/http/HttpMember.java"
    click ElectionResponse "https://github.com/chengchen/leadership-consul/blob/master/src/main/java/net/kinguin/leadership/http/ElectionResponse.java"
    click HttpMemberProperties "https://github.com/chengchen/leadership-consul/blob/master/src/main/java/net/kinguin/leadership/http/config/HttpMemberProperties.java"

    %% Styles
    classDef core fill:#E3F2FD,stroke:#90CAF9,color:#0D47A1;
    classDef factory fill:#E8F5E9,stroke:#66BB6A,color:#1B5E20;
    classDef consul fill:#E8F5E9,stroke:#4CAF50,color:#1B5E20;
    classDef http fill:#FFF3E0,stroke:#FFB74D,color:#E65100;
    classDef external fill:#ECEFF1,stroke:#90A4AE,color:#546E7A;
    classDef app fill:#FFFDE7,stroke:#FDD835,color:#F57F17;
```
