How odaviml/api-onibusbh works
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.