# nafell/goble architecture

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

- Interactive diagram: https://gitdiagram.com/nafell/goble
- Repository: https://github.com/nafell/goble

## Overview

##### Project Type and Purpose
- This project is a BLE IoT system that integrates Go (backend/gateway) and C++/Arduino (sensor node). It monitors environmental factors (using a CO2 sensor, i.e., MH-Z19C) and displays the results in an engaging, graphical manner.
- The system leverages Bluetooth on a PC/server to receive sensor data and a socket server (within the gateway) to push data to a frontend interface, ensuring real-time monitoring.

##### Analyzing the File Structure
- At the top level, you have two main directories within “src”:
- “Gateway”: Written in Go, containing several subdirectories:
◦ "ble": Handles Bluetooth communication between sensor devices and the gateway.
◦ "dbstuff": Contains submodules for database-related operations, including model generation (“model”), query generation (“query”), and additional utilities (like timer.go). This suggests usage of patterns for data modelling and querying.
◦ "main": Contains the entry point (main.go) that ties the components together.
◦ Configuration files (go.mod and go.sum) indicate dependency management for the Go backend.
- “Sensor”: Focused on sensor node code (under “goble_sensor”), including Arduino sketch (.ino) and C++ files (for processing sensor-specific data). These files support interfacing with the MH-Z19C CO2 sensor.

##### Insights from the README
- The README clearly states that the system uses Bluetooth for edge connection and sockets for sending data to a frontend.
- It also emphasizes that the sensor node is flashed onto an ESP32 (or similar BLE-enabled Arduino board) and that the PC/server must have Bluetooth capability.
- The provided drawio file and images (e.g., sensor node, sensor log) offer a visual hint of the high-level data flow and network interaction.

a. Main Components:
- Sensor Node:
- Hardware: ESP32/Arduino with BLE capability interfaced with a CO2 sensor (MH-Z19C).
- Software: Arduino sketch (goble_sensor.ino) and associated C++ modules.
- Gateway (Backend Server):
- Bluetooth Module (src/Gateway/ble): Receives BLE notifications from sensor nodes.
- Database / Data Handling Module (src/Gateway/dbstuff): Processes and structures sensor data, employing factory and query generation patterns.
- Main Application Logic (src/Gateway/main): The core service that initializes and ties the BLE and database functionalities.
- Data Distribution Layer:
- Socket Server: Though not explicitly separated as a folder, the README mentions using sockets to send data to a GUI/Frontend.
- (Optional) Frontend Component:
- While not explicitly coded in the provided structure, the system design should leave space to illustrate how sensor data is eventually displayed graphically.
- External Entities:
- PC/Server Machine with Bluetooth: Acts as the host for the gateway application.
- End Users: Viewing sensor graphs through the GUI.

b. Relationships and Interactions:
- Data Flow:
1. Sensor nodes capture environmental data (CO2 ppm) and transmit it via BLE.
2. The Gateway’s BLE module receives notifications.
3. Data is processed/stored via the database modules in “dbstuff” (using model and query generations).
4. The processed data is sent via a socket connection from the Gateway to the frontend or client application.
- Both the physical (hardware interactions with BLE and sensor) and logical (data layer, communication protocols) interactions.

c. Architectural Patterns and Design Principles:
- Modularization: Clear separation between sensor node code and backend gateway.
- Layered Architecture: Segregation of BLE communication, business/data logic, and presentation distribution (socket server).
- Use of factory and code generation patterns within the “dbstuff” module for handling data models and queries.
- Emphasis on IoT edge-computing design where sensors preprocess data and then push it to a centralized system.

d. Relevant Technologies:
- Go (for Gateway application logic, BLE handling, and database utilities)
- C++ and Arduino (for sensor node code)
- BLE and Socket protocols (for communication between sensor nodes and the gateway/GUI)
- Database abstraction libraries (inferred from the structured “dbstuff” package)

##### Final Steps
- Incorporate the external communication with the PC/server and client devices, making sure every block is clearly annotated.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Sensor Node Environment"
        sensor["Sensor Node: Arduino/ESP32 with CO2 Sensor (MH-Z19C)"]:::hardware
    end

    subgraph "Gateway (PC/Server with Bluetooth)"
        ble["Gateway – BLE Module"]:::software
        db["Gateway – Data Handling Module"]:::software
        main["Gateway – Main Application Logic"]:::software
    end

    socket["Socket/Frontend Interface"]:::software
    enduser["End Users (GUI)"]:::external

    sensor -->|"BLE_data"| ble
    ble -->|"process"| db
    db -->|"processed_data"| main
    main -->|"socket_data"| socket
    socket -->|"display"| enduser

    click sensor "https://github.com/nafell/goble/tree/main/src/Sensor/goble_sensor"
    click ble "https://github.com/nafell/goble/blob/main/src/Gateway/ble/ble.go"
    click db "https://github.com/nafell/goble/tree/main/src/Gateway/dbstuff"
    click main "https://github.com/nafell/goble/tree/main/src/Gateway/main"

    linkStyle 0 stroke:#0000ff,stroke-width:2px
    linkStyle 3 stroke:#00aa00,stroke-width:2px
    linkStyle 4 stroke:#00aa00,stroke-width:2px

    classDef hardware fill:#ffcc99,stroke:#d35400,stroke-width:2px;
    classDef software fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef external fill:#d6eaf8,stroke:#3498db,stroke-width:2px;
```
