Skip to content

daniel-pittman/rubiks-cube-solver

BranchesTags

Repository files navigation

Rubik's Cube Solver

A Case Study in Human-AI Collaborative Software Development

Project Status Python License Code Quality Tests

📖 Table of Contents

🎯 What Is This Project?

This is a fully-functional Rubik's Cube solver with three different interfaces (command-line, web, and desktop), built entirely through conversation with Claude Code, Anthropic's AI coding assistant.

The goal? To explore what's possible when humans and AI collaborate on complex software development, and to document the process so others can learn from it.

Key Facts

  • 100% of code generated by AI (Claude Code)
  • Zero lines written directly by human (except this README update!)
  • Complete working application with 3D visualization, solving algorithms, and multiple UIs
  • Full documentation of every prompt, decision, and iteration
  • Production-quality code meeting professional standards (9.07/10 pylint score, 28 passing tests)

This project serves as a real-world case study for:

  • What LLMs can do well (and where they struggle)
  • How to effectively guide AI coding assistants
  • The balance between AI capability and human direction
  • Building production-quality software through natural language

🤖 The AI Development Story

What Went Well

✅ Algorithm Implementation

  • Claude Code successfully implemented complex cube mechanics using matrix transformations
  • Built a plugin-based solver architecture with IDDFS (Iterative Deepening Depth-First Search)
  • Created accurate 3D visualizations using Three.js and OpenGL

✅ Multiple UI Paradigms

  • Command-line interface with ANSI colors and interactive REPL
  • Web interface with real-time WebSocket communication
  • Desktop application with hardware-accelerated OpenGL rendering

✅ Code Quality & Testing

  • 28 comprehensive unit and integration tests (all passing)
  • Consistent 9.0+ pylint scores throughout development
  • Clean architecture with proper separation of concerns

✅ Documentation

  • Self-documenting code with comprehensive docstrings
  • Detailed inline comments explaining complex logic
  • Configuration files with explanatory headers

Where Human Guidance Was Critical

🧠 Architecture Decisions

  • Choosing the plugin-based solver system
  • Deciding on the hybrid face-clicking + camera-dragging interaction model
  • Structuring the project into phases (Core → Solver → CLI → Web → Desktop)

🧠 Problem-Solving

  • Debugging cube rotation mechanics (initial implementation had incorrect edge cycling)
  • Fixing animation timing issues (colors updating before vs. after animations)
  • Resolving OpenGL context issues with face click detection

🧠 UX Design

  • Making the desktop app non-blocking by moving solver to background thread
  • Implementing "smart drag detection" to distinguish clicks from camera movements
  • Choosing accessible color contrasts (WCAG AA compliance)

What Didn't Work (At First)

❌ Initial Cube Implementation

  • First attempt at cube moves had incorrect edge cycling for 5 out of 6 moves
  • Required complete rewrite following proven matrix transformation approach
  • Lesson: Start with proven approaches for complex algorithms

❌ Animation Synchronization

  • Multiple attempts needed to get cube colors updating at the right time during animations
  • Issue: Understanding when to save state (before move) vs. when to animate (after move)
  • Lesson: State management in animations requires careful sequencing

❌ Face Click Detection

  • Initial OpenGL picking implementation caused GLError (invalid operation)
  • Root cause: Calling glReadPixels outside rendering context
  • Lesson: Framework constraints (like OpenGL contexts) need explicit handling

The Process

Development followed an incremental, phase-based approach:

  1. Phase 1: Core cube mechanics (505 lines, 32 tests)
  2. Phase 2: Solver system with plugin architecture (664 lines)
  3. Phase 3: CLI interface with colored terminal (650+ lines)
  4. Phase 4: Web interface with 3D visualization
  5. Phase 5: Desktop application with OpenGL rendering

Each phase was completed 100% before moving to the next. When bugs were found, we went back and fixed them properly rather than moving forward with technical debt.

🚀 Quick Start

Prerequisites

You need Python installed. Here's how to check and install:

# Check if Python is installed (need 3.11 or higher)
python3 --version

# If not installed:
# - macOS: Install from python.org or use `brew install python3`
# - Linux: `sudo apt install python3` or `sudo yum install python3`
# - Windows: Download from python.org and run installer

Installation & Running

The easiest way: Use the launcher script

# Clone the repository
git clone https://github.com/daniel-pittman/rubiks-cube-solver.git
cd rubiks-cube-solver

# Run the launcher (handles everything automatically!)
./run_app.sh

The launcher will:

  1. Create a Python virtual environment
  2. Install all dependencies
  3. Show you a menu to choose which interface to run

Menu options:

  1. CLI - Command-line interface with colored cube display
  2. Web - Flask server with 3D visualization (opens browser to localhost:5000)
  3. Desktop - PySide6 application with OpenGL 3D rendering
  4. Tests - Run all 28 unit tests to verify everything works

Manual Installation (Alternative)

# Create virtual environment
python3 -m venv venv

# Activate it
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run specific interface
python -m solver.cli              # Command-line
python -m solver.flask_app        # Web (then open localhost:5000)
python -m solver.desktop_app      # Desktop GUI

✨ Features

🧊 Core Functionality

  • Accurate Cube Mechanics: Matrix-based state using proven transformation approach
  • IDDFS Solver: Finds optimal solutions for scrambled cubes (depth 5-8)
  • Plugin Architecture: Extensible solver system for future algorithms
  • Move Notation: Standard Western notation (R, L, U, D, F, B, primes, doubles)
  • State Management: Save and restore scrambled states for solution replay

🖥️ Command-Line Interface

> scramble 5
🎲 Scrambling cube with 5 moves...
Moves: R U' F D L

> solve
🧠 Solving cube...
Solution found: L' D' F' U R'
[Step-by-step playback with colored visualization]

> help
[Comprehensive interactive help system]

Features:

  • Colored ANSI terminal output (cross-platform)
  • Interactive REPL with command history
  • Manual move execution or sequence input
  • Step-by-step solution visualization
  • Undo/redo functionality

🌐 Web Interface

Launch: python -m solver.flask_app → Open http://localhost:5000

Interactive 3D Controls:

  • Left-click face: Clockwise rotation
  • Right-click face: Counter-clockwise
  • Ctrl/Cmd+Click: 180° rotation
  • Drag background: Rotate camera view
  • Scroll: Zoom in/out
  • Auto-rotate button: Continuous rotation for viewing
  • Reset camera: Return to default angle

Features:

  • Real-time 3D cube with Three.js
  • Smart drag detection (knows click vs drag)
  • Live move history panel
  • Solution generation and playback
  • Save/restore scrambled states
  • WebSocket real-time updates
  • Mobile-responsive touch controls

🖼️ Desktop Application

Launch: python -m solver.desktop_app

Features:

  • Hardware-accelerated OpenGL rendering
  • Interactive face clicking (same controls as web)
  • Smooth rotation animations with easing
  • Background solver thread (UI stays responsive)
  • Solution playback dialog with manual controls
  • Camera orbit controls

🏗️ Architecture

Project Structure

solver/
├── core/                      # Core cube logic
│   ├── cube.py               # Cube implementation (505 lines)
│   ├── solver.py             # Solver interface (186 lines)
│   ├── solvers/              # Plugin system
│   │   ├── base_solver.py   # Abstract base (232 lines)
│   │   └── iddfs_solver.py  # IDDFS algorithm (246 lines)
│   └── tests/               # 28 unit tests
│       ├── test_cube.py
│       ├── test_cube_comprehensive.py
│       └── test_scramble.py
├── cli/                      # Command-line interface
│   ├── cli_app.py           # Interactive CLI (650+ lines)
│   └── __main__.py          # Entry point
├── web/                      # Web interface
│   ├── static/
│   │   ├── css/styles.css   # Responsive styling
│   │   └── js/
│   │       ├── cube3d.js    # Three.js visualization
│   │       ├── socket-client.js  # WebSocket sync
│   │       ├── ui-controls.js    # Interactive controls
│   │       └── app.js            # Main app logic
│   └── templates/
│       └── index.html        # Single-page app
├── desktop/                  # Desktop application
│   ├── cube_gl_widget.py    # OpenGL 3D widget
│   └── __init__.py
├── flask_app.py             # Flask + SocketIO server
├── desktop_app.py           # PySide6 main window
└── tests/                   # Integration tests
    └── test_solver_integration.py

Technology Stack

Component Technology
Backend Python 3.11+, Flask, Flask-SocketIO
Frontend Vanilla JavaScript, Three.js, Socket.IO
Desktop PySide6 (Qt6), PyOpenGL
Core Logic NumPy for array operations
Testing pytest (28 tests, 100% pass rate)
Code Quality black, isort, autoflake, pylint (9.07/10)
Version Control Git with pre-commit hooks

Key Design Patterns

  1. Plugin Architecture: Solvers register themselves; runtime selection
  2. State Preservation: Save cube state before solving for replay
  3. Event-Driven UI: WebSocket for web, Qt signals for desktop
  4. Hybrid Interaction: Seamless blending of face clicks + camera controls
  5. Background Processing: Threading for solver to keep UI responsive

🎓 What We Learned

About AI-Assisted Development

LLMs Excel At:

  • Implementing well-defined algorithms from specifications
  • Generating boilerplate and repetitive code structures
  • Writing comprehensive tests and documentation
  • Following consistent code styles and patterns
  • Applying design patterns (plugins, facades, etc.)

Humans Are Essential For:

  • High-level architecture decisions
  • Debugging subtle interaction issues
  • UX design and accessibility considerations
  • Recognizing when to restart vs. iterate
  • Deciding when "good enough" is actually good enough

The Sweet Spot:

  • Human provides vision, direction, and judgment
  • AI implements, tests, and documents
  • Human reviews, guides refinement, and maintains quality bar
  • Iterative back-and-forth until solution emerges

About Rubik's Cube Solvers

Technical Insights:

  • Matrix transformations are cleaner than position tracking
  • Edge cycling is the tricky part (not face rotation)
  • IDDFS works well for small scrambles (5-8 moves)
  • State explosion makes depth >10 impractical without heuristics
  • Animation timing requires careful state management

UX Insights:

  • Hybrid click+drag mode feels more natural than mode switching
  • Accessibility (color contrast, keyboard support) matters
  • Background processing is critical for complex solvers
  • Solution playback needs manual controls, not just auto-play

📚 Development Journey

This project was built through ~300+ conversational exchanges over several sessions. Key milestones:

Phase 1: Core Cube (September 2025)

  • Initial attempt had incorrect edge cycling
  • Complete rewrite using matrix transformation approach
  • 32 unit tests, all moves validated mathematically
  • Learning: Start with proven approaches for complex algorithms

Phase 2: Solver System (September 2025)

  • Designed plugin architecture for extensibility
  • Implemented IDDFS optimal solver
  • Created solver registry and auto-selection
  • Learning: Good architecture pays off later

Phase 3: CLI Interface (September 2025)

  • Rich terminal UI with ANSI colors
  • Interactive REPL with command history
  • Cross-platform compatibility handling
  • Learning: User experience matters even in CLI

Phase 4: Web Interface (September 2025)

  • Multiple iterations on interaction model
  • Discovered hybrid click+drag approach
  • Fixed animation synchronization issues
  • Learning: UX iteration is essential, even with AI

Phase 5: Desktop Application (October 2025)

  • Implemented hardware-accelerated OpenGL rendering
  • Solved UI freezing with background threads
  • Fixed OpenGL context issues with face clicking
  • Learning: Framework constraints require explicit handling

Phase 6: Post-Launch Features (October 2025+)

  • Scramble Reveal: Show scramble sequence in competition format
  • Copy to clipboard functionality
  • Spoiler text in move log (click-to-reveal)
  • Responsive design refinements
  • Learning: Rapid feature iteration based on user feedback

Complete development log: See conversation_summary/ for every prompt and response organized by phase.

🔬 Technical Details

Cube Representation

Uses 3D NumPy array: stickers[6 faces][3 rows][3 columns]

# Each face is a 3x3 grid of colors
stickers[Face.U] = [[W, W, W],
                    [W, W, W],
                    [W, W, W]]

Color Scheme (Western/WCA standard):

  • White (U) ↔ Yellow (D)
  • Red (R) ↔ Orange (L)
  • Green (F) ↔ Blue (B)

Move Execution

Standard notation: R, L, U, D, F, B

  • Prime ('): Counter-clockwise
  • Double (2): 180°

Implementation:

  1. Rotate the face itself (np.rot90)
  2. Cycle edge pieces between adjacent faces
  3. Reverse appropriate edges for correct orientation

IDDFS Solver

Algorithm: Iterative Deepening Depth-First Search

  • Searches depth 1, then 2, then 3, etc.
  • Guarantees optimal solution (fewest moves)
  • Practical limit: depth 8 (~5-10 seconds)

Optimization: Prunes redundant moves (e.g., no R after R')

Web Architecture

Client-Server Communication:

Browser (Three.js) ←→ SocketIO ←→ Flask ←→ Cube Core

State Sync:

  1. User action (click, scramble, solve)
  2. Client emits WebSocket event
  3. Server updates cube state
  4. Server broadcasts state to all clients
  5. Clients update 3D visualization

Testing Strategy

28 Tests covering:

  • Individual move correctness (6 tests)
  • Mathematical properties (3 tests)
  • Scramble validity (7 tests)
  • Solver integration (6 tests)
  • Edge cases (6 tests)

Run tests: ./run_app.sh → Select option 4

🤝 Contributing

This project welcomes contributions! Areas of interest:

Enhancement Ideas

  • Additional Solvers: Implement A*, IDA*, or Kociemba's algorithm
  • Performance: Optimize IDDFS with pattern databases
  • Features: Cube timer, move counter, solution comparison
  • UI/UX: Improved animations, themes, tutorials

Development Setup

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Run ./run_python_formatters.sh (must score ≥9.0/10)
  5. Run tests: pytest solver/ -v
  6. Submit pull request

Code Standards:

  • Black formatting (auto-applied)
  • Pylint score ≥9.0
  • Type hints where helpful
  • Comprehensive docstrings
  • Unit tests for new functionality

📖 Additional Documentation

  • CLAUDE.md: Instructions for continuing development with Claude Code
  • DEVELOPMENT_JOURNAL.md: Retrospective from Claude's perspective with technical architecture and lessons learned
  • conversation_summary/: Complete conversation history organized by development phase

📄 License

MIT License - See LICENSE for details

Copyright (c) 2025 Daniel Pittman

🙏 Acknowledgments

  • MagicCube (github.com/trincaog/magiccube): Reference for cube mechanics
  • Three.js: 3D visualization library
  • Flask & Socket.IO: Real-time web framework
  • PySide6: Qt6 Python bindings
  • Anthropic: Claude Code AI coding assistant

💬 Reflections on AI-Assisted Development

This project demonstrates that LLMs can build production-quality software when given proper guidance. But it's not magic—it's collaboration.

What surprised us:

  • How quickly complex features came together with good prompts
  • The importance of incremental development (don't skip phases!)
  • How much human judgment matters for architecture and UX
  • That AI-generated code can meet professional quality standards

What we'd do differently:

  • Start with even more research on cube mechanics
  • Build a test suite before implementing features
  • Document architectural decisions as we make them
  • Create a git branching strategy earlier

The bottom line: AI coding assistants are powerful tools that amplify human developers, not replace them. The human provides vision, judgment, and direction. The AI provides implementation speed, consistency, and tireless iteration.

Built through conversation between 🧠 Human Guidance + 🤖 Claude Code

Want to see the complete development conversation? Check out conversation_summary/

About

A repository detailing my attempt to "vibe code" a graphical Rubik's Cube solver with different LLMs

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages