# chernandezweb/iptv-proxy architecture

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

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

## Overview

IPTV Proxy accepts client playlist, Xtream API, and stream requests, then serves proxied playlists, metadata, guide data, or media from configured providers. Startup loads configuration and constructs the HTTP server; server routes dispatch to M3U, Xtream, admin, and stream handlers. Provider/filter management and failover are important supporting capabilities. The excerpts establish the main route and handler relationships; unsampled cache and relay details are represented only where their paths are evidenced.

Main entry points: [`pkg/server/server.go`](https://github.com/chernandezweb/iptv-proxy/blob/master/pkg/server/server.go) (HTTP server), [`pkg/server/xtreamHandles.go`](https://github.com/chernandezweb/iptv-proxy/blob/master/pkg/server/xtreamHandles.go) (Xtream endpoints), [`pkg/server/admin.go`](https://github.com/chernandezweb/iptv-proxy/blob/master/pkg/server/admin.go) (Admin API), [`pkg/server/routes.go`](https://github.com/chernandezweb/iptv-proxy/blob/master/pkg/server/routes.go) (Route dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and configuration"]
  node_main["Process entry<br/>[main.go]"]
  node_cli["CLI and config<br/>[root.go]"]
  node_provider_config["Provider settings<br/>[provider.go]"]
  node_filters["Category filters<br/>[filters.go]"]
end

subgraph group_http["HTTP server and proxy"]
  node_server["HTTP server<br/>[server.go]"]
  node_routes["Route dispatch<br/>[routes.go]"]
  node_playlist_handlers["M3U handling<br/>[handlers.go]"]
  node_stream_relay["Stream relay<br/>[relay.go]"]
end

subgraph group_xtream["Xtream services"]
  node_xtream_handlers["Xtream endpoints<br/>[xtreamHandles.go]"]
  node_xtream_client["Xtream client<br/>[xtream-proxy.go]"]
  node_cache["Response caches<br/>[cache.go]"]
end

subgraph group_admin["Provider administration"]
  node_admin_api["Admin API<br/>[admin.go]"]
  node_admin_ui["Admin UI<br/>[admin.html]"]
end

node_operator(("Operator"))
node_iptv_client(("IPTV client"))
node_provider(("IPTV provider"))

node_operator -.->|"configures"| node_cli
node_main -->|"executes"| node_cli
node_cli -->|"constructs and serves"| node_server
node_server -->|"registers routes"| node_routes
node_routes -->|"routes M3U"| node_playlist_handlers
node_routes -->|"routes Xtream"| node_xtream_handlers
node_iptv_client -.->|"requests"| node_routes
node_playlist_handlers -.->|"relays media"| node_provider
node_xtream_handlers -->|"requests metadata"| node_xtream_client
node_xtream_client -.->|"queries API"| node_provider
node_xtream_handlers -.->|"fetches streams and guide"| node_provider
node_playlist_handlers -.->|"forwards streams"| node_stream_relay
node_server -->|"uses provider settings"| node_provider_config
node_xtream_client -->|"filters categories"| node_filters
node_xtream_handlers -->|"checks cached responses"| node_cache
node_server -->|"registers admin routes"| node_admin_api
node_admin_api -->|"serves interface"| node_admin_ui
node_admin_api -->|"reads and saves"| node_provider_config
node_admin_api -->|"saves filters"| node_filters

click node_main "https://github.com/chernandezweb/iptv-proxy/blob/master/main.go"
click node_cli "https://github.com/chernandezweb/iptv-proxy/blob/master/cmd/root.go"
click node_provider_config "https://github.com/chernandezweb/iptv-proxy/blob/master/pkg/config/provider.go"
click node_filters "https://github.com/chernandezweb/iptv-proxy/blob/master/pkg/config/filters.go"
click node_server "https://github.com/chernandezweb/iptv-proxy/blob/master/pkg/server/server.go"
click node_routes "https://github.com/chernandezweb/iptv-proxy/blob/master/pkg/server/routes.go"
click node_playlist_handlers "https://github.com/chernandezweb/iptv-proxy/blob/master/pkg/server/handlers.go"
click node_stream_relay "https://github.com/chernandezweb/iptv-proxy/blob/master/pkg/server/relay.go"
click node_xtream_handlers "https://github.com/chernandezweb/iptv-proxy/blob/master/pkg/server/xtreamHandles.go"
click node_xtream_client "https://github.com/chernandezweb/iptv-proxy/blob/master/pkg/xtream-proxy/xtream-proxy.go"
click node_cache "https://github.com/chernandezweb/iptv-proxy/blob/master/pkg/server/cache.go"
click node_admin_api "https://github.com/chernandezweb/iptv-proxy/blob/master/pkg/server/admin.go"
click node_admin_ui "https://github.com/chernandezweb/iptv-proxy/blob/master/pkg/server/web/admin.html"

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_cli,node_provider_config,node_filters,node_iptv_client toneBlue
class node_server,node_routes,node_playlist_handlers,node_stream_relay toneAmber
class node_xtream_handlers,node_xtream_client,node_cache toneMint
class node_admin_api,node_admin_ui toneRose
class node_operator,node_provider toneIndigo
```

## Components

### Startup and configuration

- [Process entry](https://github.com/chernandezweb/iptv-proxy/blob/master/main.go): `main.go`
- [CLI and config](https://github.com/chernandezweb/iptv-proxy/blob/master/cmd/root.go): `cmd/root.go`
- [Provider settings](https://github.com/chernandezweb/iptv-proxy/blob/master/pkg/config/provider.go): `pkg/config/provider.go`
- [Category filters](https://github.com/chernandezweb/iptv-proxy/blob/master/pkg/config/filters.go): `pkg/config/filters.go`

### HTTP server and proxy

- [HTTP server](https://github.com/chernandezweb/iptv-proxy/blob/master/pkg/server/server.go): `pkg/server/server.go`
- [Route dispatch](https://github.com/chernandezweb/iptv-proxy/blob/master/pkg/server/routes.go): `pkg/server/routes.go`
- [M3U handling](https://github.com/chernandezweb/iptv-proxy/blob/master/pkg/server/handlers.go): `pkg/server/handlers.go`
- [Stream relay](https://github.com/chernandezweb/iptv-proxy/blob/master/pkg/server/relay.go): `pkg/server/relay.go`

### Xtream services

- [Xtream endpoints](https://github.com/chernandezweb/iptv-proxy/blob/master/pkg/server/xtreamHandles.go): `pkg/server/xtreamHandles.go`
- [Xtream client](https://github.com/chernandezweb/iptv-proxy/blob/master/pkg/xtream-proxy/xtream-proxy.go): `pkg/xtream-proxy/xtream-proxy.go`
- [Response caches](https://github.com/chernandezweb/iptv-proxy/blob/master/pkg/server/cache.go): `pkg/server/cache.go`

### Provider administration

- [Admin API](https://github.com/chernandezweb/iptv-proxy/blob/master/pkg/server/admin.go): `pkg/server/admin.go`
- [Admin UI](https://github.com/chernandezweb/iptv-proxy/blob/master/pkg/server/web/admin.html): `pkg/server/web/admin.html`

### Other components

- **Operator**
- **IPTV client**
- **IPTV provider**

## Connections

- Operator → CLI and config: configures (evidence: `README.md`)
- Process entry → CLI and config: executes (evidence: `main.go`)
- CLI and config → HTTP server: constructs and serves (evidence: `cmd/root.go`)
- HTTP server → Route dispatch: registers routes (evidence: `pkg/server/server.go`)
- Route dispatch → M3U handling: routes M3U (evidence: `pkg/server/routes.go`)
- Route dispatch → Xtream endpoints: routes Xtream (evidence: `pkg/server/routes.go`)
- IPTV client → Route dispatch: requests (evidence: `pkg/server/routes.go`)
- M3U handling → IPTV provider: relays media (evidence: `pkg/server/handlers.go`)
- Xtream endpoints → Xtream client: requests metadata (evidence: `pkg/server/xtreamHandles.go`)
- Xtream client → IPTV provider: queries API (evidence: `pkg/xtream-proxy/xtream-proxy.go`)
- Xtream endpoints → IPTV provider: fetches streams and guide (evidence: `pkg/server/xtreamHandles.go`)
- M3U handling → Stream relay: forwards streams (evidence: `pkg/server/handlers.go`)
- HTTP server → Provider settings: uses provider settings (evidence: `pkg/server/server.go`)
- Xtream client → Category filters: filters categories (evidence: `pkg/xtream-proxy/xtream-proxy.go`)
- Xtream endpoints → Response caches: checks cached responses (evidence: `pkg/server/xtreamHandles.go`)
- HTTP server → Admin API: registers admin routes (evidence: `pkg/server/server.go`)
- Admin API → Admin UI: serves interface (evidence: `pkg/server/admin.go`)
- Admin API → Provider settings: reads and saves (evidence: `pkg/server/admin.go`)
- Admin API → Category filters: saves filters (evidence: `pkg/server/admin.go`)
