Building an Interactive N-Queens Visualizer with React + TypeScript

I rebuilt this write-up after a full master-branch audit and focused it on what the code actually ships today: a single-page interactive algorithm visualizer with real-time constraint feedback, simulation playback, and responsive controls.

Live demo: https://singhAmandeep007.github.io/eight-queens-problem-visualizer/

Repository: https://github.com/singhAmandeep007/eight-queens-problem-visualizer

Table of Contents

• What the App Does
• Architecture
• Design System
• Theming
• Motion and Animations
• Particles and Background Effects
• Special Interaction
• Projects Module
• Posts and Blog Module
• About and Profile Module
• Responsiveness
• Performance
• Deployment
• Key Implementation Details
• Lessons Learned and Next Steps

What the App Does

The N-Queens puzzle asks us to place N pieces on an N x N board with zero conflicts.

This project turns that into an interactive engineering playground:

• Piece-rule switching: queen, bishop, rook, knight
• Manual mode for direct placement and conflict feedback
• Simulation mode for animated backtracking exploration
• Variable board size from 4x4 to 8x8
• Solution list replay to inspect discovered arrangements

Architecture

The app is intentionally compact but still modular in behavior:

• App shell in App.tsx
• State domains in ControlContext and AlertContext
• Algorithm and rendering orchestration in Chessboard
• Rule engine utilities in constants
• Reusable control primitives in ControlSelect and common/button

Flowchart image (static for Dev.to compatibility):

Design System

The design system is lightweight and practical:

• CSS variables define core color tokens
• Styled-components handle composable UI surfaces
• Reusable button primitive keeps action affordances consistent
• Board and controls share clear visual hierarchy and spacing

Theming

Even without a dark/light toggle, the app is tokenized:

• Primary and secondary hues drive control and action zones
• Surface and background tokens support layered feedback
• Piece and board contrast remains readable across interactions

Because tokens are centralized, runtime theme switching can be introduced later with minimal component churn.

Motion and Animations

Motion is used to explain logic rather than decorate UI:

• Simulation playback updates board state at user-selected speed
• Alerts animate in and out for lightweight status communication
• Solved-state celebration gives immediate completion feedback

Particles and Background Effects

This branch intentionally avoids heavy particle layers and uses informative effects instead:

• Conflict squares use striped overlays
• Board container shadows emphasize focus
• Celebration overlay marks solved states

That keeps the experience fast while preserving strong visual state signaling.

Special Interaction

The standout interaction is simulation control + replayability:

• Play/Stop orchestrates async search
• Simulation auto-interrupt logic handles tab visibility changes
• Solved boards can be reset and replayed rapidly

GIF fallback:

Projects Module

In this single-page architecture, the solution explorer acts as the project/results module:

• Every valid solution is persisted
• Entries are clickable to preview placements instantly
• Duplicate solutions are deduplicated using serialized keys

Posts and Blog Module

The in-app information modal works as the educational content module:

• Problem statement and interaction model are available inline
• Portal rendering avoids z-index and stacking issues
• Users can enter and exit context quickly without navigation

About and Profile Module

Profile attribution is implemented in the footer module:

• Author identity is visible in the app shell
• External profile link supports discoverability and ownership

Responsiveness

Responsive behavior is handled through global breakpoints and adaptive layouts:

• Root font scaling across screen-size bands
• Control bar wrapping under smaller widths
• Chessboard + side panel stack behavior for mobile ergonomics

Performance

Performance decisions visible in the code:

• useMemo for board-grid generation by board size
• Cached solved-state checks for repeated position sets
• Fast simulation mode for rapid enumeration
• Input controls disabled while simulation runs to reduce race conditions

Known trade-off:

• Position encoding uses row*10+col, which is compact and efficient for current board ranges (4-8), but not ideal for larger generalized boards.

Deployment

Deployment pipeline is straightforward and production-safe:

• npm run build creates dist output
• npm run deploy uses gh-pages
• Vite base path is derived from GITHUB_PAGES_REPO for GitHub Pages correctness

Key Implementation Details

1. Context-driven state architecture
2. ControlContext owns mode, speed, piece type, board size, simulation state

3. AlertContext centralizes user feedback and timeout cleanup

4. Rule engine abstraction

5. checkConflictMethods encapsulates row/column, diagonal, and knight checks

6. checkIsAttacking and checkIsSolved compose these rules for both manual and simulation paths

7. Async simulation loop

8. Recursive backtracking-style search enumerates candidate positions

9. Board state updates are interleaved with delays for visual progression

10. Stop conditions are managed with refs and side effects for safe interruption

Lessons Learned and Next Steps

Lessons:

• Explicit state boundaries make even single-page apps easier to reason about
• Algorithm visualizers benefit from controls that expose execution speed and mode
• Visual effects should carry semantic meaning, not just aesthetics

Next improvements:

• Extract solver logic to a dedicated module for stronger unit testing
• Add symmetry reduction for mathematically equivalent solutions
• Move from row*10+col encoding to coordinate tuples for long-term extensibility
• Add keyboard-first interaction flow for accessibility