# nicktindall/java-raft architecture

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

- Interactive diagram: https://gitdiagram.com/nicktindall/java-raft
- Repository: https://github.com/nicktindall/java-raft

## Overview

##### Project type and purpose
- This is a Java library (“java-raft”) implementing the Raft distributed consensus algorithm.
- It is not a user-facing front-end or full-stack app, but a core algorithm/toolkit that consumers embed in their own services.

##### File structure
- Single codebase under src/main/java/au/id/tindall/distalg/raft, split into sub-packages:
- rpc (client, server, clustermembership, snapshots)
- comms (Cluster, ClientConnection)
- elections
- log (entries, storage)
- replication
- serverstates (Follower, Candidate, Leader, plus membership/change/transfer)
- state (persistent state, snapshots)
- statemachine (command execution)
- processors (InboxProcessor, ReplicationProcessor, ProcessorManager, etc.)
- serialisation
- util, threading, timing
- client (sessions, pending responses) and clusterclient (ClusterClient, AdminClient)
- Tests mirror the same structure under src/test.

##### Key insights from the README
- Core features: leader election, log replication, snapshotting, cluster membership, linearizable semantics.
- Runtime dependency: only log4j2.
- Build/deploy via Gradle; CI via CircleCI and Jenkinsfile.

##### Main components
a. Client APIs
- ClientSession, PendingResponseRegistry, ClusterClient, ClusterAdminClient
b. Raft Server Node
- Server (ServerImpl) & ServerFactory
- RPC layer (AppendEntries, RequestVote, client RPCs)
- Communication layer (ClusterFactory → Cluster → ClientConnection)
- Processor framework (ProcessorManager, InboxProcessor, ReplicationProcessor, ElectionScheduler)
- Elections module (ElectionScheduler, ElectionTimeoutGenerator)
- Replication module (LogReplicator, HeartbeatScheduler, SnapshotReplicator)
- Log & Storage (Log, LogStorage, PersistentLogStorage, InMemoryLogStorage)
- Persistent State & Snapshots (PersistentState, Snapshotter)
- State machine (StateMachine, CommandExecutor)
- ServerStates (Follower, Candidate, Leader + membership/transfer handlers)
- Serialisation (ByteBufferIO, IDSerializer)
c. External services & resources
- Network (TCP/UDP or simulated via comms)
- Disk I/O (for persistent state & snapshots)
- Logging (log4j2)

##### Relationships & dataflows
- Client → RPC layer → Server
- Server RPC → Comms → other Server RPCs
- RPC messages → Serialisation in/out
- RPC events → InboxProcessor → ProcessorManager dispatch
- ElectionScheduler & ReplicationScheduler drive timed tasks
- Processors append to Log → Commit → apply to StateMachine
- Log entries & state → persisted to disk (LogStorage, PersistentState)
- Snapshotter triggers compaction, writes snapshots to disk
- ClusterAdminClient → RPC → membership change handlers inside ServerStates

##### Architectural patterns & principles
- Modular layering: API → RPC → Comms → Processing → Core Raft modules → Storage
- Factory pattern for pluggable components (ServerFactory, LogFactory, SnapshotterFactory)
- Event-driven processors (handlers invoked on message/events)
- Separation of concerns: each sub-package owns one slice of Raft logic
- In-memory vs persistent implementations for easy testing/flexibility

##### Essential elements to capture
- Client/ClusterClient → RPC → Server
- RPC → Comms → Network → Other RPC
- Incoming RPC → InboxProcessor → ProcessorManager
- Processors trigger ElectionScheduler, ReplicationScheduler
- Processors append entries → LogStorage → Disk
- Commit events → StateMachine.applyCommand
- Snapshotter triggered by log compaction logic
- ServerState transitions (Follower ↔ Candidate ↔ Leader)
- Factory interfaces for plugging in custom storage, threading, state machine

##### Final advice
- Clearly label interfaces and their implementations to highlight extensibility points.
- Runtime topology (clients, nodes, storage) rather than build scripts or test code.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client APIs"
        Session["ClientSession"]:::clientapi
        Pending["PendingResponseRegistry"]:::clientapi
        ClusterClient["ClusterClient"]:::clientapi
        ClusterAdmin["ClusterAdminClient"]:::clientapi
    end

    subgraph "Raft Engine"
        subgraph "RPC Layer"
            RPCClient["rpc.client"]:::engine
            RPCServer["rpc.server"]:::engine
            RPCCluster["rpc.clustermembership"]:::engine
            RPCSnapshot["rpc.snapshots"]:::engine
        end

        subgraph "Comms"
            ClusterFactory["ClusterFactory"]:::engine
            Cluster["Cluster"]:::engine
            ClientConn["ClientConnection"]:::engine
            MsgProcessor["MessageProcessor"]:::engine
        end

        subgraph "Processor Framework"
            ProcManager["ProcessorManager"]:::engine
            InboxProc["InboxProcessor"]:::engine
            ReplProc["ReplicationProcessor"]:::engine
        end

        subgraph "Elections"
            ElectSched["ElectionScheduler"]:::engine
        end

        subgraph "Replication"
            LogRepl["LogReplicator"]:::engine
            HeartbeatSched["HeartbeatReplicationScheduler"]:::engine
            SnapshotRepl["SnapshotReplicator"]:::engine
        end

        subgraph "Log & Storage"
            LogAbstr["Log"]:::interface
            LogEntries["log.entries"]:::engine
            LogStorage["LogStorage"]:::store
            InMemLog["InMemoryLogStorage"]:::store
            PersistLog["PersistentLogStorage"]:::store
        end

        subgraph "State & Snapshots"
            PersistState["PersistentState"]:::interface
            SnapInterface["Snapshot"]:::interface
            Snapshotter["Snapshotter"]:::engine
        end

        subgraph "State Machine"
            SM["StateMachine"]:::interface
            CmdExec["CommandExecutor"]:::engine
        end

        subgraph "Server States"
            Follower["Follower"]:::engine
            Candidate["Candidate"]:::engine
            Leader["Leader"]:::engine
        end
    end

    subgraph "External"
        Network["Network (TCP/UDP)"]:::external
        Disk["Disk I/O"]:::external
        Logging["log4j2"]:::external
    end

    Session -->|uses RPC| RPCServer
    Pending -->|manages responses| ProcManager
    ClusterClient -->|initiates RPC| RPCServer
    ClusterAdmin -->|admin RPC| RPCServer

    RPCServer -->|serialises| RPCClient
    RPCServer -->|sends| MsgProcessor
    MsgProcessor -->|dispatches to| InboxProc
    InboxProc -->|submits to| ProcManager

    ProcManager -->|schedules| ElectSched
    ProcManager -->|schedules| LogRepl
    ProcManager -->|schedules| SnapshotRepl

    LogRepl -->|writes to| LogAbstr
    LogAbstr -->|uses| LogStorage
    LogStorage -->|persists to| Disk
    InMemLog -->|alternative| LogStorage
    PersistLog -->|alternative| LogStorage

    ProcManager -->|commits| SM
    Snapshotter -->|compacts| PersistState
    Snapshotter -->|writes to| Disk

    RPCServer -->|heartbeat| HeartbeatSched
    RPCServer -->|snapshot RPC| SnapshotRepl

    RPCServer -->|invokes| Follower
    RPCServer -->|invokes| Candidate
    RPCServer -->|invokes| Leader

    RPCServer --> Logging

    Network --> RPCServer

    classDef clientapi fill:#D6EAF8,stroke:#3498DB;
    classDef engine fill:#AED6F1,stroke:#2E86C1;
    classDef interface fill:#A9DFBF,stroke:#27AE60;
    classDef store fill:#F9E79F,stroke:#B7950B;
    classDef external fill:#D5D8DC,stroke:#566573;

    click Session "https://github.com/nicktindall/java-raft/blob/master/src/main/java/au/id/tindall/distalg/raft/client/sessions/ClientSession.java"
    click Pending "https://github.com/nicktindall/java-raft/blob/master/src/main/java/au/id/tindall/distalg/raft/client/responses/PendingResponseRegistry.java"
    click ClusterClient "https://github.com/nicktindall/java-raft/blob/master/src/main/java/au/id/tindall/distalg/raft/clusterclient/ClusterClient.java"
    click ClusterAdmin "https://github.com/nicktindall/java-raft/blob/master/src/main/java/au/id/tindall/distalg/raft/clusterclient/ClusterAdminClient.java"
    click ElectSched "https://github.com/nicktindall/java-raft/blob/master/src/main/java/au/id/tindall/distalg/raft/elections/ElectionScheduler.java"
    click LogRepl "https://github.com/nicktindall/java-raft/blob/master/src/main/java/au/id/tindall/distalg/raft/replication/LogReplicator.java"
    click Snapshotter "https://github.com/nicktindall/java-raft/blob/master/src/main/java/au/id/tindall/distalg/raft/snapshotting/Snapshotter.java"
    click LogStorage "https://github.com/nicktindall/java-raft/blob/master/src/main/java/au/id/tindall/distalg/raft/log/storage/LogStorage.java"
    click InMemLog "https://github.com/nicktindall/java-raft/blob/master/src/main/java/au/id/tindall/distalg/raft/log/storage/InMemoryLogStorage.java"
    click PersistLog "https://github.com/nicktindall/java-raft/blob/master/src/main/java/au/id/tindall/distalg/raft/log/storage/PersistentLogStorage.java"
    click PersistState "https://github.com/nicktindall/java-raft/blob/master/src/main/java/au/id/tindall/distalg/raft/state/PersistentState.java"
    click SM "https://github.com/nicktindall/java-raft/blob/master/src/main/java/au/id/tindall/distalg/raft/statemachine/StateMachine.java"
    click Follower "https://github.com/nicktindall/java-raft/blob/master/src/main/java/au/id/tindall/distalg/raft/serverstates/Follower.java"
    click Candidate "https://github.com/nicktindall/java-raft/blob/master/src/main/java/au/id/tindall/distalg/raft/serverstates/Candidate.java"
    click Leader "https://github.com/nicktindall/java-raft/blob/master/src/main/java/au/id/tindall/distalg/raft/serverstates/Leader.java"
```
