# bariskisir/magnetplayer architecture

> Architecture diagram of the GitHub repository bariskisir/magnetplayer, 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/bariskisir/magnetplayer
- Repository: https://github.com/bariskisir/magnetplayer

## Overview

Magnet Player is a browser torrent-media player backed by a local Node helper. The main flow is: add or search for a magnet, open a torrent through the helper, select a media file, and play it while pieces download. The browser also keeps library, progress, preferences, and subtitle state. The helper exposes torrent, media, and search functionality, with torrent storage and optional transcoding beneath its HTTP routes. The graph follows the supplied tree and sampled source; links for unsampled route and subtitle internals are omitted where their wiring is unclear.

Main entry points: [`apps/web/src/app/App.tsx`](https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/app/App.tsx) (App shell), [`apps/web/src/features/library/useLibrary.ts`](https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/features/library/useLibrary.ts) (Library workflow), [`packages/helper/src/torrent/engine.ts`](https://github.com/bariskisir/magnetplayer/blob/master/packages/helper/src/torrent/engine.ts) (Torrent engine), [`packages/helper/src/http/server.ts`](https://github.com/bariskisir/magnetplayer/blob/master/packages/helper/src/http/server.ts) (HTTP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Browser app"]
  node_app["App shell<br/>[App.tsx]"]
  node_library["Library workflow<br/>[useLibrary.ts]"]
  node_library_ui["Library controls<br/>[Sidebar.tsx]"]
  node_magnet_form["Magnet entry<br/>[MagnetForm.tsx]"]
  node_torrent_session["Session client"]
  node_helper_transport["Helper transport<br/>[transport.ts]"]
  node_web_storage[("Browser database<br/>[database.ts]")]
  node_library_storage["Library storage<br/>[storage.ts]"]
end

subgraph group_helper_http["Helper HTTP"]
  node_helper_process["Helper startup<br/>[run.ts]"]
  node_http_server["HTTP server<br/>[server.ts]"]
  node_api_routes["API routes<br/>[api.ts]"]
  node_media_routes["Media routes<br/>[media.ts]"]
end

subgraph group_torrent["Torrent runtime"]
  node_torrent_engine["Torrent engine<br/>[engine.ts]"]
  node_piece_store[("Piece store<br/>[piece-store.ts]")]
  node_disk_files["Torrent files<br/>[files.ts]"]
end

subgraph group_media["Media features"]
  node_player["Player panel<br/>[PlayerPanel.tsx]"]
  node_playback["Playback control<br/>[usePlayback.ts]"]
  node_subtitle_lookup["Subtitle lookup<br/>[lookup.ts]"]
  node_subtitle_overlay["Subtitle overlay"]
  node_subtitle_storage["Subtitle cache<br/>[storage.ts]"]
  node_transcoder["Transcoder<br/>[transcoder.ts]"]
  node_hls["HLS support<br/>[hls.ts]"]
end

subgraph group_search["Search"]
  node_online_search["Online search UI"]
  node_web_search_providers["Search providers"]
  node_search_route["Search API<br/>[index.ts]"]
  node_search_providers["Torrent providers<br/>[knaben.ts]"]
end

node_user(("Viewer"))
node_peers(("Torrent peers"))
node_external_search(("Search services"))

node_user -->|"uses"| node_app
node_app -->|"manages"| node_library
node_app -->|"renders"| node_magnet_form
node_app -->|"renders"| node_library_ui
node_app -->|"renders"| node_online_search
node_app -->|"renders"| node_player
node_magnet_form -->|"submits magnet"| node_library
node_library_ui -->|"selects titles"| node_library
node_online_search -->|"searches"| node_web_search_providers
node_online_search -->|"adds results"| node_library
node_library -->|"opens session"| node_torrent_session
node_library -->|"persists entries"| node_library_storage
node_library_storage -->|"reads and writes"| node_web_storage
node_torrent_session -->|"sends requests"| node_helper_transport
node_player -->|"controls playback"| node_playback
node_playback -->|"selects and seeks"| node_torrent_session
node_subtitle_lookup -->|"uses cache"| node_subtitle_storage
node_subtitle_storage -->|"reads and writes"| node_web_storage
node_helper_process -->|"starts"| node_http_server
node_helper_transport -->|"calls API"| node_http_server
node_http_server -->|"dispatches API"| node_api_routes
node_http_server -->|"dispatches media"| node_media_routes
node_api_routes -->|"controls torrents"| node_torrent_engine
node_media_routes -->|"reads media"| node_torrent_engine
node_media_routes -->|"requests conversion"| node_transcoder
node_transcoder -->|"creates streams"| node_hls
node_torrent_engine -->|"stores pieces"| node_piece_store
node_torrent_engine -->|"loads metadata"| node_disk_files
node_torrent_engine -->|"downloads pieces"| node_peers
node_api_routes -->|"dispatches search"| node_search_route
node_search_route -->|"queries providers"| node_search_providers
node_search_providers -.->|"searches externally"| node_external_search

click node_app "https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/app/App.tsx"
click node_library "https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/features/library/useLibrary.ts"
click node_library_ui "https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/features/library/Sidebar.tsx"
click node_magnet_form "https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/features/library/MagnetForm.tsx"
click node_online_search "https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/features/library/OnlineSearchDialog.tsx"
click node_web_search_providers "https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/shared/search-providers.ts"
click node_torrent_session "https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/features/helper/useTorrentSession.ts"
click node_helper_transport "https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/features/helper/transport.ts"
click node_player "https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/features/player/PlayerPanel.tsx"
click node_playback "https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/features/player/usePlayback.ts"
click node_subtitle_lookup "https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/features/subtitles/lookup.ts"
click node_subtitle_overlay "https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/features/subtitles/useSubtitleOverlay.ts"
click node_web_storage "https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/shared/storage/database.ts"
click node_library_storage "https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/features/library/storage.ts"
click node_subtitle_storage "https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/features/subtitles/storage.ts"
click node_helper_process "https://github.com/bariskisir/magnetplayer/blob/master/packages/helper/src/cli/run.ts"
click node_http_server "https://github.com/bariskisir/magnetplayer/blob/master/packages/helper/src/http/server.ts"
click node_api_routes "https://github.com/bariskisir/magnetplayer/blob/master/packages/helper/src/http/api.ts"
click node_media_routes "https://github.com/bariskisir/magnetplayer/blob/master/packages/helper/src/http/media.ts"
click node_torrent_engine "https://github.com/bariskisir/magnetplayer/blob/master/packages/helper/src/torrent/engine.ts"
click node_piece_store "https://github.com/bariskisir/magnetplayer/blob/master/packages/helper/src/storage/piece-store.ts"
click node_disk_files "https://github.com/bariskisir/magnetplayer/blob/master/packages/helper/src/storage/files.ts"
click node_transcoder "https://github.com/bariskisir/magnetplayer/blob/master/packages/helper/src/media/transcoder.ts"
click node_hls "https://github.com/bariskisir/magnetplayer/blob/master/packages/helper/src/media/hls.ts"
click node_search_route "https://github.com/bariskisir/magnetplayer/blob/master/packages/helper/src/http/search/index.ts"
click node_search_providers "https://github.com/bariskisir/magnetplayer/blob/master/packages/helper/src/http/search/providers/knaben.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,node_library,node_library_ui,node_magnet_form,node_torrent_session,node_helper_transport,node_web_storage,node_library_storage,node_user toneBlue
class node_helper_process,node_http_server,node_api_routes,node_media_routes toneAmber
class node_torrent_engine,node_piece_store,node_disk_files toneMint
class node_player,node_playback,node_subtitle_lookup,node_subtitle_overlay,node_subtitle_storage,node_transcoder,node_hls toneRose
class node_online_search,node_web_search_providers,node_search_route,node_search_providers,node_peers,node_external_search toneIndigo
```

## Components

### Browser app

- [App shell](https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/app/App.tsx): `apps/web/src/app/App.tsx`
- [Library workflow](https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/features/library/useLibrary.ts): `apps/web/src/features/library/useLibrary.ts`
- [Library controls](https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/features/library/Sidebar.tsx): `apps/web/src/features/library/Sidebar.tsx`
- [Magnet entry](https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/features/library/MagnetForm.tsx): `apps/web/src/features/library/MagnetForm.tsx`
- [Session client](https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/features/helper/useTorrentSession.ts): `apps/web/src/features/helper/useTorrentSession.ts`
- [Helper transport](https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/features/helper/transport.ts): `apps/web/src/features/helper/transport.ts`
- [Browser database](https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/shared/storage/database.ts): `apps/web/src/shared/storage/database.ts`
- [Library storage](https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/features/library/storage.ts): `apps/web/src/features/library/storage.ts`

### Helper HTTP

- [Helper startup](https://github.com/bariskisir/magnetplayer/blob/master/packages/helper/src/cli/run.ts): `packages/helper/src/cli/run.ts`
- [HTTP server](https://github.com/bariskisir/magnetplayer/blob/master/packages/helper/src/http/server.ts): `packages/helper/src/http/server.ts`
- [API routes](https://github.com/bariskisir/magnetplayer/blob/master/packages/helper/src/http/api.ts): `packages/helper/src/http/api.ts`
- [Media routes](https://github.com/bariskisir/magnetplayer/blob/master/packages/helper/src/http/media.ts): `packages/helper/src/http/media.ts`

### Torrent runtime

- [Torrent engine](https://github.com/bariskisir/magnetplayer/blob/master/packages/helper/src/torrent/engine.ts): `packages/helper/src/torrent/engine.ts`
- [Piece store](https://github.com/bariskisir/magnetplayer/blob/master/packages/helper/src/storage/piece-store.ts): `packages/helper/src/storage/piece-store.ts`
- [Torrent files](https://github.com/bariskisir/magnetplayer/blob/master/packages/helper/src/storage/files.ts): `packages/helper/src/storage/files.ts`

### Media features

- [Player panel](https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/features/player/PlayerPanel.tsx): `apps/web/src/features/player/PlayerPanel.tsx`
- [Playback control](https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/features/player/usePlayback.ts): `apps/web/src/features/player/usePlayback.ts`
- [Subtitle lookup](https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/features/subtitles/lookup.ts): `apps/web/src/features/subtitles/lookup.ts`
- [Subtitle overlay](https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/features/subtitles/useSubtitleOverlay.ts): `apps/web/src/features/subtitles/useSubtitleOverlay.ts`
- [Subtitle cache](https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/features/subtitles/storage.ts): `apps/web/src/features/subtitles/storage.ts`
- [Transcoder](https://github.com/bariskisir/magnetplayer/blob/master/packages/helper/src/media/transcoder.ts): `packages/helper/src/media/transcoder.ts`
- [HLS support](https://github.com/bariskisir/magnetplayer/blob/master/packages/helper/src/media/hls.ts): `packages/helper/src/media/hls.ts`

### Search

- [Online search UI](https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/features/library/OnlineSearchDialog.tsx): `apps/web/src/features/library/OnlineSearchDialog.tsx`
- [Search providers](https://github.com/bariskisir/magnetplayer/blob/master/apps/web/src/shared/search-providers.ts): `apps/web/src/shared/search-providers.ts`
- [Search API](https://github.com/bariskisir/magnetplayer/blob/master/packages/helper/src/http/search/index.ts): `packages/helper/src/http/search/index.ts`
- [Torrent providers](https://github.com/bariskisir/magnetplayer/blob/master/packages/helper/src/http/search/providers/knaben.ts): `packages/helper/src/http/search/providers/knaben.ts`

### Other components

- **Viewer**
- **Torrent peers**
- **Search services**

## Connections

- Viewer → App shell: uses
- App shell → Library workflow: manages
- App shell → Magnet entry: renders
- App shell → Library controls: renders
- App shell → Online search UI: renders
- App shell → Player panel: renders
- Magnet entry → Library workflow: submits magnet
- Library controls → Library workflow: selects titles
- Online search UI → Search providers: searches
- Online search UI → Library workflow: adds results
- Library workflow → Session client: opens session
- Library workflow → Library storage: persists entries
- Library storage → Browser database: reads and writes
- Session client → Helper transport: sends requests
- Player panel → Playback control: controls playback
- Playback control → Session client: selects and seeks
- Subtitle lookup → Subtitle cache: uses cache
- Subtitle cache → Browser database: reads and writes
- Helper startup → HTTP server: starts
- Helper transport → HTTP server: calls API
- HTTP server → API routes: dispatches API
- HTTP server → Media routes: dispatches media
- API routes → Torrent engine: controls torrents
- Media routes → Torrent engine: reads media
- Media routes → Transcoder: requests conversion
- Transcoder → HLS support: creates streams
- Torrent engine → Piece store: stores pieces
- Torrent engine → Torrent files: loads metadata
- Torrent engine → Torrent peers: downloads pieces
- API routes → Search API: dispatches search
- Search API → Torrent providers: queries providers
- Torrent providers → Search services: searches externally