# mbta/mobile_app architecture

> Architecture diagram of the GitHub repository mbta/mobile_app, 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/mobile_app
- Repository: https://github.com/mbta/mobile_app

## Overview

##### High-Level Architecture (Top Layer)
- Three main components in a horizontal layout:
- iOS App (left)
- Shared KMM Module (center)
- Android App (right)

##### Core Components (Middle Layer)

a. Data Layer:
- Repositories (shared/repositories/)
- Network Clients (network/)
- Phoenix Channels (phoenix/)
- Cache System (cache/)
- Local Storage (DataStore)

b. Business Logic Layer:
- Use Cases (usecases/)
- Model Objects (model/)
- Dependency Injection (dependencyInjection/)

c. Infrastructure:
- MapBox Integration
- Custom Layer Generators (map/style/)
- Route/Stop Features Builders

##### Platform-Specific Implementations (Bottom Layer)
Split into two sections:

iOS Side:
- SwiftUI Views (iosApp/Pages/)
- ViewModels
- Native MapBox Bridge
- Analytics Integration

Android Side:
- Compose UI Components (androidApp/component/)
- ViewModels
- Native MapBox Bridge
- Analytics Integration

##### External Services (Side Panel)
Connections to:
- MBTA Backend API
- Mapbox Services
- Sentry Error Logging
- Firebase App Check
- Phoenix Channels (WebSocket)

- Real-time data flow (WebSocket connections)
- REST API calls
- Internal communication between layers
- Platform-specific bridge communications

##### Key Components to Highlight
- Real-time transit updates system
- Rendering pipeline
- Multi-language support
- Error handling and monitoring
- Location services integration
- Route/Stop data management

##### Security Layer
- Firebase App Check integration
- Mapbox key management
- API authentication

##### State Management
- Repository pattern implementation
- Shared state handling between platforms
- Cache management

##### Real-time Features
- Phoenix WebSocket channels
- Vehicle tracking
- Service alerts
- Predictions

##### Error Handling
- Sentry integration
- Error banner system
- Network connectivity monitoring

Use these visual conventions:
- Clear labels for all components and connections

## Diagram (Mermaid)

```mermaid
graph TB
    %% Main Layers
    subgraph PlatformLayer
        iOS["iOS App"]:::ios
        Android["Android App"]:::android
        Shared["Shared KMM Module"]:::shared
    end

    subgraph DataLayer["Data Layer"]
        Repositories["Repositories"]:::data
        NetworkClient["Network Client"]:::data
        PhoenixChannels["Phoenix Channels"]:::data
        Cache["Cache System"]:::data
        LocalStorage["Local Storage"]:::data
    end

    subgraph BusinessLayer["Business Logic Layer"]
        UseCases["Use Cases"]:::logic
        Models["Model Objects"]:::logic
        DI["Dependency Injection"]:::logic
    end

    subgraph MapInfra["Map Infrastructure"]
        MapBox["MapBox Integration"]:::map
        LayerGen["Layer Generators"]:::map
        FeatureBuilders["Route/Stop Features"]:::map
    end

    subgraph iOSImpl["iOS Implementation"]
        SwiftUIViews["SwiftUI Views"]:::ios
        iOSViewModels["ViewModels"]:::ios
        iOSMapBridge["Native MapBox Bridge"]:::ios
    end

    subgraph AndroidImpl["Android Implementation"]
        ComposeUI["Compose UI"]:::android
        AndroidViewModels["ViewModels"]:::android
        AndroidMapBridge["Native MapBox Bridge"]:::android
    end

    subgraph ExternalServices["External Services"]
        MBTA["MBTA Backend API"]:::external
        MapboxServices["Mapbox Services"]:::external
        Sentry["Sentry Error Logging"]:::external
        Firebase["Firebase App Check"]:::external
        WebSocket["Phoenix WebSocket"]:::external
    end

    %% Connections
    iOS --> Shared
    Android --> Shared
    Shared --> DataLayer
    DataLayer --> BusinessLayer
    BusinessLayer --> MapInfra
    MapInfra --> iOSImpl
    MapInfra --> AndroidImpl
    DataLayer --> ExternalServices

    %% Click events
    click Repositories "https://github.com/mbta/mobile_app/tree/main/shared/src/commonMain/kotlin/com/mbta/tid/mbta_app/repositories/"
    click NetworkClient "https://github.com/mbta/mobile_app/blob/main/shared/src/commonMain/kotlin/com/mbta/tid/mbta_app/network/MobileBackendClient.kt"
    click PhoenixChannels "https://github.com/mbta/mobile_app/tree/main/shared/src/commonMain/kotlin/com/mbta/tid/mbta_app/phoenix/"
    click Cache "https://github.com/mbta/mobile_app/blob/main/shared/src/commonMain/kotlin/com/mbta/tid/mbta_app/cache/ResponseCache.kt"
    click LocalStorage "https://github.com/mbta/mobile_app/blob/main/shared/src/commonMain/kotlin/com/mbta/tid/mbta_app/DataStore.kt"
    click UseCases "https://github.com/mbta/mobile_app/tree/main/shared/src/commonMain/kotlin/com/mbta/tid/mbta_app/usecases/"
    click Models "https://github.com/mbta/mobile_app/tree/main/shared/src/commonMain/kotlin/com/mbta/tid/mbta_app/model/"
    click DI "https://github.com/mbta/mobile_app/tree/main/shared/src/commonMain/kotlin/com/mbta/tid/mbta_app/dependencyInjection/"
    click LayerGen "https://github.com/mbta/mobile_app/tree/main/shared/src/commonMain/kotlin/com/mbta/tid/mbta_app/map/style/"
    click FeatureBuilders "https://github.com/mbta/mobile_app/tree/main/shared/src/commonMain/kotlin/com/mbta/tid/mbta_app/map/"
    click AndroidMapBridge "https://github.com/mbta/mobile_app/blob/main/androidApp/src/main/java/com/mbta/tid/mbta_app/android/map/MapboxBridge.kt"
    click iOSMapBridge "https://github.com/mbta/mobile_app/blob/main/iosApp/iosApp/Utils/MapboxBridge.swift"
    click ComposeUI "https://github.com/mbta/mobile_app/tree/main/androidApp/src/main/java/com/mbta/tid/mbta_app/android/component/"
    click AndroidViewModels "https://github.com/mbta/mobile_app/blob/main/androidApp/src/main/java/com/mbta/tid/mbta_app/android/map/MapViewModel.kt"
    click SwiftUIViews "https://github.com/mbta/mobile_app/tree/main/iosApp/iosApp/ComponentViews/"
    click iOSViewModels "https://github.com/mbta/mobile_app/tree/main/iosApp/iosApp/ViewModels/"

    %% Styles
    classDef ios fill:#FF6B6B
    classDef android fill:#4CAF50
    classDef shared fill:#3498DB
    classDef data fill:#F1C40F
    classDef logic fill:#9B59B6
    classDef map fill:#2ECC71
    classDef external fill:#95A5A6
```
