# mbta/ride_along architecture

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

- Interactive diagram: https://gitdiagram.com/mbta/ride_along
- Repository: https://github.com/mbta/ride_along

## Overview

##### Main System Components

a) Web Layer:
- Phoenix web framework (indicated by Phoenix endpoints and controllers)
- LiveView components for real-time updates
- API endpoints for trip information
- Authentication system

b) Core Services:
- ETA Calculator with ML Component (XGBoost model)
- MQTT Communication System
- Route Service Integration
- Rider Notification System
- SQL Processing Pipeline

c) External Services:
- ActiveMQ (Message Queue)
- OpenRouteService (for routing)
- Webhook System (for rider notifications)

##### Component Relationships

a) Data Flow:
- Vehicle location updates → MQTT → ETA Calculator
- ETA Calculator → Route Cache → Web Layer
- SQL Parser → Publisher → Message Queue
- Message Queue → MQTT Listener → Internal Services

b) Service Dependencies:
- ETA Calculator ↔ XGBoost Model
- Web Layer ↔ Authentication
- Route Cache ↔ OpenRouteService

##### Additional Elements

Include:
- System boundaries
- Load balancer (if applicable)
- Monitoring components (telemetry)
- Cache layers
- Security boundaries

##### Specific Implementation Notes

- Real-time nature of the system (LiveView + MQTT)
- ML integration for ETA prediction
- Caching strategy for routes
- Message queue-based architecture
- Authentication flow
- API endpoints structure

Remember to:
- Use consistent symbols
- Notes for critical components
- Scaling points
- Failure recovery paths

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Style Definitions
    classDef web fill:#3498db,stroke:#2980b9,color:white
    classDef core fill:#2ecc71,stroke:#27ae60,color:white
    classDef external fill:#f1c40f,stroke:#f39c12,color:black
    classDef critical fill:#e74c3c,stroke:#c0392b,color:white
    classDef cache fill:#9b59b6,stroke:#8e44ad,color:white
    classDef client fill:#95a5a6,stroke:#7f8c8d,color:white

    %% Client Layer
    subgraph Clients
        Browser["Web Browsers"]:::client
        APIConsumers["API Consumers"]:::client
    end

    %% Web Layer
    subgraph WebLayer
        WebServer["Phoenix Web Server"]:::web
        Auth["Authentication System"]:::web
        APIControllers["API Controllers"]:::web
        LiveView["LiveView Components"]:::web
    end

    %% Core Services Layer
    subgraph CoreServices
        ETACalc["ETA Calculator Service"]:::core
        XGBoost["XGBoost ML Model"]:::core
        MQTTHandler["MQTT Connection Handler"]:::core
        RouteCache["Route Cache"]:::cache
        RiderNotifier["Rider Notifier"]:::core
        SQLParser["SQL Parser"]:::core
        SQLPublisher["SQL Publisher"]:::core
        TripMgmt["Trip Management"]:::core
        VehicleTrack["Vehicle Tracking"]:::core
        ETAMonitor["ETA Monitor"]:::core
        WebhookSystem["Webhook System"]:::core
    end

    %% External Services Layer
    subgraph ExternalServices
        ActiveMQ["ActiveMQ"]:::external
        OpenRoute["OpenRouteService"]:::external
        WebhookEndpoints["Webhook Endpoints"]:::external
    end

    %% Relationships
    Browser --> WebServer
    APIConsumers --> APIControllers
    WebServer --> Auth
    WebServer --> LiveView
    WebServer --> APIControllers
    
    MQTTHandler --> ETACalc
    ETACalc --> XGBoost
    ETACalc --> RouteCache
    RouteCache --> OpenRoute
    
    SQLParser --> SQLPublisher
    SQLPublisher --> ActiveMQ
    ActiveMQ --> MQTTHandler
    
    ETACalc --> ETAMonitor
    ETAMonitor --> RiderNotifier
    RiderNotifier --> WebhookSystem
    WebhookSystem --> WebhookEndpoints
    
    VehicleTrack --> ETACalc
    TripMgmt --> ETACalc

    %% Click Events
    click WebServer "https://github.com/mbta/ride_along/blob/main/lib/ride_along_web/endpoint.ex"
    click Auth "https://github.com/mbta/ride_along/blob/main/lib/ride_along_web/auth_manager.ex"
    click APIControllers "https://github.com/mbta/ride_along/tree/main/lib/ride_along_web/controllers/api/"
    click LiveView "https://github.com/mbta/ride_along/tree/main/lib/ride_along_web/live/"
    click ETACalc "https://github.com/mbta/ride_along/tree/main/lib/ride_along/eta_calculator/"
    click XGBoost "https://github.com/mbta/ride_along/blob/main/lib/ride_along/eta_calculator/model.ex"
    click MQTTHandler "https://github.com/mbta/ride_along/tree/main/lib/ride_along/mqtt_connection/"
    click OpenRoute "https://github.com/mbta/ride_along/blob/main/lib/ride_along/open_route_service.ex"
    click RouteCache "https://github.com/mbta/ride_along/blob/main/lib/ride_along/route_cache.ex"
    click RiderNotifier "https://github.com/mbta/ride_along/blob/main/lib/ride_along/rider_notifier.ex"
    click SQLParser "https://github.com/mbta/ride_along/blob/main/lib/ride_along/sql_parser.ex"
    click SQLPublisher "https://github.com/mbta/ride_along/blob/main/lib/ride_along/sql_publisher.ex"
    click WebhookSystem "https://github.com/mbta/ride_along/blob/main/lib/ride_along/webhook_publisher.ex"
    click TripMgmt "https://github.com/mbta/ride_along/blob/main/lib/ride_along/adept/trip.ex"
    click VehicleTrack "https://github.com/mbta/ride_along/blob/main/lib/ride_along/adept/vehicle.ex"
    click ETAMonitor "https://github.com/mbta/ride_along/blob/main/lib/ride_along/eta_monitor.ex"
```
