# shambhugohel/vroom-api architecture

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

- Interactive diagram: https://gitdiagram.com/shambhugohel/vroom-api
- Repository: https://github.com/shambhugohel/vroom-api

## Overview

##### Project type and purpose
- This is a monolithic Spring Boot “CarSellingAPI” backend: a RESTful web service exposing endpoints to list, search, and manage used‐car data. It uses Spring MVC for the web layer, JPA/Hibernate for persistence to MySQL, AOP for cross-cutting concerns, and Swagger for API documentation.

##### File structure
- Top-level files: pom.xml (Maven build), application-*.properties (profiles), Tables.sql, logback.xml.
- Key packages under src/main/java/com/carportal:
- api/rest/controller (Web layer: CarDetailController, CarEngineController, etc.)
- api/rest/dto (DTOs for request/response plus paging wrappers)
- service & service/impl (Business logic interfaces & implementations)
- repository (Spring Data JPA repositories)
- entity (JPA entities: ECarDetails, ECarEngine, etc.)
- mapper (MapStruct-style or manual mappers converting between entities and DTOs/models)
- config (WebConfig, JpaConfig, AuditorAware, custom ID generators)
- audit (Auditable base classes & LogAspect for AOP logging)
- utils, exceptions, enums, constants.

##### README for additional insights
- Technology stack: Spring MVC, JPA/Hibernate, Hikari, MySQL, AspectJ AOP, SLF4J+Logback, Swagger UI.
- Future integrations: AI OCR, ML recommendation engine, data lake, chat/integration services, payment/escrow, analytics dashboards.

##### Main components
a. API Clients (Web/Mobile)
b. Spring Boot Monolith
1) Web Layer
- Spring MVC Dispatcher → Controllers (CarDetailController, CarEngineController, …)
2) Service Layer
- Business services (CarDetailService, CarEngineService, …)
3) Data Layer
- Repositories (CarDetailRepository, …) → JPA/Hibernate → MySQL
4) Cross-cutting modules
- AOP logging (LogAspect)
- Auditing (AuditableEntity, AuditorAwareImpl)
- Custom ID generation (PrefixedSequenceIdGenerator)
5) DTO & Mapping
- Request/response DTOs and mapper classes
6) Configuration & Docs
- WebConfig (CORS, resource handlers), Swagger UI (Springfox)
c. External Services (future or runtime)
- AI OCR & ML recommendation microservices (HTTP/REST)
- Data Lake / Analytics cluster
- Authentication Providers (OAuth social logins)
- Payment Gateway / Escrow
- Notification services (Email/SMS/Push)

d. Database
- MySQL instance (schema as per Tables.sql)

##### Relationships and interactions
- Client → (HTTPS) → API Gateway/Load Balancer (if present) → Spring MVC Dispatcher
- Controller → Service → Repository → MySQL
- Controllers ↔ DTOs ↔ Mappers ↔ Entities
- Service → External AI/ML services (HTTP calls)
- AOP Aspect intercepts Controllers & Services for logging/auditing
- Swagger UI served by Springfox

##### Architectural patterns & design principles
- Layered (Controller → Service → Repository)
- Dependency Injection / Inversion of Control (Spring)
- Aspect-Oriented Programming for logging & audit
- DTO pattern to decouple API model from persistence entities
- Repository pattern via Spring Data JPA
- Configuration & profile separation (dev/prod)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Clients
    Client["API Clients (Web/Mobile)"]:::external

    %% Monolith
    subgraph "Spring Boot Monolith"
        direction TB

        %% Entry
        Entry["CarPortalApplication"]:::entry

        %% Web Layer
        subgraph "Web Layer"
            direction TB
            Controllers["Controllers"]:::frontend
            subgraph "" 
                direction TB
                CDC["CarDetailController"]:::frontend
                CEC["CarEngineController"]:::frontend
                CFC["CarFeaturesController"]:::frontend
                COC["CarOuterController"]:::frontend
                CPC["CarPhotoController"]:::frontend
            end
        end

        %% DTO & Mapping
        subgraph "DTO & Mapping"
            direction TB
            DTOs["DTOs"]:::dto
            Mappers["Mappers"]:::mapper
        end

        %% Service Layer
        subgraph "Service Layer"
            direction TB
            Interfaces["Service Interfaces"]:::service
            Impl["Service Implementations"]:::service
        end

        %% Data Layer
        subgraph "Data Layer"
            direction TB
            Repos["Repositories"]:::persistence
            Entities["Entities"]:::persistence
        end

        %% Cross-Cutting
        subgraph "Cross-Cutting Concerns"
            direction TB
            AOP["LogAspect & Auditing"]:::crosscut
            IDGen["PrefixedSequenceIdGenerator"]:::crosscut
        end

        %% Config & Docs
        subgraph "Config & Docs"
            direction TB
            Config["WebConfig & JpaConfig"]:::config
            Swagger["Swagger UI"]:::config
        end

        %% Flows
        Client -->|"REST calls/JSON"| Entry
        Entry -->|starts| Controllers
        Controllers -->|invoke business logic| Interfaces
        Interfaces -->|implemented by| Impl
        Impl -->|CRUD via JPA| Repos
        Repos -->|maps to| Entities
        Entities -->|persist via JDBC/Hikari| DB
        Interfaces -->|HTTP/REST| ExternalAI
        AOP -.-> Controllers
        AOP -.-> Impl
        IDGen --> Entities
        DTOs --> Controllers
        DTOs --> Mappers
        Mappers -->|converts| Entities
        Config --> Controllers
        Swagger --> Controllers

    end

    %% Database
    DB["MySQL Database"]:::database

    %% External Services
    subgraph "External Services (Future)"
        direction TB
        ExternalAI["AI OCR & ML"]:::external
        DataLake["Data Lake/Analytics"]:::external
        AuthProv["OAuth Providers"]:::external
        Payment["Payment/Escrow"]:::external
        Notify["Notification Service"]:::external
    end

    ExternalAI -->|HTTP/REST| Interfaces
    DataLake -.->|batch| DB
    AuthProv -->|OAuth token| Entry
    Payment -->|HTTP/REST| Interfaces
    Notify -->|async| Interfaces

    %% Click Events
    click Entry "https://github.com/shambhugohel/vroom-api/blob/master/src/main/java/com/carportal/CarPortalApplication.java"
    click Controllers "https://github.com/shambhugohel/vroom-api/tree/master/src/main/java/com/carportal/api/rest/controller"
    click CDC "https://github.com/shambhugohel/vroom-api/blob/master/src/main/java/com/carportal/api/rest/controller/CarDetailController.java"
    click CEC "https://github.com/shambhugohel/vroom-api/blob/master/src/main/java/com/carportal/api/rest/controller/CarEngineController.java"
    click CFC "https://github.com/shambhugohel/vroom-api/blob/master/src/main/java/com/carportal/api/rest/controller/CarFeaturesController.java"
    click COC "https://github.com/shambhugohel/vroom-api/blob/master/src/main/java/com/carportal/api/rest/controller/CarOuterController.java"
    click CPC "https://github.com/shambhugohel/vroom-api/blob/master/src/main/java/com/carportal/api/rest/controller/CarPhotoController.java"
    click DTOs "https://github.com/shambhugohel/vroom-api/tree/master/src/main/java/com/carportal/api/rest/dto"
    click Interfaces "https://github.com/shambhugohel/vroom-api/tree/master/src/main/java/com/carportal/service"
    click Impl "https://github.com/shambhugohel/vroom-api/tree/master/src/main/java/com/carportal/service/impl"
    click Repos "https://github.com/shambhugohel/vroom-api/tree/master/src/main/java/com/carportal/repository"
    click Entities "https://github.com/shambhugohel/vroom-api/tree/master/src/main/java/com/carportal/entity"
    click Mappers "https://github.com/shambhugohel/vroom-api/tree/master/src/main/java/com/carportal/mapper"
    click AOP "https://github.com/shambhugohel/vroom-api/blob/master/src/main/java/com/carportal/audit/LogAspect.java"
    click IDGen "https://github.com/shambhugohel/vroom-api/blob/master/src/main/java/com/carportal/config/PrefixedSequenceIdGenerator.java"
    click Config "https://github.com/shambhugohel/vroom-api/blob/master/src/main/java/com/carportal/config/WebConfig.java"
    click DB "https://github.com/shambhugohel/vroom-api/blob/master/src/main/resources/Tables.sql"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6;color:#0366D6
    classDef service fill:#DFFFE0,stroke:#28A745;color:#28A745
    classDef persistence fill:#FFF5D1,stroke:#D69F00;color:#D69F00
    classDef crosscut fill:#F0F0F0,stroke:#6A737D;color:#6A737D
    classDef external fill:#FBEFEF,stroke:#CB2431;color:#CB2431
    classDef dto fill:#E8D0FF,stroke:#6F42C1;color:#6F42C1
    classDef mapper fill:#FFE8D0,stroke:#E36209;color:#E36209
    classDef config fill:#E0F2FE,stroke:#0366D6;color:#0366D6
    classDef database fill:#FFF0F0,stroke:#D73A49;color:#D73A49
    classDef entry fill:#E0F7FA,stroke:#006064,color:#006064
```
