# alvspen/gxmobile-iptv architecture

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

## Overview

广西移动 IPTV 自动播放列表生成与发布工具：定时或手动运行时，从运营商 API 获取频道数据，清洗、校验并生成确定性的 M3U；只有有效频道达到安全阈值且输出实质变化时，工作流才提交并部署。内部层包括频道列表解析、频道规范化与过滤、以及 M3U 构建。工作流细节依据 README 描述；未采样的实现连线仅在文档明确时展示。

Main entry points: [`.github/workflows/update-m3u.yml`](https://github.com/alvspen/gxmobile-iptv/blob/main/.github/workflows/update-m3u.yml) (Update workflow), [`json_to_m3u.py`](https://github.com/alvspen/gxmobile-iptv/blob/main/json_to_m3u.py) (CLI entry point), [`channels.m3u`](https://github.com/alvspen/gxmobile-iptv/blob/main/channels.m3u) (M3U playlist)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generator["Playlist generator"]
  node_script["CLI entry point<br/>[json_to_m3u.py]"]
  node_fetch["Fetch and retry<br/>[json_to_m3u.py]"]
  node_extract["Extract channels<br/>[json_to_m3u.py]"]
  node_clean["Validate and normalize<br/>[json_to_m3u.py]"]
  node_build["Build M3U<br/>[json_to_m3u.py]"]
end

subgraph group_automation["Scheduled publishing"]
  node_workflow["Update workflow<br/>[update-m3u.yml]"]
end

subgraph group_artifact["Playlist artifact"]
  node_playlist["M3U playlist<br/>[channels.m3u]"]
end

node_operator(("Schedule or operator"))
node_upstream{{"Channel API"}}
node_git{{"Git remote"}}
node_pages{{"GitHub Pages"}}
node_player(("Playlist player"))

node_operator -->|"triggers"| node_workflow
node_workflow -->|"runs"| node_script
node_script -->|"calls"| node_fetch
node_fetch -->|"requests JSON"| node_upstream
node_fetch -->|"returns data"| node_extract
node_script -->|"calls"| node_extract
node_script -->|"calls"| node_build
node_build -->|"validates channels"| node_clean
node_build -->|"writes atomically"| node_playlist
node_workflow -->|"checks changes"| node_playlist
node_workflow -->|"commits and pushes"| node_git
node_workflow -->|"deploys on change"| node_pages
node_player -->|"reads"| node_playlist

click node_workflow "https://github.com/alvspen/gxmobile-iptv/blob/main/.github/workflows/update-m3u.yml"
click node_script "https://github.com/alvspen/gxmobile-iptv/blob/main/json_to_m3u.py"
click node_fetch "https://github.com/alvspen/gxmobile-iptv/blob/main/json_to_m3u.py"
click node_extract "https://github.com/alvspen/gxmobile-iptv/blob/main/json_to_m3u.py"
click node_clean "https://github.com/alvspen/gxmobile-iptv/blob/main/json_to_m3u.py"
click node_build "https://github.com/alvspen/gxmobile-iptv/blob/main/json_to_m3u.py"
click node_playlist "https://github.com/alvspen/gxmobile-iptv/blob/main/channels.m3u"

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_script,node_fetch,node_extract,node_clean,node_build toneBlue
class node_workflow toneAmber
class node_playlist,node_upstream toneMint
class node_operator,node_git,node_pages,node_player toneIndigo
```

## Components

### Playlist generator

- [CLI entry point](https://github.com/alvspen/gxmobile-iptv/blob/main/json_to_m3u.py): `json_to_m3u.py`
- [Fetch and retry](https://github.com/alvspen/gxmobile-iptv/blob/main/json_to_m3u.py): `json_to_m3u.py`
- [Extract channels](https://github.com/alvspen/gxmobile-iptv/blob/main/json_to_m3u.py): `json_to_m3u.py`
- [Validate and normalize](https://github.com/alvspen/gxmobile-iptv/blob/main/json_to_m3u.py): `json_to_m3u.py`
- [Build M3U](https://github.com/alvspen/gxmobile-iptv/blob/main/json_to_m3u.py): `json_to_m3u.py`

### Scheduled publishing

- [Update workflow](https://github.com/alvspen/gxmobile-iptv/blob/main/.github/workflows/update-m3u.yml): `.github/workflows/update-m3u.yml`

### Playlist artifact

- [M3U playlist](https://github.com/alvspen/gxmobile-iptv/blob/main/channels.m3u): `channels.m3u`

### Other components

- **Schedule or operator**
- **Channel API**
- **Git remote**
- **GitHub Pages**
- **Playlist player**

## Connections

- Schedule or operator → Update workflow: triggers
- Update workflow → CLI entry point: runs
- CLI entry point → Fetch and retry: calls
- Fetch and retry → Channel API: requests JSON
- Fetch and retry → Extract channels: returns data
- CLI entry point → Extract channels: calls
- CLI entry point → Build M3U: calls
- Build M3U → Validate and normalize: validates channels
- Build M3U → M3U playlist: writes atomically
- Update workflow → M3U playlist: checks changes
- Update workflow → Git remote: commits and pushes
- Update workflow → GitHub Pages: deploys on change
- Playlist player → M3U playlist: reads