# muhil-amuthan/carbonwise-application architecture

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

- Interactive diagram: https://gitdiagram.com/muhil-amuthan/carbonwise-application
- Repository: https://github.com/muhil-amuthan/carbonwise-application

## Overview

CarbonWise is a carbon-intelligence platform for consumers and city/system administrators. The documented workflow runs from user and city sensor/device activity through the Spring API and AI forecasts/recommendations to dashboards, appliance timing, alerts, and reports; IoT devices exchange telemetry and control messages over MQTT. The graph preserves the major documented capabilities, but several are represented at directory level because their implementation files were not sampled. Some README integrations are documented architecture rather than verified runtime calls.

Main entry points: [`carbonwise-backend/src/main/java/com/carbonwise/controller`](https://github.com/muhil-amuthan/carbonwise-application/tree/main/carbonwise-backend/src/main/java/com/carbonwise/controller) (REST Controllers), [`carbonwise-ai/api/app.py`](https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-ai/api/app.py) (AI HTTP API), [`carbonwise-iot/gateway/mqtt_gateway.py`](https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-iot/gateway/mqtt_gateway.py) (MQTT Gateway), [`carbonwise-backend/src/main/java/com/carbonwise/service/AuthService.java`](https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-backend/src/main/java/com/carbonwise/service/AuthService.java) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Spring API"]
  node_api["REST Controllers"]
  node_auth["Authentication<br/>[AuthService.java]"]
  node_devices["Appliance Devices"]
  node_schedules["Scheduling"]
  node_citygis["City GIS<br/>[GisController.java]"]
  node_sensors["Sensor Monitoring"]
  node_reports["Reports<br/>[ReportService.java]"]
  node_notifications["Notifications"]
  node_ai_client["AI Service Client"]
  node_prediction_service["Prediction Service"]
end

subgraph group_intelligence["Carbon Intelligence"]
  node_ai_api["AI HTTP API<br/>[app.py]"]
  node_predictor["Carbon Predictor<br/>[predictor.py]"]
  node_recommender["Recommendation Engine<br/>[recommender.py]"]
  node_training["Model Training<br/>[train.py]"]
  node_preprocessing["Data Cleaning<br/>[data_cleaner.py]"]
  node_evaluation["Model Evaluation<br/>[evaluate.py]"]
end

subgraph group_iot["IoT Network"]
  node_mqtt_service["MQTT Service<br/>[MqttService.java]"]
  node_gateway["MQTT Gateway<br/>[mqtt_gateway.py]"]
  node_sensor_node["ESP32 Sensor<br/>[sensor_node.cpp]"]
  node_device_firmware["Device Controllers"]
end

subgraph group_persistence["Persistence"]
  node_database[("PostgreSQL")]
end

node_consumer(("Consumer"))
node_cityadmin(("City Admin"))
node_systemadmin(("System Admin"))
node_mqtt_broker["MQTT Broker"]
node_maps["Google Maps API"]
node_firebase["Firebase Services"]

node_consumer -->|"uses"| node_api
node_cityadmin -->|"uses"| node_api
node_systemadmin -->|"uses"| node_api
node_api -.->|"routes auth"| node_auth
node_api -.->|"routes devices"| node_devices
node_api -.->|"routes schedules"| node_schedules
node_api -.->|"routes GIS"| node_citygis
node_api -.->|"routes sensors"| node_sensors
node_api -.->|"routes reports"| node_reports
node_api -.->|"routes alerts"| node_notifications
node_api -.->|"routes forecasts"| node_prediction_service
node_prediction_service -->|"requests forecast"| node_ai_api
node_ai_api -->|"calls"| node_predictor
node_ai_api -->|"calls"| node_recommender
node_citygis -.->|"map integration"| node_maps
node_sensors -.->|"telemetry path"| node_mqtt_service
node_mqtt_service -->|"communicates"| node_mqtt_broker
node_gateway -->|"communicates"| node_mqtt_broker
node_sensor_node -.->|"sends telemetry"| node_gateway
node_device_firmware -.->|"receives control"| node_gateway
node_auth -.->|"persists users"| node_database
node_devices -.->|"reads/writes devices"| node_database
node_reports -->|"reads reports"| node_database
node_notifications -->|"saves alerts"| node_database
node_training -.->|"uses cleaned data"| node_preprocessing
node_evaluation -.->|"evaluates models"| node_training
node_api -.->|"push/storage integration"| node_firebase

click node_api "https://github.com/muhil-amuthan/carbonwise-application/tree/main/carbonwise-backend/src/main/java/com/carbonwise/controller"
click node_auth "https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-backend/src/main/java/com/carbonwise/service/AuthService.java"
click node_devices "https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-backend/src/main/java/com/carbonwise/controller/DeviceController.java"
click node_schedules "https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-backend/src/main/java/com/carbonwise/controller/ScheduleController.java"
click node_citygis "https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-backend/src/main/java/com/carbonwise/controller/GisController.java"
click node_sensors "https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-backend/src/main/java/com/carbonwise/controller/SensorController.java"
click node_reports "https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-backend/src/main/java/com/carbonwise/service/ReportService.java"
click node_notifications "https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-backend/src/main/java/com/carbonwise/notification/NotificationService.java"
click node_ai_client "https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-backend/src/main/java/com/carbonwise/ai/AiServiceClient.java"
click node_prediction_service "https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-backend/src/main/java/com/carbonwise/service/PredictionService.java"
click node_ai_api "https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-ai/api/app.py"
click node_predictor "https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-ai/prediction/predictor.py"
click node_recommender "https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-ai/recommendation/recommender.py"
click node_training "https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-ai/training/train.py"
click node_preprocessing "https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-ai/preprocessing/data_cleaner.py"
click node_evaluation "https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-ai/evaluation/evaluate.py"
click node_mqtt_service "https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-backend/src/main/java/com/carbonwise/mqtt/MqttService.java"
click node_gateway "https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-iot/gateway/mqtt_gateway.py"
click node_sensor_node "https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-iot/esp32/sensor_node.cpp"
click node_device_firmware "https://github.com/muhil-amuthan/carbonwise-application/tree/main/carbonwise-iot/firmware"

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_api,node_auth,node_devices,node_schedules,node_citygis,node_sensors,node_reports,node_notifications,node_ai_client,node_prediction_service toneBlue
class node_ai_api,node_predictor,node_recommender,node_training,node_preprocessing,node_evaluation toneAmber
class node_mqtt_service,node_gateway,node_sensor_node,node_device_firmware,node_maps toneMint
class node_database toneRose
class node_consumer,node_cityadmin,node_systemadmin,node_mqtt_broker,node_firebase toneIndigo
```

## Components

### Spring API

- [REST Controllers](https://github.com/muhil-amuthan/carbonwise-application/tree/main/carbonwise-backend/src/main/java/com/carbonwise/controller): `carbonwise-backend/src/main/java/com/carbonwise/controller`
- [Authentication](https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-backend/src/main/java/com/carbonwise/service/AuthService.java): `carbonwise-backend/src/main/java/com/carbonwise/service/AuthService.java`
- [Appliance Devices](https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-backend/src/main/java/com/carbonwise/controller/DeviceController.java): `carbonwise-backend/src/main/java/com/carbonwise/controller/DeviceController.java`
- [Scheduling](https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-backend/src/main/java/com/carbonwise/controller/ScheduleController.java): `carbonwise-backend/src/main/java/com/carbonwise/controller/ScheduleController.java`
- [City GIS](https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-backend/src/main/java/com/carbonwise/controller/GisController.java): `carbonwise-backend/src/main/java/com/carbonwise/controller/GisController.java`
- [Sensor Monitoring](https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-backend/src/main/java/com/carbonwise/controller/SensorController.java): `carbonwise-backend/src/main/java/com/carbonwise/controller/SensorController.java`
- [Reports](https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-backend/src/main/java/com/carbonwise/service/ReportService.java): `carbonwise-backend/src/main/java/com/carbonwise/service/ReportService.java`
- [Notifications](https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-backend/src/main/java/com/carbonwise/notification/NotificationService.java): `carbonwise-backend/src/main/java/com/carbonwise/notification/NotificationService.java`
- [AI Service Client](https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-backend/src/main/java/com/carbonwise/ai/AiServiceClient.java): `carbonwise-backend/src/main/java/com/carbonwise/ai/AiServiceClient.java`
- [Prediction Service](https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-backend/src/main/java/com/carbonwise/service/PredictionService.java): `carbonwise-backend/src/main/java/com/carbonwise/service/PredictionService.java`

### Carbon Intelligence

- [AI HTTP API](https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-ai/api/app.py): `carbonwise-ai/api/app.py`
- [Carbon Predictor](https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-ai/prediction/predictor.py): `carbonwise-ai/prediction/predictor.py`
- [Recommendation Engine](https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-ai/recommendation/recommender.py): `carbonwise-ai/recommendation/recommender.py`
- [Model Training](https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-ai/training/train.py): `carbonwise-ai/training/train.py`
- [Data Cleaning](https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-ai/preprocessing/data_cleaner.py): `carbonwise-ai/preprocessing/data_cleaner.py`
- [Model Evaluation](https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-ai/evaluation/evaluate.py): `carbonwise-ai/evaluation/evaluate.py`

### IoT Network

- [MQTT Service](https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-backend/src/main/java/com/carbonwise/mqtt/MqttService.java): `carbonwise-backend/src/main/java/com/carbonwise/mqtt/MqttService.java`
- [MQTT Gateway](https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-iot/gateway/mqtt_gateway.py): `carbonwise-iot/gateway/mqtt_gateway.py`
- [ESP32 Sensor](https://github.com/muhil-amuthan/carbonwise-application/blob/main/carbonwise-iot/esp32/sensor_node.cpp): `carbonwise-iot/esp32/sensor_node.cpp`
- [Device Controllers](https://github.com/muhil-amuthan/carbonwise-application/tree/main/carbonwise-iot/firmware): `carbonwise-iot/firmware`

### Persistence

- **PostgreSQL**

### Other components

- **Consumer**
- **City Admin**
- **System Admin**
- **MQTT Broker**
- **Google Maps API**
- **Firebase Services**

## Connections

- Consumer → REST Controllers: uses (evidence: `README.md`)
- City Admin → REST Controllers: uses (evidence: `README.md`)
- System Admin → REST Controllers: uses (evidence: `README.md`)
- REST Controllers → Authentication: routes auth
- REST Controllers → Appliance Devices: routes devices
- REST Controllers → Scheduling: routes schedules
- REST Controllers → City GIS: routes GIS
- REST Controllers → Sensor Monitoring: routes sensors
- REST Controllers → Reports: routes reports
- REST Controllers → Notifications: routes alerts
- REST Controllers → Prediction Service: routes forecasts
- Prediction Service → AI HTTP API: requests forecast (evidence: `carbonwise-backend/src/main/java/com/carbonwise/service/PredictionService.java`)
- AI HTTP API → Carbon Predictor: calls (evidence: `carbonwise-ai/api/app.py`)
- AI HTTP API → Recommendation Engine: calls (evidence: `carbonwise-ai/api/app.py`)
- City GIS → Google Maps API: map integration (evidence: `README.md`)
- Sensor Monitoring → MQTT Service: telemetry path (evidence: `README.md`)
- MQTT Service → MQTT Broker: communicates (evidence: `README.md`)
- MQTT Gateway → MQTT Broker: communicates (evidence: `README.md`)
- ESP32 Sensor → MQTT Gateway: sends telemetry (evidence: `README.md`)
- Device Controllers → MQTT Gateway: receives control (evidence: `README.md`)
- Authentication → PostgreSQL: persists users
- Appliance Devices → PostgreSQL: reads/writes devices
- Reports → PostgreSQL: reads reports (evidence: `carbonwise-backend/src/main/java/com/carbonwise/service/ReportService.java`)
- Notifications → PostgreSQL: saves alerts (evidence: `carbonwise-backend/src/main/java/com/carbonwise/notification/NotificationService.java`)
- Model Training → Data Cleaning: uses cleaned data
- Model Evaluation → Model Training: evaluates models
- REST Controllers → Firebase Services: push/storage integration (evidence: `README.md`)
