# hcne0/deskflix architecture

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

- Interactive diagram: https://gitdiagram.com/hcne0/deskflix
- Repository: https://github.com/hcne0/deskflix

## Overview

Deskflix is an Electron desktop app for browsing local movie and series libraries and playing them in a custom React player. The main workflow is library selection and scanning, catalog presentation and resume selection, then playback through a local FFmpeg-backed HTTP stream; playback progress is persisted for Continue Watching. The graph includes documented metadata enrichment and player controls. Some IPC handlers and scan details are only partially excerpted, so their relationships are shown only where the excerpts or README support them.

Main entry points: [`electron/main.cjs`](https://github.com/hcne0/deskflix/blob/main/electron/main.cjs) (Desktop and IPC handlers), [`src/Player.jsx`](https://github.com/hcne0/deskflix/blob/main/src/Player.jsx) (Video player), [`src/App.jsx`](https://github.com/hcne0/deskflix/blob/main/src/App.jsx) (Catalog and library UI), [`electron/preload.cjs`](https://github.com/hcne0/deskflix/blob/main/electron/preload.cjs) (IPC bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React experience"]
  node_app["Catalog and library UI<br/>[App.jsx]"]
  node_player["Video player<br/>[Player.jsx]"]
  node_audio["Audio overdrive<br/>[Player.jsx]"]
  node_react_entry["React entry<br/>[main.jsx]"]
end

subgraph group_bridge["Electron bridge"]
  node_preload["IPC bridge<br/>[preload.cjs]"]
  node_electron["Desktop and IPC handlers<br/>[main.cjs]"]
end

subgraph group_media["Media services"]
  node_library_scan["Library scanning<br/>[main.cjs]"]
  node_metadata["TMDB enrichment<br/>[main.cjs]"]
  node_stream["FFmpeg stream server<br/>[main.cjs]"]
end

subgraph group_state["Persistent state"]
  node_store[("Progress and library store<br/>[main.cjs]")]
end

node_user(("Viewer"))
node_ffmpeg["FFmpeg process"]
node_tmdb["TMDB service"]
node_local_media["Local media files"]

node_user -->|"browses"| node_app
node_react_entry -->|"renders"| node_app
node_app -->|"invokes library APIs"| node_preload
node_app -->|"opens playback"| node_player
node_player -->|"requests stream"| node_stream
node_player -->|"routes audio"| node_audio
node_preload -->|"invokes IPC handlers"| node_electron
node_electron -.->|"dispatches scans"| node_library_scan
node_library_scan -->|"reads directories"| node_local_media
node_library_scan -->|"looks up titles"| node_metadata
node_metadata -->|"requests metadata"| node_tmdb
node_electron -->|"loads and saves"| node_store
node_electron -->|"serves stream route"| node_stream
node_stream -->|"reads media"| node_local_media
node_stream -->|"spawns process"| node_ffmpeg
node_preload -->|"saves playback progress"| node_electron
node_player -.->|"saves progress via IPC"| node_store

click node_app "https://github.com/hcne0/deskflix/blob/main/src/App.jsx"
click node_player "https://github.com/hcne0/deskflix/blob/main/src/Player.jsx"
click node_audio "https://github.com/hcne0/deskflix/blob/main/src/Player.jsx"
click node_react_entry "https://github.com/hcne0/deskflix/blob/main/src/main.jsx"
click node_preload "https://github.com/hcne0/deskflix/blob/main/electron/preload.cjs"
click node_electron "https://github.com/hcne0/deskflix/blob/main/electron/main.cjs"
click node_library_scan "https://github.com/hcne0/deskflix/blob/main/electron/main.cjs"
click node_metadata "https://github.com/hcne0/deskflix/blob/main/electron/main.cjs"
click node_stream "https://github.com/hcne0/deskflix/blob/main/electron/main.cjs"
click node_store "https://github.com/hcne0/deskflix/blob/main/electron/main.cjs"

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,node_player,node_audio,node_react_entry,node_user toneBlue
class node_preload,node_electron toneAmber
class node_library_scan,node_metadata,node_stream toneMint
class node_store toneRose
class node_ffmpeg,node_tmdb,node_local_media toneIndigo
```

## Components

### React experience

- [Catalog and library UI](https://github.com/hcne0/deskflix/blob/main/src/App.jsx): `src/App.jsx`
- [Video player](https://github.com/hcne0/deskflix/blob/main/src/Player.jsx): `src/Player.jsx`
- [Audio overdrive](https://github.com/hcne0/deskflix/blob/main/src/Player.jsx): `src/Player.jsx`
- [React entry](https://github.com/hcne0/deskflix/blob/main/src/main.jsx): `src/main.jsx`

### Electron bridge

- [IPC bridge](https://github.com/hcne0/deskflix/blob/main/electron/preload.cjs): `electron/preload.cjs`
- [Desktop and IPC handlers](https://github.com/hcne0/deskflix/blob/main/electron/main.cjs): `electron/main.cjs`

### Media services

- [Library scanning](https://github.com/hcne0/deskflix/blob/main/electron/main.cjs): `electron/main.cjs`
- [TMDB enrichment](https://github.com/hcne0/deskflix/blob/main/electron/main.cjs): `electron/main.cjs`
- [FFmpeg stream server](https://github.com/hcne0/deskflix/blob/main/electron/main.cjs): `electron/main.cjs`

### Persistent state

- [Progress and library store](https://github.com/hcne0/deskflix/blob/main/electron/main.cjs): `electron/main.cjs`

### Other components

- **Viewer**
- **FFmpeg process**
- **TMDB service**
- **Local media files**

## Connections

- Viewer → Catalog and library UI: browses
- React entry → Catalog and library UI: renders (evidence: `src/main.jsx`)
- Catalog and library UI → IPC bridge: invokes library APIs (evidence: `src/App.jsx`)
- Catalog and library UI → Video player: opens playback (evidence: `src/App.jsx`)
- Video player → FFmpeg stream server: requests stream (evidence: `src/Player.jsx`)
- Video player → Audio overdrive: routes audio (evidence: `src/Player.jsx`)
- IPC bridge → Desktop and IPC handlers: invokes IPC handlers (evidence: `electron/preload.cjs`)
- Desktop and IPC handlers → Library scanning: dispatches scans (evidence: `electron/main.cjs`)
- Library scanning → Local media files: reads directories (evidence: `electron/main.cjs`)
- Library scanning → TMDB enrichment: looks up titles (evidence: `electron/main.cjs`)
- TMDB enrichment → TMDB service: requests metadata (evidence: `electron/main.cjs`)
- Desktop and IPC handlers → Progress and library store: loads and saves (evidence: `electron/main.cjs`)
- Desktop and IPC handlers → FFmpeg stream server: serves stream route (evidence: `electron/main.cjs`)
- FFmpeg stream server → Local media files: reads media (evidence: `electron/main.cjs`)
- FFmpeg stream server → FFmpeg process: spawns process (evidence: `electron/main.cjs`)
- IPC bridge → Desktop and IPC handlers: saves playback progress (evidence: `electron/preload.cjs`)
- Video player → Progress and library store: saves progress via IPC
