# kananinirav/indian-iptv-app architecture

> Architecture diagram of the GitHub repository kananinirav/indian-iptv-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kananinirav/indian-iptv-app
- Repository: https://github.com/kananinirav/indian-iptv-app

## Overview

This repo is a **Flutter-based IPTV client** packaged primarily for **Android (mobile + Android TV)** (with a `web/` target present). The app is essentially a **simple M3U/streaming player**:
- Displays a **catalog of 500+ channels**
- Supports **search**
- Plays a selected channel in **full screen**

From the tree, the “architecture” is mostly **client-side** (no backend service in this repo). The critical system interactions are **app ⇄ channel list source ⇄ streaming servers/CDNs**.

##### Flutter / Dart application (primary)
- `lib/main.dart`
App entry point: routes, app bootstrap, dependency wiring.
- `lib/screens/home.dart`
Channel listing/search UI (likely list/grid; TV vs mobile behavior may be conditional).
- `lib/screens/player.dart`
Player UI + playback lifecycle.
- `lib/provider/channels_provider.dart`
**State management / orchestration** (likely Provider pattern): fetch/parse channels, store list, search filter, selection.
- `lib/model/channel.dart`
Data model for a channel (name, logo, stream URL, group/category, etc.).
- `assets/`, `assets/images`, `images/`
Static assets (logos, screenshots).

##### Platform packaging / host shells
- `android/…`
Android host app, Gradle config, `MainActivity.kt` (Flutter activity), manifests for debug/profile/main.
- `web/index.html`, `web/manifest.json`
Web host shell (if supported).

##### External dependencies (not in tree but implied)
- **Channel source / playlist** (README credits an external repo; likely consumed as an M3U or JSON derived from it)
- **Streaming endpoints** (each channel URL points to a remote stream origin/CDN)
- **Flutter plugins** (e.g., video_player / better_player / chewie or similar—confirm via `pubspec.yaml` when drawing final tech labels)

##### User launches app
- `main.dart` initializes Flutter app + Provider(s)
##### Channel catalog loads
- `ChannelsProvider` fetches playlist/channel metadata (remote or bundled—verify implementation)
- Parses into `Channel` models
- Exposes `List<Channel>` to UI
##### Browse/search
- `HomeScreen` observes provider state
- Search input triggers provider filtering
##### Select channel
- UI navigates to `PlayerScreen` with selected `Channel`
##### Playback
- `PlayerScreen` initializes player plugin with `channel.streamUrl`
- Player connects to **external streaming server**
- Fullscreen/orientation handling is in player screen + platform shell

- `HomeScreen → ChannelsProvider` (read state, invoke search/load)
- `ChannelsProvider → Channel Source (HTTP)` (fetch playlist/metadata)
- `ChannelsProvider → Channel model` (parse/map)
- `HomeScreen → PlayerScreen` (navigation + selected channel)
- `PlayerScreen → Video Player Plugin → Stream Origin/CDN` (media streaming)
- Optionally: `Flutter App → Android Shell` (for TV/mobile specifics, intents, lifecycle)

##### Architectural pattern to highlight (how to explain structure)
This project is best shown as a **layered client architecture**:
- **Presentation layer**: `screens/` (home + player)
- **State/Controller layer**: `provider/` (ChannelsProvider)
- **Domain model layer**: `model/` (Channel)
- **Infrastructure**:
- Network fetch/parsing inside provider (or helper—if present in code)
- Player plugin integration inside player screen
- Platform shells (`android/`, `web/`) for packaging and runtime hosting

Call out that there’s **no backend in-repo**; the “system” includes external playlist and stream providers.

**Goal:** Show what the app is and who/what it talks to.

- **User** (Mobile user / Android TV user)
- **IPTV Flutter App**
- **Streaming Servers/CDNs** (multiple channel origins)

- User ↔ App (browse/search/play)
- App → Channel List Source (download playlist/metadata)
- App → Streaming Servers (HLS/DASH/etc streaming)

**Goal:** Break “IPTV Flutter App” into major deployable/runtime containers.

Containers here are:
- **Flutter UI + State (Dart runtime)**
- **Android Host (Kotlin/Gradle; APK packaging)** and optionally **Web Host (index.html/manifest)**

Inside “Flutter UI + State”, show:
- Home UI
- Player UI
- Channels Provider (state)
- Channel Model

Also add:
- **Video Playback Plugin** (as a dependency container bridging to platform decoders)
- **HTTP client** (built-in `dart:io`/`http` package—confirm via pubspec)

- Home UI ↔ Provider
- Provider → Channel Source
- Player UI → Video Plugin → Streaming Servers
- Flutter runtime ↔ Android host (lifecycle, fullscreen, TV input, etc.)

Components (label with exact filenames):
- `main.dart` (bootstrap, routing, provider registration)
- `screens/home.dart` (channel list + search + select)
- `provider/channels_provider.dart` (load/parse/filter channels)
- `model/channel.dart` (DTO/model)
- `screens/player.dart` (player initialization, fullscreen controls)

- `channels_provider.dart` outputs:
- `allChannels`
- `filteredChannels` (search results)
- `selectedChannel` (if stateful)
- `home.dart` consumes filtered list, emits “channelSelected(channel)”
- `player.dart` consumes selected channel URL, invokes playback plugin

##### Make it “very detailed” without overthinking: split into more components
Because the repo is small, detail comes from **explicitly splitting responsibilities**:
- Separate “Channel Catalog Fetch” vs “Playlist Parsing” vs “Search Filter”
- Even if in one file, show them as sub-components within `ChannelsProvider`
- Separate “Player UI Controls” vs “Player Engine/Plugin”
- Separate “Assets (logos)” vs “Remote logos” if applicable

- **Image CDN/hosts** (App → image hosts for thumbnails)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% A) System Context (L1)
  %% =========================
  subgraph L1["System Context (C4 Level 1)"]
    direction TB
    User["User\n(Android Mobile / Android TV)"]:::actor
    App["IPTV Flutter App\n(Flutter/Dart)"]:::app
    PlaylistSrc[("Channel List Source\n(Playlist/M3U/Metadata over HTTP)")]:::external
    StreamCDN[("Streaming Servers / CDNs\n(HLS/DASH/MP4 streams)")]:::external
    ImageHosts[("Image Hosts / CDNs\n(Channel logos/thumbnails)")]:::external

    User -->|"browse/search/select"| App
    App -->|"fetchPlaylist(HTTP)"| PlaylistSrc
    App -->|"streamMedia(URL)"| StreamCDN
    App -.->|"loadLogos(HTTP)"| ImageHosts
  end

  %% =========================
  %% B) Containers (L2)
  %% =========================
  subgraph L2["Containers (C4 Level 2)"]
    direction TB

    subgraph FlutterRuntime["Flutter UI + State Container\n(Dart runtime)"]
      direction TB
      HomeUI["Home UI\n(Channel catalog + search)"]:::ui
      PlayerUI["Player UI\n(Fullscreen playback)"]:::ui
      Provider["Channels Provider\n(State + orchestration)"]:::state
      Model["Channel Model\n(DTO/domain)"]:::model
      Assets["Static Assets\n(Logos/images)"]:::assets

      HomeUI <-->|"observeState()/search()"| Provider
      Provider -->|"parse/map"| Model
      HomeUI -->|"navigate(selectedChannel)"| PlayerUI
      PlayerUI -->|"renderLogo/assets"| Assets
      HomeUI -->|"renderLogo/assets"| Assets
    end

    HttpClient["HTTP Client\n(dart:io / package:http)"]:::infra
    VideoPlugin["Video Playback Plugin\n(platform decoder bridge)"]:::infra

    subgraph AndroidHost["Android Host Shell\n(Kotlin/Gradle, APK)"]
      direction TB
      MainActivity["MainActivity (FlutterActivity)"]:::platform
      AndroidManifest["AndroidManifest.xml"]:::platform
      AndroidGradle["Gradle Build (app)"]:::platform
    end

    subgraph WebHost["Web Host Shell\n(HTML/PWA)"]
      direction TB
      WebIndex["index.html"]:::platform
      WebManifest["manifest.json"]:::platform
    end

    FlutterRuntime -->|"HTTP GET"| HttpClient
    HttpClient -->|"downloadPlaylist"| PlaylistSrc

    PlayerUI -->|"initPlayer(streamUrl)"| VideoPlugin
    VideoPlugin -->|"connectToStream"| StreamCDN

    FlutterRuntime <-->|"lifecycle/fullscreen/orientation"| AndroidHost
    FlutterRuntime -.->|"webBootstrap"| WebHost
  end

  %% =========================
  %% C) Components (L3)
  %% =========================
  subgraph L3["Flutter App Components (C4 Level 3)"]
    direction TB

    MainDart["main.dart\n(App bootstrap, routes, provider registration)"]:::app
    ScreensDir["lib/screens/\n(Presentation layer)"]:::folder
    ProvidersDir["lib/provider/\n(State/controller layer)"]:::folder
    ModelsDir["lib/model/\n(Domain models)"]:::folder

    HomeDart["screens/home.dart\n(List/search UI, selection)"]:::ui
    PlayerDart["screens/player.dart\n(Player lifecycle + fullscreen UI)"]:::ui
    ChannelsProviderDart["provider/channels_provider.dart\n(fetch/parse/filter channels)"]:::state
    ChannelModelDart["model/channel.dart\n(Channel fields: name/logo/url/group)"]:::model

    subgraph ProviderInternals["ChannelsProvider responsibilities (internal split)"]
      direction TB
      FetchCatalog["Channel Catalog Fetch\n(playlist URL or bundled asset)"]:::infra
      ParsePlaylist["Playlist Parsing\n(M3U/JSON -> Channel)"]:::infra
      SearchFilter["Search/Filter\n(allChannels -> filteredChannels)"]:::infra
      SelectionState["Selection State\n(selectedChannel)"]:::infra

      ChannelsProviderDart -->|"calls"| FetchCatalog
      FetchCatalog -->|"uses"| HttpClientL3["HTTP Client"]:::infra
      HttpClientL3 -->|"GET"| PlaylistSrc

      ChannelsProviderDart -->|"calls"| ParsePlaylist
      ParsePlaylist -->|"creates"| ChannelModelDart

      ChannelsProviderDart -->|"calls"| SearchFilter
      ChannelsProviderDart -->|"updates"| SelectionState
    end

    subgraph PlayerInternals["PlayerScreen responsibilities (internal split)"]
      direction TB
      PlayerControls["Player UI Controls\n(play/pause/fullscreen)"]:::ui
      PlayerEngine["Player Engine Adapter\n(wraps plugin controller)"]:::infra

      PlayerDart -->|"owns"| PlayerControls
      PlayerDart -->|"owns"| PlayerEngine
      PlayerEngine -->|"uses"| VideoPluginL3["Video Playback Plugin"]:::infra
      VideoPluginL3 -->|"streamMedia"| StreamCDN
    end

    MainDart -->|"registerProvider()"| ChannelsProviderDart
    MainDart -->|"routeToHome()"| HomeDart
    HomeDart -->|"reads(filteredChannels)"| ChannelsProviderDart
    HomeDart -->|"channelSelected(channel)"| ChannelsProviderDart
    HomeDart -->|"navigateToPlayer(channel)"| PlayerDart
    PlayerDart -->|"uses"| ChannelModelDart

    ScreensDir --> HomeDart
    ScreensDir --> PlayerDart
    ProvidersDir --> ChannelsProviderDart
    ModelsDir --> ChannelModelDart

    Pubspec["pubspec.yaml\n(Dependencies: provider/http/video plugins)"]:::config
    Pubspec -.->|"declares"| VideoPluginL3
    Pubspec -.->|"declares"| HttpClientL3
  end

  %% =========================
  %% Click events (from component_mapping)
  %% =========================
  click MainDart "https://github.com/kananinirav/indian-iptv-app/blob/master/lib/main.dart"
  click HomeDart "https://github.com/kananinirav/indian-iptv-app/blob/master/lib/screens/home.dart"
  click PlayerDart "https://github.com/kananinirav/indian-iptv-app/blob/master/lib/screens/player.dart"
  click ChannelsProviderDart "https://github.com/kananinirav/indian-iptv-app/blob/master/lib/provider/channels_provider.dart"
  click ChannelModelDart "https://github.com/kananinirav/indian-iptv-app/blob/master/lib/model/channel.dart"
  click ScreensDir "https://github.com/kananinirav/indian-iptv-app/tree/master/lib/screens/"
  click ProvidersDir "https://github.com/kananinirav/indian-iptv-app/tree/master/lib/provider/"
  click ModelsDir "https://github.com/kananinirav/indian-iptv-app/tree/master/lib/model/"
  click Assets "https://github.com/kananinirav/indian-iptv-app/tree/master/assets/"
  click AndroidHost "https://github.com/kananinirav/indian-iptv-app/tree/master/android/"
  click MainActivity "https://github.com/kananinirav/indian-iptv-app/blob/master/android/app/src/main/kotlin/com/example/live_tv/MainActivity.kt"
  click AndroidManifest "https://github.com/kananinirav/indian-iptv-app/blob/master/android/app/src/main/AndroidManifest.xml"
  click AndroidGradle "https://github.com/kananinirav/indian-iptv-app/blob/master/android/app/build.gradle"
  click WebIndex "https://github.com/kananinirav/indian-iptv-app/blob/master/web/index.html"
  click WebManifest "https://github.com/kananinirav/indian-iptv-app/blob/master/web/manifest.json"
  click Pubspec "https://github.com/kananinirav/indian-iptv-app/blob/master/pubspec.yaml"

  %% Bonus: additional asset paths from mapping (separate nodes for click coverage)
  AssetsImages["assets/images/"]:::assets
  ImagesDir["images/"]:::assets
  click AssetsImages "https://github.com/kananinirav/indian-iptv-app/tree/master/assets/images/"
  click ImagesDir "https://github.com/kananinirav/indian-iptv-app/tree/master/images/"

  %% =========================
  %% Styles
  %% =========================
  classDef actor fill:#FFF3CD,stroke:#B08900,stroke-width:1px,color:#3B2F00
  classDef app fill:#D1ECF1,stroke:#0C5460,stroke-width:1px,color:#06343C
  classDef ui fill:#E2E3FF,stroke:#3F3D99,stroke-width:1px,color:#1D1B5C
  classDef state fill:#D4EDDA,stroke:#155724,stroke-width:1px,color:#0B2E13
  classDef model fill:#F8D7DA,stroke:#721C24,stroke-width:1px,color:#3A0D12
  classDef infra fill:#E0E0E0,stroke:#424242,stroke-width:1px,color:#1F1F1F
  classDef platform fill:#FCE8D5,stroke:#A35A00,stroke-width:1px,color:#4A2A00
  classDef external fill:#E8F5E9,stroke:#1B5E20,stroke-width:1px,color:#0B2E13,stroke-dasharray: 4 3
  classDef assets fill:#FFF0F6,stroke:#9C1458,stroke-width:1px,color:#4A0A2A
  classDef config fill:#E6F4FF,stroke:#0B5CAD,stroke-width:1px,color:#063566
  classDef folder fill:#F3F4F6,stroke:#6B7280,stroke-width:1px,color:#111827
```
