# khushalsehrawat/suems architecture

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

- Interactive diagram: https://gitdiagram.com/khushalsehrawat/suems
- Repository: https://github.com/khushalsehrawat/suems

## Overview

##### Project type and purpose
- This is a standalone backend service, implemented in Spring Boot 3 (Java 21), exposing a REST API for managing energy sources and streaming time-series sensor data. It includes a built-in scheduler that synthesizes readings. There is no bundled frontend—clients (e.g., web apps or scripts) consume the API over HTTP/JSON.

##### File structure
- Top-level configuration: pom.xml, Maven wrapper, application.properties.
- src/main/java/com/suems:
- SuemsApplication.java – Spring Boot entry point (annotated with @SpringBootApplication and @EnableScheduling).
- config/ – CorsConfig, jacksonConfig for global CORS and JSON date/time settings.
- controller/ – EnergySourceController, SensorDataController (HTTP endpoints).
- exception/ – GlobalExceptionHandler, NotFoundException.
- mappers/ – entity↔DTO conversions.
- model/ – JPA entities and enums (EnergySource, SensorData, EnergyType, EnergyStatus).
- repository/ – Spring Data JPA interfaces.
- service/ – business logic and summary calculations.
- simulator/ – DataSimulator (scheduled bean that pushes fake sensor readings into the service).
- Resources: application.properties drives DB connection, JPA DDL, scheduling flags.
- Tests: a basic SuemsApplicationTests.

##### README for additional insights
- It states core features: CRUD endpoints, recent/after/summary queries, toggleable simulator.
- Technology stack: Spring Boot, Spring Data JPA, MySQL, Maven, Java 21.

a. Main components
- External Client(s) (e.g., Web UI, curl scripts, other services)
- Spring Boot REST API container
- Controllers layer
- Services layer (business logic + summary calc)
- Simulator (Scheduled task component)
- Repositories (Spring Data JPA)
- MySQL database
b. Relationships and interactions
- Client → API (HTTP/JSON)
- API → Controller classes (request mapping)
- Controller → Service (method calls)
- Service → Repository (save/query)
- Repository → MySQL (SQL via JDBC/Hibernate)
- Simulator (Spring @Scheduled) → Service.saveSensorData() → Repository → DB
c. Architectural patterns & design principles
- Layered architecture (Controller → Service → Repository)
- Dependency injection (Spring-managed beans)
- Scheduler pattern for periodic synthetic data generation
- DTO pattern decoupling API schema from internal entities
- Global exception handling (ControllerAdvice)
d. Key technologies/frameworks/libraries
- Java 21, Spring Boot 3 (Web, Data JPA, Scheduling)
- MySQL 8
- Jackson (JavaTimeModule)
- Maven
- Lombok (if present) / Java records (not used here)
- Spring’s CORS support

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External and Configuration
    subgraph "External & Config" 
        direction TB
        Client["External Clients\n(Web UI, scripts)"]:::external
        CorsCfg["CorsConfig"]:::config
        JacksonCfg["jacksonConfig"]:::config
        AppProps["application.properties"]:::config
    end

    %% Spring Boot Application Entry
    SuemsApp["SuemsApplication"]:::external

    %% Controllers Layer
    subgraph "Controllers" 
        direction TB
        ESC["EnergySourceController"]:::controller
        SDC["SensorDataController"]:::controller
        GEH["GlobalExceptionHandler"]:::controller
        NFE["NotFoundException"]:::controller
    end

    %% DTOs Layer
    subgraph "DTOs" 
        direction TB
        ED["EnergySourceDto"]:::dto
        SDT["SensorDataDto"]:::dto
        SUMD["SummaryDto"]:::dto
        AE["ApiError"]:::dto
    end

    %% Mapping Layer
    MAPPERS["Mappers\n(Entity↔DTO)"]:::service

    %% Services & Simulator
    subgraph "Business Layer"
        direction TB
        ESS["EnergySourceService"]:::service
        SDS["SensorDataService"]:::service
        SIM["DataSimulator\n(scheduler)"]:::service
    end

    %% Repositories Layer
    subgraph "Data Layer"
        direction TB
        ESR["EnergySourceRepository"]:::repo
        SDR["SensorDataRepository"]:::repo
    end

    %% Database
    DB["MySQL Database\n(suems)"]:::db

    %% Relationships
    Client -->|"HTTP/JSON"| ESC
    Client -->|"HTTP/JSON"| SDC
    SuemsApp --> ESC
    SuemsApp --> SDC
    SuemsApp --> ESS
    SuemsApp --> SDS
    CorsCfg --> ESC
    CorsCfg --> SDC
    JacksonCfg --> ESC
    JacksonCfg --> SDC
    AppProps --> SIM
    ESC -->|uses| ED
    SDC -->|uses| SDT
    ESC -->|calls| MAPPERS
    SDC -->|calls| MAPPERS
    MAPPERS -->|to Entities| ESS
    MAPPERS -->|to Entities| SDS
    ESS -->|CRUD| ESR
    SDS -->|CRUD| SDR
    ESR -->|SQL| DB
    SDR -->|SQL| DB
    SIM -->|schedules| SDS
    GEH -->|handles exceptions| ESC
    GEH -->|handles exceptions| SDC
    GEH -->|emits| AE
    NFE --> GEH

    %% Click Events
    click SuemsApp "https://github.com/khushalsehrawat/suems/blob/main/src/main/java/com/suems/SuemsApplication.java"
    click CorsCfg "https://github.com/khushalsehrawat/suems/blob/main/src/main/java/com/suems/config/CorsConfig.java"
    click JacksonCfg "https://github.com/khushalsehrawat/suems/blob/main/src/main/java/com/suems/config/jacksonConfig.java"
    click AppProps "https://github.com/khushalsehrawat/suems/blob/main/src/main/resources/application.properties"
    click ESC "https://github.com/khushalsehrawat/suems/blob/main/src/main/java/com/suems/controller/EnergySourceController.java"
    click SDC "https://github.com/khushalsehrawat/suems/blob/main/src/main/java/com/suems/controller/SensorDataController.java"
    click ED "https://github.com/khushalsehrawat/suems/blob/main/src/main/java/com/suems/dto/EnergySourceDto.java"
    click SDT "https://github.com/khushalsehrawat/suems/blob/main/src/main/java/com/suems/dto/SensorDataDto.java"
    click SUMD "https://github.com/khushalsehrawat/suems/blob/main/src/main/java/com/suems/dto/SummaryDto.java"
    click AE "https://github.com/khushalsehrawat/suems/blob/main/src/main/java/com/suems/dto/ApiError.java"
    click GEH "https://github.com/khushalsehrawat/suems/blob/main/src/main/java/com/suems/exception/GlobalExceptionHandler.java"
    click NFE "https://github.com/khushalsehrawat/suems/blob/main/src/main/java/com/suems/exception/NotFoundException.java"
    click MAPPERS "https://github.com/khushalsehrawat/suems/blob/main/src/main/java/com/suems/mappers/Mappers.java"
    click ESS "https://github.com/khushalsehrawat/suems/blob/main/src/main/java/com/suems/service/EnergySourceService.java"
    click SDS "https://github.com/khushalsehrawat/suems/blob/main/src/main/java/com/suems/service/SensorDataService.java"
    click SIM "https://github.com/khushalsehrawat/suems/blob/main/src/main/java/com/suems/simulator/DataSimulator.java"
    click ESR "https://github.com/khushalsehrawat/suems/blob/main/src/main/java/com/suems/repository/EnergySourceRepository.java"
    click SDR "https://github.com/khushalsehrawat/suems/blob/main/src/main/java/com/suems/repository/SensorDataRepository.java"

    %% Styles
    classDef controller fill:#cce5ff,stroke:#004085,color:#004085
    classDef service fill:#d4edda,stroke:#155724,color:#155724
    classDef repo fill:#fff3cd,stroke:#856404,color:#856404
    classDef db fill:#ffeeba,stroke:#856404,color:#856404
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef config fill:#f8f9fa,stroke:#6c757d,color:#6c757d
    classDef dto fill:#f5c6cb,stroke:#721c24,color:#721c24
```
