# learnathon-by-geeky-solutions/byte-breeze architecture

> Architecture diagram of the GitHub repository learnathon-by-geeky-solutions/byte-breeze, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/learnathon-by-geeky-solutions/byte-breeze
- Repository: https://github.com/learnathon-by-geeky-solutions/byte-breeze

## Overview

##### Project Type & Purpose
- This is a monolithic, full-stack web application (“Smart Parcel Delivery System”) built on Java Spring Boot.
- It exposes role-based UIs (Customer, Rider, Admin) via Thymeleaf templates and static assets, hosts REST endpoints (e.g. for shipping cost calculation), persists data in PostgreSQL, and integrates with external services (SSLCommerz payment API, OpenTelemetry backends).

##### High-Level Component Breakdown
a. Front-End Clients
- Web browsers for three user roles (Customer, Rider, Admin).
- Static assets (CSS/JS under src/main/resources/static) and Thymeleaf templates (src/main/resources/templates).
b. Application Server (Spring Boot)
- Controllers (MVC & REST under com.bytebreeze.quickdrop.controller)
- Service Layer (business logic under com.bytebreeze.quickdrop.service)
- Data Access (Spring Data JPA repositories under com.bytebreeze.quickdrop.repository + Hibernate entities)
- Configuration (ModelMapper, RestTemplate, OpenTelemetry exporters, security)
- Utilities (file storage, hashing, profile settings)
c. Database
- PostgreSQL instance (local via docker-compose or Azure VM)
- Flyway-managed schema migrations under src/main/resources/db/migration
d. External Services
- SSLCommerz Payment Gateway
- Observability: OpenTelemetry traces → Jaeger, metrics → Prometheus/Grafana, logs → ELK (Loki)
e. DevOps / CI-CD
- Dockerfile + docker-compose.yml for local environment
- GitHub Actions workflows for build, test, code formatting, coverage
- Deployment targets: Render (PAAS) for dev, Azure VM (IAAS) for prod

##### Interactions & Data Flows
- Browser → HTTPS → Spring Boot DispatcherServlet → Controller
- Controller ↔ DTO ↔ Service layer → Repository → JDBC → PostgreSQL
- Service layer ↔ External REST API (SSLCommerz) via RestTemplate
- Service layer instrumented with OpenTelemetry SDK → OTLP exporter → Jaeger/Prometheus/Loki
- CI pipeline: Git push → GitHub Actions → Docker image build → Deploy to Render/Azure

##### Architectural Patterns & Design Principles
- Layered MVC (Presentation → Controller → Service → Repository → Database)
- DTO mapping via ModelMapper for separation of API and persistence models
- Repository Pattern with Spring Data JPA
- Configuration by profile (dev/prod/test) using Spring Boot’s application-*.properties
- Exception handling with custom exceptions and @ControllerAdvice (not shown but implied)
- Security via Spring Security + JWT and role-based access controls in SecurityConfig

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients Layer
    subgraph "Clients" 
        style Clients fill:#e0ffe0,stroke:#2d662d,stroke-width:2px
        CustomerUI["Customer UI (Browser)"]:::frontend
        RiderUI["Rider UI (Browser)"]:::frontend
        AdminUI["Admin UI (Browser)"]:::frontend
    end

    %% Application Server
    subgraph "Spring Boot Application" 
        style SpringBootApplication fill:#f0f8ff,stroke:#1a5276,stroke-width:2px

        subgraph "Presentation Layer"
            style PresentationLayer fill:#d0e7ff,stroke:#1a5276,stroke-width:1px
            StaticAssets["Static Assets"]:::backend
            Templates["Thymeleaf Templates"]:::backend
        end

        subgraph "Controller Layer"
            style ControllerLayer fill:#c8e1ff,stroke:#1a5276,stroke-width:1px
            Controllers["MVC & REST Controllers"]:::backend
            SSLController["SSLCommerzPaymentApiController"]:::backend
        end

        subgraph "Service Layer"
            style ServiceLayer fill:#b0d4ff,stroke:#1a5276,stroke-width:1px
            Services["Business Logic Services"]:::backend
            SSLService["SSLCommerzPaymentService"]:::backend
        end

        subgraph "Data Access Layer"
            style RepoLayer fill:#98c7ff,stroke:#1a5276,stroke-width:1px
            Repositories["Spring Data JPA Repositories"]:::backend
            Entities["Hibernate Entities"]:::backend
            DTOs["DTOs (API Models)"]:::backend
        end

        subgraph "Configuration"
            style ConfigLayer fill:#80baff,stroke:#1a5276,stroke-width:1px
            ModelMapperConfig["ModelMapperConfig"]:::backend
            RestTemplateConfig["RestTemplateConfig"]:::backend
            OtlpConfiguration["OtlpConfiguration"]:::backend
            SecurityConfig["SecurityConfig"]:::backend
            CustomUserDetailsService["CustomUserDetailsService"]:::backend
        end

        subgraph "Utilities & Exception"
            style UtilLayer fill:#68adff,stroke:#1a5276,stroke-width:1px
            Utilities["Utilities"]:::backend
            Exceptions["Exception Handling"]:::backend
        end

        QuickdropApp["QuickdropApplication (Entry Point)"]:::backend
    end

    %% Database
    subgraph "Database" 
        style Database fill:#f2f2f2,stroke:#4d4d4d,stroke-width:2px
        PostgreSQL["PostgreSQL"]:::db
        Flyway["Flyway Migrations"]:::db
    end

    %% External Services
    subgraph "External Services"
        style ExternalServices fill:#ffe5cc,stroke:#d35400,stroke-width:2px
        SSLCommerz["SSLCommerz Payment Gateway"]:::ext
        Jaeger["Jaeger (Tracing)"]:::ext
        PrometheusGrafana["Prometheus/Grafana (Metrics)"]:::ext
        ELK["ELK/Loki (Logging)"]:::ext
    end

    %% DevOps / CI-CD
    subgraph "DevOps / CI-CD"
        style DevOps fill:#f5e6ff,stroke:#6a1b9a,stroke-width:2px
        GitHub["GitHub"]:::devops
        Actions["GitHub Actions"]:::devops
        DockerRegistry["Docker Registry"]:::devops
        Render["Render (Dev Deploy)"]:::devops
        AzureVM["Azure VM (Prod Deploy)"]:::devops
        DockerfileNode["Dockerfile"]:::devops
        Compose["docker-compose.yml"]:::devops
        Workflows[".github/workflows"]:::devops
    end

    %% Relationships
    CustomerUI -->|HTTPS| Controllers
    RiderUI -->|HTTPS| Controllers
    AdminUI -->|HTTPS| Controllers
    StaticAssets --> Controllers
    Templates --> Controllers
    Controllers -->|calls| Services
    SSLController -->|calls| SSLService
    Services -->|uses| Repositories
    SSLService -->|REST| SSLCommerz
    Repositories -->|manages| Entities
    Repositories -->|JDBC| PostgreSQL
    Services -->|OTLP| Jaeger
    Services -->|OTLP| PrometheusGrafana
    Services -->|OTLP| ELK
    GitHub -->|push| Actions
    Actions -->|build| DockerRegistry
    DockerRegistry -->|deploy| Render
    DockerRegistry -->|deploy| AzureVM

    %% Click Events
    click StaticAssets "https://github.com/learnathon-by-geeky-solutions/byte-breeze/tree/main/src/main/resources/static"
    click Templates "https://github.com/learnathon-by-geeky-solutions/byte-breeze/tree/main/src/main/resources/templates"
    click Controllers "https://github.com/learnathon-by-geeky-solutions/byte-breeze/tree/main/src/main/java/com/bytebreeze/quickdrop/controller"
    click SSLController "https://github.com/learnathon-by-geeky-solutions/byte-breeze/blob/main/src/main/java/com/bytebreeze/quickdrop/controller/SSLCommerzPaymentApiController.java"
    click Services "https://github.com/learnathon-by-geeky-solutions/byte-breeze/tree/main/src/main/java/com/bytebreeze/quickdrop/service"
    click SSLService "https://github.com/learnathon-by-geeky-solutions/byte-breeze/blob/main/src/main/java/com/bytebreeze/quickdrop/service/SSLCommerzPaymentService.java"
    click Repositories "https://github.com/learnathon-by-geeky-solutions/byte-breeze/tree/main/src/main/java/com/bytebreeze/quickdrop/repository"
    click Entities "https://github.com/learnathon-by-geeky-solutions/byte-breeze/tree/main/src/main/java/com/bytebreeze/quickdrop/entity"
    click DTOs "https://github.com/learnathon-by-geeky-solutions/byte-breeze/tree/main/src/main/java/com/bytebreeze/quickdrop/dto"
    click ModelMapperConfig "https://github.com/learnathon-by-geeky-solutions/byte-breeze/blob/main/src/main/java/com/bytebreeze/quickdrop/config/ModelMapperConfig.java"
    click RestTemplateConfig "https://github.com/learnathon-by-geeky-solutions/byte-breeze/blob/main/src/main/java/com/bytebreeze/quickdrop/config/RestTemplateConfig.java"
    click OtlpConfiguration "https://github.com/learnathon-by-geeky-solutions/byte-breeze/blob/main/src/main/java/com/bytebreeze/quickdrop/config/OtlpConfiguration.java"
    click SecurityConfig "https://github.com/learnathon-by-geeky-solutions/byte-breeze/blob/main/src/main/java/com/bytebreeze/quickdrop/security/SecurityConfig.java"
    click CustomUserDetailsService "https://github.com/learnathon-by-geeky-solutions/byte-breeze/blob/main/src/main/java/com/bytebreeze/quickdrop/security/CustomUserDetailsService.java"
    click Utilities "https://github.com/learnathon-by-geeky-solutions/byte-breeze/tree/main/src/main/java/com/bytebreeze/quickdrop/util"
    click Exceptions "https://github.com/learnathon-by-geeky-solutions/byte-breeze/tree/main/src/main/java/com/bytebreeze/quickdrop/exception"
    click Flyway "https://github.com/learnathon-by-geeky-solutions/byte-breeze/tree/main/src/main/resources/db/migration"
    click QuickdropApp "https://github.com/learnathon-by-geeky-solutions/byte-breeze/blob/main/src/main/java/com/bytebreeze/quickdrop/QuickdropApplication.java"
    click DockerfileNode "https://github.com/learnathon-by-geeky-solutions/byte-breeze/tree/main/Dockerfile"
    click Compose "https://github.com/learnathon-by-geeky-solutions/byte-breeze/blob/main/docker-compose.yml"
    click Workflows "https://github.com/learnathon-by-geeky-solutions/byte-breeze/tree/main/.github/workflows"

    %% Styles
    classDef frontend fill:#d0ffd0,stroke:#2d662d,stroke-width:1px;
    classDef backend fill:#cce5ff,stroke:#1a5276,stroke-width:1px;
    classDef db fill:#e6e6e6,stroke:#4d4d4d,stroke-width:1px;
    classDef ext fill:#ffe0cc,stroke:#d35400,stroke-width:1px;
    classDef devops fill:#f0d9ff,stroke:#6a1b9a,stroke-width:1px;
```
