# antebrl/iptv-restream architecture

> Architecture diagram of the GitHub repository antebrl/iptv-restream, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/antebrl/iptv-restream
- Repository: https://github.com/antebrl/iptv-restream

## Overview

##### Project Type & Purpose
- The project is a full-stack IPTV solution that combines a web-based frontend with a Node.js-powered backend.
- Its purpose is to let users play, proxy, and even restream IPTV channels, complete with synchronization (watch2gether) and live chat. It also offers functionality to safely share streams (privacy mode) and overcome limitations (such as CORS and device restrictions).

##### Core Components to Capture
- Frontend: A React/TypeScript single-page application (SPA) built using Vite. It handles UI elements like channel lists, video playback, chat, notifications, and settings.
- Backend: A Node.js service broken down into clear sub-components:
- Controllers (e.g., ChannelController, ProxyController) which process incoming requests.
- Models (e.g., Channel, ChatMessage, Playlist) for representing application data.
- Services that encapsulate business logic and workflows such as ChannelService, ChatService, PlaylistService, as well as specialized services for proxying and restreaming (using FFmpeg).
- Socket Handlers (e.g., ChannelSocketHandler, ChatSocketHandler) that manage real-time communication for synchronization and live chat.
- Session services that handle session creation and management.
- Deployment & Containerization: Dockerfiles for both frontend and backend along with docker-compose setups. There is also an Nginx deployment component in the “deployment” folder, indicating the presence of a reverse proxy for routing or SSL termination.
- External Integration Components: The system uses FFmpeg (via the backend’s restream service) for handling the caching and restreaming of content. Additionally, components for proxy mode emphasize external HTTP requests and potential custom header setups.

##### Relationships & Data Flow
- The Frontend communicates with the Backend using REST APIs (via ApiService) and WebSockets (via SocketService).
- The Backend routes incoming HTTP requests through its controllers which delegate operations to the relevant services. For example, when a user selects a channel, the ChannelController might engage the Channel/Playlist services.
- The Proxy/Restream services handle media streams. In proxy mode, all stream requests from the frontend are funneled through the backend to bypass CORS and IP restrictions. In restream mode, the FFmpegService engages to cache and push the stream to the client.
- The chat and synchronization features leverage Socket Handlers in the backend and are directly connected to the frontend’s chat components.
- Deployment components (Docker Compose, Nginx) handle container orchestration and external network routing, ensuring that the frontend and backend are properly isolated yet integrated.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The separation between frontend and backend is clear, and even within the backend you have a modular structure separating controllers, models, services, and socket handling.
- Layered Architecture: Typically represented by input (controllers), business logic (services), and persistence (models – though no explicit database is shown, it could be an in-memory data store or external DB).
- Containerization: Using Docker containers with clear demarcation of services (frontend, backend, and Nginx proxy) promotes scalability and easy deployment.
- Proxy and Restreaming: Specific design decisions to manage IPTV streams – handling direct stream access issues and synchronization across multiple client devices.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Subgraph
    subgraph "Frontend"
        F1("Frontend SPA"):::frontend
        F2("VideoPlayer"):::frontend
        F3("ChannelList"):::frontend
        F4("Chat"):::frontend
        F5("Settings"):::frontend
    end
    F1 -->|"contains"| F2
    F1 -->|"contains"| F3
    F1 -->|"contains"| F4
    F1 -->|"contains"| F5

    %% Backend Subgraph
    subgraph "Backend"
        B_API("Backend API"):::backend
        %% Controllers Cluster
        subgraph "Controllers"
            B_CC("ChannelController"):::backend
            B_PC("ProxyController"):::backend
            B_CCC("CentralChannelController"):::backend
        end
        %% Models Cluster
        subgraph "Models"
            B_CM("Channel Model"):::backend
            B_CMM("ChatMessage Model"):::backend
            B_PM("Playlist Model"):::backend
        end
        %% Services Cluster
        subgraph "Services"
            S_CS("ChannelService"):::backend
            S_ChS("ChatService"):::backend
            S_PS("PlaylistService"):::backend
            S_PU("PlaylistUpdater"):::backend
            S_PH("ProxyHelperService"):::backend
            %% Restream Services Subcluster
            subgraph "Restream Services"
                RS_FF("FFmpegService"):::backend
                RS_SC("StreamController"):::backend
                RS_RS("Restream Storage Service"):::backend
            end
            %% Session Management Subcluster
            subgraph "Session Management"
                SM_SF("SessionFactory"):::backend
                SM_SH("SessionHandler"):::backend
                SM_SS("StreamedSuSession"):::backend
            end
        end
        %% Socket Handlers Cluster
        subgraph "Socket Handlers"
            SH_CH("ChannelSocketHandler"):::backend
            SH_CHT("ChatSocketHandler"):::backend
            SH_PS("PlaylistSocketHandler"):::backend
        end
    end

    %% Connections within Backend
    B_API -->|"routes"| B_CC
    B_API -->|"routes"| B_PC
    B_API -->|"routes"| B_CCC

    B_CC -->|"calls"| S_CS
    B_PC -->|"calls"| S_PH
    B_CCC -->|"calls"| S_PS

    S_CS -->|"uses"| B_CM
    S_PS -->|"uses"| B_PM

    SH_CH -->|"talksTo"| S_CS
    SH_CHT -->|"talksTo"| S_ChS
    SH_PS -->|"talksTo"| S_PS

    S_CS -->|"triggers"| RS_FF
    RS_FF -->|"controls"| RS_SC
    RS_SC -->|"storesIn"| RS_RS

    B_API -->|"initiates"| SM_SF
    SM_SF -->|"manages"| SM_SH
    SM_SH -->|"creates"| SM_SS

    %% Communication between Frontend and Backend
    F1 -->|"REST_API"| B_API
    F3 -->|"fetches"| B_API
    F4 -->|"WebSocket"| SH_CHT

    %% Deployment Subgraph
    subgraph "Deployment"
        D_DC("Docker Compose"):::deployment
        D_BD("Backend Dockerfile"):::deployment
        D_FD("Frontend Dockerfile"):::deployment
        D_NGINX("Nginx Reverse Proxy"):::deployment
    end
    D_DC --> D_BD
    D_DC --> D_FD
    D_DC --> D_NGINX
    D_NGINX -->|"routes"| B_API

    %% Click Events for Frontend Components
    click F1 "https://github.com/antebrl/iptv-restream/tree/main/frontend/"
    click F2 "https://github.com/antebrl/iptv-restream/blob/main/frontend/src/components/VideoPlayer.tsx"
    click F3 "https://github.com/antebrl/iptv-restream/blob/main/frontend/src/components/ChannelList.tsx"
    click F4 "https://github.com/antebrl/iptv-restream/blob/main/frontend/src/components/chat/Chat.tsx"
    click F5 "https://github.com/antebrl/iptv-restream/blob/main/frontend/src/components/SettingsModal.tsx"

    %% Click Events for Backend Components
    click B_API "https://github.com/antebrl/iptv-restream/blob/main/backend/server.js"
    click B_CC "https://github.com/antebrl/iptv-restream/blob/main/backend/controllers/ChannelController.js"
    click B_PC "https://github.com/antebrl/iptv-restream/blob/main/backend/controllers/ProxyController.js"
    click B_CCC "https://github.com/antebrl/iptv-restream/blob/main/backend/controllers/CentralChannelController.js"
    click B_CM "https://github.com/antebrl/iptv-restream/blob/main/backend/models/Channel.js"
    click B_CMM "https://github.com/antebrl/iptv-restream/blob/main/backend/models/ChatMessage.js"
    click B_PM "https://github.com/antebrl/iptv-restream/blob/main/backend/models/Playlist.js"
    click S_CS "https://github.com/antebrl/iptv-restream/blob/main/backend/services/ChannelService.js"
    click S_ChS "https://github.com/antebrl/iptv-restream/blob/main/backend/services/ChatService.js"
    click S_PS "https://github.com/antebrl/iptv-restream/blob/main/backend/services/PlaylistService.js"
    click S_PU "https://github.com/antebrl/iptv-restream/blob/main/backend/services/PlaylistUpdater.js"
    click S_PH "https://github.com/antebrl/iptv-restream/blob/main/backend/services/proxy/ProxyHelperService.js"
    click RS_FF "https://github.com/antebrl/iptv-restream/blob/main/backend/services/restream/FFmpegService.js"
    click RS_SC "https://github.com/antebrl/iptv-restream/blob/main/backend/services/restream/StreamController.js"
    click RS_RS "https://github.com/antebrl/iptv-restream/blob/main/backend/services/restream/StorageService.js"
    click SM_SF "https://github.com/antebrl/iptv-restream/blob/main/backend/services/session/SessionFactory.js"
    click SM_SH "https://github.com/antebrl/iptv-restream/blob/main/backend/services/session/SessionHandler.js"
    click SM_SS "https://github.com/antebrl/iptv-restream/blob/main/backend/services/session/StreamedSuSession.js"
    click SH_CH "https://github.com/antebrl/iptv-restream/blob/main/backend/socket/ChannelSocketHandler.js"
    click SH_CHT "https://github.com/antebrl/iptv-restream/blob/main/backend/socket/ChatSocketHandler.js"
    click SH_PS "https://github.com/antebrl/iptv-restream/blob/main/backend/socket/PlaylistSocketHandler.js"

    %% Click Events for Deployment Components
    click D_DC "https://github.com/antebrl/iptv-restream/blob/main/deployment/docker-compose.yml"
    click D_BD "https://github.com/antebrl/iptv-restream/tree/main/backend/Dockerfile"
    click D_FD "https://github.com/antebrl/iptv-restream/tree/main/frontend/Dockerfile"
    click D_NGINX "https://github.com/antebrl/iptv-restream/tree/main/deployment/nginx/"

    %% Styling for Color Coding
    classDef frontend fill:#d1e7dd,stroke:#0f5132,stroke-width:2px;
    classDef backend fill:#f8d7da,stroke:#842029,stroke-width:2px;
    classDef deployment fill:#cff4fc,stroke:#055160,stroke-width:2px;
```
