# elyasb14/tinyweather architecture

> Architecture diagram of the GitHub repository elyasb14/tinyweather, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/elyasb14/tinyweather
- Repository: https://github.com/elyasb14/tinyweather

## Overview

This project is a weather station application named Tinyweather. Its primary purpose is to collect sensor data from various environmental sensors (specifically, the RG-15 rain gauge and the BME680 environmental sensor) and send the telemetry data via TCP/IP—optionally integrating with Prometheus for long-term storage. The project is written in Zig, and its structure is organized with a clear separation of sensor handling, communication protocols, and utility libraries.

##### Project Type and Purpose
- Tinyweather is an IoT-style full-stack monitoring application. It interfaces with various physical sensors and sends telemetry data over TCP connections.

##### Analyzing the File Structure
- Top-Level Directories and Files:
- The “src” directory contains the core of the application:
- "src/node.zig" and "src/proxy.zig" likely represent different modes or roles in the system.
- The "src/lib" subdirectory contains various libraries for handling arguments, devices, TCP communication, Prometheus integration, and sensor-specific drivers (e.g., for BME680 and RG15).
- The “docs” directory provides additional context about components like node, proxy, and compiler watch.
- The “scripts” directory includes bootstrap scripts for diverse components such as Grafana, Prometheus, and sensor node setups, which indicates there are deployment and initialization processes that must be considered.
- Additional elements:
- Build scripts (“build.zig”, “build.zig.zon”) are used to compile the project, while test cases in the “test” directory ensure sensor data accuracy.
- The presence of CI configuration in the “.github” directory shows continuous integration practices are integrated into the development process.

##### Defining Main Components
a. Sensor Modules:
- Two primary sensor drivers exist:
- BME680: Located in “src/lib/sensors/bme680”.
- RG15 Rain Gauge: Located in “src/lib/sensors/rg15” (includes both C and header files indicating a shared or native library integration).
- This component gathers raw environmental and precipitation data.
b. Communication Layer:
- TCP Library: “src/lib/tcp.zig” handles TCP networking.
- Handlers: “src/lib/handlers.zig” likely manages TCP events and data processing.
c. Telemetry and Monitoring:
- Integration with Prometheus: “src/lib/prometheus.zig” indicates direct support for Prometheus metrics, enabling long-term storage and monitoring.
d. Application Nodes:
- The “node” (src/node.zig) is likely an application entry-point handling sensor-read and data dispatch functions.
- The “proxy” (src/proxy.zig) might manage message routing or proxy functions for data, perhaps interacting with external systems.
e. Auxiliary and Utility Components:
- “src/lib/device.zig”, “src/lib/Args.zig”, and “src/lib/helpers.zig” provide configuration, device abstraction, and helper functions for overall operation.

##### Relationships and Data Flow
- Sensors send raw data to the sensor drivers, which format and possibly preprocess it.
- The “node” component acts as the core sensor data collector, which then passes the processed data to the TCP layer.
- The TCP layer, via “src/lib/tcp.zig” and “src/lib/handlers.zig”, establishes the network communication channel.
- Data is directed to Prometheus (and optionally Grafana as bootstrapped by the scripts) for monitoring/long-term storage.
- The “proxy” component might be used to route or manage data from sensors to external telemetry endpoints.

##### Architectural Patterns to Highlight
- Modular Design: Each sensor and protocol is modularized into separate libraries aiding in maintainability.
- Separation of Concerns: Distinct roles for sensor data acquisition, network communication, and telemetry (Prometheus) integration.
- Extensibility: The structure allows easy addition of new sensors by following similar patterns (e.g., adding new directories under “src/lib/sensors/”).
- CI/CD Integration: The GitHub workflows indicate automated building and testing, which supports robust deployment practices.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Sensor Drivers"
        BME680["BME680 Driver"]:::sensor
        RG15["RG15 Rain Gauge Driver"]:::sensor
    end

    subgraph "Application Core"
        Node["Tinyweather Node"]:::core
    end

    subgraph "Communication Modules"
        TCP["TCP Library"]:::comm
        Handlers["Handlers"]:::comm
    end

    subgraph "Telemetry"
        Prom["Prometheus Integration Module"]:::telem
    end

    subgraph "Proxy Service"
        Proxy["Proxy Service"]:::core
    end

    subgraph "Auxiliary Components"
        Device["Device Abstraction"]:::aux
        Args["Argument Parser"]:::aux
        Helpers["Helper Functions"]:::aux
    end

    %% Data Flow Relationships
    BME680 -->|"sends_data"| Node
    RG15 -->|"sends_data"| Node
    Node -->|"transmits"| TCP
    TCP -->|"handled_by"| Handlers
    Handlers -->|"forwards_to"| Prom
    Node -->|"routes_to"| Proxy

    %% Auxiliary usage (internal dependency)
    Node ---|"uses"| Device
    Node ---|"uses"| Args
    Node ---|"uses"| Helpers

    %% Click Events
    click BME680 "https://github.com/elyasb14/tinyweather/blob/main/src/lib/sensors/bme680/bme680.zig"
    click RG15 "https://github.com/elyasb14/tinyweather/tree/main/src/lib/sensors/rg15/"
    click TCP "https://github.com/elyasb14/tinyweather/blob/main/src/lib/tcp.zig"
    click Handlers "https://github.com/elyasb14/tinyweather/blob/main/src/lib/handlers.zig"
    click Prom "https://github.com/elyasb14/tinyweather/blob/main/src/lib/prometheus.zig"
    click Node "https://github.com/elyasb14/tinyweather/blob/main/src/node.zig"
    click Proxy "https://github.com/elyasb14/tinyweather/blob/main/src/proxy.zig"
    click Device "https://github.com/elyasb14/tinyweather/blob/main/src/lib/device.zig"
    click Args "https://github.com/elyasb14/tinyweather/blob/main/src/lib/Args.zig"
    click Helpers "https://github.com/elyasb14/tinyweather/blob/main/src/lib/helpers.zig"

    %% Styling
    classDef sensor fill:#F4A261,stroke:#000,stroke-width:2px;
    classDef core fill:#264653,stroke:#000,stroke-width:2px,color:#fff;
    classDef comm fill:#2A9D8F,stroke:#000,stroke-width:2px;
    classDef telem fill:#E9C46A,stroke:#000,stroke-width:2px;
    classDef aux fill:#8D99AE,stroke:#000,stroke-width:2px,color:#fff;
```
