# uditrpanchal/trm-sudoku-neural-solver architecture

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

- Interactive diagram: https://gitdiagram.com/uditrpanchal/trm-sudoku-neural-solver
- Repository: https://github.com/uditrpanchal/trm-sudoku-neural-solver

## Overview

##### Project Type and Purpose
- This is a full-stack, end-to-end Sudoku solving toolkit.
- Backend: Python-based ML pipeline (dataset generator, tiny MLP-Mixer model, classical backtracking solver) exposed via CLI and FastAPI.
- Frontend: Vite + React + Tailwind dashboard for interactive experimentation, metrics, and visualization.

##### High-Level File Structure Analysis
- Top-level files:
- solve_sudoku.py – CLI entry point
- web_backend.py – FastAPI app exposing /api endpoints
- sudoku_pipeline.py – Orchestrator for dataset → model training/inference → solver refinement → metrics/logging
- tiny_recursive_model.py – PyTorch MLPMixer implementation + training harness
- sudoku_utils.py – Puzzle generation + classical backtracking solver + validation helpers
- sudoku_dataset.py – torch.utils.data.Dataset wrapper around on-the-fly puzzle generation
- train_models.py – Batch training script for research/benchmarks
- Various analysis scripts (inference.py, investigate_accuracy.py, debug_difficulty.py, etc.)
- frontend/ – React dashboard with API client, UI components, theme provider, metrics/logs panels
- Dockerfile – Container image spec for serving FastAPI + CPU Torch

##### Key Insights from README
- ML backbone: TinyRecursiveModel (1D MLPMixer)
- Refinement: Deterministic backtracking solver
- Exposed interfaces:
- CLI runner (solve_sudoku.py)
- FastAPI REST (web_backend.py + uvicorn)
- React Dashboard (frontend/)
- No persistent database; puzzles generated on demand.

##### Components
a. Client-side
- CLI Client (solve_sudoku.py)
- React Web UI (browser + Vite dev server / production build)
b. API Layer
- FastAPI App (web_backend.py)
- UVicorn Server
c. Orchestration & Business Logic
- Sudoku Pipeline (sudoku_pipeline.py)
- Training Scripts (train_models.py)
- Analysis Scripts (inference.py, investigate_accuracy.py, etc.)
d. ML Component
- TinyRecursiveModel (tiny_recursive_model.py)
- Dataset Generator (sudoku_dataset.py + sudoku_utils.py)
e. Classical Solver
- Backtracking Algorithm (sudoku_utils.py)
f. Auxiliary
- Logging & Metrics (inside pipeline; streamed via API)
- Docker Container (Dockerfile)
- Asset Store (assets/ for README screenshot)
g. Development & Build
- npm / Vite (frontend)
- pip / requirements.txt (backend)

##### Relationships and Data Flows
- CLI Client and Web UI → send run requests → FastAPI App
- FastAPI App → invokes Sudoku Pipeline
- Pipeline →
1. Generates puzzle via sudoku_dataset + sudoku_utils
2. Runs TinyRecursiveModel inference/training
3. Applies backtracking solver for refinement
4. Collects metrics & logs
- Pipeline returns results to FastAPI → API response → CLI prints or Web UI renders
- Web UI polls API endpoints (/api/health, /api/difficulties, /api/generate_puzzle, /api/run) via HTTP
- Development pipelines: train_models.py & analysis scripts call pipeline directly for research (no HTTP)

##### Architectural Patterns & Principles
- Layered architecture: Presentation (CLI, UI), API/controller (FastAPI), Domain logic (pipeline), Data/algorithmic modules (model, solver).
- Single-repository monorepo with clear separation of concerns.
- Reusable pipeline core for both CLI and API.
- Stateless service—no persistent storage; leverages on-the-fly generation.

##### Technology Stack
- Backend: Python 3.10+, FastAPI, Uvicorn, PyTorch (CPU/Torch GPU), torch.utils.data
- Frontend: Node.js 18+, Vite, React, TypeScript, Tailwind CSS, shadcn-style primitives, Radix UI, Sonner toasts
- Containerization: Docker
- Testing: pytest (test_*.py)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interfaces
    subgraph "User Interfaces"
        CLI["CLI Client\n(solve_sudoku.py)"]:::ui
        WebUI["React Web UI"]:::ui
    end

    %% Docker Container
    subgraph "Docker Container" 
        direction TB
        subgraph "API Layer"
            FastAPI["FastAPI App\n(web_backend.py)"]:::api
            Uvicorn["Uvicorn Server"]:::api
        end

        subgraph "Core Logic"
            Pipeline["Sudoku Pipeline\n(sudoku_pipeline.py)"]:::core
        end

        subgraph "ML Component"
            Model["TinyRecursiveModel\n(tiny_recursive_model.py)"]:::data
            Wrapper["TRM Wrapper\n(trm_wrapper.py)"]:::data
        end

        subgraph "Data & Algorithm Modules"
            Dataset["Dataset Generator\n(sudoku_dataset.py)"]:::data
            Solver["Classical Solver\n(sudoku_utils.py)"]:::data
        end
    end

    %% Analysis & Batch
    subgraph "Analysis & Batch"
        direction TB
        Train["Batch Training Script\n(train_models.py)"]:::core
        Inference["Inference Script\n(inference.py)"]:::aux
        Accuracy["Accuracy Investigation\n(investigate_accuracy.py)"]:::aux
        Debug["Difficulty Debugging\n(debug_difficulty.py)"]:::aux
        Speed["Speed Test Script\n(simple_speed_test.py)"]:::aux
        Check["Model Status Checker\n(check_model_status.py)"]:::aux
    end

    %% Dependencies & Assets
    Req["Backend Dependencies\n(requirements.txt)"]:::aux
    FEpkg["Frontend Dependencies\n(package.json)"]:::aux
    Assets["Asset Store\n(assets/)"]:::aux

    %% Connections
    CLI -->|"invoke"| Pipeline
    Pipeline -->|"return results"| CLI

    WebUI -->|"HTTP /api/*"| FastAPI
    FastAPI -->|"invoke pipeline"| Pipeline
    Pipeline -->|"response"| FastAPI
    FastAPI -->|"JSON response"| WebUI

    Pipeline -->|"generate puzzle"| Dataset
    Pipeline -->|"infer/train"| Model
    Model -->|"uses"| Wrapper
    Pipeline -->|"refine solution"| Solver
    Pipeline -->|"log metrics"| FastAPI

    Train -->|"direct call"| Pipeline
    Inference -->|"direct call"| Pipeline
    Accuracy -->|"direct call"| Pipeline
    Debug -->|"direct call"| Pipeline
    Speed -->|"direct call"| Pipeline
    Check -->|"direct call"| Pipeline

    WebUI --- FEpkg
    FastAPI --- Req
    Assets -.-> WebUI

    %% Click Events
    click CLI "https://github.com/uditrpanchal/trm-sudoku-neural-solver/blob/master/solve_sudoku.py"
    click WebUI "https://github.com/uditrpanchal/trm-sudoku-neural-solver/tree/master/frontend/"
    click FastAPI "https://github.com/uditrpanchal/trm-sudoku-neural-solver/blob/master/web_backend.py"
    click Uvicorn "https://github.com/uditrpanchal/trm-sudoku-neural-solver/blob/master/fast_mode_config.py"
    click Pipeline "https://github.com/uditrpanchal/trm-sudoku-neural-solver/blob/master/sudoku_pipeline.py"
    click Model "https://github.com/uditrpanchal/trm-sudoku-neural-solver/blob/master/tiny_recursive_model.py"
    click Wrapper "https://github.com/uditrpanchal/trm-sudoku-neural-solver/blob/master/trm_wrapper.py"
    click Dataset "https://github.com/uditrpanchal/trm-sudoku-neural-solver/blob/master/sudoku_dataset.py"
    click Solver "https://github.com/uditrpanchal/trm-sudoku-neural-solver/blob/master/sudoku_utils.py"
    click Train "https://github.com/uditrpanchal/trm-sudoku-neural-solver/blob/master/train_models.py"
    click Inference "https://github.com/uditrpanchal/trm-sudoku-neural-solver/blob/master/inference.py"
    click Accuracy "https://github.com/uditrpanchal/trm-sudoku-neural-solver/blob/master/investigate_accuracy.py"
    click Debug "https://github.com/uditrpanchal/trm-sudoku-neural-solver/blob/master/debug_difficulty.py"
    click Speed "https://github.com/uditrpanchal/trm-sudoku-neural-solver/blob/master/simple_speed_test.py"
    click Check "https://github.com/uditrpanchal/trm-sudoku-neural-solver/blob/master/check_model_status.py"
    click Req "https://github.com/uditrpanchal/trm-sudoku-neural-solver/blob/master/requirements.txt"
    click FEpkg "https://github.com/uditrpanchal/trm-sudoku-neural-solver/blob/master/frontend/package.json"
    click Assets "https://github.com/uditrpanchal/trm-sudoku-neural-solver/tree/master/assets/"

    %% Styles
    classDef ui fill:#9f6,stroke:#393,stroke-width:1px
    classDef api fill:#6cf,stroke:#036,stroke-width:1px
    classDef core fill:#f96,stroke:#a60,stroke-width:1px
    classDef data fill:#c9f,stroke:#639,stroke-width:1px
    classDef aux fill:#ccc,stroke:#888,stroke-width:1px
```
