# yoyuqre/smartsense architecture

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

- Interactive diagram: https://gitdiagram.com/yoyuqre/smartsense
- Repository: https://github.com/yoyuqre/smartsense

## Overview

This is a capstone system with two distinct paths: ESP32 firmware samples room sensors and emits serial readings, while a simulated historical dataset feeds analysis, ML, anomaly detection, and fail-safe lighting/HVAC decisions. A Streamlit dashboard presents frozen replay results and includes a serial mode whose live-hardware validation remains outstanding. The graph follows documented phase boundaries and indexed source references; unsampled firmware and dashboard details are kept at the level the README supports.

Main entry points: [`src/phase5_run.py`](https://github.com/yoyuqre/smartsense/blob/main/src/phase5_run.py) (Historical replay), [`src/dashboard_data.py`](https://github.com/yoyuqre/smartsense/blob/main/src/dashboard_data.py) (Dashboard data access), [`src/preprocessing.py`](https://github.com/yoyuqre/smartsense/blob/main/src/preprocessing.py) (Validation and splits), [`src/modeling.py`](https://github.com/yoyuqre/smartsense/blob/main/src/modeling.py) (Model training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["Firmware"]
  node_firmware["ESP32 firmware<br/>[main.cpp]"]
  node_serial_output["Serial readings<br/>[main.cpp]"]
end

subgraph group_history["Historical data"]
  node_config["Shared configuration<br/>[config.py]"]
  node_generator["Dataset generator<br/>[data_generator.py]"]
  node_sensor_data["Frozen sensor data<br/>[sensor_data.csv]"]
end

subgraph group_analytics["Analysis and ML"]
  node_preprocessing["Validation and splits<br/>[preprocessing.py]"]
  node_eda["Exploratory analysis<br/>[eda.py]"]
  node_modeling["Model training<br/>[modeling.py]"]
  node_model_artifacts["Persisted models"]
end

subgraph group_control["Detection and control"]
  node_detection["Anomaly and health rules<br/>[detection.py]"]
  node_control_logic["Fail-safe decisions<br/>[control_logic.py]"]
  node_replay["Historical replay<br/>[phase5_run.py]"]
  node_control_output["Control decisions<br/>[control_output.csv]"]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_data["Dashboard data access<br/>[dashboard_data.py]"]
  node_dashboard["Streamlit dashboard<br/>[app.py]"]
end

node_room_sensors(("Room sensors"))
node_actuators(("Lighting and HVAC outputs"))

node_room_sensors -->|"provide readings"| node_firmware
node_firmware -->|"emits samples"| node_serial_output
node_config -->|"configures"| node_generator
node_generator -->|"generates"| node_sensor_data
node_sensor_data -->|"loads and validates"| node_preprocessing
node_preprocessing -->|"supplies data"| node_eda
node_preprocessing -->|"supplies splits"| node_modeling
node_generator -->|"provides generator reference"| node_modeling
node_modeling -->|"persists models"| node_model_artifacts
node_sensor_data -->|"replayed over"| node_replay
node_preprocessing -->|"loads dataset"| node_replay
node_modeling -->|"loads occupancy model"| node_replay
node_detection -->|"provides detection"| node_replay
node_control_logic -->|"provides decisions"| node_replay
node_replay -->|"writes replay results"| node_control_output
node_preprocessing -->|"loads frozen data"| node_dashboard_data
node_modeling -->|"provides metrics"| node_dashboard_data
node_detection -->|"provides detection rules"| node_dashboard_data
node_control_output -->|"reads replay output"| node_dashboard_data
node_dashboard_data -->|"serves dashboard data"| node_dashboard
node_serial_output -.->|"optional serial ingestion"| node_dashboard_data
node_firmware -->|"drives outputs"| node_actuators

click node_firmware "https://github.com/yoyuqre/smartsense/blob/main/src/main.cpp"
click node_serial_output "https://github.com/yoyuqre/smartsense/blob/main/src/main.cpp"
click node_config "https://github.com/yoyuqre/smartsense/blob/main/src/config.py"
click node_generator "https://github.com/yoyuqre/smartsense/blob/main/src/data_generator.py"
click node_sensor_data "https://github.com/yoyuqre/smartsense/blob/main/data/sensor_data.csv"
click node_preprocessing "https://github.com/yoyuqre/smartsense/blob/main/src/preprocessing.py"
click node_eda "https://github.com/yoyuqre/smartsense/blob/main/src/eda.py"
click node_modeling "https://github.com/yoyuqre/smartsense/blob/main/src/modeling.py"
click node_model_artifacts "https://github.com/yoyuqre/smartsense/blob/main/models/occupancy_model.pkl"
click node_detection "https://github.com/yoyuqre/smartsense/blob/main/src/detection.py"
click node_control_logic "https://github.com/yoyuqre/smartsense/blob/main/src/control_logic.py"
click node_replay "https://github.com/yoyuqre/smartsense/blob/main/src/phase5_run.py"
click node_control_output "https://github.com/yoyuqre/smartsense/blob/main/data/control_output.csv"
click node_dashboard_data "https://github.com/yoyuqre/smartsense/blob/main/src/dashboard_data.py"
click node_dashboard "https://github.com/yoyuqre/smartsense/blob/main/app.py"

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_serial_output toneBlue
class node_config,node_generator,node_sensor_data toneAmber
class node_preprocessing,node_eda,node_modeling,node_model_artifacts toneMint
class node_detection,node_control_logic,node_replay,node_control_output toneRose
class node_dashboard_data,node_dashboard,node_room_sensors,node_actuators toneIndigo
```

## Components

### Firmware

- [ESP32 firmware](https://github.com/yoyuqre/smartsense/blob/main/src/main.cpp): `src/main.cpp`
- [Serial readings](https://github.com/yoyuqre/smartsense/blob/main/src/main.cpp): `src/main.cpp`

### Historical data

- [Shared configuration](https://github.com/yoyuqre/smartsense/blob/main/src/config.py): `src/config.py`
- [Dataset generator](https://github.com/yoyuqre/smartsense/blob/main/src/data_generator.py): `src/data_generator.py`
- [Frozen sensor data](https://github.com/yoyuqre/smartsense/blob/main/data/sensor_data.csv): `data/sensor_data.csv`

### Analysis and ML

- [Validation and splits](https://github.com/yoyuqre/smartsense/blob/main/src/preprocessing.py): `src/preprocessing.py`
- [Exploratory analysis](https://github.com/yoyuqre/smartsense/blob/main/src/eda.py): `src/eda.py`
- [Model training](https://github.com/yoyuqre/smartsense/blob/main/src/modeling.py): `src/modeling.py`
- [Persisted models](https://github.com/yoyuqre/smartsense/blob/main/models/occupancy_model.pkl): `models/occupancy_model.pkl`

### Detection and control

- [Anomaly and health rules](https://github.com/yoyuqre/smartsense/blob/main/src/detection.py): `src/detection.py`
- [Fail-safe decisions](https://github.com/yoyuqre/smartsense/blob/main/src/control_logic.py): `src/control_logic.py`
- [Historical replay](https://github.com/yoyuqre/smartsense/blob/main/src/phase5_run.py): `src/phase5_run.py`
- [Control decisions](https://github.com/yoyuqre/smartsense/blob/main/data/control_output.csv): `data/control_output.csv`

### Dashboard

- [Dashboard data access](https://github.com/yoyuqre/smartsense/blob/main/src/dashboard_data.py): `src/dashboard_data.py`
- [Streamlit dashboard](https://github.com/yoyuqre/smartsense/blob/main/app.py): `app.py`

### Other components

- **Room sensors**
- **Lighting and HVAC outputs**

## Connections

- Room sensors → ESP32 firmware: provide readings (evidence: `README.md`)
- ESP32 firmware → Serial readings: emits samples (evidence: `README.md`)
- Shared configuration → Dataset generator: configures (evidence: `README.md`)
- Dataset generator → Frozen sensor data: generates (evidence: `README.md`)
- Frozen sensor data → Validation and splits: loads and validates (evidence: `src/preprocessing.py`)
- Validation and splits → Exploratory analysis: supplies data (evidence: `src/eda.py`)
- Validation and splits → Model training: supplies splits (evidence: `src/modeling.py`)
- Dataset generator → Model training: provides generator reference (evidence: `src/modeling.py`)
- Model training → Persisted models: persists models (evidence: `README.md`)
- Frozen sensor data → Historical replay: replayed over (evidence: `README.md`)
- Validation and splits → Historical replay: loads dataset (evidence: `src/phase5_run.py`)
- Model training → Historical replay: loads occupancy model (evidence: `src/phase5_run.py`)
- Anomaly and health rules → Historical replay: provides detection (evidence: `src/phase5_run.py`)
- Fail-safe decisions → Historical replay: provides decisions (evidence: `src/phase5_run.py`)
- Historical replay → Control decisions: writes replay results (evidence: `README.md`)
- Validation and splits → Dashboard data access: loads frozen data (evidence: `src/dashboard_data.py`)
- Model training → Dashboard data access: provides metrics (evidence: `src/dashboard_data.py`)
- Anomaly and health rules → Dashboard data access: provides detection rules (evidence: `src/dashboard_data.py`)
- Control decisions → Dashboard data access: reads replay output (evidence: `README.md`)
- Dashboard data access → Streamlit dashboard: serves dashboard data (evidence: `app.py`)
- Serial readings → Dashboard data access: optional serial ingestion (evidence: `README.md`)
- ESP32 firmware → Lighting and HVAC outputs: drives outputs (evidence: `README.md`)
