# mohammadaamir1102/springbootvirtualthread architecture

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

- Interactive diagram: https://gitdiagram.com/mohammadaamir1102/springbootvirtualthread
- Repository: https://github.com/mohammadaamir1102/springbootvirtualthread

## Overview

##### Project type and purpose
- This is a standalone Spring Boot–based backend microservice whose purpose is to generate and serve CSV‐based reports (e.g. “simple_asia_report.csv”, “platform_asia_report.csv”, “virtual_asia_report.csv”) via REST endpoints.
- It demonstrates two threading models for report generation: standard platform threads vs. Java virtual threads (see ReportServiceByPlatformThread vs. ReportServiceByVirtualThread) and a custom Executor configuration (VTExecutorConfig).

##### File structure
- Top‐level files: Maven wrapper (mvnw, pom.xml), .gitignore, README.md.
- /reports folder: prepackaged CSV files used by the application.
- /src/main/java/com/aamir:
- config/VTExecutorConfig – defines Executor beans for platform or virtual threads.
- controller/ReportController – exposes REST endpoints.
- service/ReportService*, two implementations – business logic for report generation.
- repo/ConsumerRepo – DAO layer (likely a JPA repository).
- entity/ConsumerEntity – domain model.
- util/CsvReportUtil – file I/O helper for CSV parsing/writing.
- exception, constant, helper, response packages – error handling, message localization, API response wrappers.
- /src/main/resources/application.yml – runtime configuration.
- /src/test – unit tests for the Spring Boot application.

##### README
- The README contains only an illustrative image—no text. File tree and class names confirm this is a RESTful reporting service focusing on threading models.

a. Main components:
- External client (e.g. Postman, front-end, scheduler).
- Spring Boot application container:
– HTTP layer (ReportController)
– Service layer (ReportServiceByPlatformThread, ReportServiceByVirtualThread)
– Configuration (VTExecutorConfig)
– Utility (CsvReportUtil)
– Data layer (ConsumerRepo, ConsumerEntity + configured database)
– Exception handling (GlobalExceptionHandler, CustomException)
- File store (the /reports directory on the server’s filesystem)
- (Optionally) an external relational database (configured via application.yml).
b. Relationships and interactions:
1. Client issues HTTP GET (or POST) to ReportController.
2. Controller delegates to ReportService interface.
3. Depending on endpoint, Spring injects either the platform-thread or virtual-thread implementation.
4. Service uses VTExecutorConfig’s Executor to spawn tasks for reading/writing CSV (via CsvReportUtil) and/or fetching data from ConsumerRepo (database).
5. CsvReportUtil reads existing CSV files from /reports or writes new ones.
6. ConsumerRepo interacts with the database to fetch or persist ConsumerEntity records.
7. Service collects results, wraps them in ApiResponse, and returns to Controller.
8. Controller returns JSON or CSV stream to client.
c. Architectural patterns and design principles:
- Layered architecture (Controller → Service → Repository).
- Strategy pattern: two implementations of ReportService.
- Configuration‐injected Executor (Dependency Injection).
- Centralized exception handling (GlobalExceptionHandler).
- Utility class for low‐level I/O concerns (CsvReportUtil).
d. Relevant technologies and frameworks:
- Java 17+ with virtual threads (Project Loom).
- Spring Boot (Web, Data JPA).
- Maven build system.
- CSV file I/O (custom util).

##### Elements
- Cylindrical symbol for the database.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External systems
    ExternalClient(("External Client")):::external
    FileStore(["/reports (CSV files)"]):::file
    Database[(Database)]:::db

    %% Application container
    subgraph "Spring Boot Application"
        AppEntry["SpringBootVirtualThreadApplication"]:::app

        subgraph "HTTP Layer"
            ReportController["ReportController"]:::web
        end

        subgraph "Service Layer"
            ReportServiceIfc["ReportService (interface)"]:::business
            PlatformService["ReportServiceByPlatformThread"]:::business
            VirtualService["ReportServiceByVirtualThread"]:::business
        end

        subgraph "Configuration"
            VTExecutorConfig["VTExecutorConfig"]:::config
        end

        subgraph "Utility"
            CsvReportUtil["CsvReportUtil"]:::util
        end

        subgraph "Data Layer"
            ConsumerRepo["ConsumerRepo"]:::data
            ConsumerEntity["ConsumerEntity"]:::data
        end

        subgraph "Exception Handling"
            GlobalExceptionHandler["GlobalExceptionHandler"]:::exception
            CustomException["CustomException"]:::exception
        end

        subgraph "Supporting Modules"
            ErrorCode["ErrorCode"]:::support
            MessageProvider["MessageProvider"]:::support
            ApiResponse["ApiResponse"]:::support
        end
    end

    %% Flows
    ExternalClient -->|"HTTP GET /report"| ReportController
    ReportController -->|"calls generateReport()"| ReportServiceIfc
    ReportServiceIfc -->|injects| PlatformService
    ReportServiceIfc -->|injects| VirtualService
    PlatformService -->|"uses executor"| VTExecutorConfig
    VirtualService -->|"uses executor"| VTExecutorConfig
    PlatformService -->|"read/write CSV"| CsvReportUtil
    VirtualService -->|"read/write CSV"| CsvReportUtil
    PlatformService -->|"fetch data (JPA)"| ConsumerRepo
    VirtualService -->|"fetch data (JPA)"| ConsumerRepo
    ConsumerRepo -->|"maps to entity"| ConsumerEntity
    ConsumerRepo -->|"JPA query"| Database
    CsvReportUtil -->|"access files"| FileStore
    PlatformService -->|"wrap results"| ApiResponse
    VirtualService -->|"wrap results"| ApiResponse
    ApiResponse --> ReportController
    ReportController -->|"returns JSON/CSV"| ExternalClient
    ReportController -->|"handles errors"| GlobalExceptionHandler
    CustomException -->|"caught by"| GlobalExceptionHandler

    %% Click Events
    click AppEntry "https://github.com/mohammadaamir1102/springbootvirtualthread/blob/master/src/main/java/com/aamir/SpringBootVirtualThreadApplication.java"
    click ReportController "https://github.com/mohammadaamir1102/springbootvirtualthread/blob/master/src/main/java/com/aamir/controller/ReportController.java"
    click ReportServiceIfc "https://github.com/mohammadaamir1102/springbootvirtualthread/blob/master/src/main/java/com/aamir/service/ReportService.java"
    click PlatformService "https://github.com/mohammadaamir1102/springbootvirtualthread/blob/master/src/main/java/com/aamir/service/ReportServiceByPlatformThread.java"
    click VirtualService "https://github.com/mohammadaamir1102/springbootvirtualthread/blob/master/src/main/java/com/aamir/service/ReportServiceByVirtualThread.java"
    click VTExecutorConfig "https://github.com/mohammadaamir1102/springbootvirtualthread/blob/master/src/main/java/com/aamir/config/VTExecutorConfig.java"
    click CsvReportUtil "https://github.com/mohammadaamir1102/springbootvirtualthread/blob/master/src/main/java/com/aamir/util/CsvReportUtil.java"
    click ConsumerEntity "https://github.com/mohammadaamir1102/springbootvirtualthread/blob/master/src/main/java/com/aamir/entity/ConsumerEntity.java"
    click ConsumerRepo "https://github.com/mohammadaamir1102/springbootvirtualthread/blob/master/src/main/java/com/aamir/repo/ConsumerRepo.java"
    click CustomException "https://github.com/mohammadaamir1102/springbootvirtualthread/blob/master/src/main/java/com/aamir/exception/CustomException.java"
    click GlobalExceptionHandler "https://github.com/mohammadaamir1102/springbootvirtualthread/blob/master/src/main/java/com/aamir/exception/GlobalExceptionHandler.java"
    click ErrorCode "https://github.com/mohammadaamir1102/springbootvirtualthread/blob/master/src/main/java/com/aamir/constant/ErrorCode.java"
    click MessageProvider "https://github.com/mohammadaamir1102/springbootvirtualthread/blob/master/src/main/java/com/aamir/helper/MessageProvider.java"
    click ApiResponse "https://github.com/mohammadaamir1102/springbootvirtualthread/blob/master/src/main/java/com/aamir/response/ApiResponse.java"
    click FileStore "https://github.com/mohammadaamir1102/springbootvirtualthread/tree/master/reports"
    click Database "https://github.com/mohammadaamir1102/springbootvirtualthread/blob/master/src/main/resources/application.yml"

    %% Styles
    classDef external fill:#EFEFEF,stroke:#999,stroke-width:1px
    classDef web fill:#D0E8FF,stroke:#3399FF,stroke-width:1px
    classDef business fill:#DFF0D8,stroke:#3C763D,stroke-width:1px
    classDef config fill:#F2D8FF,stroke:#9933CC,stroke-width:1px
    classDef util fill:#F0F0F0,stroke:#666,stroke-width:1px
    classDef data fill:#FCF8E3,stroke:#8A6D3B,stroke-width:1px
    classDef exception fill:#F2DEDE,stroke:#A94442,stroke-width:1px
    classDef support fill:#F5ECCE,stroke:#8A6D3B,stroke-width:1px
    classDef file fill:#FFF2CC,stroke:#CC9900,stroke-width:1px
    classDef db fill:#E2E2FF,stroke:#6666CC,stroke-width:1px
    classDef app fill:#E8E8E8,stroke:#444444,stroke-width:2px,stroke-dasharray: 5 5
```
