# 4gray/iptvnator architecture

> Architecture diagram of the GitHub repository 4gray/iptvnator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/4gray/iptvnator
- Repository: https://github.com/4gray/iptvnator

## Overview

IPTVnator is a cross-platform IPTV player. The principal workflow is: a viewer opens the workspace, selects or imports a playlist/provider, the application acquires and stores catalog data, and the viewer browses a channel or VOD item before playing it inline, externally, or through embedded MPV. EPG ingestion and querying, downloads, favorites/history, search, and metadata enrichment are important supporting stages. Some feature implementations are represented by their exact enclosing paths because only partial source excerpts were available.

Main entry points: [`libs/portal`](https://github.com/4gray/iptvnator/tree/master/libs/portal) (Workspace Shell), [`apps/electron-backend/src/app/database/operations`](https://github.com/4gray/iptvnator/tree/master/apps/electron-backend/src/app/database/operations) (Catalog Operations), [`libs/portal/xtream/feature/src/lib/xtream-workspace-route-session.service.ts`](https://github.com/4gray/iptvnator/blob/master/libs/portal/xtream/feature/src/lib/xtream-workspace-route-session.service.ts) (Xtream Session), [`libs/portal/stalker/data-access/src/lib/stalker-session.service.ts`](https://github.com/4gray/iptvnator/blob/master/libs/portal/stalker/data-access/src/lib/stalker-session.service.ts) (Stalker Session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client Navigation"]
  node_app_routes["Workspace Routes<br/>[app.routes.ts]"]
  node_workspace["Workspace Shell"]
end

subgraph group_providers["Providers &amp; Catalog"]
  node_m3u_sources["M3U Sources"]
  node_xtream_session["Xtream Session"]
  node_stalker_session["Stalker Session"]
  node_catalog_ops["Catalog Operations"]
  node_search_metadata["Search Metadata"]
  node_tmdb["TMDB Enrichment<br/>[tmdb.operations.ts]"]
end

subgraph group_guideplayback["Guide &amp; Playback"]
  node_epg_fetch["EPG Fetching"]
  node_epg_worker["EPG Parser Worker"]
  node_epg_query["EPG Guide Queries"]
  node_player_controller["Embedded MPV Session"]
  node_mpv_backend["Embedded MPV Backend"]
  node_stalker_playback["Stalker VOD Playback"]
  node_playback_context["Playback Context"]
end

subgraph group_persistence["Persistence &amp; Offline"]
  node_catalog_db[("Catalog Database<br/>[schema.ts]")]
  node_epg_store[("EPG Data<br/>[schema.ts]")]
  node_downloads["Download Actions"]
  node_download_runtime["Download Runtime"]
  node_favorites_history["Favorites History"]
end

node_viewer(("Viewer"))
node_iptv_provider["IPTV Provider"]
node_native_mpv["Native MPV"]
node_metadata_service["TMDB Service"]

node_viewer -->|"opens workspace"| node_app_routes
node_app_routes -->|"loads routes"| node_workspace
node_workspace -->|"imports playlists"| node_m3u_sources
node_workspace -->|"syncs route"| node_xtream_session
node_workspace -->|"starts session"| node_stalker_session
node_m3u_sources -->|"imports catalog"| node_catalog_ops
node_xtream_session -.->|"fetches catalog"| node_iptv_provider
node_stalker_session -.->|"authenticates"| node_iptv_provider
node_xtream_session -->|"loads catalog"| node_catalog_ops
node_stalker_session -->|"loads catalog"| node_catalog_ops
node_catalog_ops -->|"reads and writes"| node_catalog_db
node_epg_fetch -->|"starts parsing"| node_epg_worker
node_epg_worker -->|"writes EPG"| node_epg_store
node_epg_query -->|"reads EPG"| node_epg_store
node_workspace -->|"requests guide"| node_epg_query
node_player_controller -->|"creates session"| node_mpv_backend
node_mpv_backend -->|"controls playback"| node_native_mpv
node_stalker_playback -->|"stores credentials"| node_playback_context
node_stalker_playback -->|"starts playback"| node_player_controller
node_downloads -->|"controls downloads"| node_download_runtime
node_download_runtime -->|"persists state"| node_catalog_db
node_workspace -->|"searches catalog"| node_search_metadata
node_workspace -->|"updates history"| node_favorites_history
node_tmdb -.->|"requests metadata"| node_metadata_service
node_tmdb -->|"stores enrichment"| node_catalog_db

click node_app_routes "https://github.com/4gray/iptvnator/blob/master/apps/web/src/app/app.routes.ts"
click node_workspace "https://github.com/4gray/iptvnator/tree/master/libs/portal"
click node_m3u_sources "https://github.com/4gray/iptvnator/blob/master/apps/electron-backend/src/app/events/m3u-source-probe.ts"
click node_xtream_session "https://github.com/4gray/iptvnator/blob/master/libs/portal/xtream/feature/src/lib/xtream-workspace-route-session.service.ts"
click node_stalker_session "https://github.com/4gray/iptvnator/blob/master/libs/portal/stalker/data-access/src/lib/stalker-session.service.ts"
click node_catalog_ops "https://github.com/4gray/iptvnator/tree/master/apps/electron-backend/src/app/database/operations"
click node_catalog_db "https://github.com/4gray/iptvnator/blob/master/apps/electron-backend/src/app/database/schema.ts"
click node_epg_fetch "https://github.com/4gray/iptvnator/blob/master/apps/electron-backend/src/app/events/epg-fetch.service.ts"
click node_epg_worker "https://github.com/4gray/iptvnator/blob/master/apps/electron-backend/src/app/workers/epg-parser.worker.ts"
click node_epg_query "https://github.com/4gray/iptvnator/blob/master/apps/electron-backend/src/app/events/epg-guide-query.service.ts"
click node_epg_store "https://github.com/4gray/iptvnator/blob/master/apps/electron-backend/src/app/database/schema.ts"
click node_player_controller "https://github.com/4gray/iptvnator/blob/master/libs/ui/playback/src/lib/embedded-mpv-player/embedded-mpv-session-controller.ts"
click node_mpv_backend "https://github.com/4gray/iptvnator/blob/master/apps/electron-backend/src/app/events/embedded-mpv.events.ts"
click node_native_mpv "https://github.com/4gray/iptvnator/blob/master/apps/electron-backend/native/src/embedded_mpv_linux.cc"
click node_stalker_playback "https://github.com/4gray/iptvnator/blob/master/libs/portal/stalker/feature/src/lib/stalker-collection-playback.controller.ts"
click node_playback_context "https://github.com/4gray/iptvnator/blob/master/apps/electron-backend/src/app/services/stalker-playback-context.service.ts"
click node_downloads "https://github.com/4gray/iptvnator/blob/master/libs/portal/downloads/feature/src/lib/download-manager-actions.service.ts"
click node_download_runtime "https://github.com/4gray/iptvnator/blob/master/apps/electron-backend/src/app/events/database/download-runtime.ts"
click node_search_metadata "https://github.com/4gray/iptvnator/blob/master/apps/electron-backend/src/app/database/operations/content-search.util.ts"
click node_favorites_history "https://github.com/4gray/iptvnator/blob/master/apps/electron-backend/src/app/database/operations/favorites.operations.ts"
click node_tmdb "https://github.com/4gray/iptvnator/blob/master/apps/electron-backend/src/app/database/operations/tmdb.operations.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_app_routes,node_workspace,node_viewer toneBlue
class node_m3u_sources,node_xtream_session,node_stalker_session,node_catalog_ops,node_search_metadata,node_tmdb toneAmber
class node_epg_fetch,node_epg_worker,node_epg_query,node_player_controller,node_mpv_backend,node_stalker_playback,node_playback_context toneMint
class node_catalog_db,node_epg_store,node_downloads,node_download_runtime,node_favorites_history toneRose
class node_iptv_provider,node_metadata_service toneIndigo
class node_native_mpv toneTeal
```

## Components

### Client Navigation

- [Workspace Routes](https://github.com/4gray/iptvnator/blob/master/apps/web/src/app/app.routes.ts): `apps/web/src/app/app.routes.ts`
- [Workspace Shell](https://github.com/4gray/iptvnator/tree/master/libs/portal): `libs/portal`

### Providers & Catalog

- [M3U Sources](https://github.com/4gray/iptvnator/blob/master/apps/electron-backend/src/app/events/m3u-source-probe.ts): `apps/electron-backend/src/app/events/m3u-source-probe.ts`
- [Xtream Session](https://github.com/4gray/iptvnator/blob/master/libs/portal/xtream/feature/src/lib/xtream-workspace-route-session.service.ts): `libs/portal/xtream/feature/src/lib/xtream-workspace-route-session.service.ts`
- [Stalker Session](https://github.com/4gray/iptvnator/blob/master/libs/portal/stalker/data-access/src/lib/stalker-session.service.ts): `libs/portal/stalker/data-access/src/lib/stalker-session.service.ts`
- [Catalog Operations](https://github.com/4gray/iptvnator/tree/master/apps/electron-backend/src/app/database/operations): `apps/electron-backend/src/app/database/operations`
- [Search Metadata](https://github.com/4gray/iptvnator/blob/master/apps/electron-backend/src/app/database/operations/content-search.util.ts): `apps/electron-backend/src/app/database/operations/content-search.util.ts`
- [TMDB Enrichment](https://github.com/4gray/iptvnator/blob/master/apps/electron-backend/src/app/database/operations/tmdb.operations.ts): `apps/electron-backend/src/app/database/operations/tmdb.operations.ts`

### Guide & Playback

- [EPG Fetching](https://github.com/4gray/iptvnator/blob/master/apps/electron-backend/src/app/events/epg-fetch.service.ts): `apps/electron-backend/src/app/events/epg-fetch.service.ts`
- [EPG Parser Worker](https://github.com/4gray/iptvnator/blob/master/apps/electron-backend/src/app/workers/epg-parser.worker.ts): `apps/electron-backend/src/app/workers/epg-parser.worker.ts`
- [EPG Guide Queries](https://github.com/4gray/iptvnator/blob/master/apps/electron-backend/src/app/events/epg-guide-query.service.ts): `apps/electron-backend/src/app/events/epg-guide-query.service.ts`
- [Embedded MPV Session](https://github.com/4gray/iptvnator/blob/master/libs/ui/playback/src/lib/embedded-mpv-player/embedded-mpv-session-controller.ts): `libs/ui/playback/src/lib/embedded-mpv-player/embedded-mpv-session-controller.ts`
- [Embedded MPV Backend](https://github.com/4gray/iptvnator/blob/master/apps/electron-backend/src/app/events/embedded-mpv.events.ts): `apps/electron-backend/src/app/events/embedded-mpv.events.ts`
- [Stalker VOD Playback](https://github.com/4gray/iptvnator/blob/master/libs/portal/stalker/feature/src/lib/stalker-collection-playback.controller.ts): `libs/portal/stalker/feature/src/lib/stalker-collection-playback.controller.ts`
- [Playback Context](https://github.com/4gray/iptvnator/blob/master/apps/electron-backend/src/app/services/stalker-playback-context.service.ts): `apps/electron-backend/src/app/services/stalker-playback-context.service.ts`

### Persistence & Offline

- [Catalog Database](https://github.com/4gray/iptvnator/blob/master/apps/electron-backend/src/app/database/schema.ts): `apps/electron-backend/src/app/database/schema.ts`
- [EPG Data](https://github.com/4gray/iptvnator/blob/master/apps/electron-backend/src/app/database/schema.ts): `apps/electron-backend/src/app/database/schema.ts`
- [Download Actions](https://github.com/4gray/iptvnator/blob/master/libs/portal/downloads/feature/src/lib/download-manager-actions.service.ts): `libs/portal/downloads/feature/src/lib/download-manager-actions.service.ts`
- [Download Runtime](https://github.com/4gray/iptvnator/blob/master/apps/electron-backend/src/app/events/database/download-runtime.ts): `apps/electron-backend/src/app/events/database/download-runtime.ts`
- [Favorites History](https://github.com/4gray/iptvnator/blob/master/apps/electron-backend/src/app/database/operations/favorites.operations.ts): `apps/electron-backend/src/app/database/operations/favorites.operations.ts`

### Other components

- **Viewer**
- **IPTV Provider**
- [Native MPV](https://github.com/4gray/iptvnator/blob/master/apps/electron-backend/native/src/embedded_mpv_linux.cc): `apps/electron-backend/native/src/embedded_mpv_linux.cc`
- **TMDB Service**

## Connections

- Viewer → Workspace Routes: opens workspace
- Workspace Routes → Workspace Shell: loads routes
- Workspace Shell → M3U Sources: imports playlists
- Workspace Shell → Xtream Session: syncs route
- Workspace Shell → Stalker Session: starts session
- M3U Sources → Catalog Operations: imports catalog
- Xtream Session → IPTV Provider: fetches catalog
- Stalker Session → IPTV Provider: authenticates
- Xtream Session → Catalog Operations: loads catalog
- Stalker Session → Catalog Operations: loads catalog
- Catalog Operations → Catalog Database: reads and writes
- EPG Fetching → EPG Parser Worker: starts parsing
- EPG Parser Worker → EPG Data: writes EPG
- EPG Guide Queries → EPG Data: reads EPG
- Workspace Shell → EPG Guide Queries: requests guide
- Embedded MPV Session → Embedded MPV Backend: creates session
- Embedded MPV Backend → Native MPV: controls playback
- Stalker VOD Playback → Playback Context: stores credentials
- Stalker VOD Playback → Embedded MPV Session: starts playback
- Download Actions → Download Runtime: controls downloads
- Download Runtime → Catalog Database: persists state
- Workspace Shell → Search Metadata: searches catalog
- Workspace Shell → Favorites History: updates history
- TMDB Enrichment → TMDB Service: requests metadata
- TMDB Enrichment → Catalog Database: stores enrichment
