# otoolep/hraftd architecture

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

- Interactive diagram: https://gitdiagram.com/otoolep/hraftd
- Repository: https://github.com/otoolep/hraftd

## Overview

##### Project type and purpose
- This is a small Go-based distributed system (“hraftd”) that demonstrates a replicated key-value store using the Hashicorp Raft consensus library.
- The README describes it as a reference implementation of Raft: each node exposes an HTTP API for GET/POST on keys, and internally uses Raft to replicate changes across a cluster.

##### File structure
- main.go: sets up the Raft node and HTTP server.
- http/service.go (+ service_test.go): HTTP API layer that handles client requests.
- store/store.go (+ store_test.go): in-memory key-value store implementing Raft’s FSM interface (applies committed log entries).
- go.mod/go.sum: dependency management (notably hashicorp/raft).
- CLUSTERING.md: documentation for multi-node setups.
- .circleci/config.yml, appveyor.yml: CI pipelines.

##### README for additional insights
- Describes how nodes discover each other (–join flag) and how Raft handles leader election, replication, and failure recovery.
- Mentions that HTTP requests for writes must go to the leader; GETs can be served by any node (allowing stale reads).

a. Main components
- Client(s): CLI or curl issuing HTTP requests.
- HTTP Service layer: Go net/http handlers (service.go).
- Raft Node (Hashicorp Raft library):
– Transport layer (RPC between nodes)
– Log store (on-disk)
– Finite State Machine (FSM) interface implemented by store/store.go
- In-memory key-value store (FSM state)
- Persistent storage directories (per-node data directory)
- Peers (other hraftd instances)

b. Relationships and interactions
1. Client → HTTP Service: POST /key and GET /key/{k}.
2. On POST: HTTP Service calls raft.Apply(entry).
3. Raft Leader appends entry to local log store, then replicates via Transport RPCs to followers.
4. Once a quorum acknowledges, the log is marked committed.
5. Raft calls FSM.Apply(logEntry) on all nodes, invoking store/store.go to update the in-memory map.
6. HTTP Service returns a success response to the client.
7. On GET: HTTP Service reads directly from the in-memory store and returns the value.

c. Architectural patterns & design principles
– Replicated State Machine: all nodes apply the same sequence of log entries.
– Leader-Follower Consensus: one leader coordinates writes, followers replicate logs.
– Pluggable FSM: separation of Raft protocol (transport + log) from application state (key-value store).
– Stateless HTTP layer (aside from hitting the FSM).

d. Technologies & libraries
– Go (language)
– net/http for service.go
– github.com/hashicorp/raft for consensus
– Filesystem for log storage and snapshots (under node data directory)
– Testing: Go’s built-in testing framework

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Clients["Clients (curl, CLI)"]:::external

    %% Cluster of hraftd Nodes
    subgraph "hraftd Cluster"
        direction TB

        subgraph "Node A (Leader)"
            direction TB
            A_main["Main (hraftd)"]:::api
            A_http["HTTP Service"]:::api
            A_raft["Raft Module"]:::consensus
            A_fsm["FSM (Key-Value Store)"]:::storage
            A_store["Data Dir (Logs & Snapshots)"]:::storage
        end

        subgraph "Node B (Follower)"
            direction TB
            B_main["Main (hraftd)"]:::api
            B_http["HTTP Service"]:::api
            B_raft["Raft Module"]:::consensus
            B_fsm["FSM (Key-Value Store)"]:::storage
            B_store["Data Dir (Logs & Snapshots)"]:::storage
        end

        subgraph "Node C (Follower)"
            direction TB
            C_main["Main (hraftd)"]:::api
            C_http["HTTP Service"]:::api
            C_raft["Raft Module"]:::consensus
            C_fsm["FSM (Key-Value Store)"]:::storage
            C_store["Data Dir (Logs & Snapshots)"]:::storage
        end
    end

    %% Documentation & CI
    subgraph "Repository Artifacts"
        direction TB
        README["README.md"]:::doc
        CLUSTERING["CLUSTERING.md"]:::doc
        GoMod["go.mod"]:::doc
        GoSum["go.sum"]:::doc
        CircleCI[".circleci/config.yml"]:::doc
        AppVeyor["appveyor.yml"]:::doc
    end

    %% Client to HTTP Service interactions
    Clients -->|"POST /key (writes to leader)"| A_http
    Clients -->|"GET /key (reads any node)"| B_http
    Clients -->|"GET /key (reads any node)"| C_http

    %% HTTP to Raft Apply
    A_http -->|"raft.Apply(entry)"| A_raft
    B_http -->|"raft.Apply(entry)"| B_raft
    C_http -->|"raft.Apply(entry)"| C_raft

    %% Raft replication between nodes
    A_raft -->|"AppendEntries RPCs"| B_raft
    A_raft -->|"AppendEntries RPCs"| C_raft

    %% Log commit to FSM
    A_raft -->|"FSM.Apply(logEntry)"| A_fsm
    B_raft -->|"FSM.Apply(logEntry)"| B_fsm
    C_raft -->|"FSM.Apply(logEntry)"| C_fsm

    %% HTTP GET reads from FSM
    A_http -->|"read FSM"| A_fsm
    B_http -->|"read FSM"| B_fsm
    C_http -->|"read FSM"| C_fsm

    %% Click Events
    click A_main "https://github.com/otoolep/hraftd/blob/master/main.go"
    click A_http "https://github.com/otoolep/hraftd/blob/master/http/service.go"
    click A_fsm "https://github.com/otoolep/hraftd/blob/master/store/store.go"
    click README "https://github.com/otoolep/hraftd/blob/master/README.md"
    click CLUSTERING "https://github.com/otoolep/hraftd/blob/master/CLUSTERING.md"
    click GoMod "https://github.com/otoolep/hraftd/blob/master/go.mod"
    click GoSum "https://github.com/otoolep/hraftd/blob/master/go.sum"
    click CircleCI "https://github.com/otoolep/hraftd/blob/master/.circleci/config.yml"
    click AppVeyor "https://github.com/otoolep/hraftd/blob/master/appveyor.yml"

    %% Styles
    classDef external fill:#dddddd,stroke:#777,stroke-width:1px;
    classDef api fill:#cce5ff,stroke:#3399ff,stroke-width:1px;
    classDef consensus fill:#ffe0b3,stroke:#ff9933,stroke-width:1px;
    classDef storage fill:#d5f5d5,stroke:#33cc33,stroke-width:1px;
    classDef doc fill:#f2f2f2,stroke:#999,stroke-width:1px,stroke-dasharray: 2 2;
```
