# matthewh33/minesweeper-ai architecture

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

- Interactive diagram: https://gitdiagram.com/matthewh33/minesweeper-ai
- Repository: https://github.com/matthewh33/minesweeper-ai

## Overview

This is a screen-based Google Minesweeper assistant. Its main workflow captures a configured screen region, classifies a fixed grid, asks the deterministic constraint solver for safe/flag moves, and displays those suggestions in an overlay and HUD. A separate capture-preview utility helps adjust screen bounds; it is not shown as wired into the assistant because no such connection is evidenced. The excerpts establish the main calls, though omitted portions limit detail on frame-loop dispatch.

Main entry points: [`Minesweeper.py`](https://github.com/matthewh33/minesweeper-ai/blob/main/Minesweeper.py) (Screen capture loop), [`google_minesweeper_solver.py`](https://github.com/matthewh33/minesweeper-ai/blob/main/google_minesweeper_solver.py) (Move inference), [`screen-config.py`](https://github.com/matthewh33/minesweeper-ai/blob/main/screen-config.py) (Capture preview)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_assistant["Live assistant"]
  node_capture["Screen capture loop<br/>[Minesweeper.py]"]
  node_classify["Grid detection<br/>[Minesweeper.py]"]
  node_overlay["Move overlay<br/>[Minesweeper.py]"]
  node_hud["Board HUD<br/>[Minesweeper.py]"]
end

subgraph group_solver["Constraint solver"]
  node_solve["Move inference"]
  node_manual["Manual board CLI"]
end

subgraph group_config["Capture configuration"]
  node_preview["Capture preview<br/>[screen-config.py]"]
end

node_user(("Operator"))
node_display["Desktop display"]

node_user -->|"starts and controls"| node_capture
node_capture -->|"passes frames"| node_classify
node_classify -->|"passes board"| node_solve
node_manual -->|"passes board"| node_solve
node_capture -->|"draws suggestions"| node_overlay
node_capture -->|"renders status"| node_hud
node_overlay -->|"shows frame"| node_display
node_hud -->|"shows panel"| node_display
node_preview -->|"previews bounds"| node_user

click node_capture "https://github.com/matthewh33/minesweeper-ai/blob/main/Minesweeper.py"
click node_classify "https://github.com/matthewh33/minesweeper-ai/blob/main/Minesweeper.py"
click node_solve "https://github.com/matthewh33/minesweeper-ai/blob/main/google_minesweeper_solver.py"
click node_manual "https://github.com/matthewh33/minesweeper-ai/blob/main/google_minesweeper_solver.py"
click node_overlay "https://github.com/matthewh33/minesweeper-ai/blob/main/Minesweeper.py"
click node_hud "https://github.com/matthewh33/minesweeper-ai/blob/main/Minesweeper.py"
click node_preview "https://github.com/matthewh33/minesweeper-ai/blob/main/screen-config.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_capture,node_classify,node_overlay,node_hud toneBlue
class node_solve,node_manual toneAmber
class node_preview toneMint
class node_user,node_display toneIndigo
```

## Components

### Live assistant

- [Screen capture loop](https://github.com/matthewh33/minesweeper-ai/blob/main/Minesweeper.py): `Minesweeper.py`
- [Grid detection](https://github.com/matthewh33/minesweeper-ai/blob/main/Minesweeper.py): `Minesweeper.py`
- [Move overlay](https://github.com/matthewh33/minesweeper-ai/blob/main/Minesweeper.py): `Minesweeper.py`
- [Board HUD](https://github.com/matthewh33/minesweeper-ai/blob/main/Minesweeper.py): `Minesweeper.py`

### Constraint solver

- [Move inference](https://github.com/matthewh33/minesweeper-ai/blob/main/google_minesweeper_solver.py): `google_minesweeper_solver.py`
- [Manual board CLI](https://github.com/matthewh33/minesweeper-ai/blob/main/google_minesweeper_solver.py): `google_minesweeper_solver.py`

### Capture configuration

- [Capture preview](https://github.com/matthewh33/minesweeper-ai/blob/main/screen-config.py): `screen-config.py`

### Other components

- **Operator**
- **Desktop display**

## Connections

- Operator → Screen capture loop: starts and controls (evidence: `README.md`)
- Screen capture loop → Grid detection: passes frames (evidence: `Minesweeper.py`)
- Grid detection → Move inference: passes board (evidence: `Minesweeper.py`)
- Manual board CLI → Move inference: passes board (evidence: `google_minesweeper_solver.py`)
- Screen capture loop → Move overlay: draws suggestions (evidence: `Minesweeper.py`)
- Screen capture loop → Board HUD: renders status (evidence: `Minesweeper.py`)
- Move overlay → Desktop display: shows frame (evidence: `Minesweeper.py`)
- Board HUD → Desktop display: shows panel (evidence: `Minesweeper.py`)
- Capture preview → Operator: previews bounds (evidence: `screen-config.py`)