# anubothu-aravind/pyodide-sudoku architecture

> Architecture diagram of the GitHub repository anubothu-aravind/pyodide-sudoku, 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/anubothu-aravind/pyodide-sudoku
- Repository: https://github.com/anubothu-aravind/pyodide-sudoku

## Overview

This is a self-hosted, offline-capable Sudoku web app backed by a Python Sudoku engine, also exposed as a Python library and CLI. The main browser workflow routes a player into campaign or free play, sends generation/solve requests to the Pyodide worker, and renders interactive boards; campaign progress and game state persist locally. Watch Solver presents traced solving as a replay, with an optional naive-solver comparison. README documents campaign, free play, solver inspection, variants, PWA operation, and a CLI; some links to unsampled subsystems are documented rather than source-verified.

Main entry points: [`frontend/src/components/levels/LevelsView.tsx`](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/components/levels/LevelsView.tsx) (Campaign mode), [`frontend/src/components/play/PlayView.tsx`](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/components/play/PlayView.tsx) (Free play), [`sudoku/web_api.py`](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/sudoku/web_api.py) (Web API facade), [`frontend/src/App.tsx`](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/App.tsx) (App router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_app["App router<br/>[App.tsx]"]
  node_campaign["Campaign mode<br/>[LevelsView.tsx]"]
  node_freeplay["Free play<br/>[PlayView.tsx]"]
  node_board["Puzzle board<br/>[Board.tsx]"]
  node_numberpad["Number pad<br/>[NumberPad.tsx]"]
  node_replay["Solver replay<br/>[SolverPlayback.tsx]"]
  node_compare["Naive comparison"]
  node_replayengine["Replay engine<br/>[replayEngine.ts]"]
  node_playstate["Play state<br/>[playReducer.ts]"]
end

subgraph group_state["Local state"]
  node_storage[("IndexedDB storage<br/>[db.ts]")]
  node_validation["Record validation<br/>[validation.ts]"]
  node_sync["Tab synchronization<br/>[sync.ts]"]
  node_export["Progress import/export<br/>[exportImport.ts]"]
end

subgraph group_runtime["Browser runtime"]
  node_client["Worker client"]
  node_worker["Pyodide worker<br/>[pyodide.worker.ts]"]
  node_pyodide["Pyodide runtime<br/>[pyodide.mjs]"]
end

subgraph group_engine["Sudoku engine"]
  node_campaignengine["Level engine<br/>[levels.py]"]
  node_grid["Grid model<br/>[grid.py]"]
  node_candidates["Candidate state<br/>[candidates.py]"]
  node_solver["Logic solver<br/>[solver.py]"]
  node_generator["Puzzle generator<br/>[generator.py]"]
  node_difficulty["Difficulty grading<br/>[difficulty.py]"]
  node_trace["Solver trace<br/>[trace.py]"]
  node_naive["Naive solver<br/>[naive.py]"]
  node_variants["Sudoku variants<br/>[variants.py]"]
end

subgraph group_interfaces["Python interfaces"]
  node_webapi["Web API facade<br/>[web_api.py]"]
  node_cli["Python CLI<br/>[cli.py]"]
end

node_player(("Player"))

node_player -->|"opens"| node_app
node_app -->|"routes to"| node_campaign
node_app -->|"routes to"| node_freeplay
node_campaign -->|"renders"| node_board
node_campaign -->|"renders"| node_numberpad
node_freeplay -->|"renders"| node_board
node_freeplay -->|"renders"| node_numberpad
node_freeplay -->|"dispatches"| node_playstate
node_campaign -->|"requests puzzles"| node_client
node_freeplay -->|"requests solving"| node_client
node_campaign -->|"loads progress"| node_storage
node_campaign -->|"synchronizes tabs"| node_sync
node_app -->|"loads stats"| node_storage
node_storage -->|"validates records"| node_validation
node_player -.->|"updates tabs"| node_sync
node_player -.->|"exports progress"| node_export
node_client -.->|"posts requests"| node_worker
node_worker -.->|"returns responses"| node_client
node_worker -.->|"runs runtime"| node_pyodide
node_pyodide -.->|"invokes facade"| node_webapi
node_webapi -->|"requests levels"| node_campaignengine
node_webapi -->|"dispatches solving"| node_solver
node_webapi -->|"generates puzzles"| node_generator
node_webapi -->|"dispatches comparison"| node_naive
node_solver -->|"updates candidates"| node_candidates
node_candidates -->|"uses grid"| node_grid
node_solver -->|"emits events"| node_trace
node_generator -->|"checks uniqueness"| node_solver
node_generator -->|"grades puzzles"| node_difficulty
node_webapi -->|"dispatches variants"| node_variants
node_freeplay -->|"shows solver"| node_replay
node_campaign -->|"shows solver"| node_replay
node_replay -.->|"scrubs trace"| node_replayengine
node_freeplay -->|"opens comparison"| node_compare
node_webapi -.->|"supports CLI"| node_cli

click node_app "https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/App.tsx"
click node_campaign "https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/components/levels/LevelsView.tsx"
click node_freeplay "https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/components/play/PlayView.tsx"
click node_board "https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/components/board/Board.tsx"
click node_numberpad "https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/components/board/NumberPad.tsx"
click node_replay "https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/components/solver/SolverPlayback.tsx"
click node_compare "https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/components/solver/NaiveCompareModal.tsx"
click node_replayengine "https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/solver/replayEngine.ts"
click node_playstate "https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/reducers/playReducer.ts"
click node_storage "https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/storage/db.ts"
click node_validation "https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/storage/validation.ts"
click node_sync "https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/storage/sync.ts"
click node_export "https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/storage/exportImport.ts"
click node_client "https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/worker/sudokuWorkerClient.ts"
click node_worker "https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/worker/pyodide.worker.ts"
click node_pyodide "https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/public/pyodide/pyodide.mjs"
click node_campaignengine "https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/sudoku/levels.py"
click node_webapi "https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/sudoku/web_api.py"
click node_grid "https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/sudoku/grid.py"
click node_candidates "https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/sudoku/candidates.py"
click node_solver "https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/sudoku/solver.py"
click node_generator "https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/sudoku/generator.py"
click node_difficulty "https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/sudoku/difficulty.py"
click node_trace "https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/sudoku/trace.py"
click node_naive "https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/sudoku/naive.py"
click node_variants "https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/sudoku/variants.py"
click node_cli "https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/sudoku/cli.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_app,node_campaign,node_freeplay,node_board,node_numberpad,node_replay,node_compare,node_replayengine,node_playstate toneBlue
class node_storage,node_validation,node_sync,node_export toneAmber
class node_client,node_worker,node_pyodide toneMint
class node_campaignengine,node_grid,node_candidates,node_solver,node_generator,node_difficulty,node_trace,node_naive,node_variants toneRose
class node_webapi,node_cli,node_player toneIndigo
```

## Components

### Web experience

- [App router](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Campaign mode](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/components/levels/LevelsView.tsx): `frontend/src/components/levels/LevelsView.tsx`
- [Free play](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/components/play/PlayView.tsx): `frontend/src/components/play/PlayView.tsx`
- [Puzzle board](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/components/board/Board.tsx): `frontend/src/components/board/Board.tsx`
- [Number pad](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/components/board/NumberPad.tsx): `frontend/src/components/board/NumberPad.tsx`
- [Solver replay](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/components/solver/SolverPlayback.tsx): `frontend/src/components/solver/SolverPlayback.tsx`
- [Naive comparison](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/components/solver/NaiveCompareModal.tsx): `frontend/src/components/solver/NaiveCompareModal.tsx`
- [Replay engine](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/solver/replayEngine.ts): `frontend/src/solver/replayEngine.ts`
- [Play state](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/reducers/playReducer.ts): `frontend/src/reducers/playReducer.ts`

### Local state

- [IndexedDB storage](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/storage/db.ts): `frontend/src/storage/db.ts`
- [Record validation](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/storage/validation.ts): `frontend/src/storage/validation.ts`
- [Tab synchronization](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/storage/sync.ts): `frontend/src/storage/sync.ts`
- [Progress import/export](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/storage/exportImport.ts): `frontend/src/storage/exportImport.ts`

### Browser runtime

- [Worker client](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/worker/sudokuWorkerClient.ts): `frontend/src/worker/sudokuWorkerClient.ts`
- [Pyodide worker](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/src/worker/pyodide.worker.ts): `frontend/src/worker/pyodide.worker.ts`
- [Pyodide runtime](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/frontend/public/pyodide/pyodide.mjs): `frontend/public/pyodide/pyodide.mjs`

### Sudoku engine

- [Level engine](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/sudoku/levels.py): `sudoku/levels.py`
- [Grid model](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/sudoku/grid.py): `sudoku/grid.py`
- [Candidate state](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/sudoku/candidates.py): `sudoku/candidates.py`
- [Logic solver](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/sudoku/solver.py): `sudoku/solver.py`
- [Puzzle generator](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/sudoku/generator.py): `sudoku/generator.py`
- [Difficulty grading](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/sudoku/difficulty.py): `sudoku/difficulty.py`
- [Solver trace](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/sudoku/trace.py): `sudoku/trace.py`
- [Naive solver](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/sudoku/naive.py): `sudoku/naive.py`
- [Sudoku variants](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/sudoku/variants.py): `sudoku/variants.py`

### Python interfaces

- [Web API facade](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/sudoku/web_api.py): `sudoku/web_api.py`
- [Python CLI](https://github.com/anubothu-aravind/pyodide-sudoku/blob/main/sudoku/cli.py): `sudoku/cli.py`

### Other components

- **Player**

## Connections

- Player → App router: opens
- App router → Campaign mode: routes to (evidence: `frontend/src/App.tsx`)
- App router → Free play: routes to (evidence: `frontend/src/App.tsx`)
- Campaign mode → Puzzle board: renders (evidence: `frontend/src/components/levels/LevelsView.tsx`)
- Campaign mode → Number pad: renders (evidence: `frontend/src/components/levels/LevelsView.tsx`)
- Free play → Puzzle board: renders (evidence: `frontend/src/components/play/PlayView.tsx`)
- Free play → Number pad: renders (evidence: `frontend/src/components/play/PlayView.tsx`)
- Free play → Play state: dispatches (evidence: `frontend/src/components/play/PlayView.tsx`)
- Campaign mode → Worker client: requests puzzles (evidence: `frontend/src/components/levels/LevelsView.tsx`)
- Free play → Worker client: requests solving (evidence: `frontend/src/components/play/PlayView.tsx`)
- Campaign mode → IndexedDB storage: loads progress (evidence: `frontend/src/components/levels/LevelsView.tsx`)
- Campaign mode → Tab synchronization: synchronizes tabs (evidence: `frontend/src/components/levels/LevelsView.tsx`)
- App router → IndexedDB storage: loads stats (evidence: `frontend/src/App.tsx`)
- IndexedDB storage → Record validation: validates records (evidence: `frontend/src/storage/db.ts`)
- Player → Tab synchronization: updates tabs
- Player → Progress import/export: exports progress
- Worker client → Pyodide worker: posts requests
- Pyodide worker → Worker client: returns responses
- Pyodide worker → Pyodide runtime: runs runtime
- Pyodide runtime → Web API facade: invokes facade
- Web API facade → Level engine: requests levels (evidence: `sudoku/web_api.py`)
- Web API facade → Logic solver: dispatches solving (evidence: `sudoku/web_api.py`)
- Web API facade → Puzzle generator: generates puzzles (evidence: `sudoku/web_api.py`)
- Web API facade → Naive solver: dispatches comparison (evidence: `sudoku/web_api.py`)
- Logic solver → Candidate state: updates candidates (evidence: `sudoku/solver.py`)
- Candidate state → Grid model: uses grid (evidence: `sudoku/candidates.py`)
- Logic solver → Solver trace: emits events (evidence: `sudoku/solver.py`)
- Puzzle generator → Logic solver: checks uniqueness (evidence: `sudoku/generator.py`)
- Puzzle generator → Difficulty grading: grades puzzles (evidence: `sudoku/generator.py`)
- Web API facade → Sudoku variants: dispatches variants (evidence: `sudoku/web_api.py`)
- Free play → Solver replay: shows solver (evidence: `frontend/src/components/play/PlayView.tsx`)
- Campaign mode → Solver replay: shows solver (evidence: `frontend/src/components/levels/LevelsView.tsx`)
- Solver replay → Replay engine: scrubs trace
- Free play → Naive comparison: opens comparison (evidence: `frontend/src/components/play/PlayView.tsx`)
- Web API facade → Python CLI: supports CLI
