# odaviml/api-onibusbh architecture

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

- Interactive diagram: https://gitdiagram.com/odaviml/api-onibusbh
- Repository: https://github.com/odaviml/api-onibusbh

## Overview

##### Project type and purpose
- This is a monolithic backend REST API (“API Ônibus BH”) built with Spring Boot (Java 21) that provides real-time bus location and line information for the Ônibus BH frontend. It periodically ingests data from an external BHTrans service, persists it in MongoDB, and serves REST endpoints to clients.

##### File structure
- Top-level artifacts:
- Dockerfile / compose.yaml / docker-compose.prod.yaml → containerized deployment (app + MongoDB)
- pom.xml / mvnw → Maven-based Java Spring Boot project
- src/main/java/com/dmware/api_onibusbh/config → WebClient, async/thread-pool, ModelMapper, MVC config
- src/main/java/.../scheduler → scheduled tasks (CoordenadasScheduler, LinhaScheduler, DicionarioScheduler) that fetch external data
- src/main/java/.../services → business logic (APIService, LinhasService, DicionarioService, OnibusService)
- src/main/java/.../repositories → Spring Data repositories (MongoDB)
- src/main/java/.../controllers → REST controllers exposing endpoints (CoordenadasController, LinhasController, DicionarioController, OnibusController)
- src/main/java/.../infra → custom response wrappers, exception handlers
- src/main/java/.../dto & entities → DTO/Entity mapping
- src/main/resources/application.properties → DB connection, scheduler intervals, Swagger config

##### README for additional insights
- Confirms features (real-time location every 20 s, line queries), tech stack (Java 21, Spring Boot, MongoDB), Docker-Compose for local/production, and Swagger for interactive docs.

- External BHTrans API (data source)
- Spring Boot Application (monolith)
– Scheduler Module
– Service Layer
– Repository Layer
– REST Controller Layer
– Infra (Error handling, CustomApiResponse)
– Config (WebClient, Async, ModelMapper, Web MVC)
- MongoDB Database
- Frontend Client (Ônibus BH web app)
- Swagger UI / API Consumers

1. Scheduler → Service → WebClient → External BHTrans API → raw JSON
2. Service → ModelMapper → Entities → Repositories → MongoDB (writes)
3. Client/Swagger UI → Controllers → Services → Repositories → MongoDB (reads)
4. Controllers → DTO → HTTP JSON → Frontend
5. ExceptionHandler intercepts errors → CustomApiResponse → Client

c. Architectural patterns & design principles
- Layered architecture (Controller → Service → Repository)
- Scheduler pattern for periodic ingestion
- Repository pattern (Spring Data MongoDB)
- DTO/Entity mapping (ModelMapper)
- Centralized exception handling (ControllerAdvice)
- Asynchronous configuration for non-blocking tasks

d. Key technologies/frameworks
- Java 21, Spring Boot
- Spring Web (REST controllers)
- Spring Scheduling (@Scheduled)
- Spring WebClient (external calls)
- Spring Data MongoDB
- ModelMapper
- Docker & Docker-Compose (app + MongoDB)
- Swagger (springdoc-openapi)

##### Essential details without over-fragmenting
- How exceptions propagate to the centralized handler.
- Swagger UI as an embedded documentation endpoint.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Docker Deployment
    subgraph "Docker-Compose" 
        direction TB
        APIContainer["API Ônibus BH (8080)"]:::infra
        MongoDB["MongoDB (27017)"]:::infra
    end
    APIContainer --> MongoDB

    %% External Entities
    ExtAPI["BHTrans External API"]:::external
    Frontend["Frontend Client (Ônibus BH)"]:::external

    %% Spring Boot Application
    subgraph "API Ônibus BH Spring Boot App"
        direction TB
        MainApp["ApiOnibusbhApplication"]:::internal

        subgraph "Config Module"
            direction TB
            AsyncConf["AsyncConfiguration"]:::internal
            ModelMap["ModelMapperConfig"]:::internal
            WebClientConf["WebClientConfig"]:::internal
            WebMVC["WebConfig"]:::internal
        end

        subgraph "Scheduler Module"
            direction TB
            CoordSched["CoordenadasScheduler"]:::internal
            LinhaSched["LinhaScheduler"]:::internal
            DicSched["DicionarioScheduler"]:::internal
        end

        subgraph "Service Layer"
            direction TB
            APIService["APIService"]:::internal
            OnibusServ["OnibusService"]:::internal
            LinhasServ["LinhasService"]:::internal
            DicServ["DicionarioService"]:::internal
        end

        subgraph "Repository Layer"
            direction TB
            LinhasRepo["LinhasRepository"]:::internal
            DicRepo["DicionarioRepository"]:::internal
        end

        subgraph "Controller Layer"
            direction TB
            OnibusCtrl["OnibusController"]:::internal
            LinhasCtrl["LinhasController"]:::internal
            DicCtrl["DicionarioController"]:::internal
        end

        subgraph "Infra"
            direction TB
            ApiResp["CustomApiResponse"]:::infra
            ExHandler["CustomExceptionHandler"]:::infra
            ErrModel["ErrorResponse"]:::infra
        end

        subgraph "DTOs & Entities"
            direction TB
            CDT["CoordenadaDTO"]:::internal
            ODT["OnibusDTO"]:::internal
            LDT["LinhaDTO"]:::internal
            DDT["DicionarioDTO"]:::internal
            LEnt["LinhaEntity"]:::internal
            DEnt["DicionarioEntity"]:::internal
        end

        subgraph "Exceptions"
            direction TB
            Ex1["CoordenadasNotFoundException"]:::internal
            Ex2["LinhaNotFoundException"]:::internal
            Ex3["LinhasNotFoundException"]:::internal
            Ex4["DicionarioNotFoundException"]:::internal
            Ex5["ValidJsonException"]:::internal
        end

        subgraph "Utils"
            direction TB
            DateDes["DateDeserializer"]:::internal
            TrimDes["TrimStringDeserializer"]:::internal
        end

        SwaggerUI["Swagger UI"]:::external
    end

    %% Data Ingestion Flow
    CoordSched -->|"schedule"| APIService
    LinhaSched -->|"schedule"| APIService
    DicSched -->|"schedule"| APIService
    APIService -->|uses| WebClientConf
    WebClientConf -->|HTTP/HTTPS| ExtAPI
    ExtAPI -->|JSON| APIService

    %% Data Persistence
    APIService -->|map| ModelMap
    ModelMap -->|entity| LEnt
    ModelMap -->|entity| DEnt
    APIService --> LinhasServ
    APIService --> OnibusServ
    APIService --> DicServ
    LinhasServ --> LinhasRepo --> MongoDB
    DicServ --> DicRepo --> MongoDB
    OnibusServ --> LinhasRepo
    OnibusServ --> DicRepo

    %% Client Query Flow
    Frontend -->|HTTP JSON| OnibusCtrl
    Frontend -->|HTTP JSON| LinhasCtrl
    Frontend -->|HTTP JSON| DicCtrl
    OnibusCtrl --> OnibusServ
    LinhasCtrl --> LinhasServ
    DicCtrl --> DicServ
    OnibusServ --> LinhasRepo
    LinhasServ --> LinhasRepo
    DicServ --> DicRepo

    %% Exception Handling
    OnibusCtrl --> ExHandler
    LinhasCtrl --> ExHandler
    DicCtrl --> ExHandler
    ExHandler --> ApiResp
    ExHandler --> ErrModel

    %% Documentation
    SwaggerUI -->|OpenAPI Docs| Frontend

    %% Container Link
    APIContainer -->|"runs"| MainApp

    %% Click Events
    click MainApp "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/ApiOnibusbhApplication.java"
    click AsyncConf "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/config/AsyncConfiguration.java"
    click ModelMap "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/config/ModelMapperConfig.java"
    click WebClientConf "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/config/WebClientConfig.java"
    click WebMVC "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/config/WebConfig.java"
    click CoordSched "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/scheduler/CoordenadasScheduler.java"
    click LinhaSched "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/scheduler/LinhaScheduler.java"
    click DicSched "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/scheduler/DicionarioScheduler.java"
    click APIService "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/services/APIService.java"
    click OnibusServ "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/services/OnibusService.java"
    click LinhasServ "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/services/LinhasService.java"
    click DicServ "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/services/DicionarioService.java"
    click LinhasRepo "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/repositories/LinhasRepository.java"
    click DicRepo "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/repositories/DicionarioRepository.java"
    click OnibusCtrl "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/controllers/OnibusController.java"
    click LinhasCtrl "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/controllers/LinhasController.java"
    click DicCtrl "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/controllers/DicionarioController.java"
    click ApiResp "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/infra/CustomApiResponse.java"
    click ExHandler "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/infra/CustomExceptionHandler.java"
    click ErrModel "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/infra/ErrorResponse.java"
    click CDT "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/dto/CoordenadaDTO.java"
    click ODT "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/dto/OnibusDTO.java"
    click LDT "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/dto/LinhaDTO.java"
    click DDT "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/dto/DicionarioDTO.java"
    click LEnt "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/entities/LinhaEntity.java"
    click DEnt "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/entities/DicionarioEntity.java"
    click Ex1 "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/exceptions/CoordenadasNotFoundException.java"
    click Ex2 "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/exceptions/LinhaNotFoundException.java"
    click Ex3 "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/exceptions/LinhasNotFoundException.java"
    click Ex4 "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/exceptions/DicionarioNotFoundException.java"
    click Ex5 "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/exceptions/ValidJsonException.java"
    click DateDes "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/utils/DateDeserializer.java"
    click TrimDes "https://github.com/odaviml/api-onibusbh/blob/main/src/main/java/com/dmware/api_onibusbh/utils/TrimStringDeserializer.java"

    %% Styles
    classDef internal fill:#E3F2FD,stroke:#2196F3,stroke-width:1px
    classDef external fill:#E8F5E9,stroke:#4CAF50,stroke-width:1px
    classDef infra fill:#FFF3E0,stroke:#FB8C00,stroke-width:1px
```
