AlgoScope

A modern, interactive algorithm visualizer that demystifies complex logic through real-time, high-fidelity animations.

Join our community for updates and support!

🌐 Live Demo

Experience AlgoScope in your browser: algo-scope-virid.vercel.app

Core Maintainers

@adityapaul26

@Bimbok

_{Click a profile or follow badge for updates and to connect with the team.}

---

💡 Project Purpose

Learning Data Structures and Algorithms (DSA) is often a daunting task for students and developers. Traditional resources like static pseudocode and textbooks fail to capture the dynamic nature of algorithms.

AlgoScope bridges this gap by providing a hands-on environment where users can watch the flow behind every operation. By transforming abstract logic into fluid animations, AlgoScope helps users build a mental model of how algorithms actually work, making the learning process intuitive, engaging, and accessible.

---

✨ Features

Feature	Description
Real-time Visualization	Watch algorithms come alive with smooth, step-by-step animations using Framer Motion and Anime.js.
Adjustable Speed	Full control over animation speed and input data to learn at your own pace.
Algorithm Coverage	Comprehensive support for Sorting (Quick, Merge, Bubble), Searching (Linear, Binary), and Graph Algorithms (BFS, DFS, Dijkstra).
Code Insights	See the actual implementation in multiple programming languages (C++, Java, Python, JS) alongside the visualization.
Interactive Playground	Create custom inputs, change array sizes, and interact directly with the canvas.
Clean UI/UX	Modern, dark-themed interface built with Tailwind CSS v4.

---

🛠️ Tech Stack

Frontend

• Framework: React 19
• Build Tool: Vite 7
• Styling: Tailwind CSS v4
• Animations: Framer Motion, Anime.js
• Routing: React Router v7

Utilities

• Syntax Highlighting: React Syntax Highlighter
• Icons: Lucide React

---

🚀 Quick Start

Follow these steps to set up AlgoScope locally on a clean machine:

Prerequisites

• Node.js (v18.x or higher)
• npm or yarn

Setup Steps

# 1. Clone the repository
git clone https://github.com/bim-adi/AlgoScope.git
cd AlgoScope

# 2. Install dependencies
npm install

# 3. Start the development server
npm run dev

Open http://localhost:5173/ in your browser to start exploring.

Docker Quick Start

If you have Docker installed, you can pull and run the pre-built image:

# 1. Pull the image
docker pull bimbok/algoscope-app:latest

# 2. Run the container
docker run -d -p 8080:80 bimbok/algoscope-app:latest

Access the app at http://localhost:8080.

---

🏗️ Architecture

AlgoScope uses a component-based architecture where each algorithm category has its own specialized visualizer:

src/
├── components/
│   ├── sortingAlgo/       # Sorting visualizer logic & animation controllers
│   ├── searchAlgo/        # Graph searching (BFS/DFS) and canvas management
│   ├── arraySearch/       # Linear/Binary search logic
│   ├── shortestPathAlgo/  # Dijkstra/Floyd-Warshall pathfinding
│   └── dataStructures/    # Stacks, Queues, and Tree visualizers
├── lib/                   # Shared utility functions and algorithm implementations
└── App.jsx                # Main routing and global state management

How It Works

1. State Management: React state tracks the current progress of the algorithm (e.g., current indices being compared).
2. Animation Engine: Framer Motion and Anime.js handle the transitions based on state changes.
3. Pseudo-code Sync: The CodeDisplay component highlights lines of code in real-time as the algorithm executes.

System Data Flow

flowchart TD
    user[User]
    subgraph UI
        input_handler((1.0 Manage User Interactions))
        vis_renderer((4.0 Visualize State Changes))
    end
    subgraph Logic
        algorithm_engine((2.0 Execute Algorithms))
        state_manager((3.0 Manage System State))
    end

    %% Data Flows
    user -- Select Algorithm, Speed, Parameters --> input_handler
    input_handler -- Start/Stop/Control Commands --> algorithm_engine
    input_handler -- Initialize/Reset State --> state_manager

    algorithm_engine -- Read Current State --> state_manager
    algorithm_engine -- Step-by-Step Updates (Array/Graph) --> state_manager

    state_manager -- Current State Data --> vis_renderer

    vis_renderer -- Animated Visual Output & Feedback --> user
    vis_renderer -- Visualization Completed/Status --> input_handler

Loading

User Workflow & Execution Logic

flowchart TD
    %% Node Definitions
    Start((Start))
    End((End))

    %% User Actions
    NavCategory["Navigate to Algorithm Category<br>(e.g., Sorting, Graph)"]
    SelectAlgo["Select Specific Algorithm<br>(e.g., Dijkstra, Quick Sort)"]
    SetConfig{"Configure Data & Parameters"}
    SetNodes["Select Source & Target Nodes"]
    SetArray["Generate or Input Array Elements"]
    SetSpeed["Adjust Visualization Speed Slider"]
    ClickStart(["Click 'Start' Button"])

    %% System Validation & Setup
    ValidateInput{"Are Inputs Valid?<br>(e.g., Nodes selected?)"}
    ShowError["Display Warning / Prompt User"]
    InitState["Initialize Algorithm State<br>(Clear highlights, reset vars)"]

    %% Execution Loop
    CheckDone{"Is Algorithm<br>Complete?"}
    ExecStep["Compute Next Algorithmic Step<br>(e.g., Compare, Swap, Traverse)"]
    UpdateState["Update Internal Data State"]
    RenderVis["Render Visual Updates via D3/React<br>(Highlight active elements)"]

    %% Playback Control
    CheckPause{"Is Execution<br>Paused?"}
    WaitResume["Wait for User to click Resume"]
    ApplyDelay["Apply Delay based on Speed Slider"]

    %% Completion
    ShowFinal["Render Final State<br>(Highlight Shortest Path / Sorted Array)"]
    ShowStats["Update Status Display<br>(Time taken, Steps completed)"]

    %% Flow logic
    Start --> NavCategory
    NavCategory --> SelectAlgo
    SelectAlgo --> SetConfig

    SetConfig -->|Graph Algorithms| SetNodes
    SetConfig -->|Array Algorithms| SetArray

    SetNodes --> SetSpeed
    SetArray --> SetSpeed
    SetSpeed --> ClickStart

    ClickStart --> ValidateInput
    ValidateInput -->|No| ShowError
    ShowError --> SetConfig

    ValidateInput -->|Yes| InitState
    InitState --> CheckDone

    %% The main visualization loop
    CheckDone -->|No| ExecStep
    ExecStep --> UpdateState
    UpdateState --> RenderVis
    RenderVis --> CheckPause

    CheckPause -->|Yes| WaitResume
    WaitResume --> CheckPause

    CheckPause -->|No| ApplyDelay
    ApplyDelay --> CheckDone

    %% Algorithm Finished
    CheckDone -->|Yes| ShowFinal
    ShowFinal --> ShowStats
    ShowStats --> End

    %% Styling for clarity
    classDef userAction fill:#2d3748,stroke:#4fd1c5,stroke-width:2px,color:#fff;
    classDef systemAction fill:#1a202c,stroke:#63b3ed,stroke-width:2px,color:#fff;
    classDef decision fill:#2b6cb0,stroke:#90cdf4,stroke-width:2px,color:#fff;

    class NavCategory,SelectAlgo,SetNodes,SetArray,SetSpeed,ClickStart,WaitResume userAction;
    class InitState,ExecStep,UpdateState,RenderVis,ApplyDelay,ShowFinal,ShowStats,ShowError systemAction;
    class SetConfig,ValidateInput,CheckDone,CheckPause decision;

Loading

---

🤝 Contributing

We welcome contributions! Whether it's a bug fix, a new algorithm visualization, or a UI improvement, your help is appreciated.

1. Fork the repo and create your branch from main.
2. Setup locally following the Quick Start guide.
3. Commit your changes with descriptive messages.
4. Open a Pull Request and describe your changes in detail.

For more detailed guidelines, please refer to our Contribution Guidelines and Code of Conduct.

---

📞 Contact

If you have any questions or want to discuss a contribution, feel free to reach out:

• Primary Channel: GitHub Issues (Best for bug reports and feature requests)
• Aditya Paul: LinkedIn
• Bratik Mukherjee: LinkedIn

---

📄 License

Released under the MIT License.

Made with ❤️ for the DSA community.