Introduction

Relevant source files

README.md

Purpose and Scope

This wiki documents the sudoku-cpp-practice repository, an educational C++ project designed to teach multiple programming concepts simultaneously through the implementation of Sudoku puzzle generation and solving. The repository contains two independent applications—a command-line interface (CLI) and a graphical user interface (GUI)—that implement identical Sudoku algorithms but differ in their presentation layer.

This Introduction page provides an overview of the repository's educational goals, architecture, and recommended learning path. For detailed instructions on building and running the applications, see Getting Started. For in-depth coverage of the Sudoku algorithms, see Core Sudoku Algorithms. For application-specific implementation details, see CLI Application Guide and GUI Application Guide.

Sources: README.md1-150

Educational Objectives

The sudoku-cpp-practice repository is structured as a learning journey that covers the following areas:

Learning Area	Concepts Covered	Primary Location
C++ Language	C++17 features, `std::array`, recursion, value semantics	cli/src/main.cpp gui-raylib/src/main.cpp
Algorithms	Backtracking, constraint satisfaction, recursive depth-first search	Functions: `Solve()`, `GeneratePuzzle()`, `IsValid()`
Data Structures	2D arrays (9×9 board), game state management	Type: `std::array<std::array<int,9>,9>`
Build Systems	CMake configuration, cross-platform compilation, dependency management	cli/CMakeLists.txt gui-raylib/CMakeLists.txt
Graphics Programming	Event-driven architecture, rendering pipeline, input handling	gui-raylib/src/main.cpp raylib integration
Version Control	Git workflow, repository management, .gitignore configuration	.gitignore GitHowTo.md

The dual-application architecture allows learners to first understand core algorithmic concepts through the simpler CLI interface, then see how those same concepts apply in a production-ready GUI context.

Sources: README.md7-22 README.md131-147

Repository Structure and File Layout

The repository follows a clean separation between the two applications, with no shared source files. Each application implements the core Sudoku logic independently, demonstrating how algorithmic patterns can be reused across different contexts.

Repository Organization Diagram

Directory Structure:

Root level: Documentation (README.md LICENSE, GitHowTo.md) and configuration (.gitignore)
cli/: Command-line application with minimal dependencies
gui-raylib/: Graphical application with raylib dependency
Each application has its own CMakeLists.txt and src/main.cpp

Sources: README.md23-34

Core Algorithm Implementation

Both applications implement the same set of Sudoku algorithms. These algorithms are not in a shared library; instead, they are implemented inline within each main.cpp file, allowing learners to see the complete implementation in context.

Algorithm-to-Code Mapping

Key Function Signatures:

bool FindEmpty(const Board& board, int& row, int& col) - Locates next empty cell
bool IsValid(const Board& board, int row, int col, int num) - Validates Sudoku rules
bool Solve(Board& board) - Recursive backtracking solver
int SolveCount(Board board, int limit) - Counts solutions up to limit
Board GeneratePuzzle() - Creates puzzle with unique solution
int Rng() - Random number generator using std::mt19937

These functions exist identically in both cli/src/main.cpp and gui-raylib/src/main.cpp

Sources: README.md113-119

Technology Stack

The repository demonstrates modern C++ development practices with minimal external dependencies:

Component	Technology	Version/Standard	Usage
Language	C++	C++17	Standard enforced via `CMAKE_CXX_STANDARD`
Build System	CMake	3.10+	Cross-platform build configuration
CLI Framework	Standard Library	C++17 stdlib	`std::cin`, `std::cout`, `std::array`
GUI Framework	raylib	5.0	Window management, rendering, input
Dependency Management	CMake FetchContent	-	Automatic raylib download and build
Version Control	Git	-	Repository management
Random Number Generation	`<random>`	C++17	`std::mt19937`, `std::uniform_int_distribution`

The CLI application has zero external dependencies, requiring only a C++17 compiler. The GUI application automatically fetches raylib during the CMake configuration phase, demonstrating modern dependency management without vendoring.

Sources: README.md36-52 README.md72-103

Application Comparison

The two applications provide different learning experiences while sharing algorithmic foundations:

CLI vs GUI Feature Matrix

Feature	CLI Application	GUI Application
Entry Point	cli/src/main.cpp `main()`	gui-raylib/src/main.cpp `main()`
User Interface	Text-based menu via `std::cin`/`std::cout`	Window-based with mouse and keyboard
Main Loop	`game_loop()` function	`while (!WindowShouldClose())`
Puzzle Display	`print_board()` function with ASCII	raylib `DrawRectangle()`, `DrawText()`
Interaction Model	Sequential (menu→generate→show)	Event-driven (continuous input)
Game State	Local variables in `game_loop()`	`GameState` struct with `puzzle`, `current`, `solution`
Input Method	Numeric menu selection	Mouse click cell selection, keyboard input
Features	Generate puzzle, show solution	Generate, solve interactively, hints, validation
External Dependencies	None	raylib (auto-fetched)
Learning Focus	Core algorithms	GUI architecture

Both applications implement the same Solve(), GeneratePuzzle(), IsValid(), SolveCount(), and FindEmpty() functions, demonstrating that algorithmic logic is independent of presentation.

Sources: README.md54-70 README.md104-129

Recommended Learning Path

The repository is designed with a specific progression in mind:

Step-by-Step Progression:

Start with Documentation (README.md): Understand project goals and structure
Build CLI First (Section 2.2): Focus on algorithms without GUI complexity
Understand Core Algorithms (Section 3): Study Solve() and GeneratePuzzle() implementations
Progress to GUI (Section 5): See how same logic applies in event-driven context
Explore Build System (Section 6): Understand CMake and dependency management
Practice Git Workflow (Section 7.1): Learn version control practices

This progression ensures that complex concepts (GUI event loops, graphics rendering) don't obscure the fundamental algorithmic concepts that are the core learning objectives.

Sources: README.md131-138

Cross-Platform Support

The repository is designed to work identically on Windows, macOS, and Linux. Platform differences are abstracted through CMake, with platform-specific handling where necessary:

Platform	Compiler	Build Tools	Executable Name
Windows	MSVC (Visual Studio 2022)	CMake + MSBuild	`cli.exe`, `sudoku_gui.exe`
macOS	Clang (Xcode tools)	CMake + Make/Ninja	`cli`, `sudoku_gui`
Linux	GCC/G++	CMake + Make/Ninja	`cli`, `sudoku_gui`

Platform-specific configuration is handled in cli/CMakeLists.txt and gui-raylib/CMakeLists.txt including MSVC-specific UTF-8 source encoding flags (/utf-8).

Build artifacts (.obj, .o, .pdb, executables, CMake cache files) are excluded from version control via .gitignore ensuring a clean repository across all platforms.

Sources: README.md36-52

Next Steps

To begin working with this repository:

For setup instructions: See Prerequisites and Setup
To build the CLI application: See Building the CLI Application
To build the GUI application: See Building the GUI Application
To understand the algorithms: See Core Sudoku Algorithms
For Git workflow guidance: See Git Workflow Guide

The rest of this wiki provides detailed technical documentation for each component of the repository, with code references, diagrams, and implementation details to support both learning and development activities.