# koonosuke/tsukechi-kushihara-waterlevel architecture

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

- Interactive diagram: https://gitdiagram.com/koonosuke/tsukechi-kushihara-waterlevel
- Repository: https://github.com/koonosuke/tsukechi-kushihara-waterlevel

## Overview

This repository’s active application is ESP32-C3 water-level telemetry firmware. Its main workflow reads and validates ultrasonic distance measurements, then sends a JSON report with cellular signal metrics to Soracom; failures are retained for later reporting and can trigger deep sleep. The sampled source shows these stages in `src/main.cpp`. The tree also contains a PCF8563 Arduino library, but the available excerpts do not show it participating in the firmware workflow, so it is omitted here.

Main entry points: [`src/main.cpp`](https://github.com/koonosuke/tsukechi-kushihara-waterlevel/blob/main/src/main.cpp) (Telemetry sender)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sampling["Measurement"]
  node_firmware["Firmware loop<br/>[main.cpp]"]
  node_distance["Distance validation<br/>[main.cpp]"]
end

subgraph group_telemetry["Cellular telemetry"]
  node_sender["Telemetry sender<br/>[main.cpp]"]
  node_signal["Signal metrics<br/>[main.cpp]"]
  node_payload["JSON report<br/>[main.cpp]"]
end

subgraph group_recovery["Failure recovery"]
  node_nvs[("NVS log store")]
  node_recovery["Retry and sleep<br/>[main.cpp]"]
end

node_ultrasonic(("Ultrasonic sensor"))
node_modem["LTE modem"]
node_soracom["Soracom endpoint"]

node_firmware -->|"reads UART"| node_ultrasonic
node_firmware -->|"validates frames"| node_distance
node_firmware -->|"calls on sample"| node_sender
node_sender -->|"queries metrics"| node_signal
node_signal -->|"sends AT commands"| node_modem
node_sender -->|"configures and posts"| node_modem
node_sender -->|"reads prior logs"| node_nvs
node_sender -->|"assembles report"| node_payload
node_payload -->|"writes request body"| node_modem
node_modem -->|"posts report"| node_soracom
node_sender -->|"stores failed-send metrics"| node_nvs
node_sender -->|"handles post failure"| node_recovery
node_recovery -->|"switches power off"| node_modem

click node_firmware "https://github.com/koonosuke/tsukechi-kushihara-waterlevel/blob/main/src/main.cpp"
click node_distance "https://github.com/koonosuke/tsukechi-kushihara-waterlevel/blob/main/src/main.cpp"
click node_sender "https://github.com/koonosuke/tsukechi-kushihara-waterlevel/blob/main/src/main.cpp"
click node_signal "https://github.com/koonosuke/tsukechi-kushihara-waterlevel/blob/main/src/main.cpp"
click node_payload "https://github.com/koonosuke/tsukechi-kushihara-waterlevel/blob/main/src/main.cpp"
click node_recovery "https://github.com/koonosuke/tsukechi-kushihara-waterlevel/blob/main/src/main.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,node_distance toneBlue
class node_sender,node_signal,node_payload toneAmber
class node_nvs,node_recovery toneMint
class node_ultrasonic,node_modem,node_soracom toneIndigo
```

## Components

### Measurement

- [Firmware loop](https://github.com/koonosuke/tsukechi-kushihara-waterlevel/blob/main/src/main.cpp): `src/main.cpp`
- [Distance validation](https://github.com/koonosuke/tsukechi-kushihara-waterlevel/blob/main/src/main.cpp): `src/main.cpp`

### Cellular telemetry

- [Telemetry sender](https://github.com/koonosuke/tsukechi-kushihara-waterlevel/blob/main/src/main.cpp): `src/main.cpp`
- [Signal metrics](https://github.com/koonosuke/tsukechi-kushihara-waterlevel/blob/main/src/main.cpp): `src/main.cpp`
- [JSON report](https://github.com/koonosuke/tsukechi-kushihara-waterlevel/blob/main/src/main.cpp): `src/main.cpp`

### Failure recovery

- **NVS log store**
- [Retry and sleep](https://github.com/koonosuke/tsukechi-kushihara-waterlevel/blob/main/src/main.cpp): `src/main.cpp`

### Other components

- **Ultrasonic sensor**
- **LTE modem**
- **Soracom endpoint**

## Connections

- Firmware loop → Ultrasonic sensor: reads UART
- Firmware loop → Distance validation: validates frames
- Firmware loop → Telemetry sender: calls on sample
- Telemetry sender → Signal metrics: queries metrics
- Signal metrics → LTE modem: sends AT commands
- Telemetry sender → LTE modem: configures and posts
- Telemetry sender → NVS log store: reads prior logs
- Telemetry sender → JSON report: assembles report
- JSON report → LTE modem: writes request body
- LTE modem → Soracom endpoint: posts report
- Telemetry sender → NVS log store: stores failed-send metrics
- Telemetry sender → Retry and sleep: handles post failure
- Retry and sleep → LTE modem: switches power off