# mbta/screens architecture

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

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

## Overview

##### Main System Components

a) Client Layer
- Multiple screen types (Bus E-Ink, Green Line E-Ink, Bus LCD, Multimodal LCD, Pre-fare LCD, DUP LCD)
- Frontend applications (React/TypeScript based on the assets structure)
- Screen-specific widgets and components

b) Application Layer
- Phoenix web server (screens_web)
- Widget framework
- Screen data processing
- Real-time information handlers
- Authentication/Authorization system

c) Data Processing Layer
- Candidate generators
- Template builders
- Alert processors
- Departure processors
- Screen configuration handlers

d) External Services Integration
- MBTA API integration
- S3 configuration storage
- Cache systems
- Real-time data feeds

##### Key Relationships to Highlight

- Data flow from external services to the application
- Request/response patterns between layers
- Widget rendering pipeline
- Screen-specific content generation flows

##### Specific Implementation Details

a) Widget Framework
- How widgets are generated and managed
- Template system
- Candidate generation process

b) Screen Types
- Demonstrate how different screen types are handled
- Screen-specific processing paths
- Content adaptation for different display types

c) Real-time Processing
- How real-time data flows through the system
- Caching mechanisms
- Update/refresh patterns

##### Important Architectural Patterns

Emphasize:
- Phoenix/Elixir supervision tree structure
- Widget-based component architecture
- Cache management system
- Screen configuration management
- Authentication/authorization flow

##### Additional Elements

Include:
- Version information
- Key technology stack components
- Main data flow paths
- Critical system boundaries

Remember to include notes about:
- Scaling considerations
- Error handling paths
- Configuration management
- Screen type-specific processing
- Real-time data flow optimizations

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        CA[Client Applications]:::client
        FC[Frontend Components]:::client
        ST[Screen Types]:::client
        CA --> FC
        FC --> ST
    end

    subgraph WebServer
        WS[Phoenix Web Server]:::server
        Auth[Authentication System]:::server
        WS --> Auth
    end

    subgraph CoreProcessing
        WF[Widget Framework]:::core
        SDP[Screen Data Processing]:::core
        CG[Candidate Generators]:::core
        TS[Template System]:::core
        WF --> SDP
        SDP --> CG
        CG --> TS
    end

    subgraph DataProcessing
        AP[Alert Processing]:::data
        RDP[Real-time Data Processing]:::data
        STH[Screen Type Handlers]:::data
        AP --> RDP
        RDP --> STH
    end

    subgraph ExternalServices
        CS[Cache System]:::external
        CM[Configuration Management]:::external
        API[External API Integration]:::external
        S3[S3 Storage]:::external
        MBTA[MBTA API]:::external
    end

    Client --> WS
    WS --> WF
    WF --> AP
    AP --> CS
    CS --> API
    API --> MBTA
    CM --> S3
    
    %% Component Mappings
    click CA "https://github.com/mbta/screens/tree/main/assets/src/apps/v2/"
    click FC "https://github.com/mbta/screens/tree/main/assets/src/components/v2/"
    click WF "https://github.com/mbta/screens/tree/main/lib/screens/v2/widget_instance/"
    click SDP "https://github.com/mbta/screens/tree/main/lib/screens/v2/screen_data/"
    click CG "https://github.com/mbta/screens/tree/main/lib/screens/v2/candidate_generator/"
    click TS "https://github.com/mbta/screens/tree/main/lib/screens/v2/template/"
    click AP "https://github.com/mbta/screens/tree/main/lib/screens/alerts/"
    click CS "https://github.com/mbta/screens/tree/main/lib/screens/cache/"
    click CM "https://github.com/mbta/screens/tree/main/lib/screens/config/"
    click WS "https://github.com/mbta/screens/tree/main/lib/screens_web/"
    click RDP "https://github.com/mbta/screens/tree/main/lib/screens/v2/departure/"
    click API "https://github.com/mbta/screens/tree/main/lib/screens/v3_api/"
    click STH "https://github.com/mbta/screens/tree/main/lib/screens/v2/candidate_generator/widgets/"
    click Auth "https://github.com/mbta/screens/tree/main/lib/screens_web/auth_manager/"

    classDef client fill:#3498db,stroke:#2980b9,color:white
    classDef server fill:#2ecc71,stroke:#27ae60,color:white
    classDef core fill:#f1c40f,stroke:#f39c12,color:black
    classDef data fill:#e74c3c,stroke:#c0392b,color:white
    classDef external fill:#9b59b6,stroke:#8e44ad,color:white

    %% Legend
    subgraph Legend
        L1[Client Components]:::client
        L2[Server Components]:::server
        L3[Core Processing]:::core
        L4[Data Processing]:::data
        L5[External Services]:::external
    end
```
