dsa_visualizer_spec.md

DSA Algorithm Visualizer - Complete Project Specification

Project Overview

Build a comprehensive web-based platform that visualizes 10+ complex DSA algorithms with beautiful animations and explanations that anyone can understand, regardless of their technical background.

Target Audience

• Students learning DSA concepts
• Teachers explaining algorithms
• Non-technical people curious about computer science
• Developers reviewing concepts

Core Requirements

1. Algorithm Selection (Minimum 10)

Implement visualizations for these algorithms, chosen for visual appeal and educational value:

1. Tower of Hanoi - Classic recursive problem with disk movements
2. N-Queens Problem - Backtracking visualization on chess board
3. 0/1 Knapsack Problem - Dynamic programming table visualization
4. Dijkstra's Shortest Path - Graph traversal with weighted edges
5. A Pathfinding* - Intelligent pathfinding with heuristics
6. Merge Sort - Divide and conquer sorting visualization
7. Quick Sort - Partition-based sorting with pivot selection
8. Binary Search Tree Operations - Insert, delete, search with rotations
9. Convex Hull (Graham Scan) - Computational geometry visualization
10. Huffman Coding - Tree building for compression
11. Sudoku Solver (Backtracking) - Grid-based constraint satisfaction
12. Maze Generation (Recursive Backtracking) - Procedural maze creation

2. Technical Stack

Frontend:

• HTML5 for structure
• CSS3 with modern features (Grid, Flexbox, Animations, Variables)
• Vanilla JavaScript (ES6+) for logic and interactivity
• Canvas API or SVG for visualizations
• Consider using lightweight libraries like:
  • D3.js for complex graph visualizations (optional)
  • GSAP for smooth animations (optional)

Backend (Optional but Recommended):

• Node.js + Express for API endpoints
• Use cases:
  • Save/share visualization configurations
  • Analytics on popular algorithms
  • User-submitted test cases
  • Optional: User accounts for saving progress

Deployment:

• Frontend: Vercel, Netlify, or GitHub Pages
• Backend (if implemented): Render, Railway, or Vercel serverless functions
• Database (if needed): MongoDB Atlas (free tier) or Supabase

3. UI/UX Requirements

Homepage:

• Hero section with animated preview
• Grid/card layout showing all algorithms
• Search and filter functionality
• Brief description for each algorithm

Individual Algorithm Page: Each algorithm visualization should have:

1. Control Panel:

   • Play/Pause button
   • Speed slider (0.5x to 4x)
   • Step forward/backward buttons
   • Reset button
   • Input controls (array size, number of queens, graph size, etc.)
   • "Randomize" button for inputs

2. Visualization Area:

   • Clean, spacious canvas/SVG area
   • Color-coded elements (use consistent color scheme)
   • Smooth animations between states
   • Highlighted current operation
   • Show comparisons, swaps, or decisions clearly

3. Explanation Section:

   • "What is this?" - Simple 2-3 sentence explanation for non-technical users
   • "How it works" - Step-by-step breakdown
   • "Real-world applications" - Where this algorithm is used
   • "Complexity Analysis" - Big O notation with simple explanation
   • Code snippet - Syntax-highlighted pseudocode or actual code

4. Interactive Tutorial:

   • First-time user walkthrough
   • Tooltips explaining what's happening
   • "Challenge mode" with problems to solve

5. Statistics Display:

   • Current step number
   • Total steps
   • Comparisons made
   • Time elapsed
   • Memory usage (conceptual)

4. Design Guidelines

Color Scheme:

• Use a consistent, modern color palette
• Suggested: Dark mode primary with accent colors
  • Background: #0f172a (dark slate)
  • Surface: #1e293b
  • Primary accent: #3b82f6 (blue)
  • Secondary: #8b5cf6 (purple)
  • Success: #10b981 (green)
  • Warning: #f59e0b (amber)
  • Error: #ef4444 (red)

Typography:

• Headings: 'Inter', 'Poppins', or 'Space Grotesk'
• Body: 'Inter' or 'System UI'
• Code: 'Fira Code' or 'JetBrains Mono'

Animations:

• Smooth transitions (300-500ms)
• Ease-in-out timing functions
• Highlight state changes
• Use CSS transforms for performance
• No janky animations - 60fps target

Responsive Design:

• Mobile-first approach
• Breakpoints: 640px, 768px, 1024px, 1280px
• Stack controls vertically on mobile
• Reduce visualization complexity on small screens

5. Code Architecture

File Structure:

dsa-visualizer/
├── frontend/
│   ├── index.html
│   ├── css/
│   │   ├── main.css
│   │   ├── components/
│   │   └── animations.css
│   ├── js/
│   │   ├── main.js
│   │   ├── algorithms/
│   │   │   ├── towerOfHanoi.js
│   │   │   ├── nQueens.js
│   │   │   ├── knapsack.js
│   │   │   ├── dijkstra.js
│   │   │   ├── aStar.js
│   │   │   ├── mergeSort.js
│   │   │   ├── quickSort.js
│   │   │   ├── bst.js
│   │   │   ├── convexHull.js
│   │   │   ├── huffman.js
│   │   │   ├── sudoku.js
│   │   │   └── mazeGen.js
│   │   ├── visualizers/
│   │   │   └── [corresponding visualizers]
│   │   ├── utils/
│   │   │   ├── animator.js
│   │   │   ├── controls.js
│   │   │   └── helpers.js
│   │   └── components/
│   │       ├── navbar.js
│   │       ├── modal.js
│   │       └── tooltip.js
│   └── assets/
│       ├── icons/
│       └── images/
├── backend/ (optional)
│   ├── server.js
│   ├── routes/
│   ├── models/
│   └── controllers/
└── README.md

JavaScript Patterns:

• Use ES6 modules
• Each algorithm should be a class with methods:
  • constructor(config)
  • initialize(input)
  • step() - execute one step
  • getState() - return current state for visualization
  • reset()
  • solve() - run complete algorithm
• Visualizer classes separate from algorithm logic
• Event-driven architecture for controls

6. Algorithm-Specific Requirements

Tower of Hanoi

• 3 pegs with colored disks
• Show move count and minimum moves
• Animate disk movements smoothly
• Highlight source and destination pegs
• Allow 3-8 disks
• Show recursive call stack (optional advanced feature)

N-Queens

• Chess board visualization (4x4 to 12x12)
• Highlight attacking queens in red
• Show backtracking steps
• Count solutions found
• Animate queen placement/removal
• Show row/column/diagonal constraints

Knapsack Problem

• Display items with weights and values
• Show DP table filling up
• Highlight current cell being computed
• Show selected items at the end
• Allow custom items input
• Show total value and weight

Dijkstra's Shortest Path

• Graph with weighted edges
• Highlight current node, visited nodes, frontier
• Show distance labels updating
• Path reconstruction at the end
• Allow users to create custom graphs
• Display priority queue state

A* Pathfinding

• Grid-based visualization
• Start/end points and obstacles
• Show open and closed sets
• Display f, g, h values
• Animate path discovery
• Compare with Dijkstra mode

Merge Sort

• Array of bars/numbers
• Show split and merge phases
• Highlight subarrays being merged
• Use different colors for different levels
• Show auxiliary array
• Comparison counter

Quick Sort

• Show pivot selection
• Animate partition process
• Highlight elements being compared
• Show recursive calls with different colors
• Option to choose pivot strategy (first, last, random, median)

Binary Search Tree

• Tree visualization with nodes and edges
• Insert/Delete/Search operations
• Show rotations for AVL tree
• Animate tree restructuring
• Highlight traversal paths
• Show balance factors

Convex Hull

• 2D point cloud
• Animate Graham Scan process
• Show current hull
• Highlight pivot point and angles
• Allow user to add points
• Show polar angle sorting step

Huffman Coding

• Input text or frequency table
• Build tree bottom-up
• Show bit assignments
• Display compression ratio
• Encode/decode text
• Show priority queue building

Sudoku Solver

• 9x9 grid
• Highlight current cell
• Show candidates for each cell
• Animate backtracking
• Allow user input puzzles
• Show solution path

Maze Generation

• Grid-based maze
• Show wall breaking process
• Animate recursive backtracking
• Display current path
• Generate various sizes
• Option for different algorithms (Prim's, Kruskal's)

7. Feature Priorities

Phase 1 (MVP):

• Implement 5 core algorithms: Tower of Hanoi, N-Queens, Merge Sort, Dijkstra, A*
• Basic UI with controls
• Responsive design
• Deploy frontend

Phase 2:

• Add remaining 5+ algorithms
• Enhanced explanations and tutorials
• Code snippets
• Improved animations

Phase 3:

• Backend implementation
• Save/share feature
• User analytics
• Challenge mode
• Community features

8. Quality Standards

Performance:

• Animations should run at 60fps
• No blocking operations on main thread
• Use requestAnimationFrame for animations
• Lazy load algorithm modules
• Optimize large dataset visualizations

Accessibility:

• Keyboard navigation support
• ARIA labels for controls
• Color contrast ratios meet WCAG AA
• Screen reader friendly explanations
• Focus indicators

Code Quality:

• ESLint configuration
• Consistent naming conventions
• Comments for complex logic
• No console errors or warnings
• Cross-browser compatibility (Chrome, Firefox, Safari, Edge)

9. Documentation Requirements

README.md should include:

• Project description and demo link
• Screenshots/GIFs of visualizations
• Features list
• Tech stack
• Setup instructions
• Contributing guidelines
• License

Code Documentation:

• JSDoc comments for functions
• Inline comments for complex algorithms
• Explanation of visualization state management

10. Deployment Checklist

• Minify CSS and JavaScript
• Optimize images and assets
• Set up CI/CD pipeline
• Configure custom domain (optional)
• Add meta tags for SEO
• Add Open Graph tags for social sharing
• Set up analytics (Google Analytics or Plausible)
• Test on multiple devices and browsers
• Add favicon and PWA manifest
• Set up error tracking (Sentry, optional)

11. Success Criteria

The project is successful when:

• All 10+ algorithms are implemented with smooth visualizations
• A non-technical person can understand what each algorithm does
• The site is fully responsive and accessible
• Load time is under 3 seconds
• No critical bugs or broken features
• Deployed and publicly accessible
• Clean, maintainable code

Implementation Strategy for Opus 4.5

Suggested Prompting Approach:

Give Opus this entire document along with this instruction:

"I want you to build this DSA Algorithm Visualizer project exactly as specified. Please work through this systematically:

1. First, create the complete project structure and all necessary files
2. Implement the core framework (controls, animator, state management)
3. Build one complete algorithm (Tower of Hanoi) as a reference implementation
4. Then implement each remaining algorithm following the same pattern
5. Create the homepage with algorithm selection
6. Add explanations and educational content for each algorithm
7. Implement responsive design and polish
8. Prepare for deployment

For each algorithm, make sure to:

• Write clean, well-commented code
• Create smooth, performant animations
• Include simple explanations that a non-technical person can understand
• Add interactive controls
• Show complexity analysis

Start with Phase 1 (MVP) and build it completely before moving to Phase 2. After completing each major component, ask me if I want to review before continuing, or if I want you to keep going.

Begin by outlining your implementation plan, then start building."

Additional Tips for Working with Opus

1. Iterative refinement: After Opus builds a component, you can ask it to improve animations, add features, or refine explanations

2. Testing prompts: "Test the [algorithm name] implementation with edge cases and make sure animations are smooth"

3. Explanation prompts: "Improve the explanation for [algorithm] to make it simpler for someone who doesn't know programming"

4. Style prompts: "Make the UI more modern and visually appealing with better color schemes and typography"

5. Debug prompts: "There's an issue with [feature], please identify and fix the bug"

Reference Resources

Visualization Inspiration:

• VisuAlgo.net
• Algorithm Visualizer (algorithm-visualizer.org)
• Sorting.at

Educational Content:

• GeeksforGeeks algorithm explanations
• MIT OpenCourseWare algorithms lectures
• Abdul Bari YouTube channel

Design Inspiration:

• Dribbble (search "algorithm visualization")
• Awwwards (educational sites)

Good luck building your DSA visualizer! This should be an impressive portfolio project that demonstrates both technical skills and ability to make complex concepts accessible.