# ranasinghe843/minesweeperrl architecture

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

- Interactive diagram: https://gitdiagram.com/ranasinghe843/minesweeperrl
- Repository: https://github.com/ranasinghe843/minesweeperrl

## Overview

MinesweeperRL contains parallel Minesweeper reinforcement-learning implementations: tabular Q-learning at the repository root and under `Minesweeper_Qlearning`, plus a neural-network/replay-based variant under `MinesweeperDQN`. The principal workflow is to train from simulated games, use the learned policy to play more games, then report outcomes; the DQN runner also plots evaluation metrics. Source excerpts show the game mechanics, root Q-learning runner, and parts of the DQN path. Some DQN model wiring is only indicated by imports, so those links are marked unverified.

Main entry points: [`MinesweeperDQN/minesweeper.py`](https://github.com/ranasinghe843/minesweeperrl/blob/main/MinesweeperDQN/minesweeper.py) (DQN engine), [`MinesweeperDQN/minesweeper_qlearning.py`](https://github.com/ranasinghe843/minesweeperrl/blob/main/MinesweeperDQN/minesweeper_qlearning.py) (DQN runner), [`minesweeper_qlearning.py`](https://github.com/ranasinghe843/minesweeperrl/blob/main/minesweeper_qlearning.py) (Q-learning runner), [`Minesweeper_Qlearning/minesweeper_qlearning.py`](https://github.com/ranasinghe843/minesweeperrl/blob/main/Minesweeper_Qlearning/minesweeper_qlearning.py) (Legacy runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tabular["Tabular Q-learning"]
  node_root_cli["Q-learning runner"]
  node_root_engine["Q-learning engine<br/>[minesweeper.py]"]
  node_legacy_cli["Legacy runner"]
  node_legacy_engine["Legacy engine<br/>[minesweeper.py]"]
end

subgraph group_dqn["DQN learning"]
  node_dqn_cli["DQN runner"]
  node_dqn_engine["DQN engine<br/>[minesweeper.py]"]
  node_replay["Experience replay<br/>[ExpReplay.py]"]
  node_neuralnet["Neural network<br/>[NN1.py]"]
  node_mlp["MLP classifier<br/>[neural_network.py]"]
  node_training_data["Training data<br/>[train_data.npy]"]
  node_labels["Training labels<br/>[train_labels.npy]"]
end

subgraph group_game["Game mechanics"]
end

subgraph group_evaluation["Evaluation"]
  node_plot["Metric plots"]
  node_game_metrics["Game outcomes"]
end

node_user(("User"))

node_user -->|"runs"| node_root_cli
node_root_cli -->|"trains and plays"| node_root_engine
node_user -.->|"runs"| node_legacy_cli
node_legacy_cli -->|"trains and plays"| node_legacy_engine
node_user -->|"runs"| node_dqn_cli
node_dqn_cli -->|"trains and plays"| node_dqn_engine
node_dqn_engine -->|"stores samples"| node_replay
node_dqn_engine -->|"gets batches"| node_replay
node_dqn_engine -.->|"uses model"| node_neuralnet
node_dqn_engine -.->|"imports model"| node_mlp
node_dqn_cli -->|"plots metrics"| node_plot
node_dqn_cli -->|"computes outcomes"| node_game_metrics

click node_root_cli "https://github.com/ranasinghe843/minesweeperrl/blob/main/minesweeper_qlearning.py"
click node_root_engine "https://github.com/ranasinghe843/minesweeperrl/blob/main/minesweeper.py"
click node_legacy_cli "https://github.com/ranasinghe843/minesweeperrl/blob/main/Minesweeper_Qlearning/minesweeper_qlearning.py"
click node_legacy_engine "https://github.com/ranasinghe843/minesweeperrl/blob/main/Minesweeper_Qlearning/minesweeper.py"
click node_dqn_cli "https://github.com/ranasinghe843/minesweeperrl/blob/main/MinesweeperDQN/minesweeper_qlearning.py"
click node_dqn_engine "https://github.com/ranasinghe843/minesweeperrl/blob/main/MinesweeperDQN/minesweeper.py"
click node_replay "https://github.com/ranasinghe843/minesweeperrl/blob/main/MinesweeperDQN/ExpReplay.py"
click node_neuralnet "https://github.com/ranasinghe843/minesweeperrl/blob/main/MinesweeperDQN/NN1.py"
click node_mlp "https://github.com/ranasinghe843/minesweeperrl/blob/main/MinesweeperDQN/neural_network.py"
click node_training_data "https://github.com/ranasinghe843/minesweeperrl/blob/main/MinesweeperDQN/train_data.npy"
click node_labels "https://github.com/ranasinghe843/minesweeperrl/blob/main/MinesweeperDQN/train_labels.npy"
click node_plot "https://github.com/ranasinghe843/minesweeperrl/blob/main/MinesweeperDQN/minesweeper_qlearning.py"
click node_game_metrics "https://github.com/ranasinghe843/minesweeperrl/blob/main/MinesweeperDQN/minesweeper_qlearning.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_root_cli,node_root_engine,node_legacy_cli,node_legacy_engine,node_user toneBlue
class node_dqn_cli,node_dqn_engine,node_replay,node_neuralnet,node_mlp,node_training_data,node_labels toneAmber
class node_plot,node_game_metrics toneRose
```

## Components

### Tabular Q-learning

- [Q-learning runner](https://github.com/ranasinghe843/minesweeperrl/blob/main/minesweeper_qlearning.py): `minesweeper_qlearning.py`
- [Q-learning engine](https://github.com/ranasinghe843/minesweeperrl/blob/main/minesweeper.py): `minesweeper.py`
- [Legacy runner](https://github.com/ranasinghe843/minesweeperrl/blob/main/Minesweeper_Qlearning/minesweeper_qlearning.py): `Minesweeper_Qlearning/minesweeper_qlearning.py`
- [Legacy engine](https://github.com/ranasinghe843/minesweeperrl/blob/main/Minesweeper_Qlearning/minesweeper.py): `Minesweeper_Qlearning/minesweeper.py`

### DQN learning

- [DQN runner](https://github.com/ranasinghe843/minesweeperrl/blob/main/MinesweeperDQN/minesweeper_qlearning.py): `MinesweeperDQN/minesweeper_qlearning.py`
- [DQN engine](https://github.com/ranasinghe843/minesweeperrl/blob/main/MinesweeperDQN/minesweeper.py): `MinesweeperDQN/minesweeper.py`
- [Experience replay](https://github.com/ranasinghe843/minesweeperrl/blob/main/MinesweeperDQN/ExpReplay.py): `MinesweeperDQN/ExpReplay.py`
- [Neural network](https://github.com/ranasinghe843/minesweeperrl/blob/main/MinesweeperDQN/NN1.py): `MinesweeperDQN/NN1.py`
- [MLP classifier](https://github.com/ranasinghe843/minesweeperrl/blob/main/MinesweeperDQN/neural_network.py): `MinesweeperDQN/neural_network.py`
- [Training data](https://github.com/ranasinghe843/minesweeperrl/blob/main/MinesweeperDQN/train_data.npy): `MinesweeperDQN/train_data.npy`
- [Training labels](https://github.com/ranasinghe843/minesweeperrl/blob/main/MinesweeperDQN/train_labels.npy): `MinesweeperDQN/train_labels.npy`

### Evaluation

- [Metric plots](https://github.com/ranasinghe843/minesweeperrl/blob/main/MinesweeperDQN/minesweeper_qlearning.py): `MinesweeperDQN/minesweeper_qlearning.py`
- [Game outcomes](https://github.com/ranasinghe843/minesweeperrl/blob/main/MinesweeperDQN/minesweeper_qlearning.py): `MinesweeperDQN/minesweeper_qlearning.py`

### Other components

- **User**

## Connections

- User → Q-learning runner: runs (evidence: `minesweeper_qlearning.py`)
- Q-learning runner → Q-learning engine: trains and plays (evidence: `minesweeper_qlearning.py`)
- User → Legacy runner: runs
- Legacy runner → Legacy engine: trains and plays (evidence: `Minesweeper_Qlearning/minesweeper_qlearning.py`)
- User → DQN runner: runs (evidence: `MinesweeperDQN/minesweeper_qlearning.py`)
- DQN runner → DQN engine: trains and plays (evidence: `MinesweeperDQN/minesweeper_qlearning.py`)
- DQN engine → Experience replay: stores samples (evidence: `MinesweeperDQN/minesweeper.py`)
- DQN engine → Experience replay: gets batches (evidence: `MinesweeperDQN/minesweeper.py`)
- DQN engine → Neural network: uses model (evidence: `MinesweeperDQN/minesweeper.py`)
- DQN engine → MLP classifier: imports model (evidence: `MinesweeperDQN/minesweeper.py`)
- DQN runner → Metric plots: plots metrics (evidence: `MinesweeperDQN/minesweeper_qlearning.py`)
- DQN runner → Game outcomes: computes outcomes (evidence: `MinesweeperDQN/minesweeper_qlearning.py`)
