# grownplanet/mmm_geo_quest architecture

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

- Interactive diagram: https://gitdiagram.com/grownplanet/mmm_geo_quest
- Repository: https://github.com/grownplanet/mmm_geo_quest

## Overview

GeoQuest is a word-seeded walking game: the player enters a word and difficulty, the computer derives a destination in Ghent, obtains a walking route, and sends successive route points to an Arduino navigator over MQTT. The navigator is intended to guide the player and report locations so the computer can advance the route and announce completion. The computer workflow is visible in the sampled Python; Arduino internals were not sampled, so those capabilities and links are based on README documentation.

Main entry points: [`computer/main.py`](https://github.com/grownplanet/mmm_geo_quest/blob/main/computer/main.py) (MQTT client), [`arduino/navigator/navigator.ino`](https://github.com/grownplanet/mmm_geo_quest/blob/main/arduino/navigator/navigator.ino) (Navigator firmware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_computer["Computer game"]
  node_game_ui["Game interface<br/>[main.py]"]
  node_destination["Word destination<br/>[main.py]"]
  node_progress["Route progress<br/>[main.py]"]
  node_completion["Game completion<br/>[main.py]"]
end

subgraph group_routing["Route planning"]
  node_route["Walking route<br/>[main.py]"]
  node_difficulty["Difficulty waypoints<br/>[main.py]"]
end

subgraph group_messaging["MQTT communication"]
  node_mqtt_client["MQTT client<br/>[main.py]"]
  node_location_input["Location messages<br/>[main.py]"]
end

subgraph group_navigator["Arduino navigator"]
  node_firmware["Navigator firmware<br/>[navigator.ino]"]
  node_direction_display["Direction display<br/>[navigator.ino]"]
end

node_player(("Player"))
node_mapbox["Mapbox Directions"]
node_broker["MQTT broker"]

node_player -->|"enters game"| node_game_ui
node_game_ui -->|"derives destination"| node_destination
node_game_ui -->|"selects difficulty"| node_difficulty
node_game_ui -->|"requests route"| node_route
node_route -->|"requests directions"| node_mapbox
node_route -.->|"reduces route points"| node_difficulty
node_game_ui -->|"starts MQTT"| node_mqtt_client
node_mqtt_client -->|"connects"| node_broker
node_broker -->|"delivers messages"| node_mqtt_client
node_mqtt_client -->|"queues locations"| node_location_input
node_location_input -->|"supplies current location"| node_progress
node_progress -->|"publishes next point"| node_mqtt_client
node_progress -->|"detects arrival"| node_completion
node_completion -->|"publishes LAST"| node_mqtt_client
node_mqtt_client -->|"sends route points"| node_firmware
node_firmware -->|"reports location"| node_mqtt_client
node_firmware -->|"shows direction"| node_direction_display

click node_game_ui "https://github.com/grownplanet/mmm_geo_quest/blob/main/computer/main.py"
click node_destination "https://github.com/grownplanet/mmm_geo_quest/blob/main/computer/main.py"
click node_route "https://github.com/grownplanet/mmm_geo_quest/blob/main/computer/main.py"
click node_difficulty "https://github.com/grownplanet/mmm_geo_quest/blob/main/computer/main.py"
click node_progress "https://github.com/grownplanet/mmm_geo_quest/blob/main/computer/main.py"
click node_completion "https://github.com/grownplanet/mmm_geo_quest/blob/main/computer/main.py"
click node_mqtt_client "https://github.com/grownplanet/mmm_geo_quest/blob/main/computer/main.py"
click node_location_input "https://github.com/grownplanet/mmm_geo_quest/blob/main/computer/main.py"
click node_firmware "https://github.com/grownplanet/mmm_geo_quest/blob/main/arduino/navigator/navigator.ino"
click node_direction_display "https://github.com/grownplanet/mmm_geo_quest/blob/main/arduino/navigator/navigator.ino"

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_ui,node_destination,node_progress,node_completion toneBlue
class node_route,node_difficulty toneAmber
class node_mqtt_client,node_location_input toneMint
class node_firmware,node_direction_display toneRose
class node_player,node_mapbox,node_broker toneIndigo
```

## Components

### Computer game

- [Game interface](https://github.com/grownplanet/mmm_geo_quest/blob/main/computer/main.py): `computer/main.py`
- [Word destination](https://github.com/grownplanet/mmm_geo_quest/blob/main/computer/main.py): `computer/main.py`
- [Route progress](https://github.com/grownplanet/mmm_geo_quest/blob/main/computer/main.py): `computer/main.py`
- [Game completion](https://github.com/grownplanet/mmm_geo_quest/blob/main/computer/main.py): `computer/main.py`

### Route planning

- [Walking route](https://github.com/grownplanet/mmm_geo_quest/blob/main/computer/main.py): `computer/main.py`
- [Difficulty waypoints](https://github.com/grownplanet/mmm_geo_quest/blob/main/computer/main.py): `computer/main.py`

### MQTT communication

- [MQTT client](https://github.com/grownplanet/mmm_geo_quest/blob/main/computer/main.py): `computer/main.py`
- [Location messages](https://github.com/grownplanet/mmm_geo_quest/blob/main/computer/main.py): `computer/main.py`

### Arduino navigator

- [Navigator firmware](https://github.com/grownplanet/mmm_geo_quest/blob/main/arduino/navigator/navigator.ino): `arduino/navigator/navigator.ino`
- [Direction display](https://github.com/grownplanet/mmm_geo_quest/blob/main/arduino/navigator/navigator.ino): `arduino/navigator/navigator.ino`

### Other components

- **Player**
- **Mapbox Directions**
- **MQTT broker**

## Connections

- Player → Game interface: enters game (evidence: `computer/main.py`)
- Game interface → Word destination: derives destination (evidence: `computer/main.py`)
- Game interface → Difficulty waypoints: selects difficulty (evidence: `computer/main.py`)
- Game interface → Walking route: requests route (evidence: `README.md`)
- Walking route → Mapbox Directions: requests directions (evidence: `computer/main.py`)
- Walking route → Difficulty waypoints: reduces route points (evidence: `computer/main.py`)
- Game interface → MQTT client: starts MQTT (evidence: `computer/main.py`)
- MQTT client → MQTT broker: connects (evidence: `computer/main.py`)
- MQTT broker → MQTT client: delivers messages (evidence: `README.md`)
- MQTT client → Location messages: queues locations (evidence: `computer/main.py`)
- Location messages → Route progress: supplies current location (evidence: `computer/main.py`)
- Route progress → MQTT client: publishes next point (evidence: `computer/main.py`)
- Route progress → Game completion: detects arrival (evidence: `computer/main.py`)
- Game completion → MQTT client: publishes LAST (evidence: `computer/main.py`)
- MQTT client → Navigator firmware: sends route points (evidence: `README.md`)
- Navigator firmware → MQTT client: reports location (evidence: `README.md`)
- Navigator firmware → Direction display: shows direction (evidence: `README.md`)
