# hirotomasato/msplayiptv architecture

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

## Overview

MSPlay IPTV collects channel records from remote M3U sources, categorizes and deduplicates them, checks stream availability, then publishes a main playlist, category playlists, and statistics. IPTV players consume the published M3U files. The sampled source confirms the manual runtime flow and file generation; README documents automated GitHub Actions updates, but the workflow source was not sampled, so its wiring is not drawn.

Main entry points: [`main.py`](https://github.com/hirotomasato/msplayiptv/blob/main/main.py) (Pipeline entry), [`src/scraper.py`](https://github.com/hirotomasato/msplayiptv/blob/main/src/scraper.py) (Source scraper), [`src/generator.py`](https://github.com/hirotomasato/msplayiptv/blob/main/src/generator.py) (Playlist generator), [`src/validator.py`](https://github.com/hirotomasato/msplayiptv/blob/main/src/validator.py) (Channel validator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Channel ingestion"]
  node_main["Pipeline entry<br/>[main.py]"]
  node_config["Runtime config<br/>[config.py]"]
  node_scraper["Source scraper<br/>[scraper.py]"]
  node_parser["M3U parser<br/>[utils.py]"]
  node_models["Channel models<br/>[models.py]"]
end

subgraph group_quality["Validation"]
  node_validator["Channel validator<br/>[validator.py]"]
  node_streamcheck["Stream checks<br/>[utils.py]"]
end

subgraph group_publish["Playlist publishing"]
  node_generator["Playlist generator<br/>[generator.py]"]
  node_formatting["Output formatting<br/>[models.py]"]
end

subgraph group_outputs["Published files"]
  node_mainlist["Main playlist<br/>[msplay.m3u]"]
  node_categorylists["Category playlists"]
  node_stats["Channel statistics<br/>[stats.json]"]
end

node_operator(("Operator"))
node_players(("IPTV players"))
node_sources["M3U sources"]
node_endpoints["Stream endpoints"]

node_operator -->|"runs"| node_main
node_main -->|"reads settings"| node_config
node_main -->|"calls scrape"| node_scraper
node_scraper -->|"reads sources"| node_config
node_scraper -->|"fetches playlists"| node_sources
node_scraper -->|"parses content"| node_parser
node_parser -->|"creates channels"| node_models
node_scraper -->|"returns channels"| node_main
node_main -->|"calls validate"| node_validator
node_validator -->|"checks streams"| node_streamcheck
node_streamcheck -->|"probes URLs"| node_endpoints
node_validator -->|"returns valid channels"| node_main
node_main -->|"calls generate"| node_generator
node_generator -->|"formats entries"| node_formatting
node_generator -->|"writes playlist"| node_mainlist
node_generator -->|"writes categories"| node_categorylists
node_generator -->|"writes statistics"| node_stats
node_players -->|"loads playlist"| node_mainlist
node_players -->|"loads playlist"| node_categorylists

click node_main "https://github.com/hirotomasato/msplayiptv/blob/main/main.py"
click node_config "https://github.com/hirotomasato/msplayiptv/blob/main/src/config.py"
click node_scraper "https://github.com/hirotomasato/msplayiptv/blob/main/src/scraper.py"
click node_parser "https://github.com/hirotomasato/msplayiptv/blob/main/src/utils.py"
click node_models "https://github.com/hirotomasato/msplayiptv/blob/main/src/models.py"
click node_validator "https://github.com/hirotomasato/msplayiptv/blob/main/src/validator.py"
click node_streamcheck "https://github.com/hirotomasato/msplayiptv/blob/main/src/utils.py"
click node_generator "https://github.com/hirotomasato/msplayiptv/blob/main/src/generator.py"
click node_formatting "https://github.com/hirotomasato/msplayiptv/blob/main/src/models.py"
click node_mainlist "https://github.com/hirotomasato/msplayiptv/blob/main/static/msplay.m3u"
click node_categorylists "https://github.com/hirotomasato/msplayiptv/tree/main/static"
click node_stats "https://github.com/hirotomasato/msplayiptv/blob/main/static/stats.json"

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_config,node_scraper,node_parser,node_models toneBlue
class node_validator,node_streamcheck toneAmber
class node_generator,node_formatting toneMint
class node_mainlist,node_categorylists,node_stats toneRose
class node_operator,node_players,node_sources,node_endpoints toneIndigo
```

## Components

### Channel ingestion

- [Pipeline entry](https://github.com/hirotomasato/msplayiptv/blob/main/main.py): `main.py`
- [Runtime config](https://github.com/hirotomasato/msplayiptv/blob/main/src/config.py): `src/config.py`
- [Source scraper](https://github.com/hirotomasato/msplayiptv/blob/main/src/scraper.py): `src/scraper.py`
- [M3U parser](https://github.com/hirotomasato/msplayiptv/blob/main/src/utils.py): `src/utils.py`
- [Channel models](https://github.com/hirotomasato/msplayiptv/blob/main/src/models.py): `src/models.py`

### Validation

- [Channel validator](https://github.com/hirotomasato/msplayiptv/blob/main/src/validator.py): `src/validator.py`
- [Stream checks](https://github.com/hirotomasato/msplayiptv/blob/main/src/utils.py): `src/utils.py`

### Playlist publishing

- [Playlist generator](https://github.com/hirotomasato/msplayiptv/blob/main/src/generator.py): `src/generator.py`
- [Output formatting](https://github.com/hirotomasato/msplayiptv/blob/main/src/models.py): `src/models.py`

### Published files

- [Main playlist](https://github.com/hirotomasato/msplayiptv/blob/main/static/msplay.m3u): `static/msplay.m3u`
- [Category playlists](https://github.com/hirotomasato/msplayiptv/tree/main/static): `static`
- [Channel statistics](https://github.com/hirotomasato/msplayiptv/blob/main/static/stats.json): `static/stats.json`

### Other components

- **Operator**
- **IPTV players**
- **M3U sources**
- **Stream endpoints**

## Connections

- Operator → Pipeline entry: runs
- Pipeline entry → Runtime config: reads settings
- Pipeline entry → Source scraper: calls scrape
- Source scraper → Runtime config: reads sources
- Source scraper → M3U sources: fetches playlists
- Source scraper → M3U parser: parses content
- M3U parser → Channel models: creates channels
- Source scraper → Pipeline entry: returns channels
- Pipeline entry → Channel validator: calls validate
- Channel validator → Stream checks: checks streams
- Stream checks → Stream endpoints: probes URLs
- Channel validator → Pipeline entry: returns valid channels
- Pipeline entry → Playlist generator: calls generate
- Playlist generator → Output formatting: formats entries
- Playlist generator → Main playlist: writes playlist
- Playlist generator → Category playlists: writes categories
- Playlist generator → Channel statistics: writes statistics
- IPTV players → Main playlist: loads playlist
- IPTV players → Category playlists: loads playlist