# andresvasped/signs_of_instability architecture

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

- Interactive diagram: https://gitdiagram.com/andresvasped/signs_of_instability
- Repository: https://github.com/andresvasped/signs_of_instability

## Overview

##### Project type and purpose
- This is an embedded IoT application running on an ESP32 using the ESP-IDF framework.
- Its goal is to read environmental data (e.g., moisture, pressure) via I²C sensors, run a rainfall/landslide-risk prediction algorithm locally, and display results on an I²C-driven LCD1602.

##### File structure
- Top-level build files: CMakeLists.txt, platformio.ini, sdkconfig.esp32dev
- src/ contains main.c and its own CMakeLists.txt – the entry point and application logic.
- / holds project-wide headers.
- lib/ includes two reusable components:
– esp32-smbus: a generic SMBus/I²C driver library
– esp32-i2c-lcd1602: an I²C LCD driver for the 1602 display
- test/ is reserved for unit or integration tests.

##### README for additional insights
- Confirms use of ESP32 + ESP-IDF to predict precipitation in landslide-prone regions.
- Implies data acquisition, local computation, and on-device feedback (LCD).

a. Main components
– Hardware layer:
- ESP32 microcontroller
- Environmental sensor(s) (e.g., BME280) on the shared I²C/SMBus
- I²C-LCD1602 display module
– Software layer (inside ESP32):
- ESP-IDF RTOS + Wi-Fi stack (optional for future telemetry)
- HAL/I²C driver (from ESP-IDF)
- esp32-smbus library (abstract SMBus transactions)
- esp32-i2c-lcd1602 library (LCD driver)
- Application modules:
· Data acquisition service
· Prediction algorithm
· Display/update service
– Build/deploy tools: CMake, PlatformIO, Wokwi simulator

b. Relationships & interactions
– The application calls the SMBus library to configure/read sensors via the I²C bus.
– Sensor data feeds into the prediction algorithm module.
– Algorithm output is passed to the LCD driver to update the display.
– All software modules sit on top of the ESP-IDF’s HAL and FreeRTOS scheduler.
– Build tools orchestrate compilation and flash the firmware onto the ESP32.

c. Architectural patterns & principles
– Layered architecture: Hardware Abstraction → Driver Libraries → Application Logic
– Separation of concerns: each library handles a single interface (SMBus, LCD)
– Modular design: easy to swap sensor or display by replacing the corresponding library

d. Key technologies & frameworks
– ESP-IDF (FreeRTOS, HAL, I²C peripheral drivers)
– CMake (build configuration)
– PlatformIO (alternative build & upload tool)
– Wokwi (hardware simulation)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Hardware Layer
    subgraph "Hardware Layer"
        direction TB
        ESP32["ESP32 Microcontroller"]:::hardware
        I2C_BUS["I²C Bus"]:::hardware
        Sensor["Environmental Sensor (e.g., BME280)"]:::hardware
        LCD["I²C LCD1602 Display"]:::hardware
    end

    %% Software Layer
    subgraph "Software Layer"
        direction TB
        subgraph "Framework"
            ESP_IDF["ESP-IDF (HAL, FreeRTOS, I²C)"]:::framework
        end
        subgraph "Driver Libraries"
            SMBUS["esp32-smbus"]:::library
            LCD_LIB["esp32-i2c-lcd1602"]:::library
        end
        subgraph "Application Modules"
            Acquisition["Data Acquisition Service"]:::application
            Prediction["Prediction Engine"]:::application
            DisplaySvc["Display/Update Service"]:::application
        end
    end

    %% Build & Tools
    subgraph "Build & Toolchain"
        direction TB
        CMAKE["CMakeLists.txt"]:::framework
        PLATFORMIO["platformio.ini"]:::framework
        WOKWI["wokwi.toml"]:::framework
        SDKCFG["sdkconfig.esp32dev"]:::framework
        README["README.md"]:::framework
    end

    %% Connections: Hardware to Software
    ESP32 -->|uses I²C| I2C_BUS
    I2C_BUS -->|connects| Sensor
    I2C_BUS -->|connects| LCD

    %% Software layering
    ESP32 --> ESP_IDF
    ESP_IDF --> SMBUS
    ESP_IDF --> LCD_LIB

    %% Data flow
    Sensor -->|raw data| Acquisition
    Acquisition -->|sensor data| Prediction
    Prediction -->|predicted risk| DisplaySvc
    DisplaySvc -->|display update| LCD

    %% Application calls drivers
    Acquisition -->|I²C read| SMBUS
    DisplaySvc -->|I²C write| LCD_LIB

    %% Build tools interactions
    CMAKE -->|builds| ESP32
    PLATFORMIO -->|builds| ESP32
    WOKWI -->|simulates| ESP32
    SDKCFG -->|configures| ESP_IDF
    README -->|documents| ESP32

    %% Click Events
    click ESP_IDF "https://github.com/andresvasped/signs_of_instability/blob/main/CMakeLists.txt"
    click PLATFORMIO "https://github.com/andresvasped/signs_of_instability/blob/main/platformio.ini"
    click WOKWI "https://github.com/andresvasped/signs_of_instability/blob/main/wokwi.toml"
    click SDKCFG "https://github.com/andresvasped/signs_of_instability/blob/main/sdkconfig.esp32dev"
    click Acquisition "https://github.com/andresvasped/signs_of_instability/blob/main/src/main.c"
    click CMAKE "https://github.com/andresvasped/signs_of_instability/blob/main/src/CMakeLists.txt"
    click README "https://github.com/andresvasped/signs_of_instability/blob/main/README.md"
    click SMBUS "https://github.com/andresvasped/signs_of_instability/tree/main/lib/esp32-smbus/"
    click LCD_LIB "https://github.com/andresvasped/signs_of_instability/tree/main/lib/esp32-i2c-lcd1602/"
    click TEST_PLACEHOLDER "https://github.com/andresvasped/signs_of_instability/tree/main/test/"
    click DIAGRAM_SRC "https://github.com/andresvasped/signs_of_instability/blob/main/diagram.json"

    %% Styles
    classDef hardware fill:#add8e6,stroke:#000,stroke-width:1px
    classDef library fill:#90ee90,stroke:#000,stroke-width:1px
    classDef application fill:#ffa500,stroke:#000,stroke-width:1px
    classDef framework fill:#d3d3d3,stroke:#000,stroke-width:1px
```
