# harborstremio/harbor architecture

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

- Interactive diagram: https://gitdiagram.com/harborstremio/harbor
- Repository: https://github.com/harborstremio/harbor

## Overview

#### Purpose and entry points
Harbor is a self-contained desktop/web client for the open Stremio addon ecosystem; it supplies UI, playback, ranking, and local integrations, not media or bundled content addons. The React application starts at `src/main.tsx`, mounts `src/App.tsx`, and routes through `src/router/router.tsx`. Native builds enter through `src-tauri/src/main.rs`; `src-tauri/src/lib.rs` wires Tauri commands and lifecycle services.

#### Application layers and navigation
The TypeScript/React frontend owns rooms, title flows, player UI, state, and remote-service clients. Route-level screens in `src/views/home.tsx`, `src/views/detail.tsx`, and `src/views/player.tsx` compose reusable visual chrome and components. `src/router/index.ts` and `src/router/sync.tsx` form the navigation/deep-link boundary; view code should consume `src/lib` domain modules rather than invoke native or remote APIs ad hoc.

#### Metadata, catalogs, and account integrations
Stremio addon resources provide catalogs, metadata, streams, and subtitles, mediated by `src/lib/stremio.ts`, `src/lib/addons.ts`, and `src/lib/streams/addons.ts`. Provider adapters normalize/enrich external metadata—principally TMDB, Cinemeta, Kitsu/AniZip, ratings/artwork services—under `src/lib/providers/`. Account-specific sync is partitioned by service, e.g. `src/lib/trakt/`, `src/lib/anilist/`, and `src/lib/simkl/`; local settings, profiles, and credentials remain client-side via `src/lib/settings.tsx`, `src/lib/settings/`, and native `src-tauri/src/settings_store.rs`.

#### Stream acquisition and ranking
Pressing play collects addon offers concurrently, resolves/decorates them, then applies parse → trust → score → rank. Frontend orchestration and fallback behavior reside in `src/lib/streams/pipeline.ts`, `src/lib/streams/resolve.ts`, and `src/lib/streams/scoring.ts`. The authoritative pure-Rust engine is `harbor-core/src/lib.rs`, with stages in `harbor-core/src/parser.rs`, `harbor-core/src/trust.rs`, and `harbor-core/src/scoring.rs`; it is compiled to WASM for the UI. Debrid adapters and direct-torrent paths are separate boundaries at `src/lib/debrid/registry.ts`, `src/lib/torrent/local-engine.ts`, and `src-tauri/src/torrent_engine.rs`.

#### Playback and native media boundary
The player route coordinates stream selection, progress, subtitles, casting, party sync, and controls; native invocation is abstracted through `src/lib/player/bridge.ts` and `src/lib/player/mpv.ts`. Rust hosts libmpv and platform rendering in `src-tauri/src/mpv.rs`, `src-tauri/src/mpv_render_linux.rs`, and `src-tauri/src/mpv_render_mac.rs`; HTML5 is an alternative frontend engine in `src/lib/player/html5/`. Native services also expose downloads/transcoding, subtitle extraction/synchronization, local-library scans, and local HTTP/proxy functions through `src-tauri/src/download.rs`, `src-tauri/src/transcode.rs`, `src-tauri/src/subsync/mod.rs`, and `src-tauri/src/web_server.rs`.

#### Live, casting, and synchronized playback
IPTV ingests M3U/Xtream/XMLTV sources, persists playlists, resolves EPG/catch-up, and feeds Live/Multiview views through `src/lib/iptv/ingest/load.ts`, `src/lib/iptv/store.ts`, and `src/views/live.tsx`. LAN casting is implemented natively for Chromecast/DLNA/AirPlay/Roku in `src-tauri/src/cast.rs`, `src-tauri/src/dlna.rs`, and `src-tauri/src/roku.rs`, with HLS/subtitle/transcode support. Together watch parties use frontend protocol/client layers in `src/lib/together/` and deploy/use a user-owned Cloudflare Worker relay at `src-tauri/relay/worker.js`.

#### Runtime, packaging, and infrastructure
Runtime targets are browser and Tauri 2 desktop shells using the system webview; frontend builds use Vite, while Rust handles OS integration. Native sidecars include libmpv, ffmpeg/ffprobe, yt-dlp, and Stremio Server, fetched by `scripts/fetch-*.mjs` into `src-tauri/`. Packaging is defined by `src-tauri/tauri.conf.json`, with platform variants and Flatpak manifests under `flatpak/`. Docker artifacts (`Dockerfile`, `docker-compose.yaml`) support containerized deployment; GitHub workflows build CI, Tauri, Flatpak, and core artifacts.

Main entry points: [`src/views/player.tsx`](https://github.com/harborstremio/harbor/blob/main/src/views/player.tsx) (Primary screens), [`src-tauri/src/lib.rs`](https://github.com/harborstremio/harbor/blob/main/src-tauri/src/lib.rs) (Tauri application), [`src/lib/streams/pipeline.ts`](https://github.com/harborstremio/harbor/blob/main/src/lib/streams/pipeline.ts) (Stream pipeline), [`src/lib/player/bridge.ts`](https://github.com/harborstremio/harbor/blob/main/src/lib/player/bridge.ts) (Player bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React frontend"]
  node_frontend_entry["Frontend entry<br/>React bootstrap<br/>[main.tsx]"]
  node_app_router["App and routes<br/>navigation shell<br/>[router.tsx]"]
  node_screens["Primary screens<br/>route views<br/>[player.tsx]"]
  node_navigation_boundary["Deep-link sync<br/>navigation boundary<br/>[sync.tsx]"]
  node_local_settings[("Settings and profiles<br/>client persistence<br/>[settings.tsx]")]
  node_iptv["IPTV ingest and store<br/>live media subsystem<br/>[load.ts]"]
  node_player_bridge["Player bridge<br/>native media boundary<br/>[bridge.ts]"]
  node_html5_player["HTML5 player<br/>web playback engine"]
  node_together["Together watch party<br/>sync client"]
end

subgraph group_streams["Stream pipeline"]
  node_stremio_client["Stremio resources<br/>addon client<br/>[stremio.ts]"]
  node_metadata_providers["Metadata providers<br/>provider adapters"]
  node_account_sync["Account sync<br/>service integrations"]
  node_stream_pipeline["Stream pipeline<br/>orchestrator<br/>[pipeline.ts]"]
  node_stream_resolver["Offer resolution<br/>stream decorator<br/>[resolve.ts]"]
  node_ranking_engine{{"Ranking engine<br/>Rust/WASM core<br/>[lib.rs]"}}
  node_debrid_torrent["Debrid and torrents<br/>stream transport<br/>[registry.ts]"]
end

subgraph group_native["Tauri native services"]
  node_tauri_entry{{"Tauri application<br/>Rust host<br/>[lib.rs]"}}
  node_mpv_host["libmpv host<br/>native playback<br/>[mpv.rs]"]
  node_native_media_services["Native media services<br/>media utilities<br/>[transcode.rs]"]
  node_casting["LAN casting<br/>native casting<br/>[cast.rs]"]
end

subgraph group_external["External ecosystem"]
  node_party_relay["User-owned party relay<br/>Cloudflare Worker<br/>[worker.js]"]
  node_addon_ecosystem["Stremio addon ecosystem<br/>remote addons"]
  node_external_services["Metadata and account services<br/>remote APIs"]
end

node_frontend_entry -->|"mounts"| node_app_router
node_app_router -->|"renders routes"| node_screens
node_navigation_boundary -->|"syncs navigation"| node_app_router
node_screens -->|"uses domain client"| node_stremio_client
node_screens -->|"requests playable offers"| node_stream_pipeline
node_screens -->|"feeds live views"| node_iptv
node_screens -->|"coordinates playback"| node_player_bridge
node_screens -->|"synchronizes parties"| node_together
node_stremio_client -->|"fetches resources"| node_addon_ecosystem
node_metadata_providers -->|"enriches from"| node_external_services
node_account_sync -->|"syncs with"| node_external_services
node_local_settings -.->|"persists through commands"| node_tauri_entry
node_stream_pipeline -->|"collects offers"| node_stremio_client
node_stream_pipeline -->|"resolves and decorates"| node_stream_resolver
node_stream_resolver -->|"selects transport"| node_debrid_torrent
node_stream_pipeline -->|"ranks via WASM"| node_ranking_engine
node_player_bridge -->|"invokes commands"| node_tauri_entry
node_player_bridge -.->|"can use"| node_html5_player
node_tauri_entry -->|"hosts playback"| node_mpv_host
node_tauri_entry -->|"exposes services"| node_native_media_services
node_tauri_entry -->|"exposes casting"| node_casting
node_together -->|"relays sync protocol"| node_party_relay
node_casting -->|"uses transcode and HLS"| node_native_media_services

click node_frontend_entry "https://github.com/harborstremio/harbor/blob/main/src/main.tsx"
click node_app_router "https://github.com/harborstremio/harbor/blob/main/src/router/router.tsx"
click node_screens "https://github.com/harborstremio/harbor/blob/main/src/views/player.tsx"
click node_navigation_boundary "https://github.com/harborstremio/harbor/blob/main/src/router/sync.tsx"
click node_stremio_client "https://github.com/harborstremio/harbor/blob/main/src/lib/stremio.ts"
click node_local_settings "https://github.com/harborstremio/harbor/blob/main/src/lib/settings.tsx"
click node_stream_pipeline "https://github.com/harborstremio/harbor/blob/main/src/lib/streams/pipeline.ts"
click node_stream_resolver "https://github.com/harborstremio/harbor/blob/main/src/lib/streams/resolve.ts"
click node_ranking_engine "https://github.com/harborstremio/harbor/blob/main/harbor-core/src/lib.rs"
click node_debrid_torrent "https://github.com/harborstremio/harbor/blob/main/src/lib/debrid/registry.ts"
click node_iptv "https://github.com/harborstremio/harbor/blob/main/src/lib/iptv/ingest/load.ts"
click node_player_bridge "https://github.com/harborstremio/harbor/blob/main/src/lib/player/bridge.ts"
click node_tauri_entry "https://github.com/harborstremio/harbor/blob/main/src-tauri/src/lib.rs"
click node_mpv_host "https://github.com/harborstremio/harbor/blob/main/src-tauri/src/mpv.rs"
click node_native_media_services "https://github.com/harborstremio/harbor/blob/main/src-tauri/src/transcode.rs"
click node_casting "https://github.com/harborstremio/harbor/blob/main/src-tauri/src/cast.rs"
click node_party_relay "https://github.com/harborstremio/harbor/blob/main/src-tauri/relay/worker.js"

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_frontend_entry,node_app_router,node_screens,node_navigation_boundary,node_local_settings,node_iptv,node_player_bridge,node_html5_player,node_together toneBlue
class node_stremio_client,node_metadata_providers,node_account_sync,node_stream_pipeline,node_stream_resolver,node_ranking_engine,node_debrid_torrent toneAmber
class node_tauri_entry,node_mpv_host,node_native_media_services,node_casting toneMint
class node_party_relay,node_addon_ecosystem,node_external_services toneRose
```

## Components

### React frontend

Browser and Tauri-webview application layers.

- [Frontend entry](https://github.com/harborstremio/harbor/blob/main/src/main.tsx): React bootstrap · `src/main.tsx`
- [App and routes](https://github.com/harborstremio/harbor/blob/main/src/router/router.tsx): navigation shell · `src/router/router.tsx`
- [Primary screens](https://github.com/harborstremio/harbor/blob/main/src/views/player.tsx): route views · Home, detail, player, and live screens compose the user experience. · `src/views/player.tsx`
- [Deep-link sync](https://github.com/harborstremio/harbor/blob/main/src/router/sync.tsx): navigation boundary · `src/router/sync.tsx`
- [Settings and profiles](https://github.com/harborstremio/harbor/blob/main/src/lib/settings.tsx): client persistence · `src/lib/settings.tsx`
- [IPTV ingest and store](https://github.com/harborstremio/harbor/blob/main/src/lib/iptv/ingest/load.ts): live media subsystem · Loads sources, persists playlists, and resolves EPG/catch-up. · `src/lib/iptv/ingest/load.ts`
- [Player bridge](https://github.com/harborstremio/harbor/blob/main/src/lib/player/bridge.ts): native media boundary · Abstracts native player invocation from route UI. · `src/lib/player/bridge.ts`
- **HTML5 player**: web playback engine · Alternative frontend playback engine.
- **Together watch party**: sync client

### Stream pipeline

Addon acquisition and stream ranking.

- [Stremio resources](https://github.com/harborstremio/harbor/blob/main/src/lib/stremio.ts): addon client · Mediates catalogs, metadata, streams, and subtitles. · `src/lib/stremio.ts`
- **Metadata providers**: provider adapters · Normalizes TMDB, Cinemeta, Kitsu/AniZip, ratings, and artwork.
- **Account sync**: service integrations · Client integrations for Trakt, AniList, and SIMKL.
- [Stream pipeline](https://github.com/harborstremio/harbor/blob/main/src/lib/streams/pipeline.ts): orchestrator · Collects offers concurrently and applies resolution, fallback, and ranking. · `src/lib/streams/pipeline.ts`
- [Offer resolution](https://github.com/harborstremio/harbor/blob/main/src/lib/streams/resolve.ts): stream decorator · `src/lib/streams/resolve.ts`
- [Ranking engine](https://github.com/harborstremio/harbor/blob/main/harbor-core/src/lib.rs): Rust/WASM core · Authoritative pure engine for parse, trust, score, and rank. · `harbor-core/src/lib.rs`
- [Debrid and torrents](https://github.com/harborstremio/harbor/blob/main/src/lib/debrid/registry.ts): stream transport · Debrid adapters and local torrent paths. · `src/lib/debrid/registry.ts`

### Tauri native services

Rust commands, media services, and OS integrations.

- [Tauri application](https://github.com/harborstremio/harbor/blob/main/src-tauri/src/lib.rs): Rust host · Wires commands and lifecycle services. · `src-tauri/src/lib.rs`
- [libmpv host](https://github.com/harborstremio/harbor/blob/main/src-tauri/src/mpv.rs): native playback · Hosts libmpv and platform rendering. · `src-tauri/src/mpv.rs`
- [Native media services](https://github.com/harborstremio/harbor/blob/main/src-tauri/src/transcode.rs): media utilities · Downloads, transcoding, subtitle sync, local HTTP/proxy, and library scans. · `src-tauri/src/transcode.rs`
- [LAN casting](https://github.com/harborstremio/harbor/blob/main/src-tauri/src/cast.rs): native casting · Chromecast, DLNA, AirPlay, and Roku with HLS/subtitle support. · `src-tauri/src/cast.rs`

### External ecosystem

Remote addons, providers, accounts, and party relay.

- [User-owned party relay](https://github.com/harborstremio/harbor/blob/main/src-tauri/relay/worker.js): Cloudflare Worker · `src-tauri/relay/worker.js`
- **Stremio addon ecosystem**: remote addons · Supplies catalogs, metadata, streams, and subtitles.
- **Metadata and account services**: remote APIs

## Connections

- Frontend entry → App and routes: mounts
- App and routes → Primary screens: renders routes
- Deep-link sync → App and routes: syncs navigation
- Primary screens → Stremio resources: uses domain client
- Primary screens → Stream pipeline: requests playable offers
- Primary screens → IPTV ingest and store: feeds live views
- Primary screens → Player bridge: coordinates playback
- Primary screens → Together watch party: synchronizes parties
- Stremio resources → Stremio addon ecosystem: fetches resources
- Metadata providers → Metadata and account services: enriches from
- Account sync → Metadata and account services: syncs with
- Settings and profiles → Tauri application: persists through commands
- Stream pipeline → Stremio resources: collects offers
- Stream pipeline → Offer resolution: resolves and decorates
- Offer resolution → Debrid and torrents: selects transport
- Stream pipeline → Ranking engine: ranks via WASM
- Player bridge → Tauri application: invokes commands
- Player bridge → HTML5 player: can use
- Tauri application → libmpv host: hosts playback
- Tauri application → Native media services: exposes services
- Tauri application → LAN casting: exposes casting
- Together watch party → User-owned party relay: relays sync protocol
- LAN casting → Native media services: uses transcode and HLS