# guovin/iptv-api architecture

> Architecture diagram of the GitHub repository guovin/iptv-api, 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-api
- Repository: https://github.com/guovin/iptv-api

## Overview

IPTV-API collects local and subscribed channel sources, normalizes and aggregates candidates, measures playback quality, then persists and publishes curated playlists/API results. Users can run updates through the desktop application, legacy Tk UI, or service/command entry points. The README also documents EPG, RTMP restreaming, playback screenshots, advanced filtering, and result management. Core orchestration and selected integrations are represented; unsampled implementation details are omitted, so some capability links are intentionally not inferred.

Main entry points: [`main.py`](https://github.com/guovin/iptv-api/blob/master/main.py) (Update workflow), [`service/app.py`](https://github.com/guovin/iptv-api/blob/master/service/app.py) (HTTP service), [`desktop_ui/main_window.py`](https://github.com/guovin/iptv-api/blob/master/desktop_ui/main_window.py) (Desktop UI), [`utils/ffmpeg/probe.py`](https://github.com/guovin/iptv-api/blob/master/utils/ffmpeg/probe.py) (Media probing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_desktop["Desktop UI<br/>[main_window.py]"]
  node_desktop_controller["Update controller<br/>[controller.py]"]
  node_legacy_ui["Tk UI<br/>[tkinter_ui.py]"]
  node_main["Update workflow<br/>[main.py]"]
  node_service["HTTP service<br/>[app.py]"]
  node_channel_ops["Channel operations"]
end

subgraph group_collection["Collection and enrichment"]
  node_subscriptions["Subscription fetch<br/>[request.py]"]
  node_epg["EPG processing<br/>[request.py]"]
  node_channel_model["Channel matching<br/>[channel.py]"]
  node_aggregation["Source aggregation<br/>[aggregator.py]"]
end

subgraph group_validation["Validation and persistence"]
  node_speed["Quality testing<br/>[speed.py]"]
  node_ffmpeg["Media probing<br/>[probe.py]"]
  node_repository[("Result repository")]
end

subgraph group_delivery["Playback and delivery"]
  node_artifacts["Playlist artifacts<br/>[artifacts.py]"]
  node_rtmp["RTMP streaming<br/>[rtmp.py]"]
  node_playback["Playback tools<br/>[playback.py]"]
end

subgraph group_operations["Operations and state"]
  node_config["Configuration<br/>[config.py]"]
end

node_user(("Operator"))
node_external_sources(("Source and EPG hosts"))
node_ffmpeg_service["FFmpeg tools"]
node_player(("IPTV player"))

node_user -->|"configures / starts"| node_desktop
node_user -->|"configures / starts"| node_legacy_ui
node_desktop -->|"queues updates"| node_desktop_controller
node_desktop_controller -->|"dispatches operations"| node_channel_ops
node_legacy_ui -->|"changes settings"| node_config
node_main -->|"fetches sources"| node_subscriptions
node_subscriptions -->|"requests playlists"| node_external_sources
node_main -->|"fetches EPG"| node_epg
node_epg -->|"requests listings"| node_external_sources
node_main -->|"matches channels"| node_channel_model
node_main -->|"aggregates candidates"| node_aggregation
node_main -->|"tests candidates"| node_speed
node_speed -->|"probes streams"| node_ffmpeg
node_ffmpeg -->|"runs probe"| node_ffmpeg_service
node_main -->|"persists results"| node_repository
node_main -->|"writes playlists"| node_artifacts
node_service -->|"starts update"| node_main
node_service -->|"reads result data"| node_repository
node_service -->|"serves RTMP routes"| node_rtmp
node_rtmp -->|"streams media"| node_player
node_desktop -->|"opens playback tools"| node_playback
node_playback -->|"captures / probes"| node_ffmpeg
node_artifacts -->|"supplies playlists"| node_player
node_main -->|"reads settings"| node_config

click node_desktop "https://github.com/guovin/iptv-api/blob/master/desktop_ui/main_window.py"
click node_desktop_controller "https://github.com/guovin/iptv-api/blob/master/desktop_ui/controller.py"
click node_legacy_ui "https://github.com/guovin/iptv-api/blob/master/tkinter_ui/tkinter_ui.py"
click node_main "https://github.com/guovin/iptv-api/blob/master/main.py"
click node_service "https://github.com/guovin/iptv-api/blob/master/service/app.py"
click node_channel_ops "https://github.com/guovin/iptv-api/blob/master/utils/channel_operations.py"
click node_subscriptions "https://github.com/guovin/iptv-api/blob/master/updates/subscribe/request.py"
click node_epg "https://github.com/guovin/iptv-api/blob/master/updates/epg/request.py"
click node_channel_model "https://github.com/guovin/iptv-api/blob/master/utils/channel.py"
click node_aggregation "https://github.com/guovin/iptv-api/blob/master/utils/aggregator.py"
click node_speed "https://github.com/guovin/iptv-api/blob/master/utils/speed.py"
click node_ffmpeg "https://github.com/guovin/iptv-api/blob/master/utils/ffmpeg/probe.py"
click node_repository "https://github.com/guovin/iptv-api/blob/master/utils/channel_repository.py"
click node_artifacts "https://github.com/guovin/iptv-api/blob/master/utils/artifacts.py"
click node_rtmp "https://github.com/guovin/iptv-api/blob/master/service/rtmp.py"
click node_playback "https://github.com/guovin/iptv-api/blob/master/desktop_ui/playback.py"
click node_config "https://github.com/guovin/iptv-api/blob/master/utils/config.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_desktop,node_desktop_controller,node_legacy_ui,node_main,node_service,node_channel_ops toneBlue
class node_subscriptions,node_epg,node_channel_model,node_aggregation toneAmber
class node_speed,node_ffmpeg,node_repository toneMint
class node_artifacts,node_rtmp,node_playback toneRose
class node_config,node_user,node_external_sources,node_ffmpeg_service,node_player toneIndigo
```

## Components

### User entry points

- [Desktop UI](https://github.com/guovin/iptv-api/blob/master/desktop_ui/main_window.py): `desktop_ui/main_window.py`
- [Update controller](https://github.com/guovin/iptv-api/blob/master/desktop_ui/controller.py): `desktop_ui/controller.py`
- [Tk UI](https://github.com/guovin/iptv-api/blob/master/tkinter_ui/tkinter_ui.py): `tkinter_ui/tkinter_ui.py`
- [Update workflow](https://github.com/guovin/iptv-api/blob/master/main.py): `main.py`
- [HTTP service](https://github.com/guovin/iptv-api/blob/master/service/app.py): `service/app.py`
- [Channel operations](https://github.com/guovin/iptv-api/blob/master/utils/channel_operations.py): `utils/channel_operations.py`

### Collection and enrichment

- [Subscription fetch](https://github.com/guovin/iptv-api/blob/master/updates/subscribe/request.py): `updates/subscribe/request.py`
- [EPG processing](https://github.com/guovin/iptv-api/blob/master/updates/epg/request.py): `updates/epg/request.py`
- [Channel matching](https://github.com/guovin/iptv-api/blob/master/utils/channel.py): `utils/channel.py`
- [Source aggregation](https://github.com/guovin/iptv-api/blob/master/utils/aggregator.py): `utils/aggregator.py`

### Validation and persistence

- [Quality testing](https://github.com/guovin/iptv-api/blob/master/utils/speed.py): `utils/speed.py`
- [Media probing](https://github.com/guovin/iptv-api/blob/master/utils/ffmpeg/probe.py): `utils/ffmpeg/probe.py`
- [Result repository](https://github.com/guovin/iptv-api/blob/master/utils/channel_repository.py): `utils/channel_repository.py`

### Playback and delivery

- [Playlist artifacts](https://github.com/guovin/iptv-api/blob/master/utils/artifacts.py): `utils/artifacts.py`
- [RTMP streaming](https://github.com/guovin/iptv-api/blob/master/service/rtmp.py): `service/rtmp.py`
- [Playback tools](https://github.com/guovin/iptv-api/blob/master/desktop_ui/playback.py): `desktop_ui/playback.py`

### Operations and state

- [Configuration](https://github.com/guovin/iptv-api/blob/master/utils/config.py): `utils/config.py`

### Other components

- **Operator**
- **Source and EPG hosts**
- **FFmpeg tools**
- **IPTV player**

## Connections

- Operator → Desktop UI: configures / starts
- Operator → Tk UI: configures / starts
- Desktop UI → Update controller: queues updates
- Update controller → Channel operations: dispatches operations
- Tk UI → Configuration: changes settings
- Update workflow → Subscription fetch: fetches sources
- Subscription fetch → Source and EPG hosts: requests playlists
- Update workflow → EPG processing: fetches EPG
- EPG processing → Source and EPG hosts: requests listings
- Update workflow → Channel matching: matches channels
- Update workflow → Source aggregation: aggregates candidates
- Update workflow → Quality testing: tests candidates
- Quality testing → Media probing: probes streams
- Media probing → FFmpeg tools: runs probe
- Update workflow → Result repository: persists results
- Update workflow → Playlist artifacts: writes playlists
- HTTP service → Update workflow: starts update
- HTTP service → Result repository: reads result data
- HTTP service → RTMP streaming: serves RTMP routes
- RTMP streaming → IPTV player: streams media
- Desktop UI → Playback tools: opens playback tools
- Playback tools → Media probing: captures / probes
- Playlist artifacts → IPTV player: supplies playlists
- Update workflow → Configuration: reads settings