# yan25-06/ai-project architecture

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

- Interactive diagram: https://gitdiagram.com/yan25-06/ai-project
- Repository: https://github.com/yan25-06/ai-project

## Overview

1. **Project shape**
   - This is a Python search/solver project with two front doors: a CLI entry point in `src/main.py` and a Streamlit GUI in `src/GUI/main.py`.
   - The core application is organized around a reusable game/state model plus multiple search algorithms.

2. **Core domain layer**
   - `src/game/game.py` appears to define the problem environment and state transitions.
   - `src/GUI/state.py` likely mirrors or adapts the same state concepts for visualization.
   - This layer is the main boundary between “problem definition” and “search algorithms.”

3. **Solver subsystem**
   - `src/solver/` contains four algorithm implementations: `BFS_solver.py`, `DFS_solver.py`, `UCS_solver.py`, and `Astar_solver.py`.
   - `solver_base.py` provides the shared interface/behavior for all solvers.
   - The solvers are the main computational subsystem and likely consume game states, expand successors, and produce a path/solution trace.

4. **Solver selection / orchestration**
   - `src/helper/solver_factory.py` is the central wiring point for choosing which solver to run.
   - This factory is the architectural seam between user choice/configuration and the algorithm implementation.

5. **GUI subsystem**
   - `src/GUI/main.py` is the Streamlit app entry point.
   - `visualizer.py` handles rendering of game state and solver results.
   - `config.py` holds GUI-specific constants, and `assets/` contains UI resources.
   - The GUI is a consumer of solver outputs rather than the place where algorithms live.

6. **Precomputed solution artifacts**
   - `src/GUI/Solution/{Astar,BFS,DFS,UCS}/MAP_*.pkl` stores serialized solution data per algorithm and map.
   - These pickle files act as a data cache or dataset for the visualizer, letting the GUI display results without recomputing them every time.
   - The repeated `MAP_1.pkl` … `MAP_20.pkl` pattern suggests multiple scenarios/maps are part of the evaluation set.

7. **Input/test generation tooling**
   - `src/bin/` contains utility scripts such as `generate_next_states.py`, `gen_test_ucs.py`, and `toy.py`.
   - `Makefile`, `testcase.txt`, and `test5.txt` suggest support tooling for generating or validating search instances.
   - This folder is auxiliary infrastructure, not the main runtime path.

8. **Testing and benchmark inputs**
   - `src/test/final_testcase.txt` and `src/test/test.py` indicate a test harness or benchmark runner for solver correctness/performance.
   - The repository seems to separate generated cases, final test cases, and interactive GUI assets.

9. **Execution flow**
   - CLI flow: `src/main.py` likely loads a map/problem, asks the factory for a solver, runs the search, and emits a solution.
   - GUI flow: Streamlit loads a selected map/solution pair from the pickle artifacts and uses the visualizer to present the state sequence.
   - In both flows, the game/state model is the common contract.

10. **Dependency boundary**
   - The architecture is intentionally layered: GUI and utility scripts sit on top, solvers in the middle, and game/state definitions at the core.
   - The search algorithms should not depend on GUI code; the GUI consumes solver outputs, not the other way around.
   - That separation is important for drawing the architecture diagram: keep “problem model,” “search engines,” and “presentation” as distinct boxes.

11. **Runtime and tooling**
   - The project is pure Python, with Streamlit as the only visible UI runtime.
   - `requirements.txt` defines the Python dependencies; `packages.txt` suggests additional system packages may be needed for the environment.
   - No database or external network service is evident; persistence is file-based via text inputs and pickle outputs.

Main entry points: [`src/helper/solver_factory.py`](https://github.com/yan25-06/ai-project/blob/main/src/helper/solver_factory.py) (Solver factory), [`src/GUI/Solution`](https://github.com/yan25-06/ai-project/tree/main/src/GUI/Solution) (Solution cache), [`src/game/game.py`](https://github.com/yan25-06/ai-project/blob/main/src/game/game.py) (Game model), [`src/solver/solver_base.py`](https://github.com/yan25-06/ai-project/blob/main/src/solver/solver_base.py) (Solver base)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_core["Core domain"]
  node_node_game["Game model<br/>domain model<br/>[game.py]"]
  node_node_factory["Solver factory<br/>orchestration<br/>[solver_factory.py]"]
end

subgraph group_group_solvers["Search engines"]
  node_node_solver_base["Solver base<br/>abstract solver<br/>[solver_base.py]"]
  node_node_bfs["BFS<br/>search algorithm<br/>[BFS_solver.py]"]
  node_node_dfs["DFS<br/>search algorithm<br/>[DFS_solver.py]"]
  node_node_ucs["UCS<br/>search algorithm<br/>[UCS_solver.py]"]
  node_node_astar["A*<br/>search algorithm<br/>[Astar_solver.py]"]
end

subgraph group_group_ui["Presentation"]
  node_node_main_cli["CLI entry<br/>python entrypoint<br/>[main.py]"]
  node_node_gui_main["GUI entry<br/>streamlit app<br/>[main.py]"]
  node_node_visualizer["Visualizer<br/>rendering<br/>[visualizer.py]"]
  node_node_gui_state["GUI state<br/>ui model<br/>[state.py]"]
  node_node_gui_config["UI config<br/>settings<br/>[config.py]"]
end

subgraph group_group_data["Artifacts"]
  node_node_pickle_cache[("Solution cache<br/>serialized results")]
  node_node_astar_cache[("A* cache<br/>pickle dataset")]
  node_node_bfs_cache[("BFS cache<br/>pickle dataset")]
  node_node_dfs_cache[("DFS cache<br/>pickle dataset")]
  node_node_ucs_cache[("UCS cache<br/>pickle dataset")]
end

subgraph group_group_tools["Tooling"]
  node_node_bin_tools["Bin tools<br/>utility scripts"]
  node_node_testcases["Test inputs<br/>benchmark data"]
end

node_node_main_cli -->|"selects solver"| node_node_factory
node_node_factory -->|"creates"| node_node_bfs
node_node_factory -->|"creates"| node_node_dfs
node_node_factory -->|"creates"| node_node_ucs
node_node_factory -->|"creates"| node_node_astar
node_node_bfs -->|"extends"| node_node_solver_base
node_node_dfs -->|"extends"| node_node_solver_base
node_node_ucs -->|"extends"| node_node_solver_base
node_node_astar -->|"extends"| node_node_solver_base
node_node_solver_base -->|"expands"| node_node_game
node_node_game -->|"loads problem"| node_node_main_cli
node_node_gui_main -->|"drives"| node_node_visualizer
node_node_gui_main -->|"uses"| node_node_gui_config
node_node_visualizer -->|"renders"| node_node_gui_state
node_node_visualizer -->|"loads traces"| node_node_pickle_cache
node_node_pickle_cache -->|"contains"| node_node_astar_cache
node_node_pickle_cache -->|"contains"| node_node_bfs_cache
node_node_pickle_cache -->|"contains"| node_node_dfs_cache
node_node_pickle_cache -->|"contains"| node_node_ucs_cache
node_node_bin_tools -->|"generates states"| node_node_game
node_node_bin_tools -->|"validates against"| node_node_testcases
node_node_testcases -->|"defines instances"| node_node_game
node_node_gui_state -->|"adapts"| node_node_game

click node_node_main_cli "https://github.com/yan25-06/ai-project/blob/main/src/main.py"
click node_node_gui_main "https://github.com/yan25-06/ai-project/blob/main/src/GUI/main.py"
click node_node_visualizer "https://github.com/yan25-06/ai-project/blob/main/src/GUI/visualizer.py"
click node_node_gui_state "https://github.com/yan25-06/ai-project/blob/main/src/GUI/state.py"
click node_node_gui_config "https://github.com/yan25-06/ai-project/blob/main/src/GUI/config.py"
click node_node_game "https://github.com/yan25-06/ai-project/blob/main/src/game/game.py"
click node_node_factory "https://github.com/yan25-06/ai-project/blob/main/src/helper/solver_factory.py"
click node_node_solver_base "https://github.com/yan25-06/ai-project/blob/main/src/solver/solver_base.py"
click node_node_bfs "https://github.com/yan25-06/ai-project/blob/main/src/solver/BFS_solver.py"
click node_node_dfs "https://github.com/yan25-06/ai-project/blob/main/src/solver/DFS_solver.py"
click node_node_ucs "https://github.com/yan25-06/ai-project/blob/main/src/solver/UCS_solver.py"
click node_node_astar "https://github.com/yan25-06/ai-project/blob/main/src/solver/Astar_solver.py"
click node_node_pickle_cache "https://github.com/yan25-06/ai-project/tree/main/src/GUI/Solution"
click node_node_astar_cache "https://github.com/yan25-06/ai-project/tree/main/src/GUI/Solution/Astar"
click node_node_bfs_cache "https://github.com/yan25-06/ai-project/tree/main/src/GUI/Solution/BFS"
click node_node_dfs_cache "https://github.com/yan25-06/ai-project/tree/main/src/GUI/Solution/DFS"
click node_node_ucs_cache "https://github.com/yan25-06/ai-project/tree/main/src/GUI/Solution/UCS"
click node_node_bin_tools "https://github.com/yan25-06/ai-project/tree/main/src/bin"
click node_node_testcases "https://github.com/yan25-06/ai-project/tree/main/src/test"

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_node_game,node_node_factory toneBlue
class node_node_solver_base,node_node_bfs,node_node_dfs,node_node_ucs,node_node_astar toneAmber
class node_node_main_cli,node_node_gui_main,node_node_visualizer,node_node_gui_state,node_node_gui_config toneMint
class node_node_pickle_cache,node_node_astar_cache,node_node_bfs_cache,node_node_dfs_cache,node_node_ucs_cache toneRose
class node_node_bin_tools,node_node_testcases toneIndigo
```

## Components

### Core domain

Problem model and shared state contract

- [Game model](https://github.com/yan25-06/ai-project/blob/main/src/game/game.py): domain model · Problem environment and transitions · `src/game/game.py`
- [Solver factory](https://github.com/yan25-06/ai-project/blob/main/src/helper/solver_factory.py): orchestration · Selects and wires the requested solver · `src/helper/solver_factory.py`

### Search engines

Reusable search algorithm implementations

- [Solver base](https://github.com/yan25-06/ai-project/blob/main/src/solver/solver_base.py): abstract solver · Shared solver interface and behavior · `src/solver/solver_base.py`
- [BFS](https://github.com/yan25-06/ai-project/blob/main/src/solver/BFS_solver.py): search algorithm · Breadth-first search implementation · `src/solver/BFS_solver.py`
- [DFS](https://github.com/yan25-06/ai-project/blob/main/src/solver/DFS_solver.py): search algorithm · Depth-first search implementation · `src/solver/DFS_solver.py`
- [UCS](https://github.com/yan25-06/ai-project/blob/main/src/solver/UCS_solver.py): search algorithm · Uniform-cost search implementation · `src/solver/UCS_solver.py`
- [A*](https://github.com/yan25-06/ai-project/blob/main/src/solver/Astar_solver.py): search algorithm · Heuristic search implementation · `src/solver/Astar_solver.py`

### Presentation

CLI and Streamlit front doors plus visualization

- [CLI entry](https://github.com/yan25-06/ai-project/blob/main/src/main.py): python entrypoint · Starts command-line solving flow · `src/main.py`
- [GUI entry](https://github.com/yan25-06/ai-project/blob/main/src/GUI/main.py): streamlit app · Starts the Streamlit interface · `src/GUI/main.py`
- [Visualizer](https://github.com/yan25-06/ai-project/blob/main/src/GUI/visualizer.py): rendering · Renders states and solution traces · `src/GUI/visualizer.py`
- [GUI state](https://github.com/yan25-06/ai-project/blob/main/src/GUI/state.py): ui model · Presentation-side state representation · `src/GUI/state.py`
- [UI config](https://github.com/yan25-06/ai-project/blob/main/src/GUI/config.py): settings · GUI constants and display settings · `src/GUI/config.py`

### Artifacts

Precomputed solution caches used by the GUI

- [Solution cache](https://github.com/yan25-06/ai-project/tree/main/src/GUI/Solution): serialized results · Precomputed solver traces for GUI playback · `src/GUI/Solution`
- [A* cache](https://github.com/yan25-06/ai-project/tree/main/src/GUI/Solution/Astar): pickle dataset · Saved A* solutions for multiple maps · `src/GUI/Solution/Astar`
- [BFS cache](https://github.com/yan25-06/ai-project/tree/main/src/GUI/Solution/BFS): pickle dataset · Saved BFS solutions for multiple maps · `src/GUI/Solution/BFS`
- [DFS cache](https://github.com/yan25-06/ai-project/tree/main/src/GUI/Solution/DFS): pickle dataset · Saved DFS solutions for multiple maps · `src/GUI/Solution/DFS`
- [UCS cache](https://github.com/yan25-06/ai-project/tree/main/src/GUI/Solution/UCS): pickle dataset · Saved UCS solutions for multiple maps · `src/GUI/Solution/UCS`

### Tooling

Scripts and test inputs for generation and validation

- [Bin tools](https://github.com/yan25-06/ai-project/tree/main/src/bin): utility scripts · State generation and solver test helpers · `src/bin`
- [Test inputs](https://github.com/yan25-06/ai-project/tree/main/src/test): benchmark data · Text fixtures for solver validation · `src/test`

## Connections

- CLI entry → Solver factory: selects solver · CLI delegates solver choice and execution
- Solver factory → BFS: creates · Factory can instantiate BFS
- Solver factory → DFS: creates · Factory can instantiate DFS
- Solver factory → UCS: creates · Factory can instantiate UCS
- Solver factory → A*: creates · Factory can instantiate A*
- BFS → Solver base: extends · BFS follows shared solver contract
- DFS → Solver base: extends · DFS follows shared solver contract
- UCS → Solver base: extends · UCS follows shared solver contract
- A* → Solver base: extends · A* follows shared solver contract
- Solver base → Game model: expands · Solvers consume game states and successor generation
- Game model → CLI entry: loads problem · CLI operates on the domain model
- GUI entry → Visualizer: drives · Streamlit entry renders the interface
- GUI entry → UI config: uses · GUI entry reads presentation settings
- Visualizer → GUI state: renders · Visualizer consumes UI state objects
- Visualizer → Solution cache: loads traces · Visualizer reads serialized solution artifacts
- Solution cache → A* cache: contains · Grouped cache for A*
- Solution cache → BFS cache: contains · Grouped cache for BFS
- Solution cache → DFS cache: contains · Grouped cache for DFS
- Solution cache → UCS cache: contains · Grouped cache for UCS
- Bin tools → Game model: generates states · Utility scripts help build or inspect search instances
- Bin tools → Test inputs: validates against · Scripts and harnesses use benchmark inputs
- Test inputs → Game model: defines instances · Test fixtures provide problem setups
- GUI state → Game model: adapts · UI state mirrors the core domain model
