# dimizorgon/tetris_rl architecture

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

- Interactive diagram: https://gitdiagram.com/dimizorgon/tetris_rl
- Repository: https://github.com/dimizorgon/tetris_rl

## Overview

This repository is a playable Tetris game with a DQN-based training workflow and an ONNX inference mode. The human workflow runs through the menu and game loop; the AI workflow generates candidate placements, evaluates them, and applies the chosen move in the same game environment. Training saves model checkpoints and episode metrics, which can be plotted separately. Source excerpts support the main calls and data flows; the README is empty, so no additional capabilities are documented.

Main entry points: [`env.py`](https://github.com/dimizorgon/tetris_rl/blob/main/env.py) (Tetris Environment), [`play_npu.py`](https://github.com/dimizorgon/tetris_rl/blob/main/play_npu.py) (ONNX Player), [`agent.py`](https://github.com/dimizorgon/tetris_rl/blob/main/agent.py) (DQN Agent), [`game.py`](https://github.com/dimizorgon/tetris_rl/blob/main/game.py) (Game State)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gameplay["Tetris Gameplay"]
  node_game_loop["Game Loop<br/>[main.py]"]
  node_game_state["Game State<br/>[game.py]"]
  node_pieces["Tetrominoes<br/>[tetromino.py]"]
  node_rules["Game Settings<br/>[settings.py]"]
end

subgraph group_ai["AI Environment"]
  node_environment["Tetris Environment<br/>[env.py]"]
  node_placement_features["Placement Features<br/>[env.py]"]
end

subgraph group_training["Training"]
  node_dqn_agent["DQN Agent<br/>[agent.py]"]
  node_checkpoint["Model Checkpoints"]
  node_training_log["Training Log<br/>[training_log.csv]"]
end

subgraph group_inference["ONNX Inference"]
  node_onnx_runner["ONNX Player<br/>[play_npu.py]"]
  node_onnx_model["ONNX Model"]
  node_onnx_runtime["ONNX Runtime"]
end

subgraph group_analytics["Metrics"]
  node_metric_plots["Metric Plots<br/>[plot_metrics.py]"]
end

node_player(("Player"))

node_player -->|"controls"| node_game_loop
node_game_loop -->|"updates"| node_game_state
node_game_loop -->|"draws ghost"| node_pieces
node_game_state -->|"creates pieces"| node_pieces
node_game_state -->|"uses settings"| node_rules
node_environment -->|"steps game"| node_game_state
node_environment -->|"enumerates shapes"| node_pieces
node_environment -->|"uses dimensions"| node_rules
node_environment -->|"extracts features"| node_placement_features
node_dqn_agent -->|"trains in"| node_environment
node_dqn_agent -->|"saves weights"| node_checkpoint
node_dqn_agent -->|"appends metrics"| node_training_log
node_onnx_runner -->|"plays through"| node_environment
node_onnx_runner -->|"imports DQN"| node_dqn_agent
node_onnx_runner -->|"converts weights"| node_checkpoint
node_onnx_runner -->|"exports model"| node_onnx_model
node_onnx_runner -->|"runs inference"| node_onnx_runtime
node_onnx_runtime -->|"loads model"| node_onnx_model
node_metric_plots -->|"reads metrics"| node_training_log

click node_game_loop "https://github.com/dimizorgon/tetris_rl/blob/main/main.py"
click node_game_state "https://github.com/dimizorgon/tetris_rl/blob/main/game.py"
click node_pieces "https://github.com/dimizorgon/tetris_rl/blob/main/tetromino.py"
click node_rules "https://github.com/dimizorgon/tetris_rl/blob/main/settings.py"
click node_environment "https://github.com/dimizorgon/tetris_rl/blob/main/env.py"
click node_placement_features "https://github.com/dimizorgon/tetris_rl/blob/main/env.py"
click node_dqn_agent "https://github.com/dimizorgon/tetris_rl/blob/main/agent.py"
click node_checkpoint "https://github.com/dimizorgon/tetris_rl/blob/main/tetris_ai_model_BEST.pth"
click node_training_log "https://github.com/dimizorgon/tetris_rl/blob/main/training_log.csv"
click node_onnx_runner "https://github.com/dimizorgon/tetris_rl/blob/main/play_npu.py"
click node_onnx_model "https://github.com/dimizorgon/tetris_rl/blob/main/tetris_agent_optimized.onnx"
click node_metric_plots "https://github.com/dimizorgon/tetris_rl/blob/main/plot_metrics.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_game_loop,node_game_state,node_pieces,node_rules toneBlue
class node_environment,node_placement_features toneAmber
class node_dqn_agent,node_checkpoint,node_training_log toneMint
class node_onnx_runner,node_onnx_model,node_onnx_runtime toneRose
class node_metric_plots,node_player toneIndigo
```

## Components

### Tetris Gameplay

- [Game Loop](https://github.com/dimizorgon/tetris_rl/blob/main/main.py): `main.py`
- [Game State](https://github.com/dimizorgon/tetris_rl/blob/main/game.py): `game.py`
- [Tetrominoes](https://github.com/dimizorgon/tetris_rl/blob/main/tetromino.py): `tetromino.py`
- [Game Settings](https://github.com/dimizorgon/tetris_rl/blob/main/settings.py): `settings.py`

### AI Environment

- [Tetris Environment](https://github.com/dimizorgon/tetris_rl/blob/main/env.py): `env.py`
- [Placement Features](https://github.com/dimizorgon/tetris_rl/blob/main/env.py): `env.py`

### Training

- [DQN Agent](https://github.com/dimizorgon/tetris_rl/blob/main/agent.py): `agent.py`
- [Model Checkpoints](https://github.com/dimizorgon/tetris_rl/blob/main/tetris_ai_model_BEST.pth): `tetris_ai_model_BEST.pth`
- [Training Log](https://github.com/dimizorgon/tetris_rl/blob/main/training_log.csv): `training_log.csv`

### ONNX Inference

- [ONNX Player](https://github.com/dimizorgon/tetris_rl/blob/main/play_npu.py): `play_npu.py`
- [ONNX Model](https://github.com/dimizorgon/tetris_rl/blob/main/tetris_agent_optimized.onnx): `tetris_agent_optimized.onnx`
- **ONNX Runtime**

### Metrics

- [Metric Plots](https://github.com/dimizorgon/tetris_rl/blob/main/plot_metrics.py): `plot_metrics.py`

### Other components

- **Player**

## Connections

- Player → Game Loop: controls (evidence: `main.py`)
- Game Loop → Game State: updates (evidence: `main.py`)
- Game Loop → Tetrominoes: draws ghost (evidence: `main.py`)
- Game State → Tetrominoes: creates pieces (evidence: `game.py`)
- Game State → Game Settings: uses settings (evidence: `game.py`)
- Tetris Environment → Game State: steps game (evidence: `env.py`)
- Tetris Environment → Tetrominoes: enumerates shapes (evidence: `env.py`)
- Tetris Environment → Game Settings: uses dimensions (evidence: `env.py`)
- Tetris Environment → Placement Features: extracts features (evidence: `env.py`)
- DQN Agent → Tetris Environment: trains in (evidence: `agent.py`)
- DQN Agent → Model Checkpoints: saves weights (evidence: `agent.py`)
- DQN Agent → Training Log: appends metrics (evidence: `agent.py`)
- ONNX Player → Tetris Environment: plays through (evidence: `play_npu.py`)
- ONNX Player → DQN Agent: imports DQN (evidence: `play_npu.py`)
- ONNX Player → Model Checkpoints: converts weights (evidence: `play_npu.py`)
- ONNX Player → ONNX Model: exports model (evidence: `play_npu.py`)
- ONNX Player → ONNX Runtime: runs inference (evidence: `play_npu.py`)
- ONNX Runtime → ONNX Model: loads model
- Metric Plots → Training Log: reads metrics (evidence: `plot_metrics.py`)
