# srgssr/pillarbox-apple architecture

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

## Overview

##### Overall project purpose and its main architectural layers
- The project is a Swift Package integrated with SwiftUI and AVFoundation/AVKit. Pillarbox is an extensible, modern media player library that handles playback features, stream resource loading (including DRM/FairPlay), analytics/monitoring, advanced user interface integration, and even testing support via its companion “Circumspect” framework.
- It is intended for both production use (by consumers integrating it in their apps or using the Demo project) and as an open-source component with clear separation into several functional modules.

##### Main components and modules to be represented
- Core Modules:
– Core: Contains essential tools, reactive publishers, time utilities, and fundamental extensions.
– CoreBusiness: Provides content-related business logic (data providers, media composition handling, server interactions).
- Player Engine:
– The Player module is the central media playing component that integrates AVFoundation, AVKit, and system services (like Control Center, Picture in Picture, and AirPlay). It includes support for playback controls, media selection, metrics, and playback state management.
- Analytics & Monitoring:
– Analytics: Integrates with external analytic platforms such as ComScore and CommandersAct, capturing events and user interaction metrics.
– Monitoring: Focuses on real-time metrics, error reporting, QoE/QoS monitoring and integrates with system logging.
- Supplementary and Utility Modules:
– Circumspect: A testing utilities framework aimed at verifying Combine pipelines and publisher behaviors.
– Streams: Handling for basic media streams (e.g., providing test audio streams).
– Plugin: A build plugin that inserts versioning information automatically into binaries.
- Demo/Showcase:
– The Demo project demonstrates usage via SwiftUI, showcasing various players, playlists, chapters, storytelling, and interactive UI components.
- External Dependencies & Integration Points:
– AVFoundation/AVKit for media playback features.
– The system’s SwiftUI elements for creating reactive, custom user interfaces.
– Integration with build systems (Swift Package Manager, Xcode configuration files, CI workflows).

##### Relationships and interactions
– “Core” and “CoreBusiness” as foundational libraries.
– “Player” module sits above these, relying on core utility functions plus specialized media selection and playback features.
– “Analytics” and “Monitoring” modules are connected to the “Player” component to capture event data and system metrics.
– The “Demo” component acts as a consumer/interface layer that illustrates how the Player and its auxiliary modules are used within a UI context.
– The Demo (client) consumes the Player API (via SwiftUI views and user interactions).
– The Player communicates with CoreBusiness/ Core modules for backend functionalities.
– Playback events and quality metrics flow from the Player to the Analytics/Monitoring systems.
– Testing tools (Circumspect) interact with these foundational components to simulate or validate behavior.
– The Plugin is part of the build and deployment process, integrated with CI workflows.
– Additionally, indicate integrations with external frameworks (AVFoundation, AVKit, external quality-of-experience systems).

##### Architectural patterns and design principles
- Modularity: The project is split into self-contained modules (Core, Player, Analytics, etc.) that can be integrated independently.
- Reactive design: Built around Combine-based publishers and observers, allowing for reactive streaming of playback events and metrics.
- Customization and extensibility: The layered structure (from low-level resource handling up to UI) promotes flexibility, allowing developers to override or extend functionality as needed.
- Clear separation of concerns: UI concerns are separated from business logic (CoreBusiness), and playback logic (Player) is decoupled from analytics and monitoring.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External and Client Layer
    Demo["Demo/Showcase (SwiftUI UI)"]:::app
    SwiftUI["SwiftUI"]:::external
    CI["CI Workflows"]:::external
    AV["AVFoundation/AVKit"]:::external

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        Core["Core"]:::infra
        CoreBusiness["CoreBusiness"]:::infra
    end

    %% Media Playback Layer
    subgraph "Media Playback Core"
        Player["Player Engine"]:::app
        Streams["Streams"]:::app
    end

    %% Analytics & Monitoring Layer
    subgraph "Analytics & Monitoring"
        Analytics["Analytics"]:::cross
        Monitoring["Monitoring"]:::cross
    end

    %% Testing & Build Tools
    subgraph "Testing & Build"
        Circumspect["Circumspect (Testing Utilities)"]:::test
        Plugin["Plugin (Build Plugin)"]:::build
    end

    %% Connections from Demo and External frameworks
    Demo -->|"uses"| Player
    Demo -->|"builtWith"| SwiftUI
    Player -->|"uses"| AV

    %% Connections within internal layers
    Player -->|"dependsOn"| Core
    Player -->|"dependsOn"| CoreBusiness
    Player -->|"integrates"| Streams
    Player -->|"logsTo"| Analytics
    Player -->|"reportsTo"| Monitoring

    %% Testing interactions
    Circumspect -->|"tests"| Player
    Circumspect -->|"tests"| Core

    %% Build integration
    Plugin -->|"integratesWith"| CI

    %% Styling Classes
    classDef infra fill:#A9D0F5,stroke:#1E90FF,stroke-width:2px;
    classDef app fill:#C4F9CF,stroke:#2ECC71,stroke-width:2px;
    classDef cross fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef test fill:#F5B7B1,stroke:#E74C3C,stroke-width:2px;
    classDef build fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef external fill:#D5DBDB,stroke:#7F8C8D,stroke-width:2px;

    %% Click Events for Component Mapping
    click Core "https://github.com/srgssr/pillarbox-apple/tree/main/Sources/Core"
    click CoreBusiness "https://github.com/srgssr/pillarbox-apple/tree/main/Sources/CoreBusiness"
    click Player "https://github.com/srgssr/pillarbox-apple/tree/main/Sources/Player"
    click Streams "https://github.com/srgssr/pillarbox-apple/tree/main/Sources/Streams"
    click Analytics "https://github.com/srgssr/pillarbox-apple/tree/main/Sources/Analytics"
    click Monitoring "https://github.com/srgssr/pillarbox-apple/tree/main/Sources/Monitoring"
    click Circumspect "https://github.com/srgssr/pillarbox-apple/tree/main/Sources/Circumspect"
    click Plugin "https://github.com/srgssr/pillarbox-apple/blob/main/Plugins/PackageInfoPlugin/plugin.swift"
    click Demo "https://github.com/srgssr/pillarbox-apple/tree/main/Demo"
```
