# mhdzumair/mediafusion architecture

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

- Interactive diagram: https://gitdiagram.com/mhdzumair/mediafusion
- Repository: https://github.com/mhdzumair/mediafusion

## Overview

MediaFusion is a self-hosted streaming aggregator: users configure sources and playback preferences, request catalogs or streams through Stremio, Kodi, or the browser, and receive playable results from indexers and supported providers. The Rust backend is the primary runtime represented in the current tree; the README documents its multi-client and provider capabilities. The tree also contains a substantial deprecated Python implementation, but the supplied excerpts do not establish its runtime wiring, so it is not drawn as a second workflow.

Main entry points: [`backend/src/routes/stream.rs`](https://github.com/mhdzumair/mediafusion/blob/main/backend/src/routes/stream.rs) (Stream endpoint), [`backend/src/db/pool.rs`](https://github.com/mhdzumair/mediafusion/blob/main/backend/src/db/pool.rs) (PostgreSQL data), [`backend/src/scrapers/orchestrator.rs`](https://github.com/mhdzumair/mediafusion/blob/main/backend/src/scrapers/orchestrator.rs) (Source aggregation), [`backend/src/main.rs`](https://github.com/mhdzumair/mediafusion/blob/main/backend/src/main.rs) (Rust API service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client experiences"]
  node_stremio["Stremio"]
  node_kodi["Kodi add-on<br/>[router.py]"]
  node_browser["Browser player<br/>[VideoPlayer.tsx]"]
  node_webapp["Web application<br/>[App.tsx]"]
  node_extension["Browser extension<br/>[App.tsx]"]
end

subgraph group_api["Backend API"]
  node_api_service["Rust API service<br/>[main.rs]"]
  node_catalog["Catalog and manifest<br/>[catalog.rs]"]
  node_stream_route["Stream endpoint<br/>[stream.rs]"]
  node_content_routes["Content management<br/>[mod.rs]"]
end

subgraph group_discovery["Discovery and aggregation"]
  node_scrapers["Source aggregation<br/>[orchestrator.rs]"]
  node_metadata["Metadata lookup<br/>[mod.rs]"]
  node_parsing["Stream parsing<br/>[mod.rs]"]
  node_indexers["Indexers and feeds"]
end

subgraph group_playback["Playback and state"]
  node_provider_adapters["Playback providers<br/>[mod.rs]"]
  node_usenet["Usenet providers<br/>[mod.rs]"]
  node_database[("PostgreSQL data<br/>[pool.rs]")]
  node_cache[("Stream cache<br/>[stream_cache.rs]")]
end

subgraph group_operations["Operations and integrations"]
  node_job_system["Background jobs<br/>[runner.rs]"]
  node_telegram_bot["Telegram bot<br/>[dispatch.rs]"]
  node_integrations["External integrations<br/>[integrations.rs]"]
end

node_users(("Viewers and admins"))

node_users -->|"configure and browse"| node_webapp
node_users -->|"install and watch"| node_stremio
node_users -->|"watch with"| node_kodi
node_webapp -->|"request services"| node_api_service
node_extension -.->|"import content"| node_api_service
node_stremio -->|"request catalogs"| node_catalog
node_kodi -->|"request catalogs"| node_catalog
node_browser -->|"request streams"| node_stream_route
node_api_service -.->|"serves routes"| node_catalog
node_api_service -.->|"serves routes"| node_stream_route
node_catalog -.->|"reads catalog data"| node_database
node_stream_route -.->|"requests candidates"| node_scrapers
node_scrapers -->|"searches sources"| node_indexers
node_scrapers -.->|"resolves metadata"| node_metadata
node_scrapers -.->|"normalizes results"| node_parsing
node_stream_route -.->|"uses stream cache"| node_cache
node_stream_route -->|"supports debrid and P2P"| node_provider_adapters
node_stream_route -.->|"supports Usenet"| node_usenet
node_content_routes -.->|"manages content"| node_database
node_job_system -.->|"persists job state"| node_database
node_telegram_bot -.->|"uses stored data"| node_database
node_integrations -.->|"uses user data"| node_database

click node_kodi "https://github.com/mhdzumair/mediafusion/blob/main/clients/kodi/plugin.video.mediafusion/lib/router.py"
click node_browser "https://github.com/mhdzumair/mediafusion/blob/main/clients/frontend/src/components/player/VideoPlayer.tsx"
click node_webapp "https://github.com/mhdzumair/mediafusion/blob/main/clients/frontend/src/App.tsx"
click node_extension "https://github.com/mhdzumair/mediafusion/blob/main/clients/browser-extension/src/popup/App.tsx"
click node_api_service "https://github.com/mhdzumair/mediafusion/blob/main/backend/src/main.rs"
click node_catalog "https://github.com/mhdzumair/mediafusion/blob/main/backend/src/routes/catalog.rs"
click node_stream_route "https://github.com/mhdzumair/mediafusion/blob/main/backend/src/routes/stream.rs"
click node_content_routes "https://github.com/mhdzumair/mediafusion/blob/main/backend/src/routes/content/mod.rs"
click node_scrapers "https://github.com/mhdzumair/mediafusion/blob/main/backend/src/scrapers/orchestrator.rs"
click node_metadata "https://github.com/mhdzumair/mediafusion/blob/main/backend/src/scrapers/metadata/mod.rs"
click node_parsing "https://github.com/mhdzumair/mediafusion/blob/main/backend/src/parser/mod.rs"
click node_provider_adapters "https://github.com/mhdzumair/mediafusion/blob/main/backend/src/providers/torrents/mod.rs"
click node_usenet "https://github.com/mhdzumair/mediafusion/blob/main/backend/src/providers/usenet/mod.rs"
click node_database "https://github.com/mhdzumair/mediafusion/blob/main/backend/src/db/pool.rs"
click node_cache "https://github.com/mhdzumair/mediafusion/blob/main/backend/src/cache/stream_cache.rs"
click node_job_system "https://github.com/mhdzumair/mediafusion/blob/main/backend/src/jobs/runner.rs"
click node_telegram_bot "https://github.com/mhdzumair/mediafusion/blob/main/backend/src/bot/dispatch.rs"
click node_integrations "https://github.com/mhdzumair/mediafusion/blob/main/backend/src/routes/integrations.rs"

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_stremio,node_kodi,node_browser,node_webapp,node_extension,node_users toneBlue
class node_api_service,node_catalog,node_stream_route,node_content_routes toneAmber
class node_scrapers,node_metadata,node_parsing,node_indexers toneMint
class node_provider_adapters,node_usenet,node_database,node_cache toneRose
class node_job_system,node_telegram_bot,node_integrations toneIndigo
```

## Components

### Client experiences

- **Stremio**
- [Kodi add-on](https://github.com/mhdzumair/mediafusion/blob/main/clients/kodi/plugin.video.mediafusion/lib/router.py): `clients/kodi/plugin.video.mediafusion/lib/router.py`
- [Browser player](https://github.com/mhdzumair/mediafusion/blob/main/clients/frontend/src/components/player/VideoPlayer.tsx): `clients/frontend/src/components/player/VideoPlayer.tsx`
- [Web application](https://github.com/mhdzumair/mediafusion/blob/main/clients/frontend/src/App.tsx): `clients/frontend/src/App.tsx`
- [Browser extension](https://github.com/mhdzumair/mediafusion/blob/main/clients/browser-extension/src/popup/App.tsx): `clients/browser-extension/src/popup/App.tsx`

### Backend API

- [Rust API service](https://github.com/mhdzumair/mediafusion/blob/main/backend/src/main.rs): `backend/src/main.rs`
- [Catalog and manifest](https://github.com/mhdzumair/mediafusion/blob/main/backend/src/routes/catalog.rs): `backend/src/routes/catalog.rs`
- [Stream endpoint](https://github.com/mhdzumair/mediafusion/blob/main/backend/src/routes/stream.rs): `backend/src/routes/stream.rs`
- [Content management](https://github.com/mhdzumair/mediafusion/blob/main/backend/src/routes/content/mod.rs): `backend/src/routes/content/mod.rs`

### Discovery and aggregation

- [Source aggregation](https://github.com/mhdzumair/mediafusion/blob/main/backend/src/scrapers/orchestrator.rs): `backend/src/scrapers/orchestrator.rs`
- [Metadata lookup](https://github.com/mhdzumair/mediafusion/blob/main/backend/src/scrapers/metadata/mod.rs): `backend/src/scrapers/metadata/mod.rs`
- [Stream parsing](https://github.com/mhdzumair/mediafusion/blob/main/backend/src/parser/mod.rs): `backend/src/parser/mod.rs`
- **Indexers and feeds**

### Playback and state

- [Playback providers](https://github.com/mhdzumair/mediafusion/blob/main/backend/src/providers/torrents/mod.rs): `backend/src/providers/torrents/mod.rs`
- [Usenet providers](https://github.com/mhdzumair/mediafusion/blob/main/backend/src/providers/usenet/mod.rs): `backend/src/providers/usenet/mod.rs`
- [PostgreSQL data](https://github.com/mhdzumair/mediafusion/blob/main/backend/src/db/pool.rs): `backend/src/db/pool.rs`
- [Stream cache](https://github.com/mhdzumair/mediafusion/blob/main/backend/src/cache/stream_cache.rs): `backend/src/cache/stream_cache.rs`

### Operations and integrations

- [Background jobs](https://github.com/mhdzumair/mediafusion/blob/main/backend/src/jobs/runner.rs): `backend/src/jobs/runner.rs`
- [Telegram bot](https://github.com/mhdzumair/mediafusion/blob/main/backend/src/bot/dispatch.rs): `backend/src/bot/dispatch.rs`
- [External integrations](https://github.com/mhdzumair/mediafusion/blob/main/backend/src/routes/integrations.rs): `backend/src/routes/integrations.rs`

### Other components

- **Viewers and admins**

## Connections

- Viewers and admins → Web application: configure and browse (evidence: `README.md`)
- Viewers and admins → Stremio: install and watch (evidence: `README.md`)
- Viewers and admins → Kodi add-on: watch with (evidence: `README.md`)
- Web application → Rust API service: request services (evidence: `README.md`)
- Browser extension → Rust API service: import content
- Stremio → Catalog and manifest: request catalogs (evidence: `README.md`)
- Kodi add-on → Catalog and manifest: request catalogs (evidence: `README.md`)
- Browser player → Stream endpoint: request streams (evidence: `README.md`)
- Rust API service → Catalog and manifest: serves routes
- Rust API service → Stream endpoint: serves routes
- Catalog and manifest → PostgreSQL data: reads catalog data
- Stream endpoint → Source aggregation: requests candidates
- Source aggregation → Indexers and feeds: searches sources (evidence: `README.md`)
- Source aggregation → Metadata lookup: resolves metadata
- Source aggregation → Stream parsing: normalizes results
- Stream endpoint → Stream cache: uses stream cache
- Stream endpoint → Playback providers: supports debrid and P2P (evidence: `README.md`)
- Stream endpoint → Usenet providers: supports Usenet
- Content management → PostgreSQL data: manages content
- Background jobs → PostgreSQL data: persists job state
- Telegram bot → PostgreSQL data: uses stored data
- External integrations → PostgreSQL data: uses user data
