# srgssr/pillarbox-android architecture

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

- Interactive diagram: https://gitdiagram.com/srgssr/pillarbox-android
- Repository: https://github.com/srgssr/pillarbox-android

## Overview

##### Main components of the system
- Build & Infrastructure:
– The “build-logic” directory contains custom Gradle plugins and scripts that set up builds, dependency management, and configurations.
– Files like settings.gradle.kts, gradle.properties, and the GitHub workflows indicate a mature CI/CD and build environment.
- Core Business Layer:
– Modules such as pillarbox-core-business and pillarbox-core-business-cast encapsulate the business logic for media content, metadata retrieval, DRM handling, integration with SRG SSR-specific services, and error handling.
- Media Playback Engine:
– The pillarbox-player module is at the heart of media playback. It wraps around Media3 components (such as ExoPlayer) and offers features like track selection, preloading, advertisement integrations, session management, and monitoring.
- Analytics:
– The pillarbox-analytics module integrates analytics tracking, metrics collection, and event logging during content playback.
- Casting Functionality:
– The pillarbox-cast module specializes in handling casting between devices by exposing cast-specific classes, player extensions, and track selection tailored for remote playback.
- User Interface (UI):
– The pillarbox-ui module provides the presentation layer for rendering the video surface and playback controls. It supports both Jetpack Compose and traditional XML Views.
- External Services & Configuration:
– External integrations (e.g., DRM providers, analytics providers) are indirectly referenced via the business and player modules. Make sure to capture these as external “dependencies” or “services” that the system integrates with.

##### Relationships and interactions
- The Build & Infrastructure layer (build-logic, Gradle scripts, CI configs) is used to compile, test, and deploy the system.
- The Core Business Layer is responsible for retrieving, processing, and providing media metadata and assets to the playback engine. It also encapsulates integration logic (e.g., DRMs through Akamai, content selection, etc.).
- The Media Playback Engine (pillarbox-player) consumes the business data and controls media sessions, streaming, buffering, playback speed, and error handling.
- The Analytics and Cast modules plug into the Media Playback Engine to provide additional monitoring (e.g., tracking playtime, stalls) and remote playback capabilities.
- The UI layer (pillarbox-ui) directly interacts with the player to display controls, subtitles, and other UI elements to the user.

##### Architectural patterns or principles
- The modular design clearly follows separation of concerns: Each module (business logic, media playback, analytics, cast, UI) stands on its own while collaborating via well-defined interfaces.
- Look for patterns such as MVVM in the UI (especially given the Compose support) and a clear service layer for integration with external entities.
- Dependency inversion is likely used so that core modules depend on interfaces that can be swapped out (for testing or customization).

##### Relevant technologies and frameworks
- AndroidX Media3 and ExoPlayer form the technical foundation for media playback.
- Gradle and its custom plugins (found in build-logic) manage project modularity and dependency resolution.
- Analytics, tracking, and monitoring use custom integrations which may encapsulate external SDKs.
- Both Compose and legacy XML Views are supported in the pillarbox-ui module.
- CI/CD is implemented using GitHub Actions (workflows defined under the .github directory).

##### Detailed architectural elements
- Dependency relationships and responsibilities of each module.
- Interactions (e.g., “Provides media metadata and asset URLs”, “Handles DRM and error processing”, “Manages media session and playback state”, “Tracks analytics events”, “Renders UI controls”).
- If desired, add in sub-components within key modules (for instance, within pillarbox-player, you might note analytics listeners, network request decoupling, or media session integration).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Build & Infrastructure"
        BL["build-logic"]:::build
    end

    subgraph "Core Business Layer"
        CB["pillarbox-core-business"]:::business
        CBC["pillarbox-core-business-cast"]:::business
    end

    subgraph "Media Playback Engine"
        PP["pillarbox-player"]:::playback
    end

    subgraph "Additional Features"
        A["pillarbox-analytics"]:::features
        C["pillarbox-cast"]:::features
    end

    subgraph "User Interface"
        UI["pillarbox-ui"]:::ui
    end

    subgraph "External Services"
        DRM["DRM Provider"]:::external
        AnalyticsS["Analytics Service"]:::external
        CI["GitHub Actions"]:::external
    end

    %% Build layer influences business modules and CI/CD
    BL -->|"compiles"| CB
    BL -->|"compiles"| CBC
    BL -->|"triggers"| CI

    %% Business Layer supplies media data to playback engine
    CB -->|"providesMediaMetadata"| PP
    CBC -->|"handlesDRMIntegration"| PP

    %% Playback engine integrates with additional features and UI
    PP -->|"tracksPlaybackEvents"| A
    PP -->|"enablesCast"| C
    PP -->|"updatesUI"| UI
    UI -->|"sendsUserCommands"| PP

    %% External integrations
    CBC -->|"integratesDRM"| DRM
    A -->|"reportsMetrics"| AnalyticsS

    %% Click Events
    click BL "https://github.com/srgssr/pillarbox-android/tree/main/build-logic"
    click CB "https://github.com/srgssr/pillarbox-android/tree/main/pillarbox-core-business"
    click CBC "https://github.com/srgssr/pillarbox-android/tree/main/pillarbox-core-business-cast"
    click PP "https://github.com/srgssr/pillarbox-android/tree/main/pillarbox-player"
    click A "https://github.com/srgssr/pillarbox-android/tree/main/pillarbox-analytics"
    click C "https://github.com/srgssr/pillarbox-android/tree/main/pillarbox-cast"
    click UI "https://github.com/srgssr/pillarbox-android/tree/main/pillarbox-ui"

    %% Styles
    classDef build fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef business fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef playback fill:#FFE0B2,stroke:#EF6C00,stroke-width:2px;
    classDef features fill:#FFF9C4,stroke:#F9A825,stroke-width:2px;
    classDef ui fill:#E1BEE7,stroke:#6A1B9A,stroke-width:2px;
    classDef external fill:#CFD8DC,stroke:#37474F,stroke-width:2px;
```
