# hashicorp/raft architecture

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

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

## Overview

##### Main Components
- Raft Consensus Engine – At the core, this component manages log replication, leader election, follower/candidate/leader state transitions, and client interactions. Look at files such as “raft.go”, “fsm.go”, “commitment.go”, and corresponding tests.
- Transports – Multiple files deal with network or in-memory communication (e.g., “tcp_transport.go”, “net_transport.go”, “inmem_transport.go”). These modules abstract the underlying transport mechanisms for message replication between nodes.
- Log, Snapshot, and State Machines – Components handling log replication (e.g., “log.go”, “replication.go”), snapshotting (e.g., “snapshot.go”, “file_snapshot.go”, “inmem_snapshot.go”), and applying state changes via an FSM interface.
- Configuration and Cluster Membership – Files like “config.go”, “configuration.go”, “membership.md”, and “peersjson.go” show how nodes are configured and how the membership or peer set is managed.
- Auxiliary and Compatibility Modules – Notice the “raft-compat” folder and the “fuzzy” directory. These likely contain compatibility wrappers and fuzz testing utilities to simulate or stress the consensus protocol.
- Metrics – The README highlights that metrics emission can be routed either via “github.com/armon/go-metrics” or “github.com/hashicorp/go-metrics”. You may want to represent this as an ancillary component that hooks into multiple parts of the system for monitoring purposes.

##### Relationships and Component Interactions
- A Raft Node – Think of each node as a self-contained unit that includes the Raft consensus engine, the transport module for communicating with peers, the log replication mechanism, and the local state machine (FSM) that applies committed log entries.
- Client/API Interactions – Though this is a library rather than a standalone service, clients (or higher-level applications) will interact with the Raft node typically through an API (see “api.go”). This component should be shown interacting with the Raft engine to commit log entries.

##### Architectural Patterns and Design Principles
- Clear Separation of Concerns – The Raft implementation cleanly separates consensus logic from state machine application, snapshotting, and client interaction.

##### Putting It All Together
- Within each node, detail the following:
- A “Raft Engine” block that contains consensus logic and leader election.
- A “Transport Module” block (with sub-labels such as TCP, in-memory, etc.) showing how nodes communicate.
- A “Log & Snapshot Store” block and an adjacent “FSM” block, showing the sequence: log entry → commit → FSM apply.
- A “Configuration & Membership” element that interacts with the Raft Engine.

## Diagram (Mermaid)

```mermaid
graph TD
    API("Client/API"):::core
    MET("Metrics & Observability"):::metrics
    AUX("Auxiliary & Compatibility Modules"):::aux

    subgraph "Raft Cluster"
        RE("Raft Consensus Engine"):::core
        TR("Transport Module"):::core
        LS("Log & Snapshot"):::core
        FSM("State Machine (FSM)"):::core
        CM("Configuration & Membership"):::core
    end

    API -->|"submits_command"| RE
    RE -->|"replicates_log"| TR
    RE -->|"persists_log"| LS
    LS -->|"applies_command"| FSM
    RE -->|"updates_config"| CM

    MET -->|"monitors"| RE
    MET -->|"monitors"| TR
    MET -->|"monitors"| LS
    MET -->|"monitors"| FSM

    AUX --- RE
    AUX --- TR

    %% Click Events for Raft Consensus Engine
    click RE "https://github.com/hashicorp/raft/blob/main/raft.go"
    click RE "https://github.com/hashicorp/raft/blob/main/raft_test.go"
    click RE "https://github.com/hashicorp/raft/blob/main/fsm.go"
    click RE "https://github.com/hashicorp/raft/blob/main/commitment.go"
    click RE "https://github.com/hashicorp/raft/blob/main/commitment_test.go"

    %% Click Events for Transports
    click TR "https://github.com/hashicorp/raft/blob/main/tcp_transport.go"
    click TR "https://github.com/hashicorp/raft/blob/main/tcp_transport_test.go"
    click TR "https://github.com/hashicorp/raft/blob/main/net_transport.go"
    click TR "https://github.com/hashicorp/raft/blob/main/net_transport_test.go"
    click TR "https://github.com/hashicorp/raft/blob/main/inmem_transport.go"
    click TR "https://github.com/hashicorp/raft/blob/main/inmem_transport_test.go"
    click TR "https://github.com/hashicorp/raft/blob/main/transport.go"
    click TR "https://github.com/hashicorp/raft/blob/main/transport_test.go"

    %% Click Events for Log, Snapshot, and State Machines
    click LS "https://github.com/hashicorp/raft/blob/main/log.go"
    click LS "https://github.com/hashicorp/raft/blob/main/replication.go"
    click LS "https://github.com/hashicorp/raft/blob/main/snapshot.go"
    click LS "https://github.com/hashicorp/raft/blob/main/file_snapshot.go"
    click LS "https://github.com/hashicorp/raft/blob/main/file_snapshot_test.go"
    click LS "https://github.com/hashicorp/raft/blob/main/inmem_snapshot.go"
    click LS "https://github.com/hashicorp/raft/blob/main/inmem_snapshot_test.go"

    %% Click Events for Configuration and Cluster Membership
    click CM "https://github.com/hashicorp/raft/blob/main/config.go"
    click CM "https://github.com/hashicorp/raft/blob/main/configuration.go"
    click CM "https://github.com/hashicorp/raft/blob/main/configuration_test.go"
    click CM "https://github.com/hashicorp/raft/blob/main/peersjson.go"
    click CM "https://github.com/hashicorp/raft/blob/main/peersjson_test.go"
    click CM "https://github.com/hashicorp/raft/blob/main/membership.md"

    %% Click Event for Client/API Interactions
    click API "https://github.com/hashicorp/raft/blob/main/api.go"

    %% Click Events for Auxiliary and Compatibility Modules
    click AUX "https://github.com/hashicorp/raft/tree/main/raft-compat"
    click AUX "https://github.com/hashicorp/raft/tree/main/fuzzy"

    classDef core fill:#bbf,stroke:#333,stroke-width:2px;
    classDef aux fill:#f9d,stroke:#933,stroke-width:2px;
    classDef metrics fill:#dfd,stroke:#393,stroke-width:2px;
```
