# nicoc144/ml-robot-navigation architecture

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

- Interactive diagram: https://gitdiagram.com/nicoc144/ml-robot-navigation
- Repository: https://github.com/nicoc144/ml-robot-navigation

## Overview

This repository is a maze-robot simulation and experimentation project. Its main workflow is to launch a simulation, load or generate a maze, plan a route, and drive a simulated robot using waypoint control; it also supports keyboard operation, autonomous ML-based control, and CSV data collection. The graph includes the documented ML experiments and batch tools. Some links are limited to README or SOURCE INDEX evidence because their implementation files were not excerpted.

Main entry points: [`maze_project/simulation/simulation.py`](https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/simulation/simulation.py) (Simulation), [`maze_project/simulation/utils.py`](https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/simulation/utils.py) (Runtime setup), [`maze_project/planning/planner.py`](https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/planning/planner.py) (Planner base), [`maze_project/control/controller.py`](https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/control/controller.py) (Motion controllers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and orchestration"]
  node_main["CLI entry<br/>[main.py]"]
  node_runtime_utils["Runtime setup<br/>[utils.py]"]
  node_batch["Batch collection<br/>[run_all.py]"]
  node_maze_tool["Maze generation tool<br/>[generate_maze.py]"]
end

subgraph group_maze["Maze and planning"]
  node_maze_data["Maze model<br/>[maze_data.py]"]
  node_generator["Maze generator<br/>[generator.py]"]
  node_planner["Planner base<br/>[planner.py]"]
  node_astar["A* planner<br/>[astar.py]"]
  node_bfs["BFS planner<br/>[bfs.py]"]
  node_dfs["DFS planner<br/>[dfs.py]"]
end

subgraph group_runtime["Robot simulation and control"]
  node_sim["Simulation<br/>[simulation.py]"]
  node_sim_maze["Physics maze<br/>[maze.py]"]
  node_robot["Differential robot<br/>[robot.py]"]
  node_sensors["Raycast sensors<br/>[sensors.py]"]
  node_controller["Motion controllers<br/>[controller.py]"]
end

subgraph group_experiments["Learning and data collection"]
  node_logger["CSV logger<br/>[sim_logger.py]"]
  node_supervised["Supervised experiments"]
  node_unsupervised["Unsupervised experiments<br/>[unsupervised.ipynb]"]
end

node_user(("User"))
node_pybullet["PyBullet"]

node_user -->|"runs"| node_main
node_main -->|"starts"| node_sim
node_main -->|"configures"| node_runtime_utils
node_runtime_utils -->|"loads"| node_maze_data
node_runtime_utils -->|"selects"| node_planner
node_runtime_utils -->|"builds"| node_controller
node_runtime_utils -->|"configures"| node_logger
node_batch -->|"uses"| node_generator
node_batch -->|"runs"| node_sim
node_batch -->|"uses"| node_logger
node_maze_tool -->|"generates"| node_generator
node_generator -->|"creates"| node_maze_data
node_planner -->|"reads"| node_maze_data
node_astar -->|"extends"| node_planner
node_bfs -->|"extends"| node_planner
node_dfs -->|"extends"| node_planner
node_sim -->|"builds"| node_sim_maze
node_sim -->|"spawns"| node_robot
node_sim -->|"attaches"| node_sensors
node_sim_maze -->|"reads"| node_maze_data
node_robot -->|"collects readings"| node_sensors
node_controller -->|"commands"| node_robot
node_sim -->|"steps physics"| node_pybullet
node_supervised -.->|"informs autonomous control"| node_controller
node_unsupervised -.->|"informs autonomous control"| node_controller

click node_main "https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/main.py"
click node_runtime_utils "https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/simulation/utils.py"
click node_batch "https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/tools/run_all.py"
click node_maze_data "https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/maze_generator/maze_data.py"
click node_generator "https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/maze_generator/generator.py"
click node_planner "https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/planning/planner.py"
click node_astar "https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/planning/astar.py"
click node_bfs "https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/planning/bfs.py"
click node_dfs "https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/planning/dfs.py"
click node_sim "https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/simulation/simulation.py"
click node_sim_maze "https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/simulation/maze.py"
click node_robot "https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/simulation/robot.py"
click node_sensors "https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/simulation/sensors.py"
click node_controller "https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/control/controller.py"
click node_logger "https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/logger/sim_logger.py"
click node_supervised "https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/learning/supervised_non-rl.ipynb"
click node_unsupervised "https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/learning/unsupervised.ipynb"
click node_maze_tool "https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/tools/generate_maze.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_main,node_runtime_utils,node_batch,node_maze_tool,node_user toneBlue
class node_maze_data,node_generator,node_planner,node_astar,node_bfs,node_dfs toneAmber
class node_sim,node_sim_maze,node_robot,node_sensors,node_controller toneMint
class node_logger,node_supervised,node_unsupervised toneRose
class node_pybullet toneIndigo
```

## Components

### Entry and orchestration

- [CLI entry](https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/main.py): `maze_project/main.py`
- [Runtime setup](https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/simulation/utils.py): `maze_project/simulation/utils.py`
- [Batch collection](https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/tools/run_all.py): `maze_project/tools/run_all.py`
- [Maze generation tool](https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/tools/generate_maze.py): `maze_project/tools/generate_maze.py`

### Maze and planning

- [Maze model](https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/maze_generator/maze_data.py): `maze_project/maze_generator/maze_data.py`
- [Maze generator](https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/maze_generator/generator.py): `maze_project/maze_generator/generator.py`
- [Planner base](https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/planning/planner.py): `maze_project/planning/planner.py`
- [A* planner](https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/planning/astar.py): `maze_project/planning/astar.py`
- [BFS planner](https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/planning/bfs.py): `maze_project/planning/bfs.py`
- [DFS planner](https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/planning/dfs.py): `maze_project/planning/dfs.py`

### Robot simulation and control

- [Simulation](https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/simulation/simulation.py): `maze_project/simulation/simulation.py`
- [Physics maze](https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/simulation/maze.py): `maze_project/simulation/maze.py`
- [Differential robot](https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/simulation/robot.py): `maze_project/simulation/robot.py`
- [Raycast sensors](https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/simulation/sensors.py): `maze_project/simulation/sensors.py`
- [Motion controllers](https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/control/controller.py): `maze_project/control/controller.py`

### Learning and data collection

- [CSV logger](https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/logger/sim_logger.py): `maze_project/logger/sim_logger.py`
- [Supervised experiments](https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/learning/supervised_non-rl.ipynb): `maze_project/learning/supervised_non-rl.ipynb`
- [Unsupervised experiments](https://github.com/nicoc144/ml-robot-navigation/blob/main/maze_project/learning/unsupervised.ipynb): `maze_project/learning/unsupervised.ipynb`

### Other components

- **User**
- **PyBullet**

## Connections

- User → CLI entry: runs (evidence: `README.md`)
- CLI entry → Simulation: starts (evidence: `maze_project/main.py`)
- CLI entry → Runtime setup: configures (evidence: `maze_project/main.py`)
- Runtime setup → Maze model: loads (evidence: `maze_project/simulation/utils.py`)
- Runtime setup → Planner base: selects (evidence: `maze_project/simulation/utils.py`)
- Runtime setup → Motion controllers: builds (evidence: `maze_project/simulation/utils.py`)
- Runtime setup → CSV logger: configures (evidence: `maze_project/simulation/utils.py`)
- Batch collection → Maze generator: uses (evidence: `maze_project/tools/run_all.py`)
- Batch collection → Simulation: runs (evidence: `maze_project/tools/run_all.py`)
- Batch collection → CSV logger: uses (evidence: `maze_project/tools/run_all.py`)
- Maze generation tool → Maze generator: generates (evidence: `maze_project/tools/generate_maze.py`)
- Maze generator → Maze model: creates (evidence: `maze_project/maze_generator/generator.py`)
- Planner base → Maze model: reads (evidence: `maze_project/planning/planner.py`)
- A* planner → Planner base: extends (evidence: `maze_project/planning/astar.py`)
- BFS planner → Planner base: extends (evidence: `maze_project/planning/bfs.py`)
- DFS planner → Planner base: extends (evidence: `maze_project/planning/dfs.py`)
- Simulation → Physics maze: builds (evidence: `maze_project/simulation/simulation.py`)
- Simulation → Differential robot: spawns (evidence: `maze_project/simulation/simulation.py`)
- Simulation → Raycast sensors: attaches (evidence: `maze_project/simulation/simulation.py`)
- Physics maze → Maze model: reads (evidence: `maze_project/simulation/maze.py`)
- Differential robot → Raycast sensors: collects readings (evidence: `maze_project/simulation/robot.py`)
- Motion controllers → Differential robot: commands (evidence: `maze_project/control/controller.py`)
- Simulation → PyBullet: steps physics (evidence: `maze_project/simulation/simulation.py`)
- Supervised experiments → Motion controllers: informs autonomous control (evidence: `README.md`)
- Unsupervised experiments → Motion controllers: informs autonomous control (evidence: `README.md`)
