# shajon-404/iptv architecture

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

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

## Overview

1. **Repository shape**
   - This is a single Next.js App Router application, not a multi-service backend.
   - The codebase is split into route folders under `app/`, shared UI in `app/components/`, domain hooks in `app/hooks/`, and server utilities in `app/lib/`.
   - The main architecture is a browser-based IPTV player with a few adjacent features: authentication, playlist sync, viewer tracking, and a separate fixtures/bracket section.

2. **Primary user-facing surface**
   - The IPTV experience is centered around the player UI in `app/components/IPTVPlayer.tsx` and the `app/components/player/*` subcomponents.
   - The player area is decomposed into channel listing, playlist management, channel stats, sidebar, and video playback views.
   - Supporting shell components like `Header`, `Footer`, `MobileNavBar`, `BackgroundScene`, and modal/popup wrappers provide the site chrome and cinematic presentation layer.

3. **Playback subsystem**
   - Media playback is a dedicated subsystem with support for multiple stream formats, as described in the README: HLS, DASH/ClearKey DRM, and MPEG-TS.
   - The project uses client-side playback engines such as HLS.js, Shaka Player, and mpegts.js, which implies that the browser is responsible for actual decoding/rendering while the server mostly brokers access.
   - The `useVideoPlayer` hook likely coordinates player state, stream selection, quality switching, and viewer-facing playback controls.

4. **IPTV backend API boundary**
   - The API under `app/api/iptv/` is the core server boundary for IPTV-specific operations.
   - Endpoints cover:
     - playlist CRUD/sync (`playlists`)
     - channel listing and channel hashing (`channels`, `channels/hash`)
     - stream proxying (`proxy`)
     - viewer telemetry (`viewers`)
   - This keeps the browser UI thin: it asks the app server for playlist/channel metadata and only hits stream sources through a controlled proxy when needed.

5. **Stream access and proxying**
   - The `app/api/iptv/proxy/route.ts` endpoint is a security and compatibility layer between client playback and external stream origins.
   - According to the README, it exists to handle CORS, geo-blocking, custom headers, and anti-SSRF validation, using Node-side HTTP handling (`undici`).
   - Architecturally, this is the main trust boundary for untrusted playlist URLs and third-party stream endpoints.

6. **Authentication and session flow**
   - Authentication is implemented as a custom Google OAuth flow, not a generic auth framework.
   - The routes under `app/api/auth/` handle login initiation, OAuth callback, logout, and session lookup.
   - Shared auth logic lives in `app/lib/auth.ts`, and `app/hooks/useAuth.tsx` suggests the client maintains session-aware UI state based on the server session endpoint.

7. **Cloud playlist sync and persistence**
   - Playlist persistence is backed by Prisma and PostgreSQL, with schema defined in `prisma/schema.prisma` and client wiring in `app/lib/prisma.ts`.
   - The client hook `useIPTVPlaylists` and the `playlists` API route form the data path for syncing user playlists across devices.
   - The README indicates playlists may be M3U or JSON, and `app/lib/playlistParser.ts` is the parsing/normalization layer before data is stored or displayed.

8. **Security gates around user actions**
   - Cloudflare Turnstile is used as an explicit anti-abuse gate, with client and server pieces in `app/components/Turnstile.tsx`, `TurnstileGuard.tsx`, and `app/actions/turnstile.ts`.
   - This is a server action boundary rather than a purely client-side widget, which matters because verification influences sensitive operations like playlist access or submission.
   - Environment variables also suggest development-origin allowlists and a disable switch for local testing.

9. **Viewer tracking and analytics**
   - `ViewerTracker.tsx` and the `app/api/iptv/viewers/` route indicate lightweight playback telemetry.
   - Channel stats in the player UI likely consume that data to show current viewer or stream-related metrics.
   - This is separate from authentication and playlist persistence: it is operational telemetry tied to playback sessions.

10. **Secondary content areas**
   - The app is not only IPTV; it also has standalone pages for About, FAQ, Login, Dashboard, and FTP.
   - The `app/fixtures/` subtree is a separate feature domain with its own page, client component, hooks, types, and UI primitives for fixtures/bracket-style content.
   - Because it has its own local component and utility structure, it should be diagrammed as a parallel feature area rather than part of the IPTV player core.

11. **Delivery, SEO, and installability**
   - `public/manifest.json` and `public/sw.js` show this app is configured as a PWA with offline/install-related behavior.
   - `robots.ts` and `sitemap.ts` indicate the app also has SEO-aware server routes.
   - `next.config.ts`, `Dockerfile`, and Node 22.19+ support show the app is meant to be deployed as a containerized Next.js server.

12. **Overall data flow**
   - Browser loads the Next.js app shell, renders public pages, and then hydrates client components for login, playlists, player, and tracking.
   - Authenticated users exchange Google OAuth/session state with the auth API, fetch or save playlists through the IPTV API, and play channels through either direct stream URLs or the proxy endpoint.
   - Persistent user data lives in PostgreSQL via Prisma; external dependencies are Google OAuth, Turnstile, and upstream stream sources/playlist URLs.

Main entry points: [`app/page.tsx`](https://github.com/shajon-404/iptv/blob/main/app/page.tsx) (Home), [`app/components/IPTVPlayer.tsx`](https://github.com/shajon-404/iptv/blob/main/app/components/IPTVPlayer.tsx) (IPTV player), [`app/api/iptv`](https://github.com/shajon-404/iptv/tree/main/app/api/iptv) (IPTV API), [`app/components/player/PlaylistManagerView.tsx`](https://github.com/shajon-404/iptv/blob/main/app/components/player/PlaylistManagerView.tsx) (Playlist manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_shell["App shell"]
  node_node_root["Home<br/>next page<br/>[page.tsx]"]
  node_node_about["About<br/>next page<br/>[page.tsx]"]
  node_node_faq["FAQ<br/>next page<br/>[page.tsx]"]
  node_node_dashboard["Dashboard<br/>next page<br/>[page.tsx]"]
  node_node_ftp["FTP<br/>next page<br/>[page.tsx]"]
  node_node_turnstile{{"Turnstile<br/>security gate<br/>[Turnstile.tsx]"}}
  node_node_turnstile_guard{{"Gate wrapper<br/>security gate<br/>[TurnstileGuard.tsx]"}}
end

subgraph group_grp_iptv["IPTV core"]
  node_node_player_shell["IPTV player<br/>client shell<br/>[IPTVPlayer.tsx]"]
  node_node_channel_list["Channel list<br/>player view"]
  node_node_playlist_mgr["Playlist manager<br/>player view"]
  node_node_playlist_sidebar["Sidebar<br/>player view"]
  node_node_channel_stats["Channel stats<br/>player view<br/>[ChannelStats.tsx]"]
  node_node_video_view["Video view<br/>player view"]
  node_node_use_video{{"useVideoPlayer<br/>hook<br/>[useVideoPlayer.ts]"}}
  node_node_iptv_api[("IPTV API<br/>api routes")]
  node_node_proxy[("Stream proxy<br/>api route<br/>[route.ts]")]
  node_node_viewer_tracker{{"Viewer tracker<br/>telemetry<br/>[ViewerTracker.tsx]"}}
end

subgraph group_grp_auth["Auth and data"]
  node_node_login["Login<br/>next page<br/>[page.tsx]"]
  node_node_use_playlists{{"useIPTVPlaylists<br/>hook"}}
  node_node_use_auth{{"useAuth<br/>hook<br/>[useAuth.tsx]"}}
  node_node_auth_api[("Auth API<br/>api routes")]
  node_node_prisma[("Prisma DB<br/>persistence<br/>[prisma.ts]")]
  node_node_auth_lib{{"Auth lib<br/>server auth<br/>[auth.ts]"}}
  node_node_playlist_parser{{"Playlist parser<br/>normalizer<br/>[playlistParser.ts]"}}
end

subgraph group_grp_fixtures["Fixtures"]
  node_node_fixtures_page["Fixtures page<br/>next page<br/>[page.tsx]"]
  node_node_fixtures_client["Fixtures client<br/>client feature<br/>[FixturesClient.tsx]"]
  node_node_fixtures_hook{{"useFixtures<br/>hook<br/>[useFixtures.ts]"}}
end

node_node_root -->|"loads"| node_node_player_shell
node_node_root -->|"nav"| node_node_about
node_node_root -->|"nav"| node_node_faq
node_node_root -->|"auth"| node_node_login
node_node_root -->|"nav"| node_node_dashboard
node_node_root -->|"nav"| node_node_ftp
node_node_player_shell -->|"composes"| node_node_channel_list
node_node_player_shell -->|"composes"| node_node_playlist_mgr
node_node_player_shell -->|"composes"| node_node_playlist_sidebar
node_node_player_shell -->|"composes"| node_node_channel_stats
node_node_player_shell -->|"composes"| node_node_video_view
node_node_use_video -->|"drives"| node_node_video_view
node_node_use_playlists -->|"feeds"| node_node_playlist_mgr
node_node_use_auth -->|"reads"| node_node_auth_api
node_node_auth_api -->|"uses"| node_node_auth_lib
node_node_iptv_api -->|"persists"| node_node_prisma
node_node_iptv_api -->|"normalizes"| node_node_playlist_parser
node_node_iptv_api -->|"includes"| node_node_proxy
node_node_proxy -->|"serves"| node_node_video_view
node_node_turnstile_guard -->|"wraps"| node_node_turnstile
node_node_turnstile_guard -->|"protects"| node_node_playlist_mgr
node_node_viewer_tracker -->|"reports"| node_node_iptv_api
node_node_fixtures_page -->|"loads"| node_node_fixtures_client
node_node_fixtures_client -->|"uses"| node_node_fixtures_hook

click node_node_root "https://github.com/shajon-404/iptv/blob/main/app/page.tsx"
click node_node_about "https://github.com/shajon-404/iptv/blob/main/app/about/page.tsx"
click node_node_faq "https://github.com/shajon-404/iptv/blob/main/app/faq/page.tsx"
click node_node_login "https://github.com/shajon-404/iptv/blob/main/app/login/page.tsx"
click node_node_dashboard "https://github.com/shajon-404/iptv/blob/main/app/dashboard/page.tsx"
click node_node_ftp "https://github.com/shajon-404/iptv/blob/main/app/ftp/page.tsx"
click node_node_player_shell "https://github.com/shajon-404/iptv/blob/main/app/components/IPTVPlayer.tsx"
click node_node_channel_list "https://github.com/shajon-404/iptv/blob/main/app/components/player/ChannelListView.tsx"
click node_node_playlist_mgr "https://github.com/shajon-404/iptv/blob/main/app/components/player/PlaylistManagerView.tsx"
click node_node_playlist_sidebar "https://github.com/shajon-404/iptv/blob/main/app/components/player/PlaylistSidebarView.tsx"
click node_node_channel_stats "https://github.com/shajon-404/iptv/blob/main/app/components/player/ChannelStats.tsx"
click node_node_video_view "https://github.com/shajon-404/iptv/blob/main/app/components/player/VideoPlayerView.tsx"
click node_node_use_video "https://github.com/shajon-404/iptv/blob/main/app/hooks/useVideoPlayer.ts"
click node_node_use_playlists "https://github.com/shajon-404/iptv/blob/main/app/hooks/useIPTVPlaylists.ts"
click node_node_use_auth "https://github.com/shajon-404/iptv/blob/main/app/hooks/useAuth.tsx"
click node_node_auth_api "https://github.com/shajon-404/iptv/tree/main/app/api/auth"
click node_node_iptv_api "https://github.com/shajon-404/iptv/tree/main/app/api/iptv"
click node_node_proxy "https://github.com/shajon-404/iptv/blob/main/app/api/iptv/proxy/route.ts"
click node_node_prisma "https://github.com/shajon-404/iptv/blob/main/app/lib/prisma.ts"
click node_node_auth_lib "https://github.com/shajon-404/iptv/blob/main/app/lib/auth.ts"
click node_node_playlist_parser "https://github.com/shajon-404/iptv/blob/main/app/lib/playlistParser.ts"
click node_node_turnstile "https://github.com/shajon-404/iptv/blob/main/app/components/Turnstile.tsx"
click node_node_turnstile_guard "https://github.com/shajon-404/iptv/blob/main/app/components/TurnstileGuard.tsx"
click node_node_viewer_tracker "https://github.com/shajon-404/iptv/blob/main/app/components/ViewerTracker.tsx"
click node_node_fixtures_page "https://github.com/shajon-404/iptv/blob/main/app/fixtures/page.tsx"
click node_node_fixtures_client "https://github.com/shajon-404/iptv/blob/main/app/fixtures/FixturesClient.tsx"
click node_node_fixtures_hook "https://github.com/shajon-404/iptv/blob/main/app/fixtures/hooks/useFixtures.ts"

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_node_root,node_node_about,node_node_faq,node_node_dashboard,node_node_ftp,node_node_turnstile,node_node_turnstile_guard toneBlue
class node_node_player_shell,node_node_channel_list,node_node_playlist_mgr,node_node_playlist_sidebar,node_node_channel_stats,node_node_video_view,node_node_use_video,node_node_iptv_api,node_node_proxy,node_node_viewer_tracker toneAmber
class node_node_login,node_node_use_playlists,node_node_use_auth,node_node_auth_api,node_node_prisma,node_node_auth_lib,node_node_playlist_parser toneMint
class node_node_fixtures_page,node_node_fixtures_client,node_node_fixtures_hook toneRose
```

## Components

### App shell

Route pages and shared chrome around the main app experience.

- [Home](https://github.com/shajon-404/iptv/blob/main/app/page.tsx): next page · Landing page entry for the app. · `app/page.tsx`
- [About](https://github.com/shajon-404/iptv/blob/main/app/about/page.tsx): next page · Public about page. · `app/about/page.tsx`
- [FAQ](https://github.com/shajon-404/iptv/blob/main/app/faq/page.tsx): next page · Public help and questions page. · `app/faq/page.tsx`
- [Dashboard](https://github.com/shajon-404/iptv/blob/main/app/dashboard/page.tsx): next page · Authenticated user area. · `app/dashboard/page.tsx`
- [FTP](https://github.com/shajon-404/iptv/blob/main/app/ftp/page.tsx): next page · Separate FTP-related page. · `app/ftp/page.tsx`
- [Turnstile](https://github.com/shajon-404/iptv/blob/main/app/components/Turnstile.tsx): security gate · Anti-abuse verification for sensitive actions. · `app/components/Turnstile.tsx`
- [Gate wrapper](https://github.com/shajon-404/iptv/blob/main/app/components/TurnstileGuard.tsx): security gate · Client/server wrapper around Turnstile-protected actions. · `app/components/TurnstileGuard.tsx`

### IPTV core

Player UI, playback hooks, and IPTV-specific API boundaries.

- [IPTV player](https://github.com/shajon-404/iptv/blob/main/app/components/IPTVPlayer.tsx): client shell · Main browser IPTV experience and orchestration layer. · `app/components/IPTVPlayer.tsx`
- [Channel list](https://github.com/shajon-404/iptv/blob/main/app/components/player/ChannelListView.tsx): player view · Channel browsing and selection UI. · `app/components/player/ChannelListView.tsx`
- [Playlist manager](https://github.com/shajon-404/iptv/blob/main/app/components/player/PlaylistManagerView.tsx): player view · Playlist editing and sync UI. · `app/components/player/PlaylistManagerView.tsx`
- [Sidebar](https://github.com/shajon-404/iptv/blob/main/app/components/player/PlaylistSidebarView.tsx): player view · Secondary playlist and navigation panel. · `app/components/player/PlaylistSidebarView.tsx`
- [Channel stats](https://github.com/shajon-404/iptv/blob/main/app/components/player/ChannelStats.tsx): player view · Viewer and stream metrics display. · `app/components/player/ChannelStats.tsx`
- [Video view](https://github.com/shajon-404/iptv/blob/main/app/components/player/VideoPlayerView.tsx): player view · Playback surface and stream rendering UI. · `app/components/player/VideoPlayerView.tsx`
- [useVideoPlayer](https://github.com/shajon-404/iptv/blob/main/app/hooks/useVideoPlayer.ts): hook · Client playback state, stream selection, and controls. · `app/hooks/useVideoPlayer.ts`
- [IPTV API](https://github.com/shajon-404/iptv/tree/main/app/api/iptv): api routes · Core IPTV server boundary for channels, playlists, proxying, and viewers. · `app/api/iptv`
- [Stream proxy](https://github.com/shajon-404/iptv/blob/main/app/api/iptv/proxy/route.ts): api route · Trust boundary for external stream access, CORS, and SSRF-safe fetching. · `app/api/iptv/proxy/route.ts`
- [Viewer tracker](https://github.com/shajon-404/iptv/blob/main/app/components/ViewerTracker.tsx): telemetry · Playback telemetry and viewer reporting. · `app/components/ViewerTracker.tsx`

### Auth and data

Authentication, session state, playlist persistence, and parsing.

- [Login](https://github.com/shajon-404/iptv/blob/main/app/login/page.tsx): next page · Authentication entry page. · `app/login/page.tsx`
- [useIPTVPlaylists](https://github.com/shajon-404/iptv/blob/main/app/hooks/useIPTVPlaylists.ts): hook · Client playlist fetch and sync state. · `app/hooks/useIPTVPlaylists.ts`
- [useAuth](https://github.com/shajon-404/iptv/blob/main/app/hooks/useAuth.tsx): hook · Session-aware auth state on the client. · `app/hooks/useAuth.tsx`
- [Auth API](https://github.com/shajon-404/iptv/tree/main/app/api/auth): api routes · Google OAuth, callback, session lookup, and logout. · `app/api/auth`
- [Prisma DB](https://github.com/shajon-404/iptv/blob/main/app/lib/prisma.ts): persistence · PostgreSQL access via Prisma. · `app/lib/prisma.ts`
- [Auth lib](https://github.com/shajon-404/iptv/blob/main/app/lib/auth.ts): server auth · Shared Google OAuth and session logic. · `app/lib/auth.ts`
- [Playlist parser](https://github.com/shajon-404/iptv/blob/main/app/lib/playlistParser.ts): normalizer · Parses and normalizes M3U and JSON playlist data. · `app/lib/playlistParser.ts`

### Fixtures

Standalone fixtures/bracket feature area.

- [Fixtures page](https://github.com/shajon-404/iptv/blob/main/app/fixtures/page.tsx): next page · Standalone fixtures/bracket entry page. · `app/fixtures/page.tsx`
- [Fixtures client](https://github.com/shajon-404/iptv/blob/main/app/fixtures/FixturesClient.tsx): client feature · Interactive fixtures/bracket UI coordinator. · `app/fixtures/FixturesClient.tsx`
- [useFixtures](https://github.com/shajon-404/iptv/blob/main/app/fixtures/hooks/useFixtures.ts): hook · Fixtures data loading and state. · `app/fixtures/hooks/useFixtures.ts`

## Connections

- Home → IPTV player: loads · Main app shell enters the IPTV player.
- Home → About: nav · Public site content.
- Home → FAQ: nav · Public help content.
- Home → Login: auth · Login entry point.
- Home → Dashboard: nav · Authenticated surface.
- Home → FTP: nav · Adjacent standalone page.
- IPTV player → Channel list: composes · Builds the main browsing UI.
- IPTV player → Playlist manager: composes · Provides playlist controls.
- IPTV player → Sidebar: composes · Renders supporting sidebar.
- IPTV player → Channel stats: composes · Shows viewer and stream stats.
- IPTV player → Video view: composes · Embeds the playback surface.
- useVideoPlayer → Video view: drives · Coordinates player state and playback.
- useIPTVPlaylists → Playlist manager: feeds · Supplies playlist sync state.
- useAuth → Auth API: reads · Consumes session state from auth endpoints.
- Auth API → Auth lib: uses · Shared OAuth and session logic.
- IPTV API → Prisma DB: persists · Stores playlist and related data.
- IPTV API → Playlist parser: normalizes · Converts playlist input into usable records.
- IPTV API → Stream proxy: includes · Stream access boundary.
- Stream proxy → Video view: serves · Proxies external streams to the browser.
- Gate wrapper → Turnstile: wraps · Enforces verification before sensitive actions.
- Gate wrapper → Playlist manager: protects · Gates playlist-related user actions.
- Viewer tracker → IPTV API: reports · Sends playback telemetry.
- Fixtures page → Fixtures client: loads · Entrypoint for the fixtures feature.
- Fixtures client → useFixtures: uses · Fetches and manages fixtures state.