# teagod-s/unbox architecture

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

- Interactive diagram: https://gitdiagram.com/teagod-s/unbox
- Repository: https://github.com/teagod-s/unbox

## Overview

UnBox is a cross-platform IPTV and local-media desktop player. Users import VOD or live sources, browse/search catalogs or scan local folders, then play selected streams with the web player or mpv; viewing history supports resume. The graph also preserves documented playback automation, source management, donations, and the library path. Backend composition links are supported by the shell service’s imports and excerpts; frontend and product-capability links rely on the shown App excerpts and README, since many implementation files were not sampled.

Main entry points: [`internal/shell/service.go`](https://github.com/teagod-s/unbox/blob/master/internal/shell/service.go) (Wails service), [`frontend/src/App.vue`](https://github.com/teagod-s/unbox/blob/master/frontend/src/App.vue) (App workflow), [`internal/provider/tvbox/drpy.go`](https://github.com/teagod-s/unbox/blob/master/internal/provider/tvbox/drpy.go) (TVBox providers), [`internal/library/library.go`](https://github.com/teagod-s/unbox/blob/master/internal/library/library.go) (Media library)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Desktop experience"]
  node_app["App workflow<br/>[App.vue]"]
  node_playview["Web playback<br/>[PlaybackView.vue]"]
  node_tracks["Track controls<br/>[useHlsTracks.ts]"]
  node_automation["Playback automation"]
  node_donation["Donation list<br/>[donation.ts]"]
end

subgraph group_catalog["Sources and catalogs"]
  node_config["Source config<br/>[resolve.go]"]
  node_crawler["JS crawler<br/>[inline.go]"]
  node_tvbox["TVBox providers<br/>[drpy.go]"]
  node_live["Live provider<br/>[live.go]"]
  node_remote(("Source services"))
end

subgraph group_media["Playback and library"]
  node_library["Media library<br/>[library.go]"]
  node_thumb["Poster generation<br/>[thumb.go]"]
  node_playback["Playback routing<br/>[controller.go]"]
  node_proxy["Stream proxy<br/>[proxy.go]"]
  node_player["Player interface<br/>[player.go]"]
  node_mpv["mpv process<br/>[mpvproc.go]"]
  node_mpvmanage["mpv manager<br/>[manager.go]"]
end

subgraph group_platform["App services and state"]
  node_shell["Wails service<br/>[service.go]"]
  node_store[("SQLite state<br/>[store.go]")]
end

node_user(("Viewer"))
node_sqlite[("SQLite database")]

node_user -->|"browses and selects"| node_app
node_app -->|"calls services"| node_shell
node_shell -->|"resolves imports"| node_config
node_config -->|"fetches source data"| node_remote
node_shell -->|"dispatches VOD"| node_tvbox
node_tvbox -.->|"runs JS sites"| node_crawler
node_tvbox -->|"requests catalog"| node_remote
node_shell -->|"loads live source"| node_live
node_live -.->|"loads playlists"| node_remote
node_shell -->|"serves library"| node_library
node_library -->|"reads and writes"| node_store
node_library -->|"generates posters"| node_thumb
node_shell -->|"prepares playback"| node_playback
node_playback -->|"registers web streams"| node_proxy
node_playback -->|"loads mpv streams"| node_player
node_mpvmanage -->|"creates process"| node_mpv
node_shell -->|"manages mpv"| node_mpvmanage
node_playview -->|"uses track state"| node_tracks
node_app -->|"renders playback"| node_playview
node_app -->|"coordinates playback"| node_automation
node_app -->|"shows donors"| node_donation
node_shell -->|"persists app state"| node_store
node_store -.->|"stores records"| node_sqlite

click node_app "https://github.com/teagod-s/unbox/blob/master/frontend/src/App.vue"
click node_playview "https://github.com/teagod-s/unbox/blob/master/frontend/src/components/PlaybackView.vue"
click node_tracks "https://github.com/teagod-s/unbox/blob/master/frontend/src/useHlsTracks.ts"
click node_automation "https://github.com/teagod-s/unbox/blob/master/frontend/src/playbackAutomation.ts"
click node_donation "https://github.com/teagod-s/unbox/blob/master/frontend/src/donation.ts"
click node_shell "https://github.com/teagod-s/unbox/blob/master/internal/shell/service.go"
click node_config "https://github.com/teagod-s/unbox/blob/master/internal/config/resolve.go"
click node_crawler "https://github.com/teagod-s/unbox/blob/master/internal/crawler/inline.go"
click node_tvbox "https://github.com/teagod-s/unbox/blob/master/internal/provider/tvbox/drpy.go"
click node_live "https://github.com/teagod-s/unbox/blob/master/internal/provider/live/live.go"
click node_library "https://github.com/teagod-s/unbox/blob/master/internal/library/library.go"
click node_thumb "https://github.com/teagod-s/unbox/blob/master/internal/library/thumb/thumb.go"
click node_playback "https://github.com/teagod-s/unbox/blob/master/internal/playback/controller.go"
click node_proxy "https://github.com/teagod-s/unbox/blob/master/internal/playback/proxy.go"
click node_player "https://github.com/teagod-s/unbox/blob/master/internal/player/player.go"
click node_mpv "https://github.com/teagod-s/unbox/blob/master/internal/player/mpvproc/mpvproc.go"
click node_mpvmanage "https://github.com/teagod-s/unbox/blob/master/internal/player/mpvplugin/manager.go"
click node_store "https://github.com/teagod-s/unbox/blob/master/internal/store/store.go"

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_playview,node_tracks,node_automation,node_donation,node_user toneBlue
class node_config,node_crawler,node_tvbox,node_live,node_remote,node_sqlite toneAmber
class node_library,node_thumb,node_playback,node_proxy,node_player,node_mpv,node_mpvmanage toneMint
class node_shell,node_store toneRose
```

## Components

### Desktop experience

- [App workflow](https://github.com/teagod-s/unbox/blob/master/frontend/src/App.vue): `frontend/src/App.vue`
- [Web playback](https://github.com/teagod-s/unbox/blob/master/frontend/src/components/PlaybackView.vue): `frontend/src/components/PlaybackView.vue`
- [Track controls](https://github.com/teagod-s/unbox/blob/master/frontend/src/useHlsTracks.ts): `frontend/src/useHlsTracks.ts`
- [Playback automation](https://github.com/teagod-s/unbox/blob/master/frontend/src/playbackAutomation.ts): `frontend/src/playbackAutomation.ts`
- [Donation list](https://github.com/teagod-s/unbox/blob/master/frontend/src/donation.ts): `frontend/src/donation.ts`

### Sources and catalogs

- [Source config](https://github.com/teagod-s/unbox/blob/master/internal/config/resolve.go): `internal/config/resolve.go`
- [JS crawler](https://github.com/teagod-s/unbox/blob/master/internal/crawler/inline.go): `internal/crawler/inline.go`
- [TVBox providers](https://github.com/teagod-s/unbox/blob/master/internal/provider/tvbox/drpy.go): `internal/provider/tvbox/drpy.go`
- [Live provider](https://github.com/teagod-s/unbox/blob/master/internal/provider/live/live.go): `internal/provider/live/live.go`
- **Source services**

### Playback and library

- [Media library](https://github.com/teagod-s/unbox/blob/master/internal/library/library.go): `internal/library/library.go`
- [Poster generation](https://github.com/teagod-s/unbox/blob/master/internal/library/thumb/thumb.go): `internal/library/thumb/thumb.go`
- [Playback routing](https://github.com/teagod-s/unbox/blob/master/internal/playback/controller.go): `internal/playback/controller.go`
- [Stream proxy](https://github.com/teagod-s/unbox/blob/master/internal/playback/proxy.go): `internal/playback/proxy.go`
- [Player interface](https://github.com/teagod-s/unbox/blob/master/internal/player/player.go): `internal/player/player.go`
- [mpv process](https://github.com/teagod-s/unbox/blob/master/internal/player/mpvproc/mpvproc.go): `internal/player/mpvproc/mpvproc.go`
- [mpv manager](https://github.com/teagod-s/unbox/blob/master/internal/player/mpvplugin/manager.go): `internal/player/mpvplugin/manager.go`

### App services and state

- [Wails service](https://github.com/teagod-s/unbox/blob/master/internal/shell/service.go): `internal/shell/service.go`
- [SQLite state](https://github.com/teagod-s/unbox/blob/master/internal/store/store.go): `internal/store/store.go`

### Other components

- **Viewer**
- **SQLite database**

## Connections

- Viewer → App workflow: browses and selects
- App workflow → Wails service: calls services (evidence: `frontend/src/App.vue`)
- Wails service → Source config: resolves imports (evidence: `internal/shell/service.go`)
- Source config → Source services: fetches source data
- Wails service → TVBox providers: dispatches VOD (evidence: `internal/shell/service.go`)
- TVBox providers → JS crawler: runs JS sites
- TVBox providers → Source services: requests catalog (evidence: `internal/provider/tvbox/drpy.go`)
- Wails service → Live provider: loads live source (evidence: `internal/shell/service.go`)
- Live provider → Source services: loads playlists
- Wails service → Media library: serves library (evidence: `internal/shell/service.go`)
- Media library → SQLite state: reads and writes (evidence: `internal/library/library.go`)
- Media library → Poster generation: generates posters (evidence: `internal/library/library.go`)
- Wails service → Playback routing: prepares playback (evidence: `internal/shell/service.go`)
- Playback routing → Stream proxy: registers web streams (evidence: `internal/playback/controller.go`)
- Playback routing → Player interface: loads mpv streams (evidence: `internal/playback/controller.go`)
- mpv manager → mpv process: creates process (evidence: `internal/player/mpvplugin/manager.go`)
- Wails service → mpv manager: manages mpv (evidence: `internal/shell/service.go`)
- Web playback → Track controls: uses track state (evidence: `frontend/src/components/PlaybackView.vue`)
- App workflow → Web playback: renders playback (evidence: `frontend/src/App.vue`)
- App workflow → Playback automation: coordinates playback (evidence: `frontend/src/App.vue`)
- App workflow → Donation list: shows donors (evidence: `frontend/src/App.vue`)
- Wails service → SQLite state: persists app state (evidence: `internal/shell/service.go`)
- SQLite state → SQLite database: stores records
