How nvlinhdev/transitlink works
Project Type & Purpose
• This is a single Spring Boot–based modular monolith (“Transit Link Backend”) that exposes REST APIs & WebSockets to support an automated shuttle dispatching system.
• It handles driver/passenger identity, route optimization, location tracking, notifications, reporting, storage, and integrates with external services (Mapbox, HERE, Keycloak, FCM, Elasticsearch, SMTP/Email).
File Structure Analysis
• Top-level build & dev files: Dockerfile, Gradle wrapper, GitLab CI scripts, container-build scripts.
• src/main/java/vn/edu/fpt/transitlink – all domain modules as Spring packages:
• identity, fleet, location, trip, notification, reporting, storage, mail_sender, mapbox_integration, here_integration, shared.
• Layering within each module: controller → service → repository (and any SPI/provider subpackages).
• Infrastructure/config under shared.config & module‐specific config (MapboxConfig, FirebaseConfig, MailConfig, RedisConfig, etc.).
• Persistence: JPA repositories (PostgreSQL) + two ES repositories (PlaceESRepository, PassengerJourneyESRepository).
• Test folders: integrationTest (with ModulithArchitectureTests) & unitTest.
README Insights
• Java 21, Spring Boot 3.4.x, PostgreSQL, Keycloak (OAuth2/OIDC), Docker/Compose, GitLab CI/CD.
• Features: automatic route optimization, multi-operator dispatching, authentication via Keycloak.
Main Components & Their Relationships
A. Client Layers
• Mobile/Web Clients (drivers/passengers)
• External Operator Dashboard
B. API Layer
• Controllers (REST + WebSocket endpoints), grouped by domain module
C. Business Layer
• Services (module-specific service interfaces + impl)
• Shared cross-cutting (security, auditing, scheduling, exception handling)
D. Persistence Layer
• PostgreSQL (primary data store via Spring Data JPA repositories)
• Elasticsearch (search/index for places & passenger journeys)
• Redis (caching, WebSocket session store)
E. Integration Layer
• Keycloak (authentication/authorization)
• Mapbox & HERE (external routing & place-search providers via SPI)
• SMTP/Email (for notifications, via mail_sender module)
• Firebase Cloud Messaging & WebSocket (real-time notifications)
F. DevOps & Build
• Docker images, GitLab CI/CD pipelines, deployment scripts
Architectural Patterns & Design Principles
• Modular Monolith (Spring Modulith pattern verified by ModulithArchitectureTests).
• Layered (Controller → Service → Repository).
• SPI/Provider pattern for external integrations (mapbox_integration.spi, here_integration).
• Configuration via Spring’s @Configuration classes (Redis, WebSocket, Swagger/OpenAPI).
• Event/async processing for email & notifications.