# nvlinhdev/transitlink architecture

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

- Interactive diagram: https://gitdiagram.com/nvlinhdev/transitlink
- Repository: https://github.com/nvlinhdev/transitlink

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "TransitLink Backend (Monolith)"
        subgraph "API Layer"
            IC["Identity Module<br/>Controller"]:::internal
            FC["Fleet Module<br/>Controller"]:::internal
            LC["Location Module<br/>Controller"]:::internal
            TC["Trip Module<br/>Controller"]:::internal
            NC["Notification Module<br/>Controller"]:::internal
            RC["Reporting Module<br/>Controller"]:::internal
            SC["Storage Module<br/>Controller"]:::internal
        end
        subgraph "Business Layer"
            IS["Identity Service"]:::internal
            FS["Fleet Service"]:::internal
            LS["Location Service"]:::internal
            TS["Trip Service"]:::internal
            NS["Notification Service"]:::internal
            RS["Reporting Service"]:::internal
            SS["Storage Service"]:::internal
        end
        subgraph "Persistence Layer"
            PG[(PostgreSQL)]:::db
            ES[(Elasticsearch)]:::db
            RD[(Redis Cache)]:::db
        end
        subgraph "Integration Layer"
            KC["Keycloak Auth"]:::external
            MB["Mapbox API"]:::external
            HR["HERE API"]:::external
            FM["Firebase Cloud Messaging"]:::external
            SM["SMTP Email"]:::external
        end
    end

    subgraph "Clients"
        MW["Mobile/Web Clients"]:::external
        OD["Operator Dashboard"]:::external
    end

    MW -->|HTTP/WS| IC
    OD -->|HTTP| FC

    IC -->|calls| IS
    FC -->|calls| FS
    LC -->|calls| LS
    TC -->|calls| TS
    NC -->|WS/HTTP| NS
    RC -->|calls| RS
    SC -->|calls| SS

    IS -->|JPA| PG
    FS -->|JPA| PG
    LS -->|JPA| PG
    TS -->|JPA| PG
    TS -->|ES| ES
    NS -->|Redis| RD
    RS -->|JPA| PG
    SS -->|JPA| PG

    IS -->|OAuth2| KC
    LS -->|"SPI REST"| MB
    LS -->|"SPI REST"| HR
    NS -->|Push| FM
    NS -->|SMTP| SM

    click IC "https://github.com/nvlinhdev/transitlink/tree/main/src/main/java/vn/edu/fpt/transitlink/identity/controller"
    click IS "https://github.com/nvlinhdev/transitlink/tree/main/src/main/java/vn/edu/fpt/transitlink/identity/service"
    click FC "https://github.com/nvlinhdev/transitlink/tree/main/src/main/java/vn/edu/fpt/transitlink/fleet/controller"
    click FS "https://github.com/nvlinhdev/transitlink/tree/main/src/main/java/vn/edu/fpt/transitlink/fleet/service"
    click LC "https://github.com/nvlinhdev/transitlink/tree/main/src/main/java/vn/edu/fpt/transitlink/location/controller"
    click LS "https://github.com/nvlinhdev/transitlink/tree/main/src/main/java/vn/edu/fpt/transitlink/location/service"
    click TC "https://github.com/nvlinhdev/transitlink/tree/main/src/main/java/vn/edu/fpt/transitlink/trip/controller"
    click TS "https://github.com/nvlinhdev/transitlink/tree/main/src/main/java/vn/edu/fpt/transitlink/trip/service"
    click NC "https://github.com/nvlinhdev/transitlink/tree/main/src/main/java/vn/edu/fpt/transitlink/notification/controller"
    click NS "https://github.com/nvlinhdev/transitlink/tree/main/src/main/java/vn/edu/fpt/transitlink/notification/service"
    click RC "https://github.com/nvlinhdev/transitlink/tree/main/src/main/java/vn/edu/fpt/transitlink/reporting/controller"
    click RS "https://github.com/nvlinhdev/transitlink/tree/main/src/main/java/vn/edu/fpt/transitlink/reporting/service"
    click SC "https://github.com/nvlinhdev/transitlink/tree/main/src/main/java/vn/edu/fpt/transitlink/storage/controller"
    click SS "https://github.com/nvlinhdev/transitlink/tree/main/src/main/java/vn/edu/fpt/transitlink/storage/service"

    classDef internal fill:#D0E8FF,stroke:#005792,color:#003f5c;
    classDef db fill:#DFFFE0,stroke:#228B22,color:#006400;
    classDef external fill:#FFE5D0,stroke:#FF8C00,color:#A0522D;
```
