# guovin/iptv architecture

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

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

## Overview

IPTV-API collects local and subscription-based channel sources, normalizes and aggregates candidates, tests stream availability and quality, then generates playlists and API-accessible results. Its desktop and legacy Tk interfaces expose configuration and operational controls; the desktop controller dispatches channel operations and manages service interactions. The README also documents EPG, RTMP streaming, playback screenshots, and result management. The excerpts show selected orchestration and storage behavior, so links for unsampled feature wiring are omitted where uncertain.

Main entry points: [`main.py`](https://github.com/guovin/iptv/blob/master/main.py) (Source collection), [`utils/channel_operations.py`](https://github.com/guovin/iptv/blob/master/utils/channel_operations.py) (Channel operations), [`desktop_ui/main_window.py`](https://github.com/guovin/iptv/blob/master/desktop_ui/main_window.py) (Desktop UI), [`service/app.py`](https://github.com/guovin/iptv/blob/master/service/app.py) (HTTP service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_gui["Desktop UI<br/>[main_window.py]"]
  node_controller["Update controller<br/>[controller.py]"]
  node_legacy_ui["Tk interface<br/>[tkinter_ui.py]"]
  node_config["Configuration<br/>[config.py]"]
end

subgraph group_collection["Collection and enrichment"]
  node_sources["Source collection<br/>[main.py]"]
  node_subscriptions["Subscription fetch<br/>[request.py]"]
  node_epg["EPG enrichment<br/>[request.py]"]
end

subgraph group_processing["Validation and results"]
  node_aggregation["Channel aggregation<br/>[aggregator.py]"]
  node_operations["Channel operations"]
  node_quality["Stream testing<br/>[channel_quality.py]"]
  node_ffmpeg["Media probing<br/>[probe.py]"]
  node_repository[("Result repository")]
  node_artifacts["Playlist artifacts<br/>[artifacts.py]"]
end

subgraph group_runtime["Serving and playback"]
  node_entry["Application entry<br/>[main.py]"]
  node_service["HTTP service<br/>[app.py]"]
  node_rtmp["RTMP streaming<br/>[rtmp.py]"]
end

node_user(("User"))
node_external_sources(("Source services"))
node_players(("Playlist players"))
node_browser(("Browser client"))

node_user -->|"operates"| node_gui
node_user -->|"configures"| node_legacy_ui
node_gui -->|"dispatches"| node_controller
node_gui -->|"configures"| node_config
node_legacy_ui -->|"updates"| node_config
node_controller -->|"invokes"| node_operations
node_entry -->|"runs"| node_sources
node_sources -->|"fetches"| node_subscriptions
node_subscriptions -->|"requests"| node_external_sources
node_sources -->|"aggregates"| node_aggregation
node_sources -->|"fetches EPG"| node_epg
node_epg -->|"requests"| node_external_sources
node_operations -->|"tests streams"| node_quality
node_quality -->|"probes media"| node_ffmpeg
node_operations -->|"persists results"| node_repository
node_operations -->|"writes outputs"| node_artifacts
node_repository -->|"serves results"| node_service
node_user -->|"requests"| node_service
node_service -->|"routes streaming"| node_rtmp
node_rtmp -->|"streams media"| node_browser
node_artifacts -->|"imports playlists"| node_players

click node_gui "https://github.com/guovin/iptv/blob/master/desktop_ui/main_window.py"
click node_controller "https://github.com/guovin/iptv/blob/master/desktop_ui/controller.py"
click node_legacy_ui "https://github.com/guovin/iptv/blob/master/tkinter_ui/tkinter_ui.py"
click node_config "https://github.com/guovin/iptv/blob/master/utils/config.py"
click node_entry "https://github.com/guovin/iptv/blob/master/main.py"
click node_service "https://github.com/guovin/iptv/blob/master/service/app.py"
click node_rtmp "https://github.com/guovin/iptv/blob/master/service/rtmp.py"
click node_sources "https://github.com/guovin/iptv/blob/master/main.py"
click node_subscriptions "https://github.com/guovin/iptv/blob/master/updates/subscribe/request.py"
click node_epg "https://github.com/guovin/iptv/blob/master/updates/epg/request.py"
click node_aggregation "https://github.com/guovin/iptv/blob/master/utils/aggregator.py"
click node_operations "https://github.com/guovin/iptv/blob/master/utils/channel_operations.py"
click node_quality "https://github.com/guovin/iptv/blob/master/utils/channel_quality.py"
click node_ffmpeg "https://github.com/guovin/iptv/blob/master/utils/ffmpeg/probe.py"
click node_repository "https://github.com/guovin/iptv/blob/master/utils/channel_repository.py"
click node_artifacts "https://github.com/guovin/iptv/blob/master/utils/artifacts.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gui,node_controller,node_legacy_ui,node_config,node_user,node_browser toneBlue
class node_sources,node_subscriptions,node_epg toneAmber
class node_aggregation,node_operations,node_quality,node_ffmpeg,node_repository,node_artifacts toneMint
class node_entry,node_service,node_rtmp toneRose
class node_external_sources,node_players toneIndigo
```

## Components

### User interfaces

- [Desktop UI](https://github.com/guovin/iptv/blob/master/desktop_ui/main_window.py): `desktop_ui/main_window.py`
- [Update controller](https://github.com/guovin/iptv/blob/master/desktop_ui/controller.py): `desktop_ui/controller.py`
- [Tk interface](https://github.com/guovin/iptv/blob/master/tkinter_ui/tkinter_ui.py): `tkinter_ui/tkinter_ui.py`
- [Configuration](https://github.com/guovin/iptv/blob/master/utils/config.py): `utils/config.py`

### Collection and enrichment

- [Source collection](https://github.com/guovin/iptv/blob/master/main.py): `main.py`
- [Subscription fetch](https://github.com/guovin/iptv/blob/master/updates/subscribe/request.py): `updates/subscribe/request.py`
- [EPG enrichment](https://github.com/guovin/iptv/blob/master/updates/epg/request.py): `updates/epg/request.py`

### Validation and results

- [Channel aggregation](https://github.com/guovin/iptv/blob/master/utils/aggregator.py): `utils/aggregator.py`
- [Channel operations](https://github.com/guovin/iptv/blob/master/utils/channel_operations.py): `utils/channel_operations.py`
- [Stream testing](https://github.com/guovin/iptv/blob/master/utils/channel_quality.py): `utils/channel_quality.py`
- [Media probing](https://github.com/guovin/iptv/blob/master/utils/ffmpeg/probe.py): `utils/ffmpeg/probe.py`
- [Result repository](https://github.com/guovin/iptv/blob/master/utils/channel_repository.py): `utils/channel_repository.py`
- [Playlist artifacts](https://github.com/guovin/iptv/blob/master/utils/artifacts.py): `utils/artifacts.py`

### Serving and playback

- [Application entry](https://github.com/guovin/iptv/blob/master/main.py): `main.py`
- [HTTP service](https://github.com/guovin/iptv/blob/master/service/app.py): `service/app.py`
- [RTMP streaming](https://github.com/guovin/iptv/blob/master/service/rtmp.py): `service/rtmp.py`

### Other components

- **User**
- **Source services**
- **Playlist players**
- **Browser client**

## Connections

- User → Desktop UI: operates
- User → Tk interface: configures
- Desktop UI → Update controller: dispatches
- Desktop UI → Configuration: configures
- Tk interface → Configuration: updates
- Update controller → Channel operations: invokes
- Application entry → Source collection: runs
- Source collection → Subscription fetch: fetches
- Subscription fetch → Source services: requests
- Source collection → Channel aggregation: aggregates
- Source collection → EPG enrichment: fetches EPG
- EPG enrichment → Source services: requests
- Channel operations → Stream testing: tests streams
- Stream testing → Media probing: probes media
- Channel operations → Result repository: persists results
- Channel operations → Playlist artifacts: writes outputs
- Result repository → HTTP service: serves results
- User → HTTP service: requests
- HTTP service → RTMP streaming: routes streaming
- RTMP streaming → Browser client: streams media
- Playlist artifacts → Playlist players: imports playlists