# sephyroth1/raft-consensus-implementation architecture

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

- Interactive diagram: https://gitdiagram.com/sephyroth1/raft-consensus-implementation
- Repository: https://github.com/sephyroth1/raft-consensus-implementation

## Overview

This repository is an incomplete, from-scratch Raft consensus implementation. Its current runtime entry point creates configured node records, registers RPC services, opens listeners, converts records into runtime nodes, and starts each node’s run loop. Node code contains election-timer handling and vote/append handlers, while shared types represent node state, log entries, roles, and queued RPC events. The README also describes heartbeat and leader-election capabilities, but end-to-end execution and the main coordinating event loop remain unfinished; the graph does not imply they are complete.

Main entry points: [`RaftNode/Node.go`](https://github.com/sephyroth1/raft-consensus-implementation/blob/main/RaftNode/Node.go) (Node lifecycle), [`shared/NodeEntry.go`](https://github.com/sephyroth1/raft-consensus-implementation/blob/main/shared/NodeEntry.go) (Node state), [`main.go`](https://github.com/sephyroth1/raft-consensus-implementation/blob/main/main.go) (Cluster startup), [`RPC/network.go`](https://github.com/sephyroth1/raft-consensus-implementation/blob/main/RPC/network.go) (RPC service wrapper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime setup"]
  node_entry["Cluster startup<br/>[main.go]"]
  node_config["Timeout configuration<br/>[config.go]"]
end

subgraph group_consensus["Raft node logic"]
  node_node["Node lifecycle<br/>[Node.go]"]
  node_vote_handler["Vote handling<br/>[Node.go]"]
  node_append_handler["Append handling<br/>[Node.go]"]
end

subgraph group_transport["RPC transport"]
  node_rpc_service["RPC service wrapper<br/>[network.go]"]
  node_request_vote["Vote RPC types<br/>[RequestVote.go]"]
  node_append_entries["Append RPC types<br/>[AppendEntries.go]"]
end

subgraph group_model["Protocol data"]
  node_node_state["Node state<br/>[NodeEntry.go]"]
  node_log_entry["Log entries<br/>[LogEntry.go]"]
  node_role["Node roles<br/>[Role.go]"]
  node_rpc_event["RPC events<br/>[RpcEvent.go]"]
end

node_entry -->|"sets values"| node_config
node_entry -->|"creates and starts"| node_node
node_entry -->|"registers and listens"| node_rpc_service
node_node -->|"chooses timeout"| node_config
node_node -->|"calls"| node_vote_handler
node_node -->|"builds vote request"| node_request_vote
node_node -->|"updates role"| node_role
node_vote_handler -->|"accepts request"| node_request_vote
node_vote_handler -->|"queues event"| node_rpc_event
node_append_handler -->|"accepts request"| node_append_entries
node_append_handler -->|"updates state"| node_node_state
node_append_handler -->|"queues event"| node_rpc_event
node_rpc_service -->|"registers service"| node_node_state
node_node -->|"holds state"| node_node_state
node_node_state -->|"contains"| node_log_entry

click node_entry "https://github.com/sephyroth1/raft-consensus-implementation/blob/main/main.go"
click node_config "https://github.com/sephyroth1/raft-consensus-implementation/blob/main/Config/config.go"
click node_node "https://github.com/sephyroth1/raft-consensus-implementation/blob/main/RaftNode/Node.go"
click node_vote_handler "https://github.com/sephyroth1/raft-consensus-implementation/blob/main/RaftNode/Node.go"
click node_append_handler "https://github.com/sephyroth1/raft-consensus-implementation/blob/main/RaftNode/Node.go"
click node_rpc_service "https://github.com/sephyroth1/raft-consensus-implementation/blob/main/RPC/network.go"
click node_request_vote "https://github.com/sephyroth1/raft-consensus-implementation/blob/main/RPC/RequestVote.go"
click node_append_entries "https://github.com/sephyroth1/raft-consensus-implementation/blob/main/RPC/AppendEntries.go"
click node_node_state "https://github.com/sephyroth1/raft-consensus-implementation/blob/main/shared/NodeEntry.go"
click node_log_entry "https://github.com/sephyroth1/raft-consensus-implementation/blob/main/shared/LogEntry.go"
click node_role "https://github.com/sephyroth1/raft-consensus-implementation/blob/main/shared/Role.go"
click node_rpc_event "https://github.com/sephyroth1/raft-consensus-implementation/blob/main/shared/RpcEvent.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_entry,node_config toneBlue
class node_node,node_vote_handler,node_append_handler toneAmber
class node_rpc_service,node_request_vote,node_append_entries toneMint
class node_node_state,node_log_entry,node_role,node_rpc_event toneRose
```

## Components

### Runtime setup

- [Cluster startup](https://github.com/sephyroth1/raft-consensus-implementation/blob/main/main.go): `main.go`
- [Timeout configuration](https://github.com/sephyroth1/raft-consensus-implementation/blob/main/Config/config.go): `Config/config.go`

### Raft node logic

- [Node lifecycle](https://github.com/sephyroth1/raft-consensus-implementation/blob/main/RaftNode/Node.go): `RaftNode/Node.go`
- [Vote handling](https://github.com/sephyroth1/raft-consensus-implementation/blob/main/RaftNode/Node.go): `RaftNode/Node.go`
- [Append handling](https://github.com/sephyroth1/raft-consensus-implementation/blob/main/RaftNode/Node.go): `RaftNode/Node.go`

### RPC transport

- [RPC service wrapper](https://github.com/sephyroth1/raft-consensus-implementation/blob/main/RPC/network.go): `RPC/network.go`
- [Vote RPC types](https://github.com/sephyroth1/raft-consensus-implementation/blob/main/RPC/RequestVote.go): `RPC/RequestVote.go`
- [Append RPC types](https://github.com/sephyroth1/raft-consensus-implementation/blob/main/RPC/AppendEntries.go): `RPC/AppendEntries.go`

### Protocol data

- [Node state](https://github.com/sephyroth1/raft-consensus-implementation/blob/main/shared/NodeEntry.go): `shared/NodeEntry.go`
- [Log entries](https://github.com/sephyroth1/raft-consensus-implementation/blob/main/shared/LogEntry.go): `shared/LogEntry.go`
- [Node roles](https://github.com/sephyroth1/raft-consensus-implementation/blob/main/shared/Role.go): `shared/Role.go`
- [RPC events](https://github.com/sephyroth1/raft-consensus-implementation/blob/main/shared/RpcEvent.go): `shared/RpcEvent.go`

## Connections

- Cluster startup → Timeout configuration: sets values (evidence: `main.go`)
- Cluster startup → Node lifecycle: creates and starts (evidence: `main.go`)
- Cluster startup → RPC service wrapper: registers and listens (evidence: `main.go`)
- Node lifecycle → Timeout configuration: chooses timeout (evidence: `RaftNode/Node.go`)
- Node lifecycle → Vote handling: calls (evidence: `RaftNode/Node.go`)
- Node lifecycle → Vote RPC types: builds vote request (evidence: `RaftNode/Node.go`)
- Node lifecycle → Node roles: updates role (evidence: `RaftNode/Node.go`)
- Vote handling → Vote RPC types: accepts request (evidence: `RaftNode/Node.go`)
- Vote handling → RPC events: queues event (evidence: `RaftNode/Node.go`)
- Append handling → Append RPC types: accepts request (evidence: `RaftNode/Node.go`)
- Append handling → Node state: updates state (evidence: `RaftNode/Node.go`)
- Append handling → RPC events: queues event (evidence: `RaftNode/Node.go`)
- RPC service wrapper → Node state: registers service (evidence: `RPC/network.go`)
- Node lifecycle → Node state: holds state (evidence: `RaftNode/Node.go`)
- Node state → Log entries: contains (evidence: `shared/NodeEntry.go`)
