# igotlinux/raft-kv architecture

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

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

## Overview

This is a five-node Raft-replicated key-value service. A client sends a write to a node’s HTTP API; the API proposes it through the store to Raft, which replicates and commits log entries. The store applies committed entries and the API returns the outcome; reads use local state, while non-leader writes receive a leader hint. Raft persists log and term state, and nodes communicate over HTTP. The admin API configures live fault injection. The graph follows the README and shown wiring; unsampled internals are not inferred.

Main entry points: [`cmd/server/main.go`](https://github.com/igotlinux/raft-kv/blob/main/cmd/server/main.go) (Node Bootstrap), [`internal/raft/raft.go`](https://github.com/igotlinux/raft-kv/blob/main/internal/raft/raft.go) (Raft Node), [`internal/kv/http_api.go`](https://github.com/igotlinux/raft-kv/blob/main/internal/kv/http_api.go) (KV HTTP API), [`internal/kv/store.go`](https://github.com/igotlinux/raft-kv/blob/main/internal/kv/store.go) (KV Store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Client API"]
  node_http_api["KV HTTP API<br/>[http_api.go]"]
end

subgraph group_state["Replicated State"]
  node_store["KV Store<br/>[store.go]"]
  node_persister[("WAL Persister<br/>[persister.go]")]
end

subgraph group_consensus["Raft Consensus"]
  node_raft["Raft Node<br/>[raft.go]"]
  node_raft_types["Log and Commands<br/>[types.go]"]
  node_raft_rpc["Raft RPC Types<br/>[rpc.go]"]
  node_http_transport["HTTP Transport<br/>[http.go]"]
end

subgraph group_operations["Node Operations"]
  node_admin_api["Fault Admin API<br/>[admin.go]"]
  node_faults["Fault Injector<br/>[http.go]"]
  node_server["Node Bootstrap<br/>[main.go]"]
end

node_client(("Client"))
node_peer_node(("Peer Raft Node"))

node_client -->|"sends requests"| node_http_api
node_http_api -->|"proposes writes"| node_store
node_http_api -->|"reads local state"| node_store
node_http_api -->|"reads status"| node_raft
node_store -->|"starts commands"| node_raft
node_raft -->|"delivers commits"| node_store
node_raft -->|"persists log state"| node_persister
node_raft -->|"sends peer RPCs"| node_http_transport
node_http_transport -->|"sends HTTP RPCs"| node_peer_node
node_peer_node -->|"calls RPC handlers"| node_http_transport
node_admin_api -->|"sets fault modes"| node_faults
node_faults -->|"filters outbound RPCs"| node_http_transport
node_server -->|"creates"| node_persister
node_server -->|"configures"| node_http_transport
node_server -->|"starts node"| node_raft
node_server -->|"runs state machine"| node_store
node_server -->|"registers API"| node_http_api
node_server -->|"registers admin routes"| node_admin_api

click node_http_api "https://github.com/igotlinux/raft-kv/blob/main/internal/kv/http_api.go"
click node_store "https://github.com/igotlinux/raft-kv/blob/main/internal/kv/store.go"
click node_raft "https://github.com/igotlinux/raft-kv/blob/main/internal/raft/raft.go"
click node_raft_types "https://github.com/igotlinux/raft-kv/blob/main/internal/raft/types.go"
click node_raft_rpc "https://github.com/igotlinux/raft-kv/blob/main/internal/raft/rpc.go"
click node_persister "https://github.com/igotlinux/raft-kv/blob/main/internal/raft/persister.go"
click node_http_transport "https://github.com/igotlinux/raft-kv/blob/main/internal/transport/http.go"
click node_admin_api "https://github.com/igotlinux/raft-kv/blob/main/internal/transport/admin.go"
click node_faults "https://github.com/igotlinux/raft-kv/blob/main/internal/transport/http.go"
click node_server "https://github.com/igotlinux/raft-kv/blob/main/cmd/server/main.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_http_api,node_client toneBlue
class node_store,node_persister toneAmber
class node_raft,node_raft_types,node_raft_rpc,node_http_transport toneMint
class node_admin_api,node_faults,node_server toneRose
class node_peer_node toneIndigo
```

## Components

### Client API

- [KV HTTP API](https://github.com/igotlinux/raft-kv/blob/main/internal/kv/http_api.go): `internal/kv/http_api.go`

### Replicated State

- [KV Store](https://github.com/igotlinux/raft-kv/blob/main/internal/kv/store.go): `internal/kv/store.go`
- [WAL Persister](https://github.com/igotlinux/raft-kv/blob/main/internal/raft/persister.go): `internal/raft/persister.go`

### Raft Consensus

- [Raft Node](https://github.com/igotlinux/raft-kv/blob/main/internal/raft/raft.go): `internal/raft/raft.go`
- [Log and Commands](https://github.com/igotlinux/raft-kv/blob/main/internal/raft/types.go): `internal/raft/types.go`
- [Raft RPC Types](https://github.com/igotlinux/raft-kv/blob/main/internal/raft/rpc.go): `internal/raft/rpc.go`
- [HTTP Transport](https://github.com/igotlinux/raft-kv/blob/main/internal/transport/http.go): `internal/transport/http.go`

### Node Operations

- [Fault Admin API](https://github.com/igotlinux/raft-kv/blob/main/internal/transport/admin.go): `internal/transport/admin.go`
- [Fault Injector](https://github.com/igotlinux/raft-kv/blob/main/internal/transport/http.go): `internal/transport/http.go`
- [Node Bootstrap](https://github.com/igotlinux/raft-kv/blob/main/cmd/server/main.go): `cmd/server/main.go`

### Other components

- **Client**
- **Peer Raft Node**

## Connections

- Client → KV HTTP API: sends requests (evidence: `README.md`)
- KV HTTP API → KV Store: proposes writes (evidence: `internal/kv/http_api.go`)
- KV HTTP API → KV Store: reads local state (evidence: `internal/kv/http_api.go`)
- KV HTTP API → Raft Node: reads status (evidence: `internal/kv/http_api.go`)
- KV Store → Raft Node: starts commands (evidence: `internal/kv/store.go`)
- Raft Node → KV Store: delivers commits (evidence: `README.md`)
- Raft Node → WAL Persister: persists log state (evidence: `internal/raft/raft.go`)
- Raft Node → HTTP Transport: sends peer RPCs (evidence: `README.md`)
- HTTP Transport → Peer Raft Node: sends HTTP RPCs (evidence: `internal/transport/http.go`)
- Peer Raft Node → HTTP Transport: calls RPC handlers (evidence: `internal/transport/http.go`)
- Fault Admin API → Fault Injector: sets fault modes (evidence: `internal/transport/admin.go`)
- Fault Injector → HTTP Transport: filters outbound RPCs (evidence: `internal/transport/http.go`)
- Node Bootstrap → WAL Persister: creates (evidence: `cmd/server/main.go`)
- Node Bootstrap → HTTP Transport: configures (evidence: `cmd/server/main.go`)
- Node Bootstrap → Raft Node: starts node (evidence: `cmd/server/main.go`)
- Node Bootstrap → KV Store: runs state machine (evidence: `cmd/server/main.go`)
- Node Bootstrap → KV HTTP API: registers API (evidence: `cmd/server/main.go`)
- Node Bootstrap → Fault Admin API: registers admin routes (evidence: `cmd/server/main.go`)
