# huytothevoz/ai_midterm architecture

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

- Interactive diagram: https://gitdiagram.com/huytothevoz/ai_midterm
- Repository: https://github.com/huytothevoz/ai_midterm

## Overview

This is an educational Sokoban AI project: a command-line menu exposes single-agent solving, search benchmarks and heuristic checks, plus competitive agents and graphical play. The main workflow is user → menu → selected runner or UI → game model/search or agents → displayed solution, score or verification results. Separate branches cover single-agent mechanics, evaluation, competitive play and interfaces. Relationships are limited to calls or dependencies visible in the supplied excerpts, SOURCE INDEX, or explicit code references; unsampled implementation details are not inferred.

Main entry points: [`main.py`](https://github.com/huytothevoz/ai_midterm/blob/main/main.py) (CLI Entrypoint), [`Ex6/game_logic_competitive.py`](https://github.com/huytothevoz/ai_midterm/blob/main/Ex6/game_logic_competitive.py) (Competitive Rules), [`Ex1/game_logic.py`](https://github.com/huytothevoz/ai_midterm/blob/main/Ex1/game_logic.py) (Single-Agent Rules), [`Ex7/agent_utils.py`](https://github.com/huytothevoz/ai_midterm/blob/main/Ex7/agent_utils.py) (Agent Search Helpers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_single["Single-Agent Sokoban"]
  node_game["Single-Agent Rules<br/>[game_logic.py]"]
  node_search["UCS and A*"]
end

subgraph group_analysis["Search Evaluation"]
  node_benchmark["Search Benchmarks<br/>[experiments.py]"]
  node_verify["Heuristic Verification"]
  node_verification_output["Verification Results"]
end

subgraph group_competitive["Competitive Play"]
  node_competitive_game["Competitive Rules"]
  node_agent1["Agent 1 GBFS<br/>[agent1.py]"]
  node_agent2["Agent 2 A*<br/>[agent2.py]"]
  node_agent_utils["Agent Search Helpers<br/>[agent_utils.py]"]
  node_match_runner["Match Runner<br/>[run_competitive.py]"]
end

subgraph group_interfaces["User Interfaces"]
  node_menu["Visual Menu<br/>[menu_ui.py]"]
  node_single_ui["Single-Agent GUI<br/>[sokoban_ui.py]"]
  node_ui_base["Shared UI Components<br/>[ui_components.py]"]
  node_competitive_ui["Competitive GUI<br/>[competitive_ui.py]"]
end

subgraph group_control["Application Control"]
  node_main["CLI Entrypoint<br/>[main.py]"]
end

node_user(("User"))

node_user -->|"selects feature"| node_main
node_main -->|"opens menu"| node_menu
node_main -->|"runs requirement"| node_game
node_main -->|"runs requirement"| node_search
node_main -->|"runs benchmark"| node_benchmark
node_main -->|"runs verification"| node_verify
node_main -->|"opens GUI"| node_single_ui
node_main -->|"runs demo"| node_competitive_game
node_main -->|"runs match"| node_match_runner
node_main -->|"opens GUI"| node_competitive_ui
node_menu -->|"opens GUI"| node_single_ui
node_menu -->|"opens GUI"| node_competitive_ui
node_benchmark -->|"creates game"| node_game
node_benchmark -->|"runs searches"| node_search
node_verify -->|"enumerates states"| node_game
node_verify -->|"checks heuristic"| node_search
node_verify -->|"writes results"| node_verification_output
node_single_ui -->|"creates game"| node_game
node_single_ui -->|"runs solver"| node_search
node_single_ui -->|"extends base"| node_ui_base
node_competitive_game -->|"reuses helpers"| node_game
node_agent1 -->|"simulates moves"| node_competitive_game
node_agent1 -->|"uses helpers"| node_agent_utils
node_agent2 -->|"simulates moves"| node_competitive_game
node_agent2 -->|"uses helpers"| node_agent_utils
node_agent_utils -->|"simulates actions"| node_competitive_game
node_agent_utils -->|"uses directions"| node_game
node_agent_utils -->|"uses distance helper"| node_search
node_match_runner -->|"creates game"| node_competitive_game
node_match_runner -->|"requests action"| node_agent1
node_match_runner -->|"requests action"| node_agent2
node_competitive_ui -->|"creates game"| node_competitive_game
node_competitive_ui -->|"extends base"| node_ui_base

click node_main "https://github.com/huytothevoz/ai_midterm/blob/main/main.py"
click node_menu "https://github.com/huytothevoz/ai_midterm/blob/main/menu_ui.py"
click node_game "https://github.com/huytothevoz/ai_midterm/blob/main/Ex1/game_logic.py"
click node_search "https://github.com/huytothevoz/ai_midterm/blob/main/Ex2/search_algorithms.py"
click node_benchmark "https://github.com/huytothevoz/ai_midterm/blob/main/Ex3/experiments.py"
click node_verify "https://github.com/huytothevoz/ai_midterm/blob/main/Ex4/verify_heuristic.py"
click node_verification_output "https://github.com/huytothevoz/ai_midterm/blob/main/Ex4/heuristic_verification.csv"
click node_single_ui "https://github.com/huytothevoz/ai_midterm/blob/main/Ex5/sokoban_ui.py"
click node_ui_base "https://github.com/huytothevoz/ai_midterm/blob/main/Ex5/ui_components.py"
click node_competitive_game "https://github.com/huytothevoz/ai_midterm/blob/main/Ex6/game_logic_competitive.py"
click node_agent1 "https://github.com/huytothevoz/ai_midterm/blob/main/Ex7/agent1.py"
click node_agent2 "https://github.com/huytothevoz/ai_midterm/blob/main/Ex7/agent2.py"
click node_agent_utils "https://github.com/huytothevoz/ai_midterm/blob/main/Ex7/agent_utils.py"
click node_match_runner "https://github.com/huytothevoz/ai_midterm/blob/main/Ex7/run_competitive.py"
click node_competitive_ui "https://github.com/huytothevoz/ai_midterm/blob/main/Ex8/competitive_ui.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,node_search,node_user toneBlue
class node_benchmark,node_verify,node_verification_output toneAmber
class node_competitive_game,node_agent1,node_agent2,node_agent_utils,node_match_runner toneMint
class node_menu,node_single_ui,node_ui_base,node_competitive_ui toneRose
class node_main toneIndigo
```

## Components

### Single-Agent Sokoban

- [Single-Agent Rules](https://github.com/huytothevoz/ai_midterm/blob/main/Ex1/game_logic.py): `Ex1/game_logic.py`
- [UCS and A*](https://github.com/huytothevoz/ai_midterm/blob/main/Ex2/search_algorithms.py): `Ex2/search_algorithms.py`

### Search Evaluation

- [Search Benchmarks](https://github.com/huytothevoz/ai_midterm/blob/main/Ex3/experiments.py): `Ex3/experiments.py`
- [Heuristic Verification](https://github.com/huytothevoz/ai_midterm/blob/main/Ex4/verify_heuristic.py): `Ex4/verify_heuristic.py`
- [Verification Results](https://github.com/huytothevoz/ai_midterm/blob/main/Ex4/heuristic_verification.csv): `Ex4/heuristic_verification.csv`

### Competitive Play

- [Competitive Rules](https://github.com/huytothevoz/ai_midterm/blob/main/Ex6/game_logic_competitive.py): `Ex6/game_logic_competitive.py`
- [Agent 1 GBFS](https://github.com/huytothevoz/ai_midterm/blob/main/Ex7/agent1.py): `Ex7/agent1.py`
- [Agent 2 A*](https://github.com/huytothevoz/ai_midterm/blob/main/Ex7/agent2.py): `Ex7/agent2.py`
- [Agent Search Helpers](https://github.com/huytothevoz/ai_midterm/blob/main/Ex7/agent_utils.py): `Ex7/agent_utils.py`
- [Match Runner](https://github.com/huytothevoz/ai_midterm/blob/main/Ex7/run_competitive.py): `Ex7/run_competitive.py`

### User Interfaces

- [Visual Menu](https://github.com/huytothevoz/ai_midterm/blob/main/menu_ui.py): `menu_ui.py`
- [Single-Agent GUI](https://github.com/huytothevoz/ai_midterm/blob/main/Ex5/sokoban_ui.py): `Ex5/sokoban_ui.py`
- [Shared UI Components](https://github.com/huytothevoz/ai_midterm/blob/main/Ex5/ui_components.py): `Ex5/ui_components.py`
- [Competitive GUI](https://github.com/huytothevoz/ai_midterm/blob/main/Ex8/competitive_ui.py): `Ex8/competitive_ui.py`

### Application Control

- [CLI Entrypoint](https://github.com/huytothevoz/ai_midterm/blob/main/main.py): `main.py`

### Other components

- **User**

## Connections

- User → CLI Entrypoint: selects feature (evidence: `main.py`)
- CLI Entrypoint → Visual Menu: opens menu (evidence: `main.py`)
- CLI Entrypoint → Single-Agent Rules: runs requirement (evidence: `main.py`)
- CLI Entrypoint → UCS and A*: runs requirement (evidence: `main.py`)
- CLI Entrypoint → Search Benchmarks: runs benchmark (evidence: `main.py`)
- CLI Entrypoint → Heuristic Verification: runs verification (evidence: `main.py`)
- CLI Entrypoint → Single-Agent GUI: opens GUI (evidence: `main.py`)
- CLI Entrypoint → Competitive Rules: runs demo (evidence: `main.py`)
- CLI Entrypoint → Match Runner: runs match (evidence: `main.py`)
- CLI Entrypoint → Competitive GUI: opens GUI (evidence: `main.py`)
- Visual Menu → Single-Agent GUI: opens GUI (evidence: `menu_ui.py`)
- Visual Menu → Competitive GUI: opens GUI (evidence: `menu_ui.py`)
- Search Benchmarks → Single-Agent Rules: creates game (evidence: `Ex3/experiments.py`)
- Search Benchmarks → UCS and A*: runs searches (evidence: `Ex3/experiments.py`)
- Heuristic Verification → Single-Agent Rules: enumerates states (evidence: `Ex4/verify_heuristic.py`)
- Heuristic Verification → UCS and A*: checks heuristic (evidence: `Ex4/verify_heuristic.py`)
- Heuristic Verification → Verification Results: writes results (evidence: `Ex4/verify_heuristic.py`)
- Single-Agent GUI → Single-Agent Rules: creates game (evidence: `Ex5/sokoban_ui.py`)
- Single-Agent GUI → UCS and A*: runs solver (evidence: `Ex5/sokoban_ui.py`)
- Single-Agent GUI → Shared UI Components: extends base (evidence: `Ex5/sokoban_ui.py`)
- Competitive Rules → Single-Agent Rules: reuses helpers (evidence: `Ex6/game_logic_competitive.py`)
- Agent 1 GBFS → Competitive Rules: simulates moves (evidence: `Ex7/agent1.py`)
- Agent 1 GBFS → Agent Search Helpers: uses helpers (evidence: `Ex7/agent1.py`)
- Agent 2 A* → Competitive Rules: simulates moves (evidence: `Ex7/agent2.py`)
- Agent 2 A* → Agent Search Helpers: uses helpers (evidence: `Ex7/agent2.py`)
- Agent Search Helpers → Competitive Rules: simulates actions (evidence: `Ex7/agent_utils.py`)
- Agent Search Helpers → Single-Agent Rules: uses directions (evidence: `Ex7/agent_utils.py`)
- Agent Search Helpers → UCS and A*: uses distance helper (evidence: `Ex7/agent_utils.py`)
- Match Runner → Competitive Rules: creates game (evidence: `Ex7/run_competitive.py`)
- Match Runner → Agent 1 GBFS: requests action (evidence: `Ex7/run_competitive.py`)
- Match Runner → Agent 2 A*: requests action (evidence: `Ex7/run_competitive.py`)
- Competitive GUI → Competitive Rules: creates game (evidence: `Ex8/competitive_ui.py`)
- Competitive GUI → Shared UI Components: extends base (evidence: `Ex8/competitive_ui.py`)