# hazardsnow/deepcore-ai architecture

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

- Interactive diagram: https://gitdiagram.com/hazardsnow/deepcore-ai
- Repository: https://github.com/hazardsnow/deepcore-ai

## Overview

DeepCore is a student-facing AI search assignment about rescuing miners in a mine. The main workflow is to choose a built-in or custom map and algorithm, construct the search environment, run a search, and inspect its solution and metrics in the CLI or graphical workbench. The runtime also supports heuristic comparisons and benchmark tables. The source excerpts establish the main dispatch and search/environment responsibilities; detailed wiring inside unsampled portions of the GUI and algorithms is not expanded.

Main entry points: [`src/deepcore/__main__.py`](https://github.com/hazardsnow/deepcore-ai/blob/main/src/deepcore/__main__.py) (CLI and GUI dispatcher), [`src/deepcore/environment.py`](https://github.com/hazardsnow/deepcore-ai/blob/main/src/deepcore/environment.py) (Mine environment), [`src/deepcore/state.py`](https://github.com/hazardsnow/deepcore-ai/blob/main/src/deepcore/state.py) (State and metrics), [`src/deepcore/solver.py`](https://github.com/hazardsnow/deepcore-ai/blob/main/src/deepcore/solver.py) (Heuristic searches)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and orchestration"]
  node_launcher["Root launcher<br/>[main.py]"]
  node_dispatcher["CLI and GUI dispatcher<br/>[__main__.py]"]
end

subgraph group_problem["Search problem model"]
  node_environment["Mine environment<br/>[environment.py]"]
  node_state["State and metrics<br/>[state.py]"]
end

subgraph group_search["Search and presentation"]
  node_uninformed["Uninformed searches<br/>[solver.py]"]
  node_bidirectional["Bidirectional search<br/>[solver.py]"]
  node_costsearch["Cost-based searches<br/>[solver.py]"]
  node_heuristicsearch["Heuristic searches<br/>[solver.py]"]
  node_heuristics["Heuristic functions<br/>[heuristics.py]"]
  node_verification["Solution verification<br/>[__main__.py]"]
  node_benchmark["Benchmark runner<br/>[__main__.py]"]
  node_workbench["Graphical workbench<br/>[visualizer.py]"]
end

node_student(("Student"))

node_student -->|"starts app"| node_launcher
node_launcher -->|"forwards CLI"| node_dispatcher
node_launcher -->|"loads demo map"| node_environment
node_dispatcher -->|"loads map"| node_environment
node_dispatcher -->|"dispatches search"| node_uninformed
node_dispatcher -->|"dispatches search"| node_bidirectional
node_dispatcher -->|"dispatches search"| node_costsearch
node_dispatcher -->|"dispatches search"| node_heuristicsearch
node_dispatcher -->|"registers functions"| node_heuristics
node_dispatcher -->|"verifies solution"| node_verification
node_dispatcher -->|"runs suite"| node_benchmark
node_dispatcher -->|"opens GUI"| node_workbench
node_uninformed -->|"requests successors"| node_environment
node_bidirectional -->|"requests predecessors"| node_environment
node_costsearch -->|"requests successors"| node_environment
node_heuristicsearch -->|"requests successors"| node_environment
node_heuristicsearch -->|"evaluates states"| node_heuristics
node_environment -->|"creates states"| node_state
node_uninformed -->|"returns metrics"| node_state
node_bidirectional -->|"returns metrics"| node_state
node_costsearch -->|"returns metrics"| node_state
node_heuristicsearch -->|"returns metrics"| node_state
node_verification -->|"replays actions"| node_environment
node_workbench -->|"renders map"| node_environment
node_workbench -->|"invokes runner"| node_dispatcher
node_workbench -->|"displays metrics"| node_state

click node_launcher "https://github.com/hazardsnow/deepcore-ai/blob/main/main.py"
click node_dispatcher "https://github.com/hazardsnow/deepcore-ai/blob/main/src/deepcore/__main__.py"
click node_environment "https://github.com/hazardsnow/deepcore-ai/blob/main/src/deepcore/environment.py"
click node_state "https://github.com/hazardsnow/deepcore-ai/blob/main/src/deepcore/state.py"
click node_uninformed "https://github.com/hazardsnow/deepcore-ai/blob/main/src/deepcore/solver.py"
click node_bidirectional "https://github.com/hazardsnow/deepcore-ai/blob/main/src/deepcore/solver.py"
click node_costsearch "https://github.com/hazardsnow/deepcore-ai/blob/main/src/deepcore/solver.py"
click node_heuristicsearch "https://github.com/hazardsnow/deepcore-ai/blob/main/src/deepcore/solver.py"
click node_heuristics "https://github.com/hazardsnow/deepcore-ai/blob/main/src/deepcore/heuristics.py"
click node_verification "https://github.com/hazardsnow/deepcore-ai/blob/main/src/deepcore/__main__.py"
click node_benchmark "https://github.com/hazardsnow/deepcore-ai/blob/main/src/deepcore/__main__.py"
click node_workbench "https://github.com/hazardsnow/deepcore-ai/blob/main/src/deepcore/visualizer.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_launcher,node_dispatcher toneBlue
class node_environment,node_state toneAmber
class node_uninformed,node_bidirectional,node_costsearch,node_heuristicsearch,node_heuristics,node_verification,node_benchmark,node_workbench toneMint
class node_student toneIndigo
```

## Components

### Entry and orchestration

- [Root launcher](https://github.com/hazardsnow/deepcore-ai/blob/main/main.py): `main.py`
- [CLI and GUI dispatcher](https://github.com/hazardsnow/deepcore-ai/blob/main/src/deepcore/__main__.py): `src/deepcore/__main__.py`

### Search problem model

- [Mine environment](https://github.com/hazardsnow/deepcore-ai/blob/main/src/deepcore/environment.py): `src/deepcore/environment.py`
- [State and metrics](https://github.com/hazardsnow/deepcore-ai/blob/main/src/deepcore/state.py): `src/deepcore/state.py`

### Search and presentation

- [Uninformed searches](https://github.com/hazardsnow/deepcore-ai/blob/main/src/deepcore/solver.py): `src/deepcore/solver.py`
- [Bidirectional search](https://github.com/hazardsnow/deepcore-ai/blob/main/src/deepcore/solver.py): `src/deepcore/solver.py`
- [Cost-based searches](https://github.com/hazardsnow/deepcore-ai/blob/main/src/deepcore/solver.py): `src/deepcore/solver.py`
- [Heuristic searches](https://github.com/hazardsnow/deepcore-ai/blob/main/src/deepcore/solver.py): `src/deepcore/solver.py`
- [Heuristic functions](https://github.com/hazardsnow/deepcore-ai/blob/main/src/deepcore/heuristics.py): `src/deepcore/heuristics.py`
- [Solution verification](https://github.com/hazardsnow/deepcore-ai/blob/main/src/deepcore/__main__.py): `src/deepcore/__main__.py`
- [Benchmark runner](https://github.com/hazardsnow/deepcore-ai/blob/main/src/deepcore/__main__.py): `src/deepcore/__main__.py`
- [Graphical workbench](https://github.com/hazardsnow/deepcore-ai/blob/main/src/deepcore/visualizer.py): `src/deepcore/visualizer.py`

### Other components

- **Student**

## Connections

- Student → Root launcher: starts app (evidence: `README.md`)
- Root launcher → CLI and GUI dispatcher: forwards CLI (evidence: `main.py`)
- Root launcher → Mine environment: loads demo map (evidence: `main.py`)
- CLI and GUI dispatcher → Mine environment: loads map (evidence: `src/deepcore/__main__.py`)
- CLI and GUI dispatcher → Uninformed searches: dispatches search (evidence: `src/deepcore/__main__.py`)
- CLI and GUI dispatcher → Bidirectional search: dispatches search (evidence: `src/deepcore/__main__.py`)
- CLI and GUI dispatcher → Cost-based searches: dispatches search (evidence: `src/deepcore/__main__.py`)
- CLI and GUI dispatcher → Heuristic searches: dispatches search (evidence: `src/deepcore/__main__.py`)
- CLI and GUI dispatcher → Heuristic functions: registers functions (evidence: `src/deepcore/__main__.py`)
- CLI and GUI dispatcher → Solution verification: verifies solution (evidence: `src/deepcore/__main__.py`)
- CLI and GUI dispatcher → Benchmark runner: runs suite (evidence: `src/deepcore/__main__.py`)
- CLI and GUI dispatcher → Graphical workbench: opens GUI (evidence: `src/deepcore/__main__.py`)
- Uninformed searches → Mine environment: requests successors (evidence: `src/deepcore/solver.py`)
- Bidirectional search → Mine environment: requests predecessors (evidence: `src/deepcore/solver.py`)
- Cost-based searches → Mine environment: requests successors (evidence: `src/deepcore/solver.py`)
- Heuristic searches → Mine environment: requests successors (evidence: `src/deepcore/solver.py`)
- Heuristic searches → Heuristic functions: evaluates states (evidence: `src/deepcore/__main__.py`)
- Mine environment → State and metrics: creates states (evidence: `src/deepcore/environment.py`)
- Uninformed searches → State and metrics: returns metrics (evidence: `src/deepcore/solver.py`)
- Bidirectional search → State and metrics: returns metrics (evidence: `src/deepcore/solver.py`)
- Cost-based searches → State and metrics: returns metrics (evidence: `src/deepcore/solver.py`)
- Heuristic searches → State and metrics: returns metrics (evidence: `src/deepcore/solver.py`)
- Solution verification → Mine environment: replays actions (evidence: `src/deepcore/__main__.py`)
- Graphical workbench → Mine environment: renders map (evidence: `src/deepcore/visualizer.py`)
- Graphical workbench → CLI and GUI dispatcher: invokes runner (evidence: `src/deepcore/visualizer.py`)
- Graphical workbench → State and metrics: displays metrics (evidence: `src/deepcore/visualizer.py`)
