# guovin/tv architecture

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

## Overview

IPTV-API collects local and subscribed channel sources, normalizes and aggregates candidates, checks stream availability and quality, then generates categorized playlists and serves results. Users can initiate updates through the desktop or legacy Tk interface, or run the service/API workflow. The README also documents EPG, RTMP streaming, playback screenshots, and result management. Sampled source confirms parts of the desktop task dispatch, source fetching, EPG fetching, persistence, and service behavior; some capability links reflect README documentation rather than inspected implementation.

Main entry points: [`main.py`](https://github.com/guovin/tv/blob/master/main.py) (Update workflow), [`desktop_ui/app.py`](https://github.com/guovin/tv/blob/master/desktop_ui/app.py) (Desktop app), [`desktop_ui/main_window.py`](https://github.com/guovin/tv/blob/master/desktop_ui/main_window.py) (Main window), [`utils/channel_quality.py`](https://github.com/guovin/tv/blob/master/utils/channel_quality.py) (Stream validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_desktop["Desktop app<br/>[app.py]"]
  node_window["Main window<br/>[main_window.py]"]
  node_controller["Update controller<br/>[controller.py]"]
  node_legacy_ui["Tk interface<br/>[tkinter_ui.py]"]
end

subgraph group_pipeline["Update pipeline"]
  node_entry["Update workflow<br/>[main.py]"]
  node_operations["Channel operations"]
  node_subscriptions["Subscription fetch<br/>[request.py]"]
  node_aggregation["Source aggregation<br/>[aggregator.py]"]
  node_aliases["Channel matching<br/>[alias.py]"]
  node_quality["Stream validation<br/>[channel_quality.py]"]
  node_ffprobe["Media probing<br/>[probe.py]"]
end

subgraph group_results["Results and storage"]
  node_repository[("Result repository")]
  node_artifacts["Playlist artifacts<br/>[artifacts.py]"]
end

subgraph group_features["Streaming features"]
  node_epg["EPG fetch<br/>[request.py]"]
  node_rtmp["RTMP streaming<br/>[rtmp.py]"]
  node_playback["Playback tools<br/>[playback.py]"]
end

subgraph group_runtime["Runtime and service"]
  node_service["HTTP service<br/>[app.py]"]
  node_config["Configuration<br/>[config.py]"]
end

node_user(("User"))
node_external{{"Source endpoints"}}

node_user -->|"starts app"| node_desktop
node_desktop -->|"opens UI"| node_window
node_user -->|"configures"| node_legacy_ui
node_window -->|"dispatches tasks"| node_controller
node_controller -->|"invokes operation"| node_operations
node_legacy_ui -->|"updates settings"| node_config
node_operations -->|"runs update"| node_entry
node_entry -->|"fetches sources"| node_subscriptions
node_subscriptions -->|"requests streams"| node_external
node_entry -->|"fetches guide"| node_epg
node_epg -->|"requests listings"| node_external
node_entry -->|"aggregates candidates"| node_aggregation
node_entry -->|"matches channels"| node_aliases
node_entry -->|"tests candidates"| node_quality
node_quality -->|"probes media"| node_ffprobe
node_entry -->|"persists results"| node_repository
node_repository -->|"provides result data"| node_artifacts
node_entry -->|"generates playlists"| node_artifacts
node_desktop -->|"launches service"| node_service
node_service -->|"serves results"| node_repository
node_service -->|"routes streaming"| node_rtmp
node_window -->|"previews streams"| node_playback
node_quality -->|"checks availability"| node_external
node_entry -->|"reads settings"| node_config

click node_desktop "https://github.com/guovin/tv/blob/master/desktop_ui/app.py"
click node_window "https://github.com/guovin/tv/blob/master/desktop_ui/main_window.py"
click node_controller "https://github.com/guovin/tv/blob/master/desktop_ui/controller.py"
click node_legacy_ui "https://github.com/guovin/tv/blob/master/tkinter_ui/tkinter_ui.py"
click node_entry "https://github.com/guovin/tv/blob/master/main.py"
click node_operations "https://github.com/guovin/tv/blob/master/utils/channel_operations.py"
click node_subscriptions "https://github.com/guovin/tv/blob/master/updates/subscribe/request.py"
click node_epg "https://github.com/guovin/tv/blob/master/updates/epg/request.py"
click node_aggregation "https://github.com/guovin/tv/blob/master/utils/aggregator.py"
click node_aliases "https://github.com/guovin/tv/blob/master/utils/alias.py"
click node_quality "https://github.com/guovin/tv/blob/master/utils/channel_quality.py"
click node_ffprobe "https://github.com/guovin/tv/blob/master/utils/ffmpeg/probe.py"
click node_repository "https://github.com/guovin/tv/blob/master/utils/channel_repository.py"
click node_artifacts "https://github.com/guovin/tv/blob/master/utils/artifacts.py"
click node_service "https://github.com/guovin/tv/blob/master/service/app.py"
click node_rtmp "https://github.com/guovin/tv/blob/master/service/rtmp.py"
click node_playback "https://github.com/guovin/tv/blob/master/desktop_ui/playback.py"
click node_config "https://github.com/guovin/tv/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_window,node_controller,node_legacy_ui,node_user toneBlue
class node_entry,node_operations,node_subscriptions,node_aggregation,node_aliases,node_quality,node_ffprobe toneAmber
class node_repository,node_artifacts toneMint
class node_epg,node_rtmp,node_playback toneRose
class node_service,node_config,node_external toneIndigo
```

## Components

### User interfaces

- [Desktop app](https://github.com/guovin/tv/blob/master/desktop_ui/app.py): `desktop_ui/app.py`
- [Main window](https://github.com/guovin/tv/blob/master/desktop_ui/main_window.py): `desktop_ui/main_window.py`
- [Update controller](https://github.com/guovin/tv/blob/master/desktop_ui/controller.py): `desktop_ui/controller.py`
- [Tk interface](https://github.com/guovin/tv/blob/master/tkinter_ui/tkinter_ui.py): `tkinter_ui/tkinter_ui.py`

### Update pipeline

- [Update workflow](https://github.com/guovin/tv/blob/master/main.py): `main.py`
- [Channel operations](https://github.com/guovin/tv/blob/master/utils/channel_operations.py): `utils/channel_operations.py`
- [Subscription fetch](https://github.com/guovin/tv/blob/master/updates/subscribe/request.py): `updates/subscribe/request.py`
- [Source aggregation](https://github.com/guovin/tv/blob/master/utils/aggregator.py): `utils/aggregator.py`
- [Channel matching](https://github.com/guovin/tv/blob/master/utils/alias.py): `utils/alias.py`
- [Stream validation](https://github.com/guovin/tv/blob/master/utils/channel_quality.py): `utils/channel_quality.py`
- [Media probing](https://github.com/guovin/tv/blob/master/utils/ffmpeg/probe.py): `utils/ffmpeg/probe.py`

### Results and storage

- [Result repository](https://github.com/guovin/tv/blob/master/utils/channel_repository.py): `utils/channel_repository.py`
- [Playlist artifacts](https://github.com/guovin/tv/blob/master/utils/artifacts.py): `utils/artifacts.py`

### Streaming features

- [EPG fetch](https://github.com/guovin/tv/blob/master/updates/epg/request.py): `updates/epg/request.py`
- [RTMP streaming](https://github.com/guovin/tv/blob/master/service/rtmp.py): `service/rtmp.py`
- [Playback tools](https://github.com/guovin/tv/blob/master/desktop_ui/playback.py): `desktop_ui/playback.py`

### Runtime and service

- [HTTP service](https://github.com/guovin/tv/blob/master/service/app.py): `service/app.py`
- [Configuration](https://github.com/guovin/tv/blob/master/utils/config.py): `utils/config.py`

### Other components

- **User**
- **Source endpoints**

## Connections

- User → Desktop app: starts app
- Desktop app → Main window: opens UI
- User → Tk interface: configures
- Main window → Update controller: dispatches tasks
- Update controller → Channel operations: invokes operation
- Tk interface → Configuration: updates settings
- Channel operations → Update workflow: runs update
- Update workflow → Subscription fetch: fetches sources
- Subscription fetch → Source endpoints: requests streams
- Update workflow → EPG fetch: fetches guide
- EPG fetch → Source endpoints: requests listings
- Update workflow → Source aggregation: aggregates candidates
- Update workflow → Channel matching: matches channels
- Update workflow → Stream validation: tests candidates
- Stream validation → Media probing: probes media
- Update workflow → Result repository: persists results
- Result repository → Playlist artifacts: provides result data
- Update workflow → Playlist artifacts: generates playlists
- Desktop app → HTTP service: launches service
- HTTP service → Result repository: serves results
- HTTP service → RTMP streaming: routes streaming
- Main window → Playback tools: previews streams
- Stream validation → Source endpoints: checks availability
- Update workflow → Configuration: reads settings