# p-types/raft-consensus-distributed-systems-simulator architecture

> Architecture diagram of the GitHub repository p-types/raft-consensus-distributed-systems-simulator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/p-types/raft-consensus-distributed-systems-simulator
- Repository: https://github.com/p-types/raft-consensus-distributed-systems-simulator

## Overview

This repository is a Raft consensus simulator that grows from an in-memory algorithm demonstration into a networked cluster with persistence, HTTP controls, and a live dashboard. Its main user workflow is to run nodes, submit commands to a leader, and observe replicated state; operators can also simulate partitions and heal links. The Python phases are separate educational simulations, while the Go phase provides the networked runtime. The dashboard and some documented capabilities are represented from README/tree evidence; unsampled wiring is not asserted.

Main entry points: [`phase4_networking/cmd/node/main.go`](https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase4_networking/cmd/node/main.go) (Node Process), [`phase4_networking/raft/node.go`](https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase4_networking/raft/node.go) (Raft Node State), [`phase4_networking/raft/command_endpoint.go`](https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase4_networking/raft/command_endpoint.go) (Command Endpoints), [`phase4_networking/raft/replication.go`](https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase4_networking/raft/replication.go) (Log Replication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python Simulations"]
  node_phase1["Core Node State<br/>[raft_node.py]"]
  node_election_sim["Election Simulation<br/>[cluster.py]"]
  node_election_node["Election Node Logic<br/>[raft_node.py]"]
  node_replication_sim["Replication Simulation<br/>[cluster.py]"]
  node_replication_node["Replication Node Logic<br/>[raft_node.py]"]
end

subgraph group_raft["Networked Raft"]
  node_process["Node Process<br/>[main.go]"]
  node_go_node["Raft Node State<br/>[node.go]"]
  node_election["Network Elections<br/>[election.go]"]
  node_replication["Log Replication<br/>[replication.go]"]
  node_persistence[("Durable State<br/>[persist.go]")]
  node_rpc["Peer RPC<br/>[rpc.go]"]
end

subgraph group_control["Cluster Controls"]
  node_status["Status Endpoint<br/>[status_endpoint.go]"]
  node_commands["Command Endpoints"]
end

subgraph group_observe["Dashboard"]
  node_dashboard["Live Dashboard<br/>[index.html]"]
end

node_user(("Client / Operator"))
node_peers(("Raft Peers"))

node_election_sim -->|"uses node logic"| node_election_node
node_replication_sim -->|"uses node logic"| node_replication_node
node_process -->|"starts server"| node_go_node
node_process -->|"registers endpoint"| node_status
node_process -->|"registers endpoints"| node_commands
node_process -->|"runs election"| node_election
node_process -->|"constructs node"| node_go_node
node_go_node -->|"loads saved state"| node_persistence
node_commands -->|"proposes command"| node_go_node
node_commands -->|"blocks or heals peer"| node_go_node
node_replication -->|"sends AppendEntries"| node_rpc
node_replication -->|"persists proposal"| node_persistence
node_peers -.->|"exchange RPCs"| node_rpc
node_user -->|"submits commands"| node_commands
node_user -->|"views cluster"| node_dashboard
node_dashboard -->|"polls status"| node_status

click node_phase1 "https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase1_state/raft_node.py"
click node_election_sim "https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase2_election/cluster.py"
click node_election_node "https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase2_election/raft_node.py"
click node_replication_sim "https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase3_replication/cluster.py"
click node_replication_node "https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase3_replication/raft_node.py"
click node_process "https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase4_networking/cmd/node/main.go"
click node_go_node "https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase4_networking/raft/node.go"
click node_election "https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase4_networking/raft/election.go"
click node_replication "https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase4_networking/raft/replication.go"
click node_persistence "https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase4_networking/raft/persist.go"
click node_rpc "https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase4_networking/raft/rpc.go"
click node_status "https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase4_networking/raft/status_endpoint.go"
click node_commands "https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase4_networking/raft/command_endpoint.go"
click node_dashboard "https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/dashboard/index.html"

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_phase1,node_election_sim,node_election_node,node_replication_sim,node_replication_node,node_user toneBlue
class node_process,node_go_node,node_election,node_replication,node_persistence,node_rpc toneAmber
class node_status,node_commands toneMint
class node_dashboard toneRose
class node_peers toneIndigo
```

## Components

### Python Simulations

- [Core Node State](https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase1_state/raft_node.py): `phase1_state/raft_node.py`
- [Election Simulation](https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase2_election/cluster.py): `phase2_election/cluster.py`
- [Election Node Logic](https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase2_election/raft_node.py): `phase2_election/raft_node.py`
- [Replication Simulation](https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase3_replication/cluster.py): `phase3_replication/cluster.py`
- [Replication Node Logic](https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase3_replication/raft_node.py): `phase3_replication/raft_node.py`

### Networked Raft

- [Node Process](https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase4_networking/cmd/node/main.go): `phase4_networking/cmd/node/main.go`
- [Raft Node State](https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase4_networking/raft/node.go): `phase4_networking/raft/node.go`
- [Network Elections](https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase4_networking/raft/election.go): `phase4_networking/raft/election.go`
- [Log Replication](https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase4_networking/raft/replication.go): `phase4_networking/raft/replication.go`
- [Durable State](https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase4_networking/raft/persist.go): `phase4_networking/raft/persist.go`
- [Peer RPC](https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase4_networking/raft/rpc.go): `phase4_networking/raft/rpc.go`

### Cluster Controls

- [Status Endpoint](https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase4_networking/raft/status_endpoint.go): `phase4_networking/raft/status_endpoint.go`
- [Command Endpoints](https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/phase4_networking/raft/command_endpoint.go): `phase4_networking/raft/command_endpoint.go`

### Dashboard

- [Live Dashboard](https://github.com/p-types/raft-consensus-distributed-systems-simulator/blob/main/dashboard/index.html): `dashboard/index.html`

### Other components

- **Client / Operator**
- **Raft Peers**

## Connections

- Election Simulation → Election Node Logic: uses node logic (evidence: `phase2_election/cluster.py`)
- Replication Simulation → Replication Node Logic: uses node logic (evidence: `phase3_replication/cluster.py`)
- Node Process → Raft Node State: starts server (evidence: `phase4_networking/cmd/node/main.go`)
- Node Process → Status Endpoint: registers endpoint (evidence: `phase4_networking/cmd/node/main.go`)
- Node Process → Command Endpoints: registers endpoints (evidence: `phase4_networking/cmd/node/main.go`)
- Node Process → Network Elections: runs election (evidence: `phase4_networking/cmd/node/main.go`)
- Node Process → Raft Node State: constructs node (evidence: `phase4_networking/cmd/node/main.go`)
- Raft Node State → Durable State: loads saved state (evidence: `phase4_networking/raft/node.go`)
- Command Endpoints → Raft Node State: proposes command (evidence: `phase4_networking/raft/command_endpoint.go`)
- Command Endpoints → Raft Node State: blocks or heals peer (evidence: `phase4_networking/raft/command_endpoint.go`)
- Log Replication → Peer RPC: sends AppendEntries (evidence: `phase4_networking/raft/replication.go`)
- Log Replication → Durable State: persists proposal (evidence: `phase4_networking/raft/replication.go`)
- Raft Peers → Peer RPC: exchange RPCs
- Client / Operator → Command Endpoints: submits commands (evidence: `phase4_networking/raft/command_endpoint.go`)
- Client / Operator → Live Dashboard: views cluster (evidence: `README.md`)
- Live Dashboard → Status Endpoint: polls status (evidence: `README.md`)
