Stop Debugging by Hand: I Built a Real-Time Linked List Visualizer

Demo

Introduction

While grinding through Data Structures and Algorithms problems, I repeatedly hit the same wall: debugging pointer logic in Linked Lists.

Even when the algorithm was conceptually clear, understanding how pointers like curr, prev, next, slow, or fast were actually transforming the list at runtime was a headache. I often found myself mentally simulating the execution or scribbling messy diagrams on paper. This manual process was slow, error-prone, and frustrating.. especially when dealing with complex multi-pointer transformations.

Traditional debugging tools don't provide a structural view of pointer relationships, and print() debugging linked lists results in a terminal full of unreadable memory addresses. I needed a way to see exactly what my code was doing to the structure as it executed.

This led to the creation of NeurAL-Viz: a real-time Linked List visualizer that runs actual Python code, records every execution step, and allows you to "time travel" through the state changes, in order to understand the pointer movements better.

The goal was not to simulate linked list behavior, but to observe the actual runtime state of the program. I wanted a tool that could execute real Python code, track the memory identity of nodes, and record every meaningful step. Crucially, it needed to allow rewinding and replaying the algorithm so I could pinpoint exactly where my logic drifted.

System Architecture

The system is built entirely for the browser, removing the need for backend infrastructure. It consists of three main components: a Python execution engine, a state snapshot system, and a visual rendering layer.

1. To handle the execution, I used Pyodide, a port of CPython to WebAssembly. This allows the application to run a full Python interpreter directly in the browser. To ensure the UI remains responsive and secure, the user's code executes inside a Web Worker. This isolates the heavy lifting and allows me to cap execution time, preventing infinite loops.. a common pitfall in Linked List problems, from freezing the browser.

2. Modeling and Monitoring Memory
   Inside this execution environment, I defined a custom Node class. Because Pyodide treats these as real Python objects, their identities remain stable throughout the program's lifecycle. I track each node using its memory address (id(node)), which acts as a stable primary key to map objects between the Python runtime and the JavaScript frontend. At every step of execution, the system performs a memory sweep. It scans global variables to discover active Node instances and inspects their next and prev attributes. By identifying nodes that are not referenced by any other node’s next pointer, the system can intelligently detect list heads and reconstruct the full graph structure.

3. Tracking Pointers in Real-Time
   The most difficult part of learning Linked Lists isn't the nodes; it's the pointers. To visualize variables like slow and fast, the system inspects runtime variable bindings during execution. For each step, the engine maps variable names to the specific node objects they reference. If curr and temp both point to the same node, the visualizer knows to attach both labels to that specific ID. This makes pointer movement immediately visible, you don't just see the value change, you see the label physically move across the screen.

4. Implementing Time-Travel Debugging
   To support the "time-travel" feature, the system acts like a flight recorder. It captures a snapshot of the entire Linked List state, nodes, positions, connections, and active variables.. after every line of code execution. These snapshots are stored sequentially in a history buffer. Once execution completes (or is terminated by the loop guard), this full history is sent to the frontend. The scrubber UI simply maps the slider position to an array index. When you drag the slider, the React frontend hydrates the graph with the data from that specific slice of time. This allows you to inspect exactly how the list looked at step 5 versus step 50, making it trivial to debug logic errors inside loops.

5. Visualization Layer
   The frontend visualization utilizes React Flow. I chose this library because it handles node-based graphs efficiently. Because the visual state is derived from the actual Python memory dump, the visualization is never an approximation. It is a 1:1 representation of the code's effect on memory.

Final Outcome

This project started as a personal utility to help me visualize next pointers, but it evolved into a comprehensive educational tool. It allows users to write Python code, execute it safely in the browser, and validate their pointer logic visually rather than mentally.

You can try the tool or view the source code here:

Live Site
GitHub Repository

While my primary focus remains on AI/ML, building this system deepened my understanding of runtime inspection, program tracing, and Pyodide. If this tool helps even one person finally understand how to reverse a Linked List without a headache, it was worth the build.