⚓ Raft Consensus Visualizer

A polished system design visualizer for understanding how the Raft consensus algorithm works.

This project focuses on clarity over infrastructure. It uses a deterministic in-browser simulation with no database so developers can study leader election, quorum, heartbeats, log replication, and failure recovery through an interactive UI.

🔗 Live Demo

https://raft-consensus-visualizer.netlify.app/

👀 Preview

🖥️ App Preview

🎞️ Interactive Demo GIF

📘 Overview

Raft can feel abstract when it is described only in text. This project turns the algorithm into a visual system design tool so you can inspect cluster behavior tick by tick, introduce failures, and watch recovery play out in a way that is easier to reason about.

It is intentionally built as a product-quality explainer rather than a rough demo:

• a deterministic in-browser simulation
• a professional front-end interface
• strongly typed state transitions
• a clean separation between simulation engine and view layer

🧠 What It Demonstrates

• leader election after timeout
• heartbeat stabilization from a leader
• quorum-based commit behavior
• follower and leader isolation scenarios
• targeted restore actions for isolated leaders and followers
• full cluster recovery after partitions heal

✨ Core Features

• pause, resume, or single-step the cluster clock
• tune heartbeat and election timeout settings
• switch between 3-node and 5-node clusters
• inject client requests to observe commit rules
• isolate leaders or followers independently
• restore only the leader, only a follower, or the whole cluster
• inspect event logs and cluster-level design notes in real time

🛠️ Stack

• React
• TypeScript
• Vite
• SCSS

📐 Principles

• DRY architecture with reusable UI sections
• SOLID-oriented separation between simulation engine and interface
• strongly typed domain models
• professional product UI rather than a throwaway demo aesthetic

📁 Project Structure

• src/lib/raft/ contains the simulation engine and Raft state transitions
• src/hooks/ contains UI-facing orchestration hooks
• src/components/ contains reusable visual building blocks
• src/styles/ contains SCSS variables, mixins, and app-level styling
• .github/workflows/ contains CI and deploy automation

🚀 Local Development

npm install
npm run dev

✅ Quality Checks

npm run lint
npm run build

🔄 GitHub Actions And Deployment

This project includes a GitHub Actions workflow for Node.js CI for Netlify deployment.

What it does:

• installs dependencies with npm ci
• runs npm run lint
• runs npm run build
• triggers a Netlify deploy hook on pushes to main

Workflow file:

• .github/workflows/node.js.yml

🎯 Why This Matters

Raft is a foundational system design topic for distributed coordination, replicated state machines, and fault-tolerant infrastructure. A clear visualizer makes it easier to teach, learn, and review the algorithm with confidence.

⭐ Star And Share

If this project helped you understand Raft, please consider starring the repository and sharing it with others who are learning distributed systems or preparing for system design interviews.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

📫 Contact

Built by Olayiwola Akinnagbe.

• GitHub: https://github.com/Olayiwola72
• LinkedIn: https://www.linkedin.com/in/olayiwola-akinnagbe/
• Twitter: https://twitter.com/OlayiwolaAkinn1
• Portfolio: https://olayiwola-akinnagbe.netlify.app/
• Resume: https://drive.google.com/file/d/119Hkfzy2sHD9gm9V5Oe4m0Xm5vamPNgt/view?usp=sharing

If you would like to collaborate, give feedback, or hire me, feel free to reach out.