# niki-mardari/g-cacher architecture

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

- Interactive diagram: https://gitdiagram.com/niki-mardari/g-cacher
- Repository: https://github.com/niki-mardari/g-cacher

## Overview

G-Cacher combines a portable ESP32-S3 GNSS logger with a web platform for telemetry, mapping, saved locations, a GeoCache game, and 3D terrain visualization. The principal workflow runs from GNSS and sensor acquisition through device display, SD logging, and telemetry upload; the backend processes and stores data, then serves it to web views and returns GeoCache guidance to the device. Device and frontend excerpts support their local flows; backend behavior is only partly sampled, so uncertain endpoint wiring is omitted.

Main entry points: [`Web/backend/app/main.py`](https://github.com/niki-mardari/g-cacher/blob/main/Web/backend/app/main.py) (FastAPI service), [`Firmware/src/G_Cacher/G_Cacher.ino`](https://github.com/niki-mardari/g-cacher/blob/main/Firmware/src/G_Cacher/G_Cacher.ino) (Firmware loop), [`Web/frontend/js/app.js`](https://github.com/niki-mardari/g-cacher/blob/main/Web/frontend/js/app.js) (Telemetry dashboard), [`Web/frontend/js/geocache.js`](https://github.com/niki-mardari/g-cacher/blob/main/Web/frontend/js/geocache.js) (GeoCache game)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_device["Device firmware"]
  node_device_app["Firmware loop<br/>[G_Cacher.ino]"]
  node_gnss_mgr["GNSS parsing<br/>[GnssManager.cpp]"]
  node_sensor_mgr["Sensor readings<br/>[SensorManager.cpp]"]
  node_touch["Touch navigation<br/>[InputManager.cpp]"]
  node_display["Device menus<br/>[UiManager.cpp]"]
  node_logging["SD logging<br/>[StorageManager.cpp]"]
  node_network["Network and saves<br/>[NetworkManager.cpp]"]
end

subgraph group_service["API and persistence"]
  node_api["FastAPI service<br/>[main.py]"]
  node_database[("PostgreSQL data<br/>[init.sql]")]
end

subgraph group_web["Web experiences"]
  node_telemetry["Telemetry dashboard<br/>[app.js]"]
  node_geocache["GeoCache game<br/>[geocache.js]"]
  node_saved["Saved locations<br/>[saved-locations.js]"]
  node_terrain["3D terrain viewer<br/>[terrain.js]"]
end

node_user(("Device and web user"))
node_gnss["GNSS receiver"]
node_sensors["Environmental sensors"]
node_sd[("SD card")]
node_map_service["Map tiles"]

node_user -->|"touches controls"| node_touch
node_touch -->|"changes menu or requests save"| node_device_app
node_gnss -->|"sends NMEA"| node_gnss_mgr
node_gnss_mgr -->|"updates fix state"| node_device_app
node_sensors -->|"provides readings"| node_sensor_mgr
node_sensor_mgr -->|"updates sensor state"| node_device_app
node_device_app -->|"renders current state"| node_display
node_device_app -->|"updates log"| node_logging
node_logging -->|"appends records"| node_sd
node_device_app -->|"updates connectivity"| node_network
node_network -->|"posts telemetry and saved assets"| node_api
node_api -->|"returns GeoCache guidance"| node_network
node_api -->|"reads and writes records"| node_database
node_user -->|"views map and track"| node_telemetry
node_telemetry -->|"fetches dashboard data"| node_api
node_telemetry -->|"posts simulated telemetry"| node_api
node_telemetry -->|"loads map tiles"| node_map_service
node_user -->|"views game"| node_geocache
node_geocache -->|"fetches locations and telemetry"| node_api
node_geocache -->|"loads map tiles"| node_map_service
node_user -->|"manages saved points"| node_saved
node_saved -->|"retrieves and updates assets"| node_api
node_user -->|"inspects terrain points"| node_terrain
node_terrain -.->|"loads recorded points"| node_api

click node_device_app "https://github.com/niki-mardari/g-cacher/blob/main/Firmware/src/G_Cacher/G_Cacher.ino"
click node_gnss_mgr "https://github.com/niki-mardari/g-cacher/blob/main/Firmware/src/G_Cacher/GnssManager.cpp"
click node_sensor_mgr "https://github.com/niki-mardari/g-cacher/blob/main/Firmware/src/G_Cacher/SensorManager.cpp"
click node_touch "https://github.com/niki-mardari/g-cacher/blob/main/Firmware/src/G_Cacher/InputManager.cpp"
click node_display "https://github.com/niki-mardari/g-cacher/blob/main/Firmware/src/G_Cacher/UiManager.cpp"
click node_logging "https://github.com/niki-mardari/g-cacher/blob/main/Firmware/src/G_Cacher/StorageManager.cpp"
click node_network "https://github.com/niki-mardari/g-cacher/blob/main/Firmware/src/G_Cacher/NetworkManager.cpp"
click node_api "https://github.com/niki-mardari/g-cacher/blob/main/Web/backend/app/main.py"
click node_database "https://github.com/niki-mardari/g-cacher/blob/main/Web/database/init.sql"
click node_telemetry "https://github.com/niki-mardari/g-cacher/blob/main/Web/frontend/js/app.js"
click node_geocache "https://github.com/niki-mardari/g-cacher/blob/main/Web/frontend/js/geocache.js"
click node_saved "https://github.com/niki-mardari/g-cacher/blob/main/Web/frontend/js/saved-locations.js"
click node_terrain "https://github.com/niki-mardari/g-cacher/blob/main/Web/frontend/js/terrain.js"

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_device_app,node_gnss_mgr,node_sensor_mgr,node_touch,node_display,node_logging,node_network,node_user toneBlue
class node_api,node_database,node_sd toneAmber
class node_telemetry,node_geocache,node_saved,node_terrain toneMint
class node_gnss,node_sensors,node_map_service toneIndigo
```

## Components

### Device firmware

- [Firmware loop](https://github.com/niki-mardari/g-cacher/blob/main/Firmware/src/G_Cacher/G_Cacher.ino): `Firmware/src/G_Cacher/G_Cacher.ino`
- [GNSS parsing](https://github.com/niki-mardari/g-cacher/blob/main/Firmware/src/G_Cacher/GnssManager.cpp): `Firmware/src/G_Cacher/GnssManager.cpp`
- [Sensor readings](https://github.com/niki-mardari/g-cacher/blob/main/Firmware/src/G_Cacher/SensorManager.cpp): `Firmware/src/G_Cacher/SensorManager.cpp`
- [Touch navigation](https://github.com/niki-mardari/g-cacher/blob/main/Firmware/src/G_Cacher/InputManager.cpp): `Firmware/src/G_Cacher/InputManager.cpp`
- [Device menus](https://github.com/niki-mardari/g-cacher/blob/main/Firmware/src/G_Cacher/UiManager.cpp): `Firmware/src/G_Cacher/UiManager.cpp`
- [SD logging](https://github.com/niki-mardari/g-cacher/blob/main/Firmware/src/G_Cacher/StorageManager.cpp): `Firmware/src/G_Cacher/StorageManager.cpp`
- [Network and saves](https://github.com/niki-mardari/g-cacher/blob/main/Firmware/src/G_Cacher/NetworkManager.cpp): `Firmware/src/G_Cacher/NetworkManager.cpp`

### API and persistence

- [FastAPI service](https://github.com/niki-mardari/g-cacher/blob/main/Web/backend/app/main.py): `Web/backend/app/main.py`
- [PostgreSQL data](https://github.com/niki-mardari/g-cacher/blob/main/Web/database/init.sql): `Web/database/init.sql`

### Web experiences

- [Telemetry dashboard](https://github.com/niki-mardari/g-cacher/blob/main/Web/frontend/js/app.js): `Web/frontend/js/app.js`
- [GeoCache game](https://github.com/niki-mardari/g-cacher/blob/main/Web/frontend/js/geocache.js): `Web/frontend/js/geocache.js`
- [Saved locations](https://github.com/niki-mardari/g-cacher/blob/main/Web/frontend/js/saved-locations.js): `Web/frontend/js/saved-locations.js`
- [3D terrain viewer](https://github.com/niki-mardari/g-cacher/blob/main/Web/frontend/js/terrain.js): `Web/frontend/js/terrain.js`

### Other components

- **Device and web user**
- **GNSS receiver**
- **Environmental sensors**
- **SD card**
- **Map tiles**

## Connections

- Device and web user → Touch navigation: touches controls
- Touch navigation → Firmware loop: changes menu or requests save
- GNSS receiver → GNSS parsing: sends NMEA
- GNSS parsing → Firmware loop: updates fix state
- Environmental sensors → Sensor readings: provides readings
- Sensor readings → Firmware loop: updates sensor state
- Firmware loop → Device menus: renders current state
- Firmware loop → SD logging: updates log
- SD logging → SD card: appends records
- Firmware loop → Network and saves: updates connectivity
- Network and saves → FastAPI service: posts telemetry and saved assets
- FastAPI service → Network and saves: returns GeoCache guidance
- FastAPI service → PostgreSQL data: reads and writes records
- Device and web user → Telemetry dashboard: views map and track
- Telemetry dashboard → FastAPI service: fetches dashboard data
- Telemetry dashboard → FastAPI service: posts simulated telemetry
- Telemetry dashboard → Map tiles: loads map tiles
- Device and web user → GeoCache game: views game
- GeoCache game → FastAPI service: fetches locations and telemetry
- GeoCache game → Map tiles: loads map tiles
- Device and web user → Saved locations: manages saved points
- Saved locations → FastAPI service: retrieves and updates assets
- Device and web user → 3D terrain viewer: inspects terrain points
- 3D terrain viewer → FastAPI service: loads recorded points