# iptv-org/iptv architecture

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

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

## Overview

IPTV is both a public collection of channel playlists and a TypeScript command-line toolkit for maintaining and presenting that collection. The user-facing result is a generated M3U playlist that viewers can open in a video player; the README also documents alternate playlists and links to a separate EPG utility. Internally, the scripts load channel metadata, model streams and playlists, and provide validation, generation, and README-table commands. Relationships below follow the sampled code, SOURCE INDEX references, and README; unsampled command internals are not assumed.

Main entry points: [`scripts/api.ts`](https://github.com/iptv-org/iptv/blob/master/scripts/api.ts) (Data API), [`scripts/models/stream.ts`](https://github.com/iptv-org/iptv/blob/master/scripts/models/stream.ts) (Stream model), [`scripts/commands/playlist`](https://github.com/iptv-org/iptv/tree/master/scripts/commands/playlist) (Playlist commands), [`scripts/commands/issue/validate.ts`](https://github.com/iptv-org/iptv/blob/master/scripts/commands/issue/validate.ts) (Issue validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Playlist workflow"]
  node_playlist["Public playlists"]
  node_cli["Maintenance commands"]
  node_playlist_commands["Playlist commands"]
  node_generators["Playlist generators"]
end

subgraph group_data["Channel data"]
  node_api["Data API<br/>[api.ts]"]
  node_data_files[("Channel data files<br/>[constants.ts]")]
  node_stream["Stream model<br/>[stream.ts]"]
end

subgraph group_tooling["Validation and reports"]
  node_stream_tester["Stream tester<br/>[streamTester.ts]"]
  node_proxy_parser["Proxy parser<br/>[proxyParser.ts]"]
  node_issue_commands["Issue validation<br/>[validate.ts]"]
  node_discussion_commands["Discussion validation<br/>[validate.ts]"]
  node_report["Report creation<br/>[create.ts]"]
end

subgraph group_presentation["Playlist presentation"]
  node_playlist_model["Playlist model<br/>[playlist.ts]"]
  node_parser["Playlist parser<br/>[playlistParser.ts]"]
  node_readme_update["README update<br/>[update.ts]"]
  node_tables["Markdown tables"]
  node_countries_table["Country table<br/>[countriesTable.ts]"]
end

node_viewer(("Video player user"))
node_epg_tools["EPG utilities"]
node_database_repo[("IPTV database")]

node_viewer -->|"opens"| node_playlist
node_api -->|"loads data"| node_data_files
node_stream -->|"reads metadata"| node_api
node_playlist_model -->|"formats streams"| node_stream
node_parser -->|"creates streams"| node_stream
node_stream_tester -->|"parses proxy"| node_proxy_parser
node_issue_commands -->|"loads data"| node_api
node_issue_commands -->|"uses core"| node_stream_tester
node_discussion_commands -->|"loads data"| node_api
node_report -->|"loads data"| node_api
node_playlist_commands -->|"loads data"| node_api
node_playlist_commands -->|"uses model"| node_stream
node_readme_update -->|"loads data"| node_api
node_readme_update -->|"uses tables"| node_tables
node_countries_table -->|"reads metadata"| node_api
node_countries_table -->|"lists playlist links"| node_playlist
node_database_repo -->|"provides channel data"| node_api
node_playlist -.->|"EPG download"| node_epg_tools

click node_cli "https://github.com/iptv-org/iptv/tree/master/scripts/commands"
click node_playlist_commands "https://github.com/iptv-org/iptv/tree/master/scripts/commands/playlist"
click node_api "https://github.com/iptv-org/iptv/blob/master/scripts/api.ts"
click node_data_files "https://github.com/iptv-org/iptv/blob/master/scripts/constants.ts"
click node_stream "https://github.com/iptv-org/iptv/blob/master/scripts/models/stream.ts"
click node_playlist_model "https://github.com/iptv-org/iptv/blob/master/scripts/models/playlist.ts"
click node_parser "https://github.com/iptv-org/iptv/blob/master/scripts/core/playlistParser.ts"
click node_generators "https://github.com/iptv-org/iptv/tree/master/scripts/generators"
click node_stream_tester "https://github.com/iptv-org/iptv/blob/master/scripts/core/streamTester.ts"
click node_proxy_parser "https://github.com/iptv-org/iptv/blob/master/scripts/core/proxyParser.ts"
click node_issue_commands "https://github.com/iptv-org/iptv/blob/master/scripts/commands/issue/validate.ts"
click node_discussion_commands "https://github.com/iptv-org/iptv/blob/master/scripts/commands/discussion/validate.ts"
click node_report "https://github.com/iptv-org/iptv/blob/master/scripts/commands/report/create.ts"
click node_readme_update "https://github.com/iptv-org/iptv/blob/master/scripts/commands/readme/update.ts"
click node_tables "https://github.com/iptv-org/iptv/tree/master/scripts/tables"
click node_countries_table "https://github.com/iptv-org/iptv/blob/master/scripts/tables/countriesTable.ts"

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_playlist,node_cli,node_playlist_commands,node_generators,node_viewer toneBlue
class node_api,node_data_files,node_stream,node_database_repo toneAmber
class node_stream_tester,node_proxy_parser,node_issue_commands,node_discussion_commands,node_report toneMint
class node_playlist_model,node_parser,node_readme_update,node_tables,node_countries_table toneRose
class node_epg_tools toneIndigo
```

## Components

### Playlist workflow

- **Public playlists**
- [Maintenance commands](https://github.com/iptv-org/iptv/tree/master/scripts/commands): `scripts/commands`
- [Playlist commands](https://github.com/iptv-org/iptv/tree/master/scripts/commands/playlist): `scripts/commands/playlist`
- [Playlist generators](https://github.com/iptv-org/iptv/tree/master/scripts/generators): `scripts/generators`

### Channel data

- [Data API](https://github.com/iptv-org/iptv/blob/master/scripts/api.ts): `scripts/api.ts`
- [Channel data files](https://github.com/iptv-org/iptv/blob/master/scripts/constants.ts): `scripts/constants.ts`
- [Stream model](https://github.com/iptv-org/iptv/blob/master/scripts/models/stream.ts): `scripts/models/stream.ts`

### Validation and reports

- [Stream tester](https://github.com/iptv-org/iptv/blob/master/scripts/core/streamTester.ts): `scripts/core/streamTester.ts`
- [Proxy parser](https://github.com/iptv-org/iptv/blob/master/scripts/core/proxyParser.ts): `scripts/core/proxyParser.ts`
- [Issue validation](https://github.com/iptv-org/iptv/blob/master/scripts/commands/issue/validate.ts): `scripts/commands/issue/validate.ts`
- [Discussion validation](https://github.com/iptv-org/iptv/blob/master/scripts/commands/discussion/validate.ts): `scripts/commands/discussion/validate.ts`
- [Report creation](https://github.com/iptv-org/iptv/blob/master/scripts/commands/report/create.ts): `scripts/commands/report/create.ts`

### Playlist presentation

- [Playlist model](https://github.com/iptv-org/iptv/blob/master/scripts/models/playlist.ts): `scripts/models/playlist.ts`
- [Playlist parser](https://github.com/iptv-org/iptv/blob/master/scripts/core/playlistParser.ts): `scripts/core/playlistParser.ts`
- [README update](https://github.com/iptv-org/iptv/blob/master/scripts/commands/readme/update.ts): `scripts/commands/readme/update.ts`
- [Markdown tables](https://github.com/iptv-org/iptv/tree/master/scripts/tables): `scripts/tables`
- [Country table](https://github.com/iptv-org/iptv/blob/master/scripts/tables/countriesTable.ts): `scripts/tables/countriesTable.ts`

### Other components

- **Video player user**
- **EPG utilities**
- **IPTV database**

## Connections

- Video player user → Public playlists: opens
- Data API → Channel data files: loads data (evidence: `scripts/api.ts`)
- Stream model → Data API: reads metadata (evidence: `scripts/models/stream.ts`)
- Playlist model → Stream model: formats streams (evidence: `scripts/models/playlist.ts`)
- Playlist parser → Stream model: creates streams (evidence: `scripts/core/playlistParser.ts`)
- Stream tester → Proxy parser: parses proxy (evidence: `scripts/core/streamTester.ts`)
- Issue validation → Data API: loads data (evidence: `scripts/commands/issue/validate.ts`)
- Issue validation → Stream tester: uses core (evidence: `scripts/commands/issue/validate.ts`)
- Discussion validation → Data API: loads data (evidence: `scripts/commands/discussion/validate.ts`)
- Report creation → Data API: loads data (evidence: `scripts/commands/report/create.ts`)
- Playlist commands → Data API: loads data (evidence: `scripts/commands/playlist/update.ts`)
- Playlist commands → Stream model: uses model (evidence: `scripts/commands/playlist/update.ts`)
- README update → Data API: loads data (evidence: `scripts/commands/readme/update.ts`)
- README update → Markdown tables: uses tables (evidence: `scripts/commands/readme/update.ts`)
- Country table → Data API: reads metadata (evidence: `scripts/tables/countriesTable.ts`)
- Country table → Public playlists: lists playlist links (evidence: `scripts/tables/countriesTable.ts`)
- IPTV database → Data API: provides channel data
- Public playlists → EPG utilities: EPG download
