# zhimin-dev/iptv-checker architecture

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

- Interactive diagram: https://gitdiagram.com/zhimin-dev/iptv-checker
- Repository: https://github.com/zhimin-dev/iptv-checker

## Overview

1. This repository is primarily an IPTV playlist checking product, not just a library. From the files shown, the repo is packaged for three delivery modes: Docker image, Docker Compose, and standalone CLI/binary.

2. The application’s core runtime is a long-lived checker service with a Web management UI on top. The container exposes internal service port 8089, and the README maps it to host port 8081, so the UI/API and background jobs are served by the same process boundary.

3. The main domain subsystem is playlist ingestion and normalization. It accepts M3U, M3U8, and TXT playlists, then standardizes channel metadata such as `tvg-name`, `tvg-id`, and `group-title`, including EPG-based name matching and cleanup of quality suffixes like “4K”.

4. The checking subsystem is the heart of the product. It supports two validation paths: lightweight HTTP checks and stronger FFmpeg-based checks. That implies a split between fast availability probing and more accurate stream verification.

5. Task execution is asynchronous and batch-oriented. The README explicitly calls out concurrent checks, scheduled tasks, and import/export of tasks, so the architecture likely has a job queue or worker pool behind the UI rather than single-request processing.

6. Results are transformed into exportable outputs. The product supports exporting usable channel lists in M3U or TXT format, and can split output by IPv4 vs IPv6. That means the checker is not only validating streams but also acting as a filtering and publishing pipeline.

7. The Web management layer is an operational control plane. It handles task management, configuration editing, backup/restore, and result export, with a dark-mode UI. This UI is the main boundary for human interaction; the actual checking logic runs behind it.

8. Configuration is a first-class subsystem. The README highlights timeout tuning, custom sorting, keyword matching, fastest-stream selection, EPG settings, host management, and group mapping import/export. That suggests the app stores and reuses operational metadata across runs, not just ephemeral check state.

9. External integration is centered on GitHub API access. The app uses GitHub to fetch release-related data and/or assets, and it supports a GitHub token to raise API quota from 60 requests/hour to 5000 requests/hour. It also has fallback behavior to HTML parsing when unauthenticated requests are rate-limited.

10. FFmpeg is an important runtime dependency because it materially changes the architecture of stream validation. The system must spawn or orchestrate media probes in addition to plain HTTP requests, so the deployment environment needs FFmpeg available for full functionality.

11. The repo’s delivery and release pipeline is organized around GitHub Actions and container packaging. The visible workflows include separate build paths for Docker and GitHub releases, plus a release workflow, indicating automated build/test/package publishing rather than manual release steps.

12. Operationally, Docker is the primary deployment boundary. The included `docker-compose.yaml` and `dockerfile` show the project is designed to run as a self-contained service, while the standalone binary path is provided for users who prefer CLI execution.

13. From an architecture-diagram perspective, the key data flow is: user uploads or configures playlist/EPG/settings → backend schedules check jobs → checker validates streams via HTTP and/or FFmpeg → results are normalized and filtered → UI exposes them for review/export → optional backup/import/export and release packaging keep state portable.

14. The recent changelog items suggest the architecture has also grown security and portability boundaries: GitHub REST API migration, SSRF and path traversal hardening, connection reuse optimizations, and global host management. Those are important to reflect as cross-cutting concerns in the diagram, even though the source tree is not included here.

Main entry points: [`.github/workflows`](https://github.com/zhimin-dev/iptv-checker/blob/main/.github/workflows) (Release flow), [`dockerfile`](https://github.com/zhimin-dev/iptv-checker/tree/main/dockerfile) (Docker image), [`Makefile`](https://github.com/zhimin-dev/iptv-checker/tree/main/Makefile) (CLI binary), [`docker-compose.yaml`](https://github.com/zhimin-dev/iptv-checker/blob/main/docker-compose.yaml) (Compose stack)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_delivery["Delivery"]
  node_docker_image["Docker image<br/>runtime packaging"]
  node_compose_stack["Compose stack<br/>deployment orchestration"]
  node_cli_binary["CLI binary<br/>standalone runtime"]
end

subgraph group_runtime["Runtime"]
  node_service_core(("Checker service<br/>long-lived service"))
  node_web_ui["Web UI<br/>control plane"]
  node_task_orchestrator["Task engine<br/>async jobs"]
  node_playlist_ingest["Playlist ingest<br/>normalization"]
  node_epg_matcher["EPG matcher<br/>metadata cleanup"]
  node_check_engine{{"Check engine<br/>validation core"}}
  node_http_probe["HTTP probe<br/>fast check"]
  node_ffmpeg_probe["FFmpeg probe<br/>deep check"]
  node_result_pipeline["Result pipeline<br/>filter/export"]
  node_export_formats["Exports<br/>m3u/txt output"]
end

subgraph group_ops["Operations"]
  node_config_store[("Config store<br/>operational state")]
  node_github_integration["GitHub API<br/>external integration"]
  node_security_controls{{"Safety guards<br/>cross-cutting hardening"}}
  node_release_pipeline["Release flow<br/>CI/CD<br/>[workflows]"]
end

node_docker_image -->|"runs"| node_service_core
node_compose_stack -->|"orchestrates"| node_service_core
node_cli_binary -->|"starts"| node_service_core
node_service_core -->|"serves"| node_web_ui
node_service_core -->|"hosts"| node_task_orchestrator
node_web_ui -->|"edits"| node_config_store
node_web_ui -->|"submits"| node_task_orchestrator
node_task_orchestrator -->|"feeds"| node_playlist_ingest
node_playlist_ingest -->|"normalizes"| node_epg_matcher
node_epg_matcher -->|"prepares"| node_check_engine
node_task_orchestrator -->|"dispatches"| node_check_engine
node_check_engine -->|"uses"| node_http_probe
node_check_engine -->|"uses"| node_ffmpeg_probe
node_ffmpeg_probe -->|"yields"| node_result_pipeline
node_http_probe -->|"yields"| node_result_pipeline
node_result_pipeline -->|"publishes"| node_export_formats
node_config_store -->|"drives"| node_task_orchestrator
node_config_store -->|"guides"| node_playlist_ingest
node_github_integration -->|"supports"| node_release_pipeline
node_security_controls -->|"protects"| node_service_core
node_release_pipeline -->|"builds"| node_docker_image
node_release_pipeline -->|"builds"| node_cli_binary

click node_docker_image "https://github.com/zhimin-dev/iptv-checker/tree/main/dockerfile"
click node_compose_stack "https://github.com/zhimin-dev/iptv-checker/blob/main/docker-compose.yaml"
click node_cli_binary "https://github.com/zhimin-dev/iptv-checker/tree/main/Makefile"
click node_release_pipeline "https://github.com/zhimin-dev/iptv-checker/blob/main/.github/workflows"

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_docker_image,node_compose_stack,node_cli_binary toneBlue
class node_service_core,node_web_ui,node_task_orchestrator,node_playlist_ingest,node_epg_matcher,node_check_engine,node_http_probe,node_ffmpeg_probe,node_result_pipeline,node_export_formats toneAmber
class node_config_store,node_github_integration,node_security_controls,node_release_pipeline toneMint
```

## Components

### Delivery

Ways the checker is packaged and run.

- [Docker image](https://github.com/zhimin-dev/iptv-checker/tree/main/dockerfile): runtime packaging · Primary containerized deployment for the service. · `dockerfile`
- [Compose stack](https://github.com/zhimin-dev/iptv-checker/blob/main/docker-compose.yaml): deployment orchestration · Self-contained multi-container or single-service run via Compose. · `docker-compose.yaml`
- [CLI binary](https://github.com/zhimin-dev/iptv-checker/tree/main/Makefile): standalone runtime · Standalone executable path for non-container execution. · `Makefile`

### Runtime

Core service, workflow, and domain subsystems.

- **Checker service**: long-lived service · Single process boundary hosting the web UI, API, and background jobs.
- **Web UI**: control plane · Operational interface for managing tasks, settings, backups, and exports.
- **Task engine**: async jobs · Schedules, queues, and runs concurrent playlist checking work.
- **Playlist ingest**: normalization · Parses M3U, M3U8, and TXT playlists and standardizes channel metadata.
- **EPG matcher**: metadata cleanup · Matches EPG names/IDs and cleans noisy channel labels such as quality suffixes.
- **Check engine**: validation core · Performs stream validation and decides channel availability.
- **HTTP probe**: fast check · Lightweight availability validation path using HTTP requests.
- **FFmpeg probe**: deep check · Stronger media-stream verification path using FFmpeg.
- **Result pipeline**: filter/export · Normalizes checked channels into usable output lists.
- **Exports**: m3u/txt output · Produces filtered M3U or TXT outputs, including IPv4/IPv6 splits.

### Operations

Configuration, integrations, and release pipeline.

- **Config store**: operational state · Persists timeouts, sorting, keyword rules, host mapping, and EPG settings.
- **GitHub API**: external integration · Fetches release-related data with token-based quota expansion and fallback parsing.
- **Safety guards**: cross-cutting hardening · Protects against SSRF, path traversal, and other operational attack surfaces.
- [Release flow](https://github.com/zhimin-dev/iptv-checker/blob/main/.github/workflows): CI/CD · GitHub Actions and packaging workflow for Docker and releases. · `.github/workflows`

## Connections

- Docker image → Checker service: runs · Container starts the checker service.
- Compose stack → Checker service: orchestrates · Compose wires the service runtime and exposed port.
- CLI binary → Checker service: starts · Standalone build launches the same core runtime.
- Checker service → Web UI: serves · The UI is exposed by the main service boundary.
- Checker service → Task engine: hosts · Background jobs run inside the same process boundary.
- Web UI → Config store: edits · Users manage operational settings and persisted state.
- Web UI → Task engine: submits · UI creates import, check, export, and maintenance tasks.
- Task engine → Playlist ingest: feeds · Imported playlists enter normalization before checking.
- Playlist ingest → EPG matcher: normalizes · Metadata cleanup and EPG-based matching standardize channels.
- EPG matcher → Check engine: prepares · Cleaned channel records are handed to the validator.
- Task engine → Check engine: dispatches · Concurrent work batches route channels into validation.
- Check engine → HTTP probe: uses · Fast path for lightweight availability checks.
- Check engine → FFmpeg probe: uses · Deep path for stronger stream verification.
- FFmpeg probe → Result pipeline: yields · Verified stream results flow into filtering and publishing.
- HTTP probe → Result pipeline: yields · Probe outcomes are converted into output candidates.
- Result pipeline → Exports: publishes · Filtered results are emitted as M3U or TXT exports.
- Config store → Task engine: drives · Timeouts, sorting, keywords, and host rules shape execution.
- Config store → Playlist ingest: guides · Mapping and normalization settings affect ingest behavior.
- GitHub API → Release flow: supports · Release data and assets come from GitHub services.
- Safety guards → Checker service: protects · Cross-cutting hardening applies to the runtime boundary.
- Release flow → Docker image: builds · CI packages container artifacts.
- Release flow → CLI binary: builds · CI also publishes standalone binaries.
