# broscr/iptv-player architecture

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

- Interactive diagram: https://gitdiagram.com/broscr/iptv-player
- Repository: https://github.com/broscr/iptv-player

## Overview

##### Project type and purpose
- This is an Android mobile application (“IPTV Player”) whose sole purpose is to load and play IPTV streams from M3U playlist files. It’s built in a single Gradle “app” module with standard Android project conventions (Activities, Fragments, resources, tests).

##### File structure
- Top-level: build scripts, Gradle wrapper, settings.gradle, LICENSE, README, images
- “app/” module:
- src/main/java/com/broscr/iptvplayer – application code organized into packages: adapters, database, filereader, models, ui (activities & fragments), utils
- src/main/res – layouts, drawables, menus, values (themes, strings)
- src/androidTest & src/test – instrumentation and unit tests
- Dependencies declared in app/build.gradle include Realm (local DB), ExoPlayer (media playback), EasyPermissions, Timber.

##### Key insights from the README
- Reads only M3U files (local or remote)
- Screenshots show screens: File select → Home (categories) → Channel list → Player → Favorites → About
- Uses Realm to store favorites/metadata, ExoPlayer to stream, EasyPermissions for runtime storage/Internet permissions, Timber for logging

##### Main components
a. Presentation Layer
- Activities & Fragments: FileSelectActivity, MainActivity (home/categories), ChannelActivity (list), PlayerActivity, AboutFragment, FavoriteFragment
- Adapters & ViewModels: CategoryAdapter, ChannelListAdapter, SearchAdapter, ChannelViewModel, AboutViewModel, etc.
b. Domain / ViewModel Layer
- ViewModels mediate between UI and Data Layer
- ChannelViewFactory builds channel entry views
c. Data Layer
- FileReader: parses M3U files and extracts categories + channel URLs
- IPTvRealm: manages Realm database for favorites and caching metadata
d. Playback Engine
- ExoPlayer component invoked by PlayerActivity for video/audio streaming
e. Utilities & Services
- EasyPermissions: requesting READ_EXTERNAL_STORAGE or network permission
- Timber: centralized logging
- Helper classes for click callbacks (CategoryOnClick, ChannelOnClick)
f. External Systems
- Local file system (M3U file selected by user)
- Network endpoints for live streams encoded in M3U
- Third-party libraries (Realm, ExoPlayer, etc.)

##### Relationships and flows
- User taps “Select File” → FileSelectActivity → EasyPermissions → FileReader reads/parses M3U → populates Model objects (Category, Channel) → stored or cached via IPTvRealm → ViewModel exposes LiveData to MainActivity/Fragments → Adapters render lists
- User selects a channel → ChannelViewModel provides channel URL → PlayerActivity initializes ExoPlayer with URL → ExoPlayer streams content → video view in UI
- Favorite toggle → ViewModel updates Realm database → FavoriteFragment reads from Realm
- Logging events flow from all layers through Timber to the Android log.

##### Architectural patterns & design principles
- MVVM (Model-View-ViewModel) in UI packages
- Repository-style Data Layer (FileReader + Realm as data sources)
- Clear separation of concerns: UI, business logic, data storage, playback engine
- Dependency on open-source libraries kept modular

## Diagram (Mermaid)

```mermaid
graph TB
    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        FS["FileSelectActivity"]:::ui
        MA["MainActivity"]:::ui
        CA["ChannelActivity"]:::ui
        PA["PlayerActivity"]:::ui
        AF["AboutFragment"]:::ui
        FF["FavoriteFragment"]:::ui
        CF["CategoriesFragment"]:::ui

        CatAd["CategoryAdapter"]:::ui
        ChListAd["ChannelListAdapter"]:::ui
        SearchAd["SearchAdapter"]:::ui

        CVF["ChannelViewFactory"]:::ui
    end

    %% ViewModel Layer
    subgraph "ViewModel Layer"
        direction TB
        ChVM["ChannelViewModel"]:::ui
        AbVM["AboutViewModel"]:::ui
        FavVM["FavoriteViewModel"]:::ui
        CatVM["CategoriesViewModel"]:::ui
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        FR["FileReader"]:::data
        DB["IPTvRealm"]:::data
        CM["Channel Model"]:::data
    end

    %% Playback Engine
    subgraph "Playback Engine"
        direction TB
        EP["ExoPlayer"]:::playback
    end

    %% Utilities & Services
    subgraph "Utilities & Services"
        direction TB
        EPm["EasyPermissions"]:::util
        TM["Timber"]:::util
        COn["CategoryOnClick"]:::util
        ChOn["ChannelOnClick"]:::util
        HL["Helper"]:::util
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        FSYS["File System"]:::external
        NET["Network Streams"]:::external
        Libs["Third-Party Libraries"]:::external
    end

    %% Relationships
    FS -->|request permission| EPm
    EPm -->|open file| FSYS
    FS -->|file path| FR
    FR -->|parse M3U playlist| CM
    CM -->|store metadata| DB
    MA -->|show categories| CatVM
    CF -->|bind data| CatVM
    CatVM -->|categories list| CatAd
    CatAd -->|onClick| COn
    COn -->|select category| CF

    MA -->|show channels| ChVM
    CA -->|bind data| ChVM
    ChVM -->|channels list| ChListAd
    ChListAd -->|onClick| ChOn
    ChOn -->|select channel| CA

    CA -->|channel URL| PA
    PA -->|initialize| EP
    EP -->|stream content| NET
    PA -->|video output| PA

    AF -->|info data| AbVM
    FF -->|favorites data| FavVM

    FavVM -->|queries| DB
    AbVM -->|static content| Libs

    DB -->|persist| FSYS

    %% Logging
    FS -->|log event| TM
    MA -->|log event| TM
    CA -->|log event| TM
    PA -->|log event| TM
    FR -->|log event| TM
    DB -->|log event| TM

    %% Click events
    click FS "https://github.com/broscr/iptv-player/blob/master/app/src/main/java/com/broscr/iptvplayer/ui/activitys/fileselect/FileSelectActivity.java"
    click MA "https://github.com/broscr/iptv-player/blob/master/app/src/main/java/com/broscr/iptvplayer/ui/activitys/main/MainActivity.java"
    click CA "https://github.com/broscr/iptv-player/blob/master/app/src/main/java/com/broscr/iptvplayer/ui/activitys/channels/ChannelActivity.java"
    click PA "https://github.com/broscr/iptv-player/blob/master/app/src/main/java/com/broscr/iptvplayer/ui/activitys/player/PlayerActivity.java"
    click AF "https://github.com/broscr/iptv-player/blob/master/app/src/main/java/com/broscr/iptvplayer/ui/fragments/about/AboutFragment.java"
    click FF "https://github.com/broscr/iptv-player/blob/master/app/src/main/java/com/broscr/iptvplayer/ui/fragments/favorite/FavoriteFragment.java"
    click CF "https://github.com/broscr/iptv-player/blob/master/app/src/main/java/com/broscr/iptvplayer/ui/fragments/home/CategoriesFragment.java"
    click CatAd "https://github.com/broscr/iptv-player/blob/master/app/src/main/java/com/broscr/iptvplayer/adapters/CategoryAdapter.java"
    click ChListAd "https://github.com/broscr/iptv-player/blob/master/app/src/main/java/com/broscr/iptvplayer/adapters/ChannelListAdapter.java"
    click SearchAd "https://github.com/broscr/iptv-player/blob/master/app/src/main/java/com/broscr/iptvplayer/adapters/SearchAdapter.java"
    click ChVM "https://github.com/broscr/iptv-player/blob/master/app/src/main/java/com/broscr/iptvplayer/ui/activitys/channels/ChannelViewModel.java"
    click AbVM "https://github.com/broscr/iptv-player/blob/master/app/src/main/java/com/broscr/iptvplayer/ui/fragments/about/AboutViewModel.java"
    click FavVM "https://github.com/broscr/iptv-player/blob/master/app/src/main/java/com/broscr/iptvplayer/ui/fragments/favorite/FavoriteViewModel.java"
    click CatVM "https://github.com/broscr/iptv-player/blob/master/app/src/main/java/com/broscr/iptvplayer/ui/fragments/home/CategoriesViewModel.java"
    click CVF "https://github.com/broscr/iptv-player/blob/master/app/src/main/java/com/broscr/iptvplayer/ui/activitys/channels/ChannelViewFactory.java"
    click FR "https://github.com/broscr/iptv-player/blob/master/app/src/main/java/com/broscr/iptvplayer/filereader/FileReader.java"
    click DB "https://github.com/broscr/iptv-player/blob/master/app/src/main/java/com/broscr/iptvplayer/database/IPTvRealm.java"
    click CM "https://github.com/broscr/iptv-player/blob/master/app/src/main/java/com/broscr/iptvplayer/models/Channel.java"
    click COn "https://github.com/broscr/iptv-player/blob/master/app/src/main/java/com/broscr/iptvplayer/utils/CategoryOnClick.java"
    click ChOn "https://github.com/broscr/iptv-player/blob/master/app/src/main/java/com/broscr/iptvplayer/utils/ChannelOnClick.java"
    click HL "https://github.com/broscr/iptv-player/blob/master/app/src/main/java/com/broscr/iptvplayer/utils/Helper.java"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085
    classDef data fill:#d4edda,stroke:#155724,color:#155724
    classDef playback fill:#ffe5b4,stroke:#ff8c00,color:#8c4500
    classDef util fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef external fill:#f8f9fa,stroke:#6c757d,color:#6c757d
```
