Sudoku C++

An offline Sudoku game built with C++23 and Qt6 for desktop users who prefer keyboard navigation and offline-only operation.

This project is entirely vibe coded using Claude Code — no manual coding involved. It serves as a personal experiment to explore what's possible with AI-assisted development and how to work effectively with Claude Code on a non-trivial C++ codebase.

Features

• Puzzle generation with 5 difficulty levels and guaranteed unique solutions
• 54 solving strategies with step-by-step hints
• Training mode for learning solving techniques
• Undo/redo, pencil marks, keyboard navigation
• Encrypted save/load (YAML + zlib + libsodium)
• Statistics tracking
• Localization (English, German)
• SIMD-accelerated solver (AVX2/AVX-512)

Technology Stack

Language	C++23
UI	Qt6 Widgets
Build	CMake + Ninja + Conan
Testing	Catch2
Architecture	MVVM
Dependencies	spdlog, yaml-cpp, zlib, libsodium

Prerequisites

• C++23 compatible compiler (GCC 14+, Clang 18+, or MSVC 2022+)
• CMake 3.28+
• Conan 2.0+
• Python 3.8+ (for Conan)
• ccache (optional, for faster recompilation)

Building the Project

Quick Start (Linux/macOS)

# Install dependencies, configure, and build
conan install . --build=missing
cmake --preset release
cmake --build --preset release

# Run
./build/Release/bin/sudoku

Windows (MSVC + Qt6)

Prerequisites:

1. Visual Studio 2022/2026 with the Desktop development with C++ workload
2. Qt6 — install via Qt Online Installer, selecting the MSVC 2022 64-bit component
3. Conan 2 — pip install conan
4. CMake — install separately or provided via Conan tool_requires

Build and run:

REM Release build
scripts\build_windows.bat

REM Debug build
scripts\build_windows_debug.bat

REM Run
build\Release\bin\sudoku.exe

The build scripts auto-detect the Visual Studio installation via vswhere.

Creating a Windows installer:

Requires NSIS (winget install NSIS.NSIS).

scripts\create_installer.bat

Build Configurations

# Release (default)
conan install . --build=missing
cmake --preset release && cmake --build --preset release

# Debug (full debug symbols in all dependencies)
conan install . --profile=gcc-15-debug --build=missing
cmake --preset debug && cmake --build --preset debug

# RelWithDebInfo (optimized + debug symbols for profiling)
conan install . --profile=gcc-15-relwithdebinfo --build=missing
cmake --preset relwithdebinfo && cmake --build --preset relwithdebinfo

To build with Clang instead, use the clang-21-* profiles (e.g. clang-21-release). GCC and Clang share the same build directory per build type — rebuild to switch.

See CONAN_PROFILES.md for profile details.

AppImage (Linux)

./scripts/build_appimage.sh

Profile-Guided Optimization

./scripts/pgo_build.sh

Testing

# Unit tests (904 test cases)
./build/Release/bin/tests/unit_tests

# Integration tests
./build/Release/bin/tests/integration_tests

# UI tests (Qt6, headless)
QT_QPA_PLATFORM=offscreen ctest --test-dir build/Release -R "^test_" --output-on-failure

# Run specific test case or tag
./build/Release/bin/tests/unit_tests "GameValidator - Move Validation"
./build/Release/bin/tests/unit_tests "[game_validator]"

Code Coverage

./scripts/coverage.sh              # Quick summary
./scripts/coverage.sh html         # HTML report

Code Quality Tools

./scripts/format.sh                # Format code (clang-format)
./scripts/format.sh check          # Check formatting only
./scripts/tidy.sh check            # clang-tidy analysis
./scripts/cppcheck.sh              # Cppcheck analysis
./scripts/cpd.sh                   # Copy-paste detection
./scripts/dead-code.sh             # Dead code detection
./scripts/iwyu.sh                  # Include-what-you-use

Project Structure

sudoku-cpp/
├── src/
│   ├── core/              # Business logic (Model layer)
│   ├── model/             # Domain models
│   ├── view_model/        # Presentation logic
│   ├── view/              # UI rendering (Qt6 Widgets)
│   └── infrastructure/    # Cross-cutting concerns
├── include/               # Shared public headers
├── tests/
│   ├── unit/              # Unit tests (904 test cases)
│   ├── integration/       # Integration tests
│   ├── ui/                # Qt6 UI tests (offscreen)
│   ├── benchmarks/        # Performance benchmarks
│   ├── data/              # Test fixtures
│   └── helpers/           # Test utilities
├── scripts/               # Build and analysis scripts
├── CMakeLists.txt         # Build configuration
└── conanfile.py           # Dependency management

Architecture

The project follows MVVM (Model-View-ViewModel) architecture with strict separation of concerns:

• Model Layer: Business logic (GameValidator, PuzzleGenerator, SudokuSolver, SaveManager)
• ViewModel Layer: Presentation logic with Observable pattern
• View Layer: UI rendering with Qt6 Widgets

Key architectural principles:

• Dependency Injection via interfaces
• Single-threaded design (no mutexes needed)
• Observable pattern for reactive UI updates
• Test-Driven Development (TDD)

Performance

All puzzle generation runs single-threaded — no background workers or thread pools. Performance comes from Zobrist hashing, memoization, SIMD constraint propagation, and runtime CPU dispatch (Scalar/AVX2/AVX-512).

Measured on AMD Ryzen 9 9950X (single core, AVX-512):

• Easy: ~0.07ms
• Medium: ~0.18ms
• Hard: ~0.72ms
• Expert: ~0.73ms
• Master: ~0.74ms

Development

Pre-Commit Hook

./scripts/setup-hooks.sh

Checks GPLv3 license headers and formatting on staged files. Optionally run clang-tidy with TIDY=1 git commit.

Cross-Compiler Testing

# Build and test with GCC
conan install . --profile=gcc-15-release --build=missing
cmake --preset release
cmake --build --preset release
./build/Release/bin/tests/unit_tests

# Rebuild with Clang (shares build/Release directory)
conan install . --profile=clang-21-release --build=missing
cmake --preset release
cmake --build --preset release
./build/Release/bin/tests/unit_tests

License

This project is licensed under the GNU General Public License v3.0 (GPLv3) — see the LICENSE file for details.

See ACKNOWLEDGMENTS.md for credits and THIRD_PARTY_LICENSES.md for dependency licenses.