# j-a-a-m/ukraine_alarm_map architecture

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

- Interactive diagram: https://gitdiagram.com/j-a-a-m/ukraine_alarm_map
- Repository: https://github.com/j-a-a-m/ukraine_alarm_map

## Overview

JAAM is an archived Ukrainian air-alert map ecosystem: embedded devices present status and sensor information, while backend services collect and prepare alert and environmental data for clients. The README also identifies a data portal and browser-based firmware flasher. The sampled source shows firmware initialization and Redis-backed backend components, but not enough wiring to establish every service-to-service or device-to-server connection; those links are omitted rather than inferred.

Main entry points: [`firmware/src/JaamFirmware.cpp`](https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/firmware/src/JaamFirmware.cpp) (Firmware runtime), [`deploy/web_server/web_server.py`](https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/deploy/web_server/web_server.py) (Web server), [`flasher/flasher.js`](https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/flasher/flasher.js) (Browser flasher), [`deploy/update_server/update_server.py`](https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/deploy/update_server/update_server.py) (Release service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["JAAM device firmware"]
  node_firmware_main["Firmware runtime<br/>[JaamFirmware.cpp]"]
  node_display["Display<br/>[JaamDisplay.cpp]"]
  node_settings["Settings<br/>[JaamSettings.cpp]"]
  node_homeassistant["Home Assistant"]
  node_climate_sensor["Climate sensor"]
  node_light_sensor["Light sensor"]
  node_button["Device buttons<br/>[JaamButton.cpp]"]
end

subgraph group_collect["Data collection"]
  node_alerts_collector["Alert collector<br/>[alerts.py]"]
  node_etryvoga_collector["Etryvoga collector<br/>[etryvoga.py]"]
  node_ety_ws_collector["Etryvoga WS collector<br/>[etryvoga_ws.py]"]
end

subgraph group_backend["Backend data services"]
  node_updater["Data updater<br/>[updater.py]"]
  node_redis[("Redis data store")]
  node_websocket_server["WebSocket server"]
end

subgraph group_clients["User interfaces"]
  node_web_server["Web server<br/>[web_server.py]"]
  node_device_map["Device map<br/>[device_map.py]"]
end

subgraph group_updates["Firmware updates"]
  node_flasher["Browser flasher<br/>[flasher.js]"]
  node_update_server["Release service<br/>[update_server.py]"]
  node_device_updater["Device updater<br/>[updater.cpp]"]
end

node_device_user(("Device user"))
node_portal_user(("Portal user"))
node_flasher_user(("Flasher user"))

node_device_user -->|"uses device"| node_firmware_main
node_firmware_main -->|"initializes"| node_display
node_firmware_main -->|"initializes"| node_settings
node_firmware_main -->|"initializes"| node_climate_sensor
node_firmware_main -->|"initializes"| node_light_sensor
node_firmware_main -->|"initializes"| node_button
node_firmware_main -->|"runs loop"| node_homeassistant
node_alerts_collector -->|"reads and writes"| node_redis
node_etryvoga_collector -->|"stores data"| node_redis
node_ety_ws_collector -->|"stores data"| node_redis
node_updater -->|"publishes data"| node_redis
node_websocket_server -->|"reads client data"| node_redis
node_web_server -->|"reads data"| node_redis
node_device_map -->|"reads locations"| node_redis
node_portal_user -->|"views portal"| node_web_server
node_flasher_user -->|"flashes firmware"| node_flasher
node_flasher -.->|"requests releases"| node_update_server
node_update_server -.->|"provides updates"| node_device_updater

click node_firmware_main "https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/firmware/src/JaamFirmware.cpp"
click node_display "https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/firmware/src/JaamDisplay.cpp"
click node_settings "https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/firmware/src/JaamSettings.cpp"
click node_homeassistant "https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/firmware/src/JaamHomeAssistant.cpp"
click node_climate_sensor "https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/firmware/src/JaamClimateSensor.cpp"
click node_light_sensor "https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/firmware/src/JaamLightSensor.cpp"
click node_button "https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/firmware/src/JaamButton.cpp"
click node_alerts_collector "https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/deploy/alerts/alerts.py"
click node_etryvoga_collector "https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/deploy/etryvoga/etryvoga.py"
click node_ety_ws_collector "https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/deploy/etryvoga_ws/etryvoga_ws.py"
click node_updater "https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/deploy/updater/updater.py"
click node_websocket_server "https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/deploy/websocket_server/websocket_server.py"
click node_web_server "https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/deploy/web_server/web_server.py"
click node_device_map "https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/deploy/device_map/device_map.py"
click node_flasher "https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/flasher/flasher.js"
click node_update_server "https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/deploy/update_server/update_server.py"
click node_device_updater "https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/updater/src/updater.cpp"

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_firmware_main,node_display,node_settings,node_homeassistant,node_climate_sensor,node_light_sensor,node_button,node_device_user,node_portal_user,node_flasher_user toneBlue
class node_alerts_collector,node_etryvoga_collector,node_ety_ws_collector toneAmber
class node_updater,node_redis,node_websocket_server toneMint
class node_web_server,node_device_map toneRose
class node_flasher,node_update_server,node_device_updater toneIndigo
```

## Components

### JAAM device firmware

- [Firmware runtime](https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/firmware/src/JaamFirmware.cpp): `firmware/src/JaamFirmware.cpp`
- [Display](https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/firmware/src/JaamDisplay.cpp): `firmware/src/JaamDisplay.cpp`
- [Settings](https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/firmware/src/JaamSettings.cpp): `firmware/src/JaamSettings.cpp`
- [Home Assistant](https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/firmware/src/JaamHomeAssistant.cpp): `firmware/src/JaamHomeAssistant.cpp`
- [Climate sensor](https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/firmware/src/JaamClimateSensor.cpp): `firmware/src/JaamClimateSensor.cpp`
- [Light sensor](https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/firmware/src/JaamLightSensor.cpp): `firmware/src/JaamLightSensor.cpp`
- [Device buttons](https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/firmware/src/JaamButton.cpp): `firmware/src/JaamButton.cpp`

### Data collection

- [Alert collector](https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/deploy/alerts/alerts.py): `deploy/alerts/alerts.py`
- [Etryvoga collector](https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/deploy/etryvoga/etryvoga.py): `deploy/etryvoga/etryvoga.py`
- [Etryvoga WS collector](https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/deploy/etryvoga_ws/etryvoga_ws.py): `deploy/etryvoga_ws/etryvoga_ws.py`

### Backend data services

- [Data updater](https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/deploy/updater/updater.py): `deploy/updater/updater.py`
- **Redis data store**
- [WebSocket server](https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/deploy/websocket_server/websocket_server.py): `deploy/websocket_server/websocket_server.py`

### User interfaces

- [Web server](https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/deploy/web_server/web_server.py): `deploy/web_server/web_server.py`
- [Device map](https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/deploy/device_map/device_map.py): `deploy/device_map/device_map.py`

### Firmware updates

- [Browser flasher](https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/flasher/flasher.js): `flasher/flasher.js`
- [Release service](https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/deploy/update_server/update_server.py): `deploy/update_server/update_server.py`
- [Device updater](https://github.com/j-a-a-m/ukraine_alarm_map/blob/develop/updater/src/updater.cpp): `updater/src/updater.cpp`

### Other components

- **Device user**
- **Portal user**
- **Flasher user**

## Connections

- Device user → Firmware runtime: uses device (evidence: `README.md`)
- Firmware runtime → Display: initializes (evidence: `firmware/src/JaamFirmware.cpp`)
- Firmware runtime → Settings: initializes (evidence: `firmware/src/JaamFirmware.cpp`)
- Firmware runtime → Climate sensor: initializes (evidence: `firmware/src/JaamFirmware.cpp`)
- Firmware runtime → Light sensor: initializes (evidence: `firmware/src/JaamFirmware.cpp`)
- Firmware runtime → Device buttons: initializes (evidence: `firmware/src/JaamFirmware.cpp`)
- Firmware runtime → Home Assistant: runs loop (evidence: `firmware/src/JaamFirmware.cpp`)
- Alert collector → Redis data store: reads and writes (evidence: `deploy/alerts/alerts.py`)
- Etryvoga collector → Redis data store: stores data (evidence: `deploy/etryvoga/etryvoga.py`)
- Etryvoga WS collector → Redis data store: stores data (evidence: `deploy/etryvoga_ws/etryvoga_ws.py`)
- Data updater → Redis data store: publishes data (evidence: `deploy/updater/updater.py`)
- WebSocket server → Redis data store: reads client data (evidence: `deploy/websocket_server/websocket_server.py`)
- Web server → Redis data store: reads data (evidence: `deploy/web_server/web_server.py`)
- Device map → Redis data store: reads locations (evidence: `deploy/device_map/device_map.py`)
- Portal user → Web server: views portal (evidence: `README.md`)
- Flasher user → Browser flasher: flashes firmware (evidence: `README.md`)
- Browser flasher → Release service: requests releases
- Release service → Device updater: provides updates
