# khadeer0503/home-energy-tracker architecture

> Architecture diagram of the GitHub repository khadeer0503/home-energy-tracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/khadeer0503/home-energy-tracker
- Repository: https://github.com/khadeer0503/home-energy-tracker

## Overview

Home Energy Tracker is a microservices system for household electricity monitoring. Smart-device readings enter through the ingestion API, are published to Kafka, and are processed for usage history and alerts; residents can also manage users and devices and query aggregated usage. The graph shows the documented relational and time-series storage roles, but the sampled excerpts do not establish the implementations’ exact persistence calls or the alert-event producer wiring. The README also describes gateway, security, and observability capabilities, but no corresponding source paths appear in this tree.

Main entry points: [`Services/Energy-Usage-Service/src/main/java/com/Home_Energy_Tracker/Energy_Usage_Service/service/ENERGYUSAGE_IMPL/EnergyUsageServiceIMPL.java`](https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/Energy-Usage-Service/src/main/java/com/Home_Energy_Tracker/Energy_Usage_Service/service/ENERGYUSAGE_IMPL/EnergyUsageServiceIMPL.java) (Usage processor), [`Services/IOT-Ingestion-Service/src/main/java/com/Home_Energy_Tracker/IOT_Ingestion_Service/service/INGESTION_IMPL/IngestionServiceImpl.java`](https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/IOT-Ingestion-Service/src/main/java/com/Home_Energy_Tracker/IOT_Ingestion_Service/service/INGESTION_IMPL/IngestionServiceImpl.java) (Ingestion service), [`Services/Alert-Service/src/main/java/com/Home_Energy_Tracker/Alert_Service/service/AlertService.java`](https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/Alert-Service/src/main/java/com/Home_Energy_Tracker/Alert_Service/service/AlertService.java) (Alert listener), [`Services/Alert-Service/src/main/java/com/Home_Energy_Tracker/Alert_Service/service/EmailService.java`](https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/Alert-Service/src/main/java/com/Home_Energy_Tracker/Alert_Service/service/EmailService.java) (Email service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Reading ingestion"]
  node_ingestion_api["Ingestion API"]
  node_ingestion_service["Ingestion service"]
  node_usage_event["Usage event"]
end

subgraph group_usage["Usage analytics"]
  node_usage_service["Usage processor"]
  node_usage_api["Usage API"]
  node_device_client["Device client<br/>[DeviceClient.java]"]
  node_user_client["User client<br/>[UserClient.java]"]
end

subgraph group_management["Account and devices"]
  node_device_api["Device API"]
  node_device_service["Device service"]
  node_device_repository["Device repository"]
  node_user_api["User API"]
  node_user_service["User service"]
  node_user_repository["User repository"]
end

subgraph group_alerts["Alert delivery"]
  node_alert_event["Alert event<br/>[AlertingEvent.java]"]
  node_alert_service["Alert listener<br/>[AlertService.java]"]
  node_email_service["Email service<br/>[EmailService.java]"]
  node_alert_repository["Alert repository"]
end

subgraph group_infrastructure["Messaging and storage"]
  node_energy_topic["Usage topic"]
  node_usage_store[("Time-series store")]
  node_alerts_topic["Alerts topic"]
  node_relational_store[("Relational store")]
end

node_device_actor(("Smart device"))
node_resident(("Resident"))
node_mail_provider["Mail provider"]

node_device_actor -->|"submits reading"| node_ingestion_api
node_ingestion_api -->|"calls"| node_ingestion_service
node_ingestion_service -->|"builds event"| node_usage_event
node_ingestion_service -->|"publishes"| node_energy_topic
node_energy_topic -.->|"delivers readings"| node_usage_service
node_resident -->|"requests history"| node_usage_api
node_usage_api -->|"calls"| node_usage_service
node_usage_service -.->|"queries and stores"| node_usage_store
node_usage_service -.->|"looks up devices"| node_device_client
node_usage_service -.->|"looks up users"| node_user_client
node_resident -->|"manages devices"| node_device_api
node_device_api -->|"calls"| node_device_service
node_device_service -->|"reads and writes"| node_device_repository
node_device_repository -.->|"persists"| node_relational_store
node_resident -->|"manages account"| node_user_api
node_user_api -->|"calls"| node_user_service
node_user_service -->|"reads and writes"| node_user_repository
node_user_repository -.->|"persists"| node_relational_store
node_alerts_topic -.->|"delivers alerts"| node_alert_service
node_alert_service -->|"receives event"| node_alert_event
node_alert_service -->|"calls"| node_email_service
node_email_service -->|"sends email"| node_mail_provider
node_email_service -->|"records delivery"| node_alert_repository
node_alert_repository -.->|"persists"| node_relational_store

click node_ingestion_api "https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/IOT-Ingestion-Service/src/main/java/com/Home_Energy_Tracker/IOT_Ingestion_Service/controller/IngestionController.java"
click node_ingestion_service "https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/IOT-Ingestion-Service/src/main/java/com/Home_Energy_Tracker/IOT_Ingestion_Service/service/INGESTION_IMPL/IngestionServiceImpl.java"
click node_usage_event "https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/IOT-Ingestion-Service/src/main/java/com/Home_Energy_Tracker/kafka/event/EnergyUsageEvent.java"
click node_usage_service "https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/Energy-Usage-Service/src/main/java/com/Home_Energy_Tracker/Energy_Usage_Service/service/ENERGYUSAGE_IMPL/EnergyUsageServiceIMPL.java"
click node_usage_api "https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/Energy-Usage-Service/src/main/java/com/Home_Energy_Tracker/Energy_Usage_Service/controller/EnergyUsageController.java"
click node_usage_store "https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/Energy-Usage-Service/src/main/java/com/Home_Energy_Tracker/Energy_Usage_Service/config/InfluxDBConfig.java"
click node_device_client "https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/Energy-Usage-Service/src/main/java/com/Home_Energy_Tracker/Energy_Usage_Service/client/DeviceClient.java"
click node_user_client "https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/Energy-Usage-Service/src/main/java/com/Home_Energy_Tracker/Energy_Usage_Service/client/UserClient.java"
click node_device_api "https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/Device-Service/src/main/java/com/Home_Energy_Tracker/Device_Service/controller/DeviceController.java"
click node_device_service "https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/Device-Service/src/main/java/com/Home_Energy_Tracker/Device_Service/service/DEVICE_IMPL/DeviceServiceImpl.java"
click node_device_repository "https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/Device-Service/src/main/java/com/Home_Energy_Tracker/Device_Service/repository/DeviceRepository.java"
click node_user_api "https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/User-Service/src/main/java/com/Home_Energy_Tracker/User_Service/controller/UserController.java"
click node_user_service "https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/User-Service/src/main/java/com/Home_Energy_Tracker/User_Service/service/USER_IMPL/UserServiceImpl.java"
click node_user_repository "https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/User-Service/src/main/java/com/Home_Energy_Tracker/User_Service/repository/UserRepository.java"
click node_alert_event "https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/Alert-Service/src/main/java/Kafka/event/AlertingEvent.java"
click node_alert_service "https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/Alert-Service/src/main/java/com/Home_Energy_Tracker/Alert_Service/service/AlertService.java"
click node_email_service "https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/Alert-Service/src/main/java/com/Home_Energy_Tracker/Alert_Service/service/EmailService.java"
click node_alert_repository "https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/Alert-Service/src/main/java/com/Home_Energy_Tracker/Alert_Service/repository/AlertRepository.java"

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_ingestion_api,node_ingestion_service,node_usage_event toneBlue
class node_usage_service,node_usage_api,node_device_client,node_user_client toneAmber
class node_device_api,node_device_service,node_device_repository,node_user_api,node_user_service,node_user_repository toneMint
class node_alert_event,node_alert_service,node_email_service,node_alert_repository toneRose
class node_energy_topic,node_usage_store,node_alerts_topic,node_relational_store,node_device_actor,node_resident,node_mail_provider toneIndigo
```

## Components

### Reading ingestion

- [Ingestion API](https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/IOT-Ingestion-Service/src/main/java/com/Home_Energy_Tracker/IOT_Ingestion_Service/controller/IngestionController.java): `Services/IOT-Ingestion-Service/src/main/java/com/Home_Energy_Tracker/IOT_Ingestion_Service/controller/IngestionController.java`
- [Ingestion service](https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/IOT-Ingestion-Service/src/main/java/com/Home_Energy_Tracker/IOT_Ingestion_Service/service/INGESTION_IMPL/IngestionServiceImpl.java): `Services/IOT-Ingestion-Service/src/main/java/com/Home_Energy_Tracker/IOT_Ingestion_Service/service/INGESTION_IMPL/IngestionServiceImpl.java`
- [Usage event](https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/IOT-Ingestion-Service/src/main/java/com/Home_Energy_Tracker/kafka/event/EnergyUsageEvent.java): `Services/IOT-Ingestion-Service/src/main/java/com/Home_Energy_Tracker/kafka/event/EnergyUsageEvent.java`

### Usage analytics

- [Usage processor](https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/Energy-Usage-Service/src/main/java/com/Home_Energy_Tracker/Energy_Usage_Service/service/ENERGYUSAGE_IMPL/EnergyUsageServiceIMPL.java): `Services/Energy-Usage-Service/src/main/java/com/Home_Energy_Tracker/Energy_Usage_Service/service/ENERGYUSAGE_IMPL/EnergyUsageServiceIMPL.java`
- [Usage API](https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/Energy-Usage-Service/src/main/java/com/Home_Energy_Tracker/Energy_Usage_Service/controller/EnergyUsageController.java): `Services/Energy-Usage-Service/src/main/java/com/Home_Energy_Tracker/Energy_Usage_Service/controller/EnergyUsageController.java`
- [Device client](https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/Energy-Usage-Service/src/main/java/com/Home_Energy_Tracker/Energy_Usage_Service/client/DeviceClient.java): `Services/Energy-Usage-Service/src/main/java/com/Home_Energy_Tracker/Energy_Usage_Service/client/DeviceClient.java`
- [User client](https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/Energy-Usage-Service/src/main/java/com/Home_Energy_Tracker/Energy_Usage_Service/client/UserClient.java): `Services/Energy-Usage-Service/src/main/java/com/Home_Energy_Tracker/Energy_Usage_Service/client/UserClient.java`

### Account and devices

- [Device API](https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/Device-Service/src/main/java/com/Home_Energy_Tracker/Device_Service/controller/DeviceController.java): `Services/Device-Service/src/main/java/com/Home_Energy_Tracker/Device_Service/controller/DeviceController.java`
- [Device service](https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/Device-Service/src/main/java/com/Home_Energy_Tracker/Device_Service/service/DEVICE_IMPL/DeviceServiceImpl.java): `Services/Device-Service/src/main/java/com/Home_Energy_Tracker/Device_Service/service/DEVICE_IMPL/DeviceServiceImpl.java`
- [Device repository](https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/Device-Service/src/main/java/com/Home_Energy_Tracker/Device_Service/repository/DeviceRepository.java): `Services/Device-Service/src/main/java/com/Home_Energy_Tracker/Device_Service/repository/DeviceRepository.java`
- [User API](https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/User-Service/src/main/java/com/Home_Energy_Tracker/User_Service/controller/UserController.java): `Services/User-Service/src/main/java/com/Home_Energy_Tracker/User_Service/controller/UserController.java`
- [User service](https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/User-Service/src/main/java/com/Home_Energy_Tracker/User_Service/service/USER_IMPL/UserServiceImpl.java): `Services/User-Service/src/main/java/com/Home_Energy_Tracker/User_Service/service/USER_IMPL/UserServiceImpl.java`
- [User repository](https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/User-Service/src/main/java/com/Home_Energy_Tracker/User_Service/repository/UserRepository.java): `Services/User-Service/src/main/java/com/Home_Energy_Tracker/User_Service/repository/UserRepository.java`

### Alert delivery

- [Alert event](https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/Alert-Service/src/main/java/Kafka/event/AlertingEvent.java): `Services/Alert-Service/src/main/java/Kafka/event/AlertingEvent.java`
- [Alert listener](https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/Alert-Service/src/main/java/com/Home_Energy_Tracker/Alert_Service/service/AlertService.java): `Services/Alert-Service/src/main/java/com/Home_Energy_Tracker/Alert_Service/service/AlertService.java`
- [Email service](https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/Alert-Service/src/main/java/com/Home_Energy_Tracker/Alert_Service/service/EmailService.java): `Services/Alert-Service/src/main/java/com/Home_Energy_Tracker/Alert_Service/service/EmailService.java`
- [Alert repository](https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/Alert-Service/src/main/java/com/Home_Energy_Tracker/Alert_Service/repository/AlertRepository.java): `Services/Alert-Service/src/main/java/com/Home_Energy_Tracker/Alert_Service/repository/AlertRepository.java`

### Messaging and storage

- **Usage topic**
- [Time-series store](https://github.com/khadeer0503/home-energy-tracker/blob/main/Services/Energy-Usage-Service/src/main/java/com/Home_Energy_Tracker/Energy_Usage_Service/config/InfluxDBConfig.java): `Services/Energy-Usage-Service/src/main/java/com/Home_Energy_Tracker/Energy_Usage_Service/config/InfluxDBConfig.java`
- **Alerts topic**
- **Relational store**

### Other components

- **Smart device**
- **Resident**
- **Mail provider**

## Connections

- Smart device → Ingestion API: submits reading
- Ingestion API → Ingestion service: calls
- Ingestion service → Usage event: builds event
- Ingestion service → Usage topic: publishes
- Usage topic → Usage processor: delivers readings
- Resident → Usage API: requests history
- Usage API → Usage processor: calls
- Usage processor → Time-series store: queries and stores
- Usage processor → Device client: looks up devices
- Usage processor → User client: looks up users
- Resident → Device API: manages devices
- Device API → Device service: calls
- Device service → Device repository: reads and writes
- Device repository → Relational store: persists
- Resident → User API: manages account
- User API → User service: calls
- User service → User repository: reads and writes
- User repository → Relational store: persists
- Alerts topic → Alert listener: delivers alerts
- Alert listener → Alert event: receives event
- Alert listener → Email service: calls
- Email service → Mail provider: sends email
- Email service → Alert repository: records delivery
- Alert repository → Relational store: persists