# 1cfer/tars architecture

> Architecture diagram of the GitHub repository 1cfer/tars, 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/1cfer/tars
- Repository: https://github.com/1cfer/tars

## Overview

TARS is an ESP32 environmental monitor: it samples and filters sensor readings, displays them locally, and periodically sends a JSON update to the MOREHA/FIWARE cloud. Its state machine separates startup, reading, sending, and developer setup. The developer mode also supports Wi-Fi setup and web-based OTA/configuration. The README documents the cloud’s Keyrock–Wilma–Orion flow and historical dashboard; those services are external to this repository. Some firmware wiring is unsampled, so the graph omits unverified calls and uses the README for documented transitions.

Main entry points: [`firmware/TARS/StateMachine.cpp`](https://github.com/1cfer/tars/blob/main/firmware/TARS/StateMachine.cpp) (State machine), [`firmware/TARS/Estados.cpp`](https://github.com/1cfer/tars/blob/main/firmware/TARS/Estados.cpp) (Sending state), [`firmware/TARS/TokenManager.h`](https://github.com/1cfer/tars/blob/main/firmware/TARS/TokenManager.h) (Token manager), [`firmware/TARS/WiFiManager.h`](https://github.com/1cfer/tars/blob/main/firmware/TARS/WiFiManager.h) (Wi-Fi manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["Device firmware"]
  node_sketch["Firmware entry<br/>[TARS.ino]"]
  node_machine["State machine<br/>[StateMachine.cpp]"]
  node_startup["Startup state<br/>[Estados.cpp]"]
  node_reading["Reading state<br/>[Estados.cpp]"]
  node_sending["Sending state<br/>[Estados.cpp]"]
  node_developer["Developer state<br/>[Estados.cpp]"]
  node_button["Button events<br/>[ButtonHandler.h]"]
  node_sensors["Sensor acquisition<br/>[SensorManager.cpp]"]
  node_display["OLED screens<br/>[DisplayManager.cpp]"]
  node_payload["Payload builder<br/>[PayloadBuilder.cpp]"]
end

subgraph group_connectivity["Network and setup"]
  node_config[("App configuration<br/>[AppConfig.h]")]
  node_wifi["Wi-Fi manager<br/>[WiFiManager.h]"]
  node_ota["Setup and OTA<br/>[DevWebOTA.cpp]"]
  node_token["Token manager<br/>[TokenManager.h]"]
end

subgraph group_cloud["Cloud platform"]
  node_keyrock["Keyrock"]
  node_wilma["Wilma proxy"]
  node_orion[("Orion broker")]
  node_history[("QuantumLeap / CrateDB")]
  node_moreha["MOREHA dashboard"]
end

subgraph group_hardware["Physical device"]
  node_enclosure["3D-printed enclosure<br/>[TARS_TOP.3mf]"]
end

node_operator(("Device operator"))
node_network(("Wi-Fi network"))

node_operator -.->|"operates"| node_sketch
node_sketch -.->|"runs"| node_machine
node_machine -->|"dispatches"| node_startup
node_machine -->|"dispatches"| node_reading
node_machine -->|"dispatches"| node_sending
node_machine -->|"dispatches"| node_developer
node_button -->|"provides events"| node_machine
node_startup -->|"connects through"| node_wifi
node_reading -->|"reads periodically"| node_sensors
node_reading -->|"refreshes"| node_display
node_sending -->|"gets averages"| node_sensors
node_sending -->|"builds payload"| node_payload
node_developer -->|"handles requests"| node_ota
node_developer -->|"configures network"| node_wifi
node_developer -->|"shows setup screens"| node_display
node_config -->|"supplies credentials"| node_token
node_sending -->|"ensures token"| node_token
node_token -->|"requests token"| node_keyrock
node_sending -->|"PATCHes payload"| node_wilma
node_wilma -->|"validates token"| node_keyrock
node_wilma -->|"forwards update"| node_orion
node_orion -->|"feeds history"| node_history
node_history -.->|"serves history"| node_moreha
node_network -.->|"connects to"| node_wifi

click node_sketch "https://github.com/1cfer/tars/blob/main/firmware/TARS/TARS.ino"
click node_machine "https://github.com/1cfer/tars/blob/main/firmware/TARS/StateMachine.cpp"
click node_startup "https://github.com/1cfer/tars/blob/main/firmware/TARS/Estados.cpp"
click node_reading "https://github.com/1cfer/tars/blob/main/firmware/TARS/Estados.cpp"
click node_sending "https://github.com/1cfer/tars/blob/main/firmware/TARS/Estados.cpp"
click node_developer "https://github.com/1cfer/tars/blob/main/firmware/TARS/Estados.cpp"
click node_button "https://github.com/1cfer/tars/blob/main/firmware/TARS/ButtonHandler.h"
click node_sensors "https://github.com/1cfer/tars/blob/main/firmware/TARS/SensorManager.cpp"
click node_display "https://github.com/1cfer/tars/blob/main/firmware/TARS/DisplayManager.cpp"
click node_payload "https://github.com/1cfer/tars/blob/main/firmware/TARS/PayloadBuilder.cpp"
click node_config "https://github.com/1cfer/tars/blob/main/firmware/TARS/AppConfig.h"
click node_wifi "https://github.com/1cfer/tars/blob/main/firmware/TARS/WiFiManager.h"
click node_ota "https://github.com/1cfer/tars/blob/main/firmware/TARS/DevWebOTA.cpp"
click node_token "https://github.com/1cfer/tars/blob/main/firmware/TARS/TokenManager.h"
click node_enclosure "https://github.com/1cfer/tars/blob/main/hardware/TARS_TOP.3mf"

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_sketch,node_machine,node_startup,node_reading,node_sending,node_developer,node_button,node_sensors,node_display,node_payload toneBlue
class node_config,node_wifi,node_ota,node_token toneAmber
class node_keyrock,node_wilma,node_orion,node_history,node_moreha toneMint
class node_enclosure toneRose
class node_operator,node_network toneIndigo
```

## Components

### Device firmware

- [Firmware entry](https://github.com/1cfer/tars/blob/main/firmware/TARS/TARS.ino): `firmware/TARS/TARS.ino`
- [State machine](https://github.com/1cfer/tars/blob/main/firmware/TARS/StateMachine.cpp): `firmware/TARS/StateMachine.cpp`
- [Startup state](https://github.com/1cfer/tars/blob/main/firmware/TARS/Estados.cpp): `firmware/TARS/Estados.cpp`
- [Reading state](https://github.com/1cfer/tars/blob/main/firmware/TARS/Estados.cpp): `firmware/TARS/Estados.cpp`
- [Sending state](https://github.com/1cfer/tars/blob/main/firmware/TARS/Estados.cpp): `firmware/TARS/Estados.cpp`
- [Developer state](https://github.com/1cfer/tars/blob/main/firmware/TARS/Estados.cpp): `firmware/TARS/Estados.cpp`
- [Button events](https://github.com/1cfer/tars/blob/main/firmware/TARS/ButtonHandler.h): `firmware/TARS/ButtonHandler.h`
- [Sensor acquisition](https://github.com/1cfer/tars/blob/main/firmware/TARS/SensorManager.cpp): `firmware/TARS/SensorManager.cpp`
- [OLED screens](https://github.com/1cfer/tars/blob/main/firmware/TARS/DisplayManager.cpp): `firmware/TARS/DisplayManager.cpp`
- [Payload builder](https://github.com/1cfer/tars/blob/main/firmware/TARS/PayloadBuilder.cpp): `firmware/TARS/PayloadBuilder.cpp`

### Network and setup

- [App configuration](https://github.com/1cfer/tars/blob/main/firmware/TARS/AppConfig.h): `firmware/TARS/AppConfig.h`
- [Wi-Fi manager](https://github.com/1cfer/tars/blob/main/firmware/TARS/WiFiManager.h): `firmware/TARS/WiFiManager.h`
- [Setup and OTA](https://github.com/1cfer/tars/blob/main/firmware/TARS/DevWebOTA.cpp): `firmware/TARS/DevWebOTA.cpp`
- [Token manager](https://github.com/1cfer/tars/blob/main/firmware/TARS/TokenManager.h): `firmware/TARS/TokenManager.h`

### Cloud platform

- **Keyrock**
- **Wilma proxy**
- **Orion broker**
- **QuantumLeap / CrateDB**
- **MOREHA dashboard**

### Physical device

- [3D-printed enclosure](https://github.com/1cfer/tars/blob/main/hardware/TARS_TOP.3mf): `hardware/TARS_TOP.3mf`

### Other components

- **Device operator**
- **Wi-Fi network**

## Connections

- Device operator → Firmware entry: operates
- Firmware entry → State machine: runs
- State machine → Startup state: dispatches (evidence: `README.md`)
- State machine → Reading state: dispatches (evidence: `README.md`)
- State machine → Sending state: dispatches (evidence: `README.md`)
- State machine → Developer state: dispatches (evidence: `README.md`)
- Button events → State machine: provides events
- Startup state → Wi-Fi manager: connects through (evidence: `firmware/TARS/Estados.cpp`)
- Reading state → Sensor acquisition: reads periodically (evidence: `firmware/TARS/Estados.cpp`)
- Reading state → OLED screens: refreshes (evidence: `firmware/TARS/Estados.cpp`)
- Sending state → Sensor acquisition: gets averages (evidence: `firmware/TARS/Estados.cpp`)
- Sending state → Payload builder: builds payload (evidence: `firmware/TARS/Estados.cpp`)
- Developer state → Setup and OTA: handles requests (evidence: `firmware/TARS/Estados.cpp`)
- Developer state → Wi-Fi manager: configures network (evidence: `firmware/TARS/Estados.cpp`)
- Developer state → OLED screens: shows setup screens (evidence: `firmware/TARS/Estados.cpp`)
- App configuration → Token manager: supplies credentials (evidence: `firmware/TARS/TokenManager.h`)
- Sending state → Token manager: ensures token (evidence: `firmware/TARS/Estados.cpp`)
- Token manager → Keyrock: requests token (evidence: `firmware/TARS/TokenManager.h`)
- Sending state → Wilma proxy: PATCHes payload (evidence: `README.md`)
- Wilma proxy → Keyrock: validates token (evidence: `README.md`)
- Wilma proxy → Orion broker: forwards update (evidence: `README.md`)
- Orion broker → QuantumLeap / CrateDB: feeds history (evidence: `README.md`)
- QuantumLeap / CrateDB → MOREHA dashboard: serves history
- Wi-Fi network → Wi-Fi manager: connects to
