# zrhnd/simulator-micromouse architecture

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

- Interactive diagram: https://gitdiagram.com/zrhnd/simulator-micromouse
- Repository: https://github.com/zrhnd/simulator-micromouse

## Overview

This repository combines a micromouse simulator with algorithms that run against it. The main workflow is to select a maze, launch an algorithm through mms, exchange sensor and movement commands, and visualize the resulting run. The documented flood-fill solver senses walls, updates its map, computes distances from the goal, and chooses moves; the tree also includes a Q-learning agent and a reference C++ template. Simulator internals and some integrations are represented at the directory level where source excerpts were unavailable.

Main entry points: [`sim/mms-app`](https://github.com/zrhnd/simulator-micromouse/tree/main/sim/mms-app) (mms simulator), [`sim/mms-src/src/Maze.cpp`](https://github.com/zrhnd/simulator-micromouse/blob/main/sim/mms-src/src/Maze.cpp) (Maze model), [`sim/algorithms/flood-fill-c/main.c`](https://github.com/zrhnd/simulator-micromouse/blob/main/sim/algorithms/flood-fill-c/main.c) (Flood-fill entry), [`sim/algorithms/flood-fill-c/solver.c`](https://github.com/zrhnd/simulator-micromouse/blob/main/sim/algorithms/flood-fill-c/solver.c) (Flood-fill solver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Simulator"]
  node_mms["mms simulator"]
  node_entry["Simulator entry<br/>[Main.cpp]"]
  node_driver["Simulator driver<br/>[Driver.cpp]"]
end

subgraph group_maze["Maze and display"]
  node_maze_files["Competition mazes"]
  node_maze_model["Maze model<br/>[Maze.cpp]"]
  node_map_model["Grid map<br/>[Map.cpp]"]
  node_maze_view["Maze view<br/>[MazeView.cpp]"]
  node_mouse["Mouse state<br/>[Mouse.cpp]"]
end

subgraph group_algorithms["Solvers"]
  node_flood_main["Flood-fill entry<br/>[main.c]"]
  node_flood_solver["Flood-fill solver<br/>[solver.c]"]
  node_queue["BFS queue<br/>[queue.c]"]
  node_q_agent["Q-learning agent<br/>[main.py]"]
  node_cpp_template["C++ reference<br/>[Main.cpp]"]
end

subgraph group_protocol["Algorithm interface"]
  node_c_api["C simulator API<br/>[API.c]"]
  node_cpp_api["C++ simulator API<br/>[API.cpp]"]
end

subgraph group_state["Agent state"]
  node_q_state["Learned state<br/>[main.py]"]
end

node_user(("Operator"))

node_user -->|"selects maze and runs"| node_mms
node_maze_files -->|"provides maze files"| node_mms
node_mms -->|"runs simulator"| node_entry
node_entry -->|"calls drive"| node_driver
node_driver -->|"coordinates simulation"| node_maze_model
node_maze_model -->|"uses grid map"| node_map_model
node_maze_model -->|"tracks mouse"| node_mouse
node_maze_view -->|"renders simulation"| node_mms
node_mms -->|"launches algorithm"| node_flood_main
node_flood_main -->|"initializes and commands"| node_c_api
node_flood_main -->|"requests next move"| node_flood_solver
node_flood_solver -->|"reads sensors and displays"| node_c_api
node_flood_solver -->|"runs BFS"| node_queue
node_c_api -->|"exchanges simulator commands"| node_mms
node_mms -->|"can launch algorithm"| node_q_agent
node_q_agent -->|"loads and saves"| node_q_state
node_q_agent -->|"senses and moves"| node_mms
node_mms -.->|"can launch template"| node_cpp_template
node_cpp_template -->|"calls simulator API"| node_cpp_api
node_cpp_api -->|"exchanges simulator commands"| node_mms

click node_mms "https://github.com/zrhnd/simulator-micromouse/tree/main/sim/mms-app"
click node_entry "https://github.com/zrhnd/simulator-micromouse/blob/main/sim/mms-src/src/Main.cpp"
click node_driver "https://github.com/zrhnd/simulator-micromouse/blob/main/sim/mms-src/src/Driver.cpp"
click node_maze_files "https://github.com/zrhnd/simulator-micromouse/tree/main/sim/mazes/mazefiles"
click node_maze_model "https://github.com/zrhnd/simulator-micromouse/blob/main/sim/mms-src/src/Maze.cpp"
click node_map_model "https://github.com/zrhnd/simulator-micromouse/blob/main/sim/mms-src/src/Map.cpp"
click node_maze_view "https://github.com/zrhnd/simulator-micromouse/blob/main/sim/mms-src/src/MazeView.cpp"
click node_flood_main "https://github.com/zrhnd/simulator-micromouse/blob/main/sim/algorithms/flood-fill-c/main.c"
click node_flood_solver "https://github.com/zrhnd/simulator-micromouse/blob/main/sim/algorithms/flood-fill-c/solver.c"
click node_queue "https://github.com/zrhnd/simulator-micromouse/blob/main/sim/algorithms/flood-fill-c/queue.c"
click node_q_agent "https://github.com/zrhnd/simulator-micromouse/blob/main/sim/algorithms/q-learning/main.py"
click node_cpp_template "https://github.com/zrhnd/simulator-micromouse/blob/main/sim/algorithms/mms-cpp/Main.cpp"
click node_c_api "https://github.com/zrhnd/simulator-micromouse/blob/main/sim/algorithms/flood-fill-c/API.c"
click node_cpp_api "https://github.com/zrhnd/simulator-micromouse/blob/main/sim/algorithms/mms-cpp/API.cpp"
click node_mouse "https://github.com/zrhnd/simulator-micromouse/blob/main/sim/mms-src/src/Mouse.cpp"
click node_q_state "https://github.com/zrhnd/simulator-micromouse/blob/main/sim/algorithms/q-learning/main.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_mms,node_entry,node_driver toneBlue
class node_maze_files,node_maze_model,node_map_model,node_maze_view,node_mouse toneAmber
class node_flood_main,node_flood_solver,node_queue,node_q_agent,node_cpp_template toneMint
class node_c_api,node_cpp_api toneRose
class node_q_state,node_user toneIndigo
```

## Components

### Simulator

- [mms simulator](https://github.com/zrhnd/simulator-micromouse/tree/main/sim/mms-app): `sim/mms-app`
- [Simulator entry](https://github.com/zrhnd/simulator-micromouse/blob/main/sim/mms-src/src/Main.cpp): `sim/mms-src/src/Main.cpp`
- [Simulator driver](https://github.com/zrhnd/simulator-micromouse/blob/main/sim/mms-src/src/Driver.cpp): `sim/mms-src/src/Driver.cpp`

### Maze and display

- [Competition mazes](https://github.com/zrhnd/simulator-micromouse/tree/main/sim/mazes/mazefiles): `sim/mazes/mazefiles`
- [Maze model](https://github.com/zrhnd/simulator-micromouse/blob/main/sim/mms-src/src/Maze.cpp): `sim/mms-src/src/Maze.cpp`
- [Grid map](https://github.com/zrhnd/simulator-micromouse/blob/main/sim/mms-src/src/Map.cpp): `sim/mms-src/src/Map.cpp`
- [Maze view](https://github.com/zrhnd/simulator-micromouse/blob/main/sim/mms-src/src/MazeView.cpp): `sim/mms-src/src/MazeView.cpp`
- [Mouse state](https://github.com/zrhnd/simulator-micromouse/blob/main/sim/mms-src/src/Mouse.cpp): `sim/mms-src/src/Mouse.cpp`

### Solvers

- [Flood-fill entry](https://github.com/zrhnd/simulator-micromouse/blob/main/sim/algorithms/flood-fill-c/main.c): `sim/algorithms/flood-fill-c/main.c`
- [Flood-fill solver](https://github.com/zrhnd/simulator-micromouse/blob/main/sim/algorithms/flood-fill-c/solver.c): `sim/algorithms/flood-fill-c/solver.c`
- [BFS queue](https://github.com/zrhnd/simulator-micromouse/blob/main/sim/algorithms/flood-fill-c/queue.c): `sim/algorithms/flood-fill-c/queue.c`
- [Q-learning agent](https://github.com/zrhnd/simulator-micromouse/blob/main/sim/algorithms/q-learning/main.py): `sim/algorithms/q-learning/main.py`
- [C++ reference](https://github.com/zrhnd/simulator-micromouse/blob/main/sim/algorithms/mms-cpp/Main.cpp): `sim/algorithms/mms-cpp/Main.cpp`

### Algorithm interface

- [C simulator API](https://github.com/zrhnd/simulator-micromouse/blob/main/sim/algorithms/flood-fill-c/API.c): `sim/algorithms/flood-fill-c/API.c`
- [C++ simulator API](https://github.com/zrhnd/simulator-micromouse/blob/main/sim/algorithms/mms-cpp/API.cpp): `sim/algorithms/mms-cpp/API.cpp`

### Agent state

- [Learned state](https://github.com/zrhnd/simulator-micromouse/blob/main/sim/algorithms/q-learning/main.py): `sim/algorithms/q-learning/main.py`

### Other components

- **Operator**

## Connections

- Operator → mms simulator: selects maze and runs
- Competition mazes → mms simulator: provides maze files
- mms simulator → Simulator entry: runs simulator
- Simulator entry → Simulator driver: calls drive
- Simulator driver → Maze model: coordinates simulation
- Maze model → Grid map: uses grid map
- Maze model → Mouse state: tracks mouse
- Maze view → mms simulator: renders simulation
- mms simulator → Flood-fill entry: launches algorithm
- Flood-fill entry → C simulator API: initializes and commands
- Flood-fill entry → Flood-fill solver: requests next move
- Flood-fill solver → C simulator API: reads sensors and displays
- Flood-fill solver → BFS queue: runs BFS
- C simulator API → mms simulator: exchanges simulator commands
- mms simulator → Q-learning agent: can launch algorithm
- Q-learning agent → Learned state: loads and saves
- Q-learning agent → mms simulator: senses and moves
- mms simulator → C++ reference: can launch template
- C++ reference → C++ simulator API: calls simulator API
- C++ simulator API → mms simulator: exchanges simulator commands