# maxnasiri/iptv architecture

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

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

## Overview

IPTV is a repository of public channel-stream links, with scripts for editing, validating, and exporting playlists and generating categorized playlist outputs and README tables. The central data layer loads and indexes IPTV metadata; stream models use those lookups to enrich and serialize stream records. The README also points users to external database and EPG projects. The available excerpts show data loading and parsing, but not CLI dispatch or the full generator invocation path, so those connections are omitted.

Main entry points: [`scripts/commands/readme/update.ts`](https://github.com/maxnasiri/iptv/blob/master/scripts/commands/readme/update.ts) (README updater), [`scripts/api.ts`](https://github.com/maxnasiri/iptv/blob/master/scripts/api.ts) (Metadata loader and index), [`scripts/commands/playlist/edit.ts`](https://github.com/maxnasiri/iptv/blob/master/scripts/commands/playlist/edit.ts) (Playlist commands), [`scripts/core/playlistParser.ts`](https://github.com/maxnasiri/iptv/blob/master/scripts/core/playlistParser.ts) (Playlist parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_playlist["Playlist workflow"]
  node_playlist_cmds["Playlist commands<br/>[edit.ts]"]
  node_playlist_parser["Playlist parser<br/>[playlistParser.ts]"]
end

subgraph group_metadata["Metadata and models"]
  node_stream_model["Stream model<br/>[stream.ts]"]
  node_metadata_api["Metadata loader and index<br/>[api.ts]"]
end

subgraph group_generation["Playlist generation"]
  node_generator_base["Generator interface<br/>[generator.ts]"]
  node_categories_gen["Category playlists"]
  node_countries_gen["Country playlists"]
  node_languages_gen["Language playlists"]
  node_subdivisions_gen["Subdivision playlists"]
  node_cities_gen["City playlists<br/>[citiesGenerator.ts]"]
  node_regions_gen["Region playlists"]
  node_sources_gen["Source playlists"]
  node_raw_gen["Raw playlists<br/>[rawGenerator.ts]"]
  node_index_gens["Index playlists<br/>[indexGenerator.ts]"]
  node_index_category["Category index"]
  node_index_country["Country index"]
  node_index_language["Language index"]
end

subgraph group_reporting["Tables and reports"]
  node_readme_cmd["README updater<br/>[update.ts]"]
  node_country_table["Country table<br/>[countriesTable.ts]"]
  node_language_table["Language table<br/>[languagesTable.ts]"]
  node_other_tables["Category and region tables"]
end

subgraph group_integrations["External services"]
  node_data_manager["IPTV SDK data manager"]
  node_database[("iptv-org database")]
  node_epg["EPG utilities"]
end

node_users(("Playlist users"))

node_users -->|"use playlists"| node_playlist_cmds
node_playlist_cmds -->|"parses playlists"| node_playlist_parser
node_playlist_parser -->|"creates streams"| node_stream_model
node_metadata_api -->|"loads and processes"| node_data_manager
node_stream_model -->|"reads lookups"| node_metadata_api
node_users -.->|"download guides"| node_epg
node_metadata_api -.->|"uses channel data"| node_database
node_readme_cmd -->|"uses tables"| node_country_table
node_readme_cmd -.->|"uses tables"| node_language_table
node_readme_cmd -.->|"uses tables"| node_other_tables

click node_playlist_cmds "https://github.com/maxnasiri/iptv/blob/master/scripts/commands/playlist/edit.ts"
click node_playlist_parser "https://github.com/maxnasiri/iptv/blob/master/scripts/core/playlistParser.ts"
click node_stream_model "https://github.com/maxnasiri/iptv/blob/master/scripts/models/stream.ts"
click node_metadata_api "https://github.com/maxnasiri/iptv/blob/master/scripts/api.ts"
click node_generator_base "https://github.com/maxnasiri/iptv/blob/master/scripts/generators/generator.ts"
click node_categories_gen "https://github.com/maxnasiri/iptv/blob/master/scripts/generators/categoriesGenerator.ts"
click node_countries_gen "https://github.com/maxnasiri/iptv/blob/master/scripts/generators/countriesGenerator.ts"
click node_languages_gen "https://github.com/maxnasiri/iptv/blob/master/scripts/generators/languagesGenerator.ts"
click node_subdivisions_gen "https://github.com/maxnasiri/iptv/blob/master/scripts/generators/subdivisionsGenerator.ts"
click node_cities_gen "https://github.com/maxnasiri/iptv/blob/master/scripts/generators/citiesGenerator.ts"
click node_regions_gen "https://github.com/maxnasiri/iptv/blob/master/scripts/generators/regionsGenerator.ts"
click node_sources_gen "https://github.com/maxnasiri/iptv/blob/master/scripts/generators/sourcesGenerator.ts"
click node_raw_gen "https://github.com/maxnasiri/iptv/blob/master/scripts/generators/rawGenerator.ts"
click node_index_gens "https://github.com/maxnasiri/iptv/blob/master/scripts/generators/indexGenerator.ts"
click node_index_category "https://github.com/maxnasiri/iptv/blob/master/scripts/generators/indexCategoryGenerator.ts"
click node_index_country "https://github.com/maxnasiri/iptv/blob/master/scripts/generators/indexCountryGenerator.ts"
click node_index_language "https://github.com/maxnasiri/iptv/blob/master/scripts/generators/indexLanguageGenerator.ts"
click node_readme_cmd "https://github.com/maxnasiri/iptv/blob/master/scripts/commands/readme/update.ts"
click node_country_table "https://github.com/maxnasiri/iptv/blob/master/scripts/tables/countriesTable.ts"
click node_language_table "https://github.com/maxnasiri/iptv/blob/master/scripts/tables/languagesTable.ts"
click node_other_tables "https://github.com/maxnasiri/iptv/tree/master/scripts/tables"

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_cmds,node_playlist_parser,node_users toneBlue
class node_stream_model,node_metadata_api toneAmber
class node_generator_base,node_categories_gen,node_countries_gen,node_languages_gen,node_subdivisions_gen,node_cities_gen,node_regions_gen,node_sources_gen,node_raw_gen,node_index_gens,node_index_category,node_index_country,node_index_language toneMint
class node_readme_cmd,node_country_table,node_language_table,node_other_tables toneRose
class node_data_manager,node_database,node_epg toneIndigo
```

## Components

### Playlist workflow

- [Playlist commands](https://github.com/maxnasiri/iptv/blob/master/scripts/commands/playlist/edit.ts): `scripts/commands/playlist/edit.ts`
- [Playlist parser](https://github.com/maxnasiri/iptv/blob/master/scripts/core/playlistParser.ts): `scripts/core/playlistParser.ts`

### Metadata and models

- [Stream model](https://github.com/maxnasiri/iptv/blob/master/scripts/models/stream.ts): `scripts/models/stream.ts`
- [Metadata loader and index](https://github.com/maxnasiri/iptv/blob/master/scripts/api.ts): `scripts/api.ts`

### Playlist generation

- [Generator interface](https://github.com/maxnasiri/iptv/blob/master/scripts/generators/generator.ts): `scripts/generators/generator.ts`
- [Category playlists](https://github.com/maxnasiri/iptv/blob/master/scripts/generators/categoriesGenerator.ts): `scripts/generators/categoriesGenerator.ts`
- [Country playlists](https://github.com/maxnasiri/iptv/blob/master/scripts/generators/countriesGenerator.ts): `scripts/generators/countriesGenerator.ts`
- [Language playlists](https://github.com/maxnasiri/iptv/blob/master/scripts/generators/languagesGenerator.ts): `scripts/generators/languagesGenerator.ts`
- [Subdivision playlists](https://github.com/maxnasiri/iptv/blob/master/scripts/generators/subdivisionsGenerator.ts): `scripts/generators/subdivisionsGenerator.ts`
- [City playlists](https://github.com/maxnasiri/iptv/blob/master/scripts/generators/citiesGenerator.ts): `scripts/generators/citiesGenerator.ts`
- [Region playlists](https://github.com/maxnasiri/iptv/blob/master/scripts/generators/regionsGenerator.ts): `scripts/generators/regionsGenerator.ts`
- [Source playlists](https://github.com/maxnasiri/iptv/blob/master/scripts/generators/sourcesGenerator.ts): `scripts/generators/sourcesGenerator.ts`
- [Raw playlists](https://github.com/maxnasiri/iptv/blob/master/scripts/generators/rawGenerator.ts): `scripts/generators/rawGenerator.ts`
- [Index playlists](https://github.com/maxnasiri/iptv/blob/master/scripts/generators/indexGenerator.ts): `scripts/generators/indexGenerator.ts`
- [Category index](https://github.com/maxnasiri/iptv/blob/master/scripts/generators/indexCategoryGenerator.ts): `scripts/generators/indexCategoryGenerator.ts`
- [Country index](https://github.com/maxnasiri/iptv/blob/master/scripts/generators/indexCountryGenerator.ts): `scripts/generators/indexCountryGenerator.ts`
- [Language index](https://github.com/maxnasiri/iptv/blob/master/scripts/generators/indexLanguageGenerator.ts): `scripts/generators/indexLanguageGenerator.ts`

### Tables and reports

- [README updater](https://github.com/maxnasiri/iptv/blob/master/scripts/commands/readme/update.ts): `scripts/commands/readme/update.ts`
- [Country table](https://github.com/maxnasiri/iptv/blob/master/scripts/tables/countriesTable.ts): `scripts/tables/countriesTable.ts`
- [Language table](https://github.com/maxnasiri/iptv/blob/master/scripts/tables/languagesTable.ts): `scripts/tables/languagesTable.ts`
- [Category and region tables](https://github.com/maxnasiri/iptv/tree/master/scripts/tables): `scripts/tables`

### External services

- **IPTV SDK data manager**
- **iptv-org database**
- **EPG utilities**

### Other components

- **Playlist users**

## Connections

- Playlist users → Playlist commands: use playlists (evidence: `README.md`)
- Playlist commands → Playlist parser: parses playlists (evidence: `scripts/commands/playlist/edit.ts`)
- Playlist parser → Stream model: creates streams (evidence: `scripts/core/playlistParser.ts`)
- Metadata loader and index → IPTV SDK data manager: loads and processes (evidence: `scripts/api.ts`)
- Stream model → Metadata loader and index: reads lookups (evidence: `scripts/models/stream.ts`)
- Playlist users → EPG utilities: download guides (evidence: `README.md`)
- Metadata loader and index → iptv-org database: uses channel data (evidence: `README.md`)
- README updater → Country table: uses tables (evidence: `scripts/commands/readme/update.ts`)
- README updater → Language table: uses tables (evidence: `scripts/commands/readme/update.ts`)
- README updater → Category and region tables: uses tables (evidence: `scripts/commands/readme/update.ts`)