# free-tv/iptv architecture

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

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

## Overview

Free TV is a worldwide catalog of free-to-watch television streams, distributed as M3U playlists. The main user workflow is to select a country playlist and open it in a compatible player. Markdown channel lists are also checked for availability: the checker probes streams, classifies results, and records run history; a dashboard generator turns that history into a status page. The map reflects documented behavior and sampled source; checker internals and some runtime wiring were not fully excerpted.

Main entry points: [`make_playlist.py`](https://github.com/free-tv/iptv/blob/master/make_playlist.py) (M3U Generator), [`check_channels.py`](https://github.com/free-tv/iptv/blob/master/check_channels.py) (Channel Checker), [`playlist.m3u8`](https://github.com/free-tv/iptv/blob/master/playlist.m3u8) (Combined Playlist), [`playlists`](https://github.com/free-tv/iptv/tree/master/playlists) (Country Playlists)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Channel Catalog"]
  node_lists["Channel Lists"]
  node_epg["EPG Sources<br/>[epglist.txt]"]
end

subgraph group_playlists["Playlist Delivery"]
  node_builder["M3U Generator<br/>[make_playlist.py]"]
  node_combined["Combined Playlist<br/>[playlist.m3u8]"]
  node_country["Country Playlists"]
end

subgraph group_monitoring["Stream Monitoring"]
  node_checker["Channel Checker<br/>[check_channels.py]"]
  node_history[("Check History<br/>[history.jsonl]")]
end

subgraph group_status["Status Reporting"]
  node_dashboard["Dashboard Generator"]
  node_statuspage["Status Dashboard"]
end

node_viewer(("Playlist User"))
node_player["M3U Player"]
node_streams{{"Stream Hosts"}}
node_ffprobe["ffprobe"]

node_viewer -->|"selects"| node_country
node_viewer -->|"selects"| node_combined
node_builder -->|"reads"| node_lists
node_builder -->|"reads"| node_epg
node_builder -->|"writes"| node_combined
node_builder -->|"writes"| node_country
node_country -.->|"opens in"| node_player
node_combined -.->|"opens in"| node_player
node_checker -->|"reads"| node_lists
node_checker -->|"probes"| node_streams
node_checker -->|"confirms dead"| node_ffprobe
node_checker -->|"appends results"| node_history
node_dashboard -->|"reads"| node_history
node_dashboard -->|"generates"| node_statuspage

click node_lists "https://github.com/free-tv/iptv/tree/master/lists"
click node_epg "https://github.com/free-tv/iptv/blob/master/epglist.txt"
click node_builder "https://github.com/free-tv/iptv/blob/master/make_playlist.py"
click node_combined "https://github.com/free-tv/iptv/blob/master/playlist.m3u8"
click node_country "https://github.com/free-tv/iptv/tree/master/playlists"
click node_checker "https://github.com/free-tv/iptv/blob/master/check_channels.py"
click node_history "https://github.com/free-tv/iptv/blob/master/.github/checker-history/history.jsonl"
click node_dashboard "https://github.com/free-tv/iptv/blob/master/generate_dashboard.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_lists,node_epg,node_viewer toneBlue
class node_builder,node_combined,node_country toneAmber
class node_checker,node_history toneMint
class node_dashboard,node_statuspage toneRose
class node_player,node_streams,node_ffprobe toneIndigo
```

## Components

### Channel Catalog

- [Channel Lists](https://github.com/free-tv/iptv/tree/master/lists): `lists`
- [EPG Sources](https://github.com/free-tv/iptv/blob/master/epglist.txt): `epglist.txt`

### Playlist Delivery

- [M3U Generator](https://github.com/free-tv/iptv/blob/master/make_playlist.py): `make_playlist.py`
- [Combined Playlist](https://github.com/free-tv/iptv/blob/master/playlist.m3u8): `playlist.m3u8`
- [Country Playlists](https://github.com/free-tv/iptv/tree/master/playlists): `playlists`

### Stream Monitoring

- [Channel Checker](https://github.com/free-tv/iptv/blob/master/check_channels.py): `check_channels.py`
- [Check History](https://github.com/free-tv/iptv/blob/master/.github/checker-history/history.jsonl): `.github/checker-history/history.jsonl`

### Status Reporting

- [Dashboard Generator](https://github.com/free-tv/iptv/blob/master/generate_dashboard.py): `generate_dashboard.py`
- **Status Dashboard**

### Other components

- **Playlist User**
- **M3U Player**
- **Stream Hosts**
- **ffprobe**

## Connections

- Playlist User → Country Playlists: selects (evidence: `README.md`)
- Playlist User → Combined Playlist: selects (evidence: `README.md`)
- M3U Generator → Channel Lists: reads (evidence: `make_playlist.py`)
- M3U Generator → EPG Sources: reads (evidence: `make_playlist.py`)
- M3U Generator → Combined Playlist: writes (evidence: `make_playlist.py`)
- M3U Generator → Country Playlists: writes (evidence: `make_playlist.py`)
- Country Playlists → M3U Player: opens in
- Combined Playlist → M3U Player: opens in
- Channel Checker → Channel Lists: reads (evidence: `check_channels.py`)
- Channel Checker → Stream Hosts: probes (evidence: `check_channels.py`)
- Channel Checker → ffprobe: confirms dead (evidence: `check_channels.py`)
- Channel Checker → Check History: appends results (evidence: `check_channels.py`)
- Dashboard Generator → Check History: reads (evidence: `generate_dashboard.py`)
- Dashboard Generator → Status Dashboard: generates (evidence: `generate_dashboard.py`)
