# blackwacth/iptv-api architecture

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

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

## Overview

IPTV-API gathers live-stream candidates from configurable local and network sources, normalizes them by channel, measures and filters stream quality, then writes playlist/API results and optionally serves them. The README documents RTMP/HLS, EPG, aliases, custom templates, and scheduling; sampled excerpts confirm orchestration, source-request behavior, channel processing, speed testing, and HTTP/RTMP service behavior. Several source-to-orchestrator links and unsampled capabilities are represented at the module level because the excerpts do not show all wiring.

Main entry points: [`main.py`](https://github.com/blackwacth/iptv-api/blob/master/main.py) (Update scheduler), [`service/app.py`](https://github.com/blackwacth/iptv-api/blob/master/service/app.py) (Result and playback service), [`tkinter_ui/tkinter_ui.py`](https://github.com/blackwacth/iptv-api/blob/master/tkinter_ui/tkinter_ui.py) (Desktop controls), [`updates/hotel/request.py`](https://github.com/blackwacth/iptv-api/blob/master/updates/hotel/request.py) (Hotel discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_entry["Entry and settings"]
  node_main["Update scheduler<br/>[main.py]"]
  node_ui["Desktop controls<br/>[tkinter_ui.py]"]
  node_config["Runtime settings<br/>[config.py]"]
end

subgraph group_g_sources["Stream discovery"]
  node_local["Local sources<br/>[local.py]"]
  node_subscribe["Subscription fetch<br/>[request.py]"]
  node_hotel["Hotel discovery<br/>[request.py]"]
  node_multicast["Multicast discovery<br/>[request.py]"]
  node_fofa["FOFA discovery<br/>[request.py]"]
  node_online["Keyword search<br/>[request.py]"]
end

subgraph group_g_process["Channel processing"]
  node_channel["Channel normalization<br/>[channel.py]"]
  node_alias["Channel aliases<br/>[alias.py]"]
  node_speed["Stream validation<br/>[speed.py]"]
  node_epg["Program guide<br/>[request.py]"]
  node_db[("Result metadata<br/>[db.py]")]
end

subgraph group_g_delivery["Results and playback"]
  node_playlist["Playlist generation<br/>[channel.py]"]
  node_http["Result and playback service<br/>[app.py]"]
  node_rtmp["RTMP HLS relay<br/>[app.py]"]
end

node_user(("Operator"))
node_viewer(("IPTV viewer"))

node_user -->|"configures"| node_ui
node_user -->|"starts update"| node_main
node_ui -->|"updates settings"| node_config
node_main -->|"reads settings"| node_config
node_main -->|"loads sources"| node_local
node_main -->|"dispatches fetch"| node_subscribe
node_main -->|"dispatches search"| node_hotel
node_main -->|"dispatches search"| node_multicast
node_main -->|"dispatches search"| node_online
node_hotel -.->|"queries FOFA"| node_fofa
node_multicast -.->|"queries FOFA"| node_fofa
node_main -->|"combines channels"| node_channel
node_main -->|"applies aliases"| node_alias
node_main -->|"tests streams"| node_speed
node_main -.->|"fetches guide"| node_epg
node_main -->|"stores metadata"| node_db
node_main -->|"writes results"| node_playlist
node_viewer -->|"requests playlist"| node_http
node_http -->|"reads result files"| node_playlist
node_http -->|"reads stream data"| node_db
node_http -->|"starts relay"| node_rtmp
node_rtmp -->|"serves stream"| node_viewer

click node_main "https://github.com/blackwacth/iptv-api/blob/master/main.py"
click node_ui "https://github.com/blackwacth/iptv-api/blob/master/tkinter_ui/tkinter_ui.py"
click node_config "https://github.com/blackwacth/iptv-api/blob/master/utils/config.py"
click node_local "https://github.com/blackwacth/iptv-api/blob/master/tkinter_ui/local.py"
click node_subscribe "https://github.com/blackwacth/iptv-api/blob/master/updates/subscribe/request.py"
click node_hotel "https://github.com/blackwacth/iptv-api/blob/master/updates/hotel/request.py"
click node_multicast "https://github.com/blackwacth/iptv-api/blob/master/updates/multicast/request.py"
click node_fofa "https://github.com/blackwacth/iptv-api/blob/master/updates/fofa/request.py"
click node_online "https://github.com/blackwacth/iptv-api/blob/master/updates/online_search/request.py"
click node_channel "https://github.com/blackwacth/iptv-api/blob/master/utils/channel.py"
click node_alias "https://github.com/blackwacth/iptv-api/blob/master/utils/alias.py"
click node_speed "https://github.com/blackwacth/iptv-api/blob/master/utils/speed.py"
click node_epg "https://github.com/blackwacth/iptv-api/blob/master/updates/epg/request.py"
click node_db "https://github.com/blackwacth/iptv-api/blob/master/utils/db.py"
click node_playlist "https://github.com/blackwacth/iptv-api/blob/master/utils/channel.py"
click node_http "https://github.com/blackwacth/iptv-api/blob/master/service/app.py"
click node_rtmp "https://github.com/blackwacth/iptv-api/blob/master/service/app.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_main,node_ui,node_config,node_viewer toneBlue
class node_local,node_subscribe,node_hotel,node_multicast,node_fofa,node_online toneAmber
class node_channel,node_alias,node_speed,node_epg,node_db toneMint
class node_playlist,node_http,node_rtmp toneRose
class node_user toneIndigo
```

## Components

### Entry and settings

- [Update scheduler](https://github.com/blackwacth/iptv-api/blob/master/main.py): `main.py`
- [Desktop controls](https://github.com/blackwacth/iptv-api/blob/master/tkinter_ui/tkinter_ui.py): `tkinter_ui/tkinter_ui.py`
- [Runtime settings](https://github.com/blackwacth/iptv-api/blob/master/utils/config.py): `utils/config.py`

### Stream discovery

- [Local sources](https://github.com/blackwacth/iptv-api/blob/master/tkinter_ui/local.py): `tkinter_ui/local.py`
- [Subscription fetch](https://github.com/blackwacth/iptv-api/blob/master/updates/subscribe/request.py): `updates/subscribe/request.py`
- [Hotel discovery](https://github.com/blackwacth/iptv-api/blob/master/updates/hotel/request.py): `updates/hotel/request.py`
- [Multicast discovery](https://github.com/blackwacth/iptv-api/blob/master/updates/multicast/request.py): `updates/multicast/request.py`
- [FOFA discovery](https://github.com/blackwacth/iptv-api/blob/master/updates/fofa/request.py): `updates/fofa/request.py`
- [Keyword search](https://github.com/blackwacth/iptv-api/blob/master/updates/online_search/request.py): `updates/online_search/request.py`

### Channel processing

- [Channel normalization](https://github.com/blackwacth/iptv-api/blob/master/utils/channel.py): `utils/channel.py`
- [Channel aliases](https://github.com/blackwacth/iptv-api/blob/master/utils/alias.py): `utils/alias.py`
- [Stream validation](https://github.com/blackwacth/iptv-api/blob/master/utils/speed.py): `utils/speed.py`
- [Program guide](https://github.com/blackwacth/iptv-api/blob/master/updates/epg/request.py): `updates/epg/request.py`
- [Result metadata](https://github.com/blackwacth/iptv-api/blob/master/utils/db.py): `utils/db.py`

### Results and playback

- [Playlist generation](https://github.com/blackwacth/iptv-api/blob/master/utils/channel.py): `utils/channel.py`
- [Result and playback service](https://github.com/blackwacth/iptv-api/blob/master/service/app.py): `service/app.py`
- [RTMP HLS relay](https://github.com/blackwacth/iptv-api/blob/master/service/app.py): `service/app.py`

### Other components

- **Operator**
- **IPTV viewer**

## Connections

- Operator → Desktop controls: configures
- Operator → Update scheduler: starts update
- Desktop controls → Runtime settings: updates settings
- Update scheduler → Runtime settings: reads settings
- Update scheduler → Local sources: loads sources
- Update scheduler → Subscription fetch: dispatches fetch
- Update scheduler → Hotel discovery: dispatches search
- Update scheduler → Multicast discovery: dispatches search
- Update scheduler → Keyword search: dispatches search
- Hotel discovery → FOFA discovery: queries FOFA
- Multicast discovery → FOFA discovery: queries FOFA
- Update scheduler → Channel normalization: combines channels
- Update scheduler → Channel aliases: applies aliases
- Update scheduler → Stream validation: tests streams
- Update scheduler → Program guide: fetches guide
- Update scheduler → Result metadata: stores metadata
- Update scheduler → Playlist generation: writes results
- IPTV viewer → Result and playback service: requests playlist
- Result and playback service → Playlist generation: reads result files
- Result and playback service → Result metadata: reads stream data
- Result and playback service → RTMP HLS relay: starts relay
- RTMP HLS relay → IPTV viewer: serves stream