shajon-404/iptv

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.