# rg1990/cv-sudoku-solver architecture

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

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

## Overview

##### Project type and purpose
- This is a Python project that combines a computer‐vision + deep‐learning pipeline for extracting and solving Sudoku puzzles from images, along with a Pygame‐based interactive Sudoku game.
- Key use cases:
- Train or load a CNN model to classify digits.
- Process an image of a Sudoku grid (OpenCV) → recognize digits (Keras model) → solve (backtracking).
- Render solution back onto original image or present as an interactive game (Pygame).

##### File structure
- Top‐level scripts:
- prepare_data.py → builds the font + MNIST datasets.
- train.py → trains a Keras CNN, outputs to /models.
- sudoku_main.py → CLI for processing a Sudoku image end‐to‐end.
- sudoku_game.py → launches the Pygame UI for preloaded puzzles or drag/drop images.
- sudoku_solver_class.py → the backtracking solver core.
- sudoku_utils.py → shared utilities (image transforms, grid extraction, digit bounding).
- Data directories:
- data/digit_images & data/font_exclude → font‐based digit images.
- data/sudoku_images → raw input images.
- data/sudoku_puzzles → text‐based puzzles for game mode.
- Models directory: saved .keras model files.
- Config & deps: requirements.txt, .gitignore.

##### README for additional insights
- Confirms two pipelines:
A. CV + DL → solve + overlay solution.
B. Pygame UI → choose from text puzzles or drag/drop image → hint, check, solve.
- Libraries: OpenCV, Keras, Pygame.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layer 1: Data
    subgraph "Layer 1: Data Preparation"
        style Layer1 fill:none,stroke:none
        data_digit["data/digit_images/"]:::data
        data_font["data/font_exclude/"]:::data
        prepare["prepare_data.py"]:::compute
        data_digit -->|provides font images| prepare
        data_font -->|provides font images| prepare
    end

    %% Layer 2: Training
    subgraph "Layer 2: Model Training"
        style Layer2 fill:none,stroke:none
        train["train.py"]:::compute
        models["models/"]:::data
        prepare -->|datasets| train
        train -->|.keras model| models
    end

    %% Layer 3: Inference
    subgraph "Layer 3: Inference Pipeline"
        style Layer3 fill:none,stroke:none
        sudoku_images["data/sudoku_images/"]:::data
        utils["sudoku_utils.py"]:::compute
        main["sudoku_main.py"]:::compute
        models -->|load model| main
        sudoku_images -->|input images| main
        main -->|uses utilities| utils
    end

    %% Layer 4: Solver
    subgraph "Layer 4: Solver Core"
        style Layer4 fill:none,stroke:none
        solver["sudoku_solver_class.py"]:::business
        utils -->|extract grid| solver
        main -->|passes grid| solver
        solver -->|solution matrix| main
    end

    %% Layer 5: UI / Rendering
    subgraph "Layer 5: Rendering & UI"
        style Layer5 fill:none,stroke:none
        overlay["Overlay Solution"]:::ui
        game["sudoku_game.py"]:::ui
        main -->|overlays solution| overlay
        sudoku_puzzles["data/sudoku_puzzles/"]:::data
        sudoku_puzzles -->|load puzzles| game
        sudoku_images -->|drag/drop images| game
        models -->|load model| game
        utils -->|CV & utils| game
        solver -->|solve requests| game
    end

    %% Infrastructure / Docs
    subgraph "Project Files"
        style Infra fill:none,stroke:none
        req["requirements.txt"]:::infra
        gitignore[".gitignore"]:::infra
        readme["README.md"]:::infra
    end

    %% Click Events
    click prepare "https://github.com/rg1990/cv-sudoku-solver/blob/main/prepare_data.py"
    click data_digit "https://github.com/rg1990/cv-sudoku-solver/tree/main/data/digit_images/"
    click data_font "https://github.com/rg1990/cv-sudoku-solver/tree/main/data/font_exclude/"
    click train "https://github.com/rg1990/cv-sudoku-solver/blob/main/train.py"
    click models "https://github.com/rg1990/cv-sudoku-solver/tree/main/models/"
    click sudoku_images "https://github.com/rg1990/cv-sudoku-solver/tree/main/data/sudoku_images/"
    click sudoku_puzzles "https://github.com/rg1990/cv-sudoku-solver/tree/main/data/sudoku_puzzles/"
    click utils "https://github.com/rg1990/cv-sudoku-solver/blob/main/sudoku_utils.py"
    click main "https://github.com/rg1990/cv-sudoku-solver/blob/main/sudoku_main.py"
    click solver "https://github.com/rg1990/cv-sudoku-solver/blob/main/sudoku_solver_class.py"
    click game "https://github.com/rg1990/cv-sudoku-solver/blob/main/sudoku_game.py"
    click req "https://github.com/rg1990/cv-sudoku-solver/blob/main/requirements.txt"
    click gitignore "https://github.com/rg1990/cv-sudoku-solver/blob/main/.gitignore"
    click readme "https://github.com/rg1990/cv-sudoku-solver/blob/main/README.md"

    %% Styles
    classDef data fill:#D6EAF8,stroke:#2980B9
    classDef compute fill:#D5F5E3,stroke:#27AE60
    classDef business fill:#FAD7A0,stroke:#E67E22
    classDef ui fill:#E8DAEF,stroke:#8E44AD
    classDef infra fill:#F2F3F4,stroke:#7F8C8D
```
