# cosc111-sudoku-solver/sudoku-solver architecture

> Architecture diagram of the GitHub repository cosc111-sudoku-solver/sudoku-solver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cosc111-sudoku-solver/sudoku-solver
- Repository: https://github.com/cosc111-sudoku-solver/sudoku-solver

## Overview

This package turns a Sudoku image into a reviewed, solved grid and can save the result as CSV. The CLI coordinates image preparation, grid detection, OCR, interactive correction, solving, display, and optional export. The solver supports both exhaustive solution collection and animated single-solution search. OCR relies on the external Tesseract executable. Relationships follow the CLI and solver calls shown in the excerpts; the README documents the user workflow and capabilities.

Main entry points: [`sudoku_solver_ocr/main.py`](https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/main.py) (Workflow coordinator), [`sudoku_solver_ocr/sudoku_solver.py`](https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/sudoku_solver.py) (Animated solving), [`sudoku_solver_ocr/sudoku_utils.py`](https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/sudoku_utils.py) (Review and edit), [`sudoku_solver_ocr/sudoku_ocr.py`](https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/sudoku_ocr.py) (Recognize digits)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflow"]
  node_main["Workflow coordinator<br/>[main.py]"]
end

subgraph group_vision["Image recognition"]
  node_prepare["Prepare image<br/>[sudoku_ocr.py]"]
  node_crop["Crop grid<br/>[sudoku_ocr.py]"]
  node_split["Split cells<br/>[sudoku_ocr.py]"]
  node_recognize["Recognize digits<br/>[sudoku_ocr.py]"]
end

subgraph group_solve["Sudoku solving"]
  node_constraints["Placement checks<br/>[sudoku_solver.py]"]
  node_search["Backtracking search<br/>[sudoku_solver.py]"]
  node_animated["Animated solving<br/>[sudoku_solver.py]"]
end

subgraph group_interaction["Review and results"]
  node_review["Review and edit<br/>[sudoku_utils.py]"]
  node_grid_utils["Grid formatting<br/>[sudoku_utils.py]"]
  node_board["Board display<br/>[sudoku_utils.py]"]
  node_csv["CSV utilities<br/>[sudoku_utils.py]"]
end

node_user(("CLI user"))
node_tesseract["Tesseract OCR"]
node_csvfile["Solution CSV"]

node_user -->|"runs CLI"| node_main
node_main -->|"loads image"| node_prepare
node_main -->|"crops grid"| node_crop
node_main -->|"splits cells"| node_split
node_main -->|"reads digits"| node_recognize
node_recognize -->|"requests OCR"| node_tesseract
node_main -->|"requests review"| node_review
node_review -->|"formats grid"| node_grid_utils
node_review -->|"displays board"| node_board
node_main -->|"formats solution"| node_grid_utils
node_main -->|"prints solution"| node_board
node_main -->|"solves puzzle"| node_search
node_search -->|"checks placements"| node_constraints
node_main -->|"solves animated"| node_animated
node_animated -->|"searches solution"| node_search
node_animated -->|"refreshes display"| node_board
node_main -->|"writes solution"| node_csv
node_csv -->|"writes CSV"| node_csvfile

click node_main "https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/main.py"
click node_prepare "https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/sudoku_ocr.py"
click node_crop "https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/sudoku_ocr.py"
click node_split "https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/sudoku_ocr.py"
click node_recognize "https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/sudoku_ocr.py"
click node_review "https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/sudoku_utils.py"
click node_grid_utils "https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/sudoku_utils.py"
click node_constraints "https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/sudoku_solver.py"
click node_search "https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/sudoku_solver.py"
click node_animated "https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/sudoku_solver.py"
click node_board "https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/sudoku_utils.py"
click node_csv "https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/sudoku_utils.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_user toneBlue
class node_prepare,node_crop,node_split,node_recognize toneAmber
class node_constraints,node_search,node_animated toneMint
class node_review,node_grid_utils,node_board,node_csv toneRose
class node_tesseract,node_csvfile toneIndigo
```

## Components

### CLI workflow

- [Workflow coordinator](https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/main.py): `sudoku_solver_ocr/main.py`

### Image recognition

- [Prepare image](https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/sudoku_ocr.py): `sudoku_solver_ocr/sudoku_ocr.py`
- [Crop grid](https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/sudoku_ocr.py): `sudoku_solver_ocr/sudoku_ocr.py`
- [Split cells](https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/sudoku_ocr.py): `sudoku_solver_ocr/sudoku_ocr.py`
- [Recognize digits](https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/sudoku_ocr.py): `sudoku_solver_ocr/sudoku_ocr.py`

### Sudoku solving

- [Placement checks](https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/sudoku_solver.py): `sudoku_solver_ocr/sudoku_solver.py`
- [Backtracking search](https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/sudoku_solver.py): `sudoku_solver_ocr/sudoku_solver.py`
- [Animated solving](https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/sudoku_solver.py): `sudoku_solver_ocr/sudoku_solver.py`

### Review and results

- [Review and edit](https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/sudoku_utils.py): `sudoku_solver_ocr/sudoku_utils.py`
- [Grid formatting](https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/sudoku_utils.py): `sudoku_solver_ocr/sudoku_utils.py`
- [Board display](https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/sudoku_utils.py): `sudoku_solver_ocr/sudoku_utils.py`
- [CSV utilities](https://github.com/cosc111-sudoku-solver/sudoku-solver/blob/main/sudoku_solver_ocr/sudoku_utils.py): `sudoku_solver_ocr/sudoku_utils.py`

### Other components

- **CLI user**
- **Tesseract OCR**
- **Solution CSV**

## Connections

- CLI user → Workflow coordinator: runs CLI (evidence: `README.md`)
- Workflow coordinator → Prepare image: loads image (evidence: `sudoku_solver_ocr/main.py`)
- Workflow coordinator → Crop grid: crops grid (evidence: `sudoku_solver_ocr/main.py`)
- Workflow coordinator → Split cells: splits cells (evidence: `sudoku_solver_ocr/main.py`)
- Workflow coordinator → Recognize digits: reads digits (evidence: `sudoku_solver_ocr/main.py`)
- Recognize digits → Tesseract OCR: requests OCR (evidence: `sudoku_solver_ocr/sudoku_ocr.py`)
- Workflow coordinator → Review and edit: requests review (evidence: `sudoku_solver_ocr/main.py`)
- Review and edit → Grid formatting: formats grid (evidence: `sudoku_solver_ocr/sudoku_utils.py`)
- Review and edit → Board display: displays board (evidence: `sudoku_solver_ocr/sudoku_utils.py`)
- Workflow coordinator → Grid formatting: formats solution (evidence: `sudoku_solver_ocr/main.py`)
- Workflow coordinator → Board display: prints solution (evidence: `sudoku_solver_ocr/main.py`)
- Workflow coordinator → Backtracking search: solves puzzle (evidence: `sudoku_solver_ocr/main.py`)
- Backtracking search → Placement checks: checks placements (evidence: `sudoku_solver_ocr/sudoku_solver.py`)
- Workflow coordinator → Animated solving: solves animated (evidence: `sudoku_solver_ocr/main.py`)
- Animated solving → Backtracking search: searches solution (evidence: `sudoku_solver_ocr/sudoku_solver.py`)
- Animated solving → Board display: refreshes display (evidence: `sudoku_solver_ocr/sudoku_solver.py`)
- Workflow coordinator → CSV utilities: writes solution (evidence: `sudoku_solver_ocr/main.py`)
- CSV utilities → Solution CSV: writes CSV (evidence: `sudoku_solver_ocr/sudoku_utils.py`)
