# sidh3369/iptv-stremio architecture

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

- Interactive diagram: https://gitdiagram.com/sidh3369/iptv-stremio
- Repository: https://github.com/sidh3369/iptv-stremio

## Overview

##### Project type and purpose
- This is a lightweight Node.js “Stremio Addon” project whose sole job is to serve a manifest and proxy a single video‐stream URL into Stremio.
- It exposes HTTP endpoints (manifest.json and stream URLs) that the Stremio client consumes.

##### File structure
- Top level:
- index.js – the entire application entry point (defines manifest, implements HTTP server, handles video fetch).
- package.json / package-lock.json – Node.js dependencies (likely includes `express` or `stremio-addon-sdk`).
- .gitignore, README.md.
- No separate frontend or database layers: it’s purely a backend HTTP service.

##### README for insights
- Describes how to start the server (`npm start`, `npm run dev`).
- Mentions optional environment variables (.env) for configuration (e.g., `FETCH_TIMEOUT`, stream URL).
- Endpoints:
- GET /manifest.json – provides addon metadata to Stremio
- Subsequent calls (e.g., /stream?video=…) to fetch or proxy the video stream.

##### Main components for the system design
a. Stremio Client (External Consumer)
b. IPTV Stremio Addon Service (Node.js process)
– HTTP Server (Express or built-in HTTP)
– Manifest Generator (builds the JSON manifest)
– Stream Proxy/Fetcher (fetches the video from the configured URL)
– Configuration Loader (reads .env / environment variables)
c. Upstream Video Host (the single external URL or CDN)
d. (Optional) Development Tooling – nodemon for auto‐restart

##### Relationships and data flows
1. Stremio Client → HTTP GET /manifest.json on Addon Service → returns JSON manifest.
2. Stremio Client parses manifest and, when user plays a video, → HTTP GET /stream (or similar) on Addon Service.
3. Addon Service Stream Proxy → fetches video bytes from Upstream Video Host → pipes them back to Stremio Client.

##### Architectural patterns/principles
- Single‐responsibility: only two routes (manifest, stream).
- Stateless HTTP server.
- Configurable via environment (.env).
- Minimal third‐party dependencies to reduce overhead.

##### Technologies/frameworks
- Node.js (v14+) runtime.
- Express or native HTTP for endpoint routing.
- stremio-addon-sdk (if used) for manifest scaffolding.
- dotenv (optional) for environment configuration.
- nodemon (dev only).

## Diagram (Mermaid)

```mermaid
flowchart TD
    classDef external fill:#AED8FF,stroke:#009;
    classDef internal fill:#B3FFB3,stroke:#0A0;
    classDef provider fill:#FFB3B3,stroke:#F00;
    classDef doc fill:#E0B3FF,stroke:#60F;

    StremioClient["Stremio Client"]:::external

    subgraph "IPTV Stremio Addon Service"
        direction TB
        ManifestHandler["Manifest Handler"]:::internal
        StreamProxy["Stream Proxy/Fetcher"]:::internal
        ConfigLoader["Configuration Loader\n(.env)"]:::internal
    end

    UpstreamHost["Upstream Video Host"]:::provider

    subgraph "Project Files"
        direction TB
        PackageNode["package.json"]:::doc
        Readme["README.md"]:::doc
        GitIgnore[".gitignore"]:::doc
    end

    StremioClient -->|GET /manifest.json| ManifestHandler
    ManifestHandler -->|200 OK JSON manifest| StremioClient

    StremioClient -->|GET /stream?video=...| StreamProxy
    StreamProxy -->|fetch video bytes| UpstreamHost
    UpstreamHost -->|video stream| StreamProxy
    StreamProxy -->|stream response| StremioClient

    ConfigLoader -->|env variables| StreamProxy
    ConfigLoader -->|env variables| ManifestHandler

    click ManifestHandler "https://github.com/sidh3369/iptv-stremio/blob/main/index.js"
    click StreamProxy "https://github.com/sidh3369/iptv-stremio/blob/main/index.js"
    click ConfigLoader "https://github.com/sidh3369/iptv-stremio/blob/main/index.js"
    click PackageNode "https://github.com/sidh3369/iptv-stremio/blob/main/package.json"
    click Readme "https://github.com/sidh3369/iptv-stremio/blob/main/README.md"
    click GitIgnore "https://github.com/sidh3369/iptv-stremio/blob/main/.gitignore"
```
