Model a Sudoku grid as 81 cells and every rule as the 27 units and 20 peers, so parsing, validity, candidates, and solutions are all exact strings you can assert against. Each lesson is one idea with pinned values: the candidate set of a cell after removing its peers, a naked single cascading through its peers, a hidden single found in a unit, a contradiction (zero candidates) forcing a backtrack, the most-constrained cell chosen, an already-solved grid returned unchanged, an invalid puzzle reported as no solution, a two-solution puzzle reported as non-unique, and the exact solved grid of a known hardest puzzle.
Over 28 lessons you build a working Sudoku solver as a small importable library, following Peter Norvig''s classic recipe: constraint propagation to shrink the problem, then backtracking search to finish it. Because the whole design is deterministic - a fixed cell and candidate order, and a self-defined seeded generator - every lesson pins exact values (a candidate set, a solved 81-character grid, a solution count) that reproduce in any language you choose.
You start with the board: an 81-cell grid, parsing and printing an 81-character puzzle string, the 27 units (9 rows, 9 columns, 9 boxes) and each cell''s 20 peers, and a no-duplicates validity check. You compute each empty cell''s candidate set, then write a correct backtracking solver and make it fast with the most-constrained-cell (MRV) heuristic. Next comes Norvig''s propagation core - naked singles, hidden singles, propagation to a fixpoint, and contradiction detection - interleaved with search for the full fast solver. The final chapter counts solutions to test uniqueness, generates a uniquely-solvable puzzle from a seed, and rates difficulty, and the capstone solves a suite of real puzzles (an easy one, a hard one, and a known hardest) to their exact solved grids.
This is a genuinely complete teaching-grade solver: it solves any valid 9x9 puzzle, reports no-solution and non-unique puzzles honestly, and generates its own. It builds the constraint-propagation-plus-search design directly and stops short of the alternative exact-cover formulation (Knuth''s Dancing Links) and of human-style solving techniques beyond singles (naked and hidden pairs, box-line reduction, X-Wing), which are natural next steps rather than gaps in the solver.
A Sudoku board is a 9x9 grid, but the whole solver is easier to write over a flat run of 81 cells numbered 0 to 80. Today you build the tiny conversion between a (row, column) pair and that flat index, the coordinate system every later lesson stands on.
Convert between a (row, column) pair and a single 0-to-80 cell index.
Every rule in Sudoku is about the same 81 squares, so before anything else we fix
how to name a square. A 9x9 board has natural (row, column) coordinates, but a
flat array of 81 cells is far easier to loop over, copy, and compare than a nested
one. The bridge between the two is plain arithmetic: row-major order lays row 0
first (cells 0 to 8), then row 1 (cells 9 to 17), and so on, so a cell’s index is
row*9 + col, and you recover the coordinates with integer division and remainder.
This is deliberately tiny, but it is the coordinate system the entire solver is
written in. Rows, columns, boxes, peers, candidates, and every printed grid all
index into this same 0-to-80 space, so getting the mapping exactly right - and
noticing that column 8 of row 4 is 4*9 + 5 = 41, not 45 - is where it all starts.
// row-major: walk 9 cells per row, then across the rowfunc Index(row, col int) int { return row*9 + col }func RowOf(i int) int { return i / 9 }func ColOf(i int) int { return i % 9 }
A genuinely complete teaching-grade engine and CLI that solves, rates, and generates any valid 9x9 Sudoku - parse and validity, per-cell candidates, backtracking search with the MRV heuristic, naked-single and hidden-single propagation to a fixpoint with contradiction detection, the full propagation-plus-search solver, solution counting for uniqueness, and a seeded generator - but difficulty is only a binary Easy/Hard split, and the propagation stops at naked and hidden singles rather than the fuller human-technique repertoire.
The essay this project is built on - representing a grid as cell-to-candidates, assigning as constraint propagation (eliminate a value from a cell's peers, cascade naked and hidden singles), and finishing with depth-first search over the most-constrained cell. The clearest short account of the whole approach.
The alternative formulation: model Sudoku as an exact-cover problem and solve it with Algorithm X over a doubly-linked-list matrix (DLX). A different and elegant lens on the same puzzle, and the natural next project after this one.
The Constraint Satisfaction Problems chapter is the textbook home of everything here - variables, domains, and constraints; arc consistency and AC-3; the minimum-remaining-values heuristic; and backtracking search. Sudoku is its canonical worked example.
The exhaustive-search proof that every proper (uniquely solvable) Sudoku needs at least 17 clues. Background for the uniqueness and generation chapter, and the source of the famous 17-clue puzzles used as test data.
A practical writeup of generating puzzles by digging holes from a full grid while a unique solution remains, and grading difficulty by which solving techniques a puzzle requires - the direct companion to this project's generation and difficulty lessons.