# alparslancevik/occatv architecture

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

- Interactive diagram: https://gitdiagram.com/alparslancevik/occatv
- Repository: https://github.com/alparslancevik/occatv

## Overview

OccaTV is a Windows IPTV and media-center application. A user adds an M3U or Xtream source, the local server builds searchable live/VOD/series libraries, and the interface requests playback through a loopback-only gateway backed by FFmpeg; YouTube uses yt-dlp. Separate branches cover XMLTV guide matching, reminders and recordings, playback controls, and channel health. The sampled server and library code support the core orchestration links; some feature wiring is documented in the README but its handlers were not sampled.

Main entry points: [`src/http-server.mjs`](https://github.com/alparslancevik/occatv/blob/main/src/http-server.mjs) (Local media server), [`desktop/main.cjs`](https://github.com/alparslancevik/occatv/blob/main/desktop/main.cjs) (Electron host), [`public/index.html`](https://github.com/alparslancevik/occatv/blob/main/public/index.html) (Player interface), [`src/library.mjs`](https://github.com/alparslancevik/occatv/blob/main/src/library.mjs) (Channel library)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop and interface"]
  node_electron["Electron host<br/>[main.cjs]"]
  node_ui["Player interface<br/>[index.html]"]
  node_server["Local media server<br/>[http-server.mjs]"]
  node_runner["Server launcher<br/>[server.mjs]"]
end

subgraph group_sources["Source and guide"]
  node_playlist["Playlist config<br/>[config.mjs]"]
  node_library["Channel library<br/>[library.mjs]"]
  node_m3u["M3U parser<br/>[m3u-parser.mjs]"]
  node_xtream["Xtream loader<br/>[xtream.mjs]"]
  node_epg["EPG guide<br/>[epg.mjs]"]
end

subgraph group_playback["Playback services"]
  node_media["Media session<br/>[media-session.mjs]"]
  node_youtube["YouTube resolver<br/>[youtube.mjs]"]
  node_probe["Media probe<br/>[media-probe.mjs]"]
  node_subtitles["Subtitle service<br/>[subtitles.mjs]"]
  node_timeshift["Live buffer<br/>[timeshift.mjs]"]
end

subgraph group_operations["Viewing operations"]
  node_health["Channel health<br/>[health-monitor.mjs]"]
  node_scheduler["Plan scheduler<br/>[scheduler.mjs]"]
  node_recording["Recording service<br/>[recording.mjs]"]
end

node_viewer(("Viewer"))
node_external(("IPTV and EPG sources"))
node_ffmpeg["FFmpeg"]
node_ytdlp["yt-dlp"]
node_userdata[("User data and cache")]

node_viewer -->|"starts app"| node_electron
node_electron -->|"starts server"| node_server
node_electron -->|"loads interface"| node_ui
node_runner -->|"starts server"| node_server
node_ui -->|"requests API"| node_server
node_server -->|"loads config"| node_playlist
node_server -->|"loads sources"| node_library
node_library -->|"parses M3U"| node_m3u
node_library -->|"loads Xtream"| node_xtream
node_external -->|"provides playlists"| node_m3u
node_external -->|"provides account"| node_xtream
node_server -->|"loads guide"| node_epg
node_external -->|"provides XMLTV"| node_epg
node_ui -->|"requests playback"| node_server
node_server -->|"dispatches stream"| node_media
node_media -->|"runs engine"| node_ffmpeg
node_server -->|"resolves link"| node_youtube
node_youtube -->|"runs resolver"| node_ytdlp
node_server -->|"requests details"| node_probe
node_server -->|"serves subtitles"| node_subtitles
node_server -->|"manages buffer"| node_timeshift
node_server -->|"checks channels"| node_health
node_server -->|"manages plans"| node_scheduler
node_server -->|"starts recordings"| node_recording
node_server -->|"reads and writes"| node_userdata
node_epg -->|"caches guide"| node_userdata
node_health -->|"persists results"| node_userdata
node_scheduler -->|"persists schedules"| node_userdata
node_recording -->|"stores recordings"| node_userdata

click node_electron "https://github.com/alparslancevik/occatv/blob/main/desktop/main.cjs"
click node_ui "https://github.com/alparslancevik/occatv/blob/main/public/index.html"
click node_server "https://github.com/alparslancevik/occatv/blob/main/src/http-server.mjs"
click node_runner "https://github.com/alparslancevik/occatv/blob/main/src/server.mjs"
click node_playlist "https://github.com/alparslancevik/occatv/blob/main/src/config.mjs"
click node_library "https://github.com/alparslancevik/occatv/blob/main/src/library.mjs"
click node_m3u "https://github.com/alparslancevik/occatv/blob/main/src/m3u-parser.mjs"
click node_xtream "https://github.com/alparslancevik/occatv/blob/main/src/xtream.mjs"
click node_epg "https://github.com/alparslancevik/occatv/blob/main/src/epg.mjs"
click node_media "https://github.com/alparslancevik/occatv/blob/main/src/media-session.mjs"
click node_youtube "https://github.com/alparslancevik/occatv/blob/main/src/youtube.mjs"
click node_probe "https://github.com/alparslancevik/occatv/blob/main/src/media-probe.mjs"
click node_subtitles "https://github.com/alparslancevik/occatv/blob/main/src/subtitles.mjs"
click node_timeshift "https://github.com/alparslancevik/occatv/blob/main/src/timeshift.mjs"
click node_health "https://github.com/alparslancevik/occatv/blob/main/src/health-monitor.mjs"
click node_scheduler "https://github.com/alparslancevik/occatv/blob/main/src/scheduler.mjs"
click node_recording "https://github.com/alparslancevik/occatv/blob/main/src/recording.mjs"

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_electron,node_ui,node_server,node_runner,node_viewer toneBlue
class node_playlist,node_library,node_m3u,node_xtream,node_epg,node_userdata toneAmber
class node_media,node_youtube,node_probe,node_subtitles,node_timeshift toneMint
class node_health,node_scheduler,node_recording toneRose
class node_external,node_ffmpeg,node_ytdlp toneIndigo
```

## Components

### Desktop and interface

- [Electron host](https://github.com/alparslancevik/occatv/blob/main/desktop/main.cjs): `desktop/main.cjs`
- [Player interface](https://github.com/alparslancevik/occatv/blob/main/public/index.html): `public/index.html`
- [Local media server](https://github.com/alparslancevik/occatv/blob/main/src/http-server.mjs): `src/http-server.mjs`
- [Server launcher](https://github.com/alparslancevik/occatv/blob/main/src/server.mjs): `src/server.mjs`

### Source and guide

- [Playlist config](https://github.com/alparslancevik/occatv/blob/main/src/config.mjs): `src/config.mjs`
- [Channel library](https://github.com/alparslancevik/occatv/blob/main/src/library.mjs): `src/library.mjs`
- [M3U parser](https://github.com/alparslancevik/occatv/blob/main/src/m3u-parser.mjs): `src/m3u-parser.mjs`
- [Xtream loader](https://github.com/alparslancevik/occatv/blob/main/src/xtream.mjs): `src/xtream.mjs`
- [EPG guide](https://github.com/alparslancevik/occatv/blob/main/src/epg.mjs): `src/epg.mjs`

### Playback services

- [Media session](https://github.com/alparslancevik/occatv/blob/main/src/media-session.mjs): `src/media-session.mjs`
- [YouTube resolver](https://github.com/alparslancevik/occatv/blob/main/src/youtube.mjs): `src/youtube.mjs`
- [Media probe](https://github.com/alparslancevik/occatv/blob/main/src/media-probe.mjs): `src/media-probe.mjs`
- [Subtitle service](https://github.com/alparslancevik/occatv/blob/main/src/subtitles.mjs): `src/subtitles.mjs`
- [Live buffer](https://github.com/alparslancevik/occatv/blob/main/src/timeshift.mjs): `src/timeshift.mjs`

### Viewing operations

- [Channel health](https://github.com/alparslancevik/occatv/blob/main/src/health-monitor.mjs): `src/health-monitor.mjs`
- [Plan scheduler](https://github.com/alparslancevik/occatv/blob/main/src/scheduler.mjs): `src/scheduler.mjs`
- [Recording service](https://github.com/alparslancevik/occatv/blob/main/src/recording.mjs): `src/recording.mjs`

### Other components

- **Viewer**
- **IPTV and EPG sources**
- **FFmpeg**
- **yt-dlp**
- **User data and cache**

## Connections

- Viewer → Electron host: starts app
- Electron host → Local media server: starts server
- Electron host → Player interface: loads interface
- Server launcher → Local media server: starts server
- Player interface → Local media server: requests API
- Local media server → Playlist config: loads config
- Local media server → Channel library: loads sources
- Channel library → M3U parser: parses M3U
- Channel library → Xtream loader: loads Xtream
- IPTV and EPG sources → M3U parser: provides playlists
- IPTV and EPG sources → Xtream loader: provides account
- Local media server → EPG guide: loads guide
- IPTV and EPG sources → EPG guide: provides XMLTV
- Player interface → Local media server: requests playback
- Local media server → Media session: dispatches stream
- Media session → FFmpeg: runs engine
- Local media server → YouTube resolver: resolves link
- YouTube resolver → yt-dlp: runs resolver
- Local media server → Media probe: requests details
- Local media server → Subtitle service: serves subtitles
- Local media server → Live buffer: manages buffer
- Local media server → Channel health: checks channels
- Local media server → Plan scheduler: manages plans
- Local media server → Recording service: starts recordings
- Local media server → User data and cache: reads and writes
- EPG guide → User data and cache: caches guide
- Channel health → User data and cache: persists results
- Plan scheduler → User data and cache: persists schedules
- Recording service → User data and cache: stores recordings