+-----------------------------------------------------------------------------------------+
|                  Raft Node State Transition Diagram (2026)                              |
+-----------------------------------------------------------------------------------------+

             +-----------------------------------------------+
             |                                               |
             ▼                                               |
     +---------------+   Election Timeout   +---------------+| Discovers current Leader
     |   FOLLOWER    | -------------------> |   CANDIDATE   || or newer Term (Term > t)
     +---------------+                      +---------------+|
             ▲                                      │        |
             │                                      │ Receives Votes from
             │ Discovers newer Term (Term > t)      │ Quorum Majority (N/2 + 1)
             │                                      ▼
             │                              +---------------+
             +----------------------------- |    LEADER     |
                                            +---------------+

+-----------------------------------------------------------------------------------------+
|                  The 3 Subproblems of Raft Decomposed                                   |
+-----------------------------------------------------------------------------------------+

1. LEADER ELECTION:
   - Heartbeat SLA: Leader sends periodic 'AppendEntries' heartbeats every 50ms.
   - Election Timeout: Followers wait a randomized window (150ms–300ms).
   - If no heartbeat is received, Follower increments 'currentTerm' and becomes Candidate!
   - Requests votes via 'RequestVote' RPC. First candidate to secure (N/2 + 1) votes becomes Leader!

2. LOG REPLICATION:
   - Client sends write: 'SET key = "value"'.
   - Leader appends entry to local log and sends 'AppendEntries' RPC to all followers.
   - When majority of followers respond with success, Leader commits entry and applies to State Machine.
   - Leader notifies followers of commit index in the next heartbeat.

3. SAFETY (Leader Completeness Property):
   - A follower will REJECT a candidate's vote if candidate's log is less up-to-date than follower's.
   - Guarantees that any committed log entry is present on the newly elected leader for all future terms!

+-----------------------------------------------------------------------------------------+
|                  Joint Consensus Configuration Transition                               |
+-----------------------------------------------------------------------------------------+

[CONFIGURATION TRANSITION]: Cluster moving from C_old (Nodes 1,2,3) to C_new (Nodes 1,2,3,4,5)

Step 1: Leader commits Joint Configuration entry: 'C_old,new'
        - Any consensus decision requires MAJORITY of C_old AND MAJORITY of C_new!
        - Neither C_old nor C_new can make independent unilateral decisions!

Step 2: Once 'C_old,new' is committed to a majority, Leader commits 'C_new'.
        - Cluster safely transitions to 5-node configuration with zero downtime!

// raft/node.go
package main

import (
	"context"
	"log"
	"time"

	"go.etcd.io/raft/v3"
	"go.etcd.io/raft/v3/raftpb"
)

type RaftClusterNode struct {
	id         uint64
	node       raft.Node
	storage    *raft.MemoryStorage
	transport  *RaftNetworkTransport
	commitChan chan string
}

func StartRaftNode(nodeID uint64, peers []raft.Peer, commitChan chan string) *RaftClusterNode {
	storage := raft.NewMemoryStorage()

	// 1. Configure Raft Consensus Engine
	c := &raft.Config{
		ID:                        nodeID,
		ElectionTick:              10, // 10 ticks * 100ms = 1000ms Election Timeout
		HeartbeatTick:             1,  // 1 tick * 100ms = 100ms Heartbeat
		Storage:                   storage,
		MaxSizePerMsg:             1024 * 1024,
		MaxInflightMsgs:           256,
		CheckQuorum:               true,
		PreVote:                   true, // Prevents disrupted nodes from causing election churn!
	}

	// 2. Initialize Node
	node := raft.StartNode(c, peers)
	rn := &RaftClusterNode{
		id:         nodeID,
		node:       node,
		storage:    storage,
		commitChan: commitChan,
	}

	go rn.eventLoop()
	return rn
}

// 3. Deterministic Event Processing Loop
func (rn *RaftClusterNode) eventLoop() {
	ticker := time.NewTicker(100 * time.Millisecond)
	defer ticker.Stop()

	for {
		select {
		case <-ticker.C:
			// Advances the logical clock by 1 tick
			rn.node.Tick()

		case rd := <-rn.node.Ready():
			// Save entries to durable disk storage
			rn.storage.Append(rd.Entries)

			// Send outbound messages across network to peers
			for _, msg := range rd.Messages {
				rn.transport.Send(msg)
			}

			// Apply committed entries to Key-Value State Machine!
			for _, entry := range rd.CommittedEntries {
				if entry.Type == raftpb.EntryNormal && len(entry.Data) > 0 {
					log.Printf("🔒 [NODE %d COMMITTED] Applying log index %d to State Machine: %s", rn.id, entry.Index, string(entry.Data))
					rn.commitChan <- string(entry.Data)
				}
			}

			// Advance Ready state
			rn.node.Advance()
		}
	}
}

// Propose a new Client Write Command to the Leader
func (rn *RaftClusterNode) ProposeWrite(ctx context.Context, key, value string) error {
	cmd := []byte(key + ":" + value)
	return rn.node.Propose(ctx, cmd)
}

+-----------------------------------------------------------------------------------------+
|                  Raft Pre-Vote Phase Mechanics                                          |
+-----------------------------------------------------------------------------------------+

[NETWORK PARTITION HEALS: Disconnected Node 4 returns to cluster]
  │
  ▼ (Without Pre-Vote: Node 4 increments Term to 15 -> Disrupts stable Leader!)
+-----------------------------------------------------------------+
| WITH PRE-VOTE ENABLED (Raft Best Practice):                     |
| 1. Node 4 sends 'PreVote' RPC without incrementing Term.        |
| 2. Majority replies: "We already have an active healthy Leader!"|
| 3. Node 4 steps down immediately without causing election churn!|
+-----------------------------------------------------------------+

       +-------------------------------------------------------------+
       |             Quorum Commit Write Latency (Milliseconds)      |
       +-------------------------------------------------------------+
 3-Node Raft Cluster (Single Cloud Region)   | = [1.8 ms]
 5-Node Raft Cluster (Multi-AZ Cross-Zone)   | == [3.4 ms]
 Multi-Region WAN Raft Cluster (Cross-Cloud) | ==================== [38.5 ms]
                                             +-------------------------------------+
                                             0ms     10ms    20ms    30ms    40ms