# maxdorninger/mediamanager architecture

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

- Interactive diagram: https://gitdiagram.com/maxdorninger/mediamanager
- Repository: https://github.com/maxdorninger/mediamanager

## Overview

MediaManager is a web-based manager for TV and movie libraries. Users browse or add media, search metadata and indexers, initiate downloads, and manage imports and library items. The backend separates movie and TV workflows from shared media services, torrent handling, persistence, authentication, and notifications. README capabilities include TMDB/TVDB support and OAuth/OIDC; these integration branches are represented at subsystem level where their runtime wiring was not excerpted. Dashed links mark relationships documented only generally or not shown in sampled source.

Main entry points: [`media_manager/main.py`](https://github.com/maxdorninger/mediamanager/blob/master/media_manager/main.py) (API application), [`media_manager/movies/service.py`](https://github.com/maxdorninger/mediamanager/blob/master/media_manager/movies/service.py) (Movie workflow), [`media_manager/tv/service.py`](https://github.com/maxdorninger/mediamanager/blob/master/media_manager/tv/service.py) (TV workflow), [`media_manager/common/service.py`](https://github.com/maxdorninger/mediamanager/blob/master/media_manager/common/service.py) (Shared media service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_web["Web application"]
end

subgraph group_api["API and identity"]
  node_app["API application<br/>[main.py]"]
  node_auth["Authentication"]
end

subgraph group_media["Media workflows"]
  node_movies["Movie workflow<br/>[service.py]"]
  node_tv["TV workflow<br/>[service.py]"]
  node_shared["Shared media service<br/>[service.py]"]
  node_metadata["Metadata providers"]
end

subgraph group_integrations["Search and downloads"]
  node_indexing["Indexer search<br/>[service.py]"]
  node_indexer_adapters["Indexer adapters"]
  node_torrent_service["Download workflow<br/>[service.py]"]
  node_download_manager["Download clients<br/>[manager.py]"]
end

subgraph group_platform["State and automation"]
  node_movie_store[("Movie persistence<br/>[repository.py]")]
  node_tv_store[("TV persistence<br/>[repository.py]")]
  node_torrent_store[("Torrent persistence<br/>[repository.py]")]
  node_notification["Notifications<br/>[manager.py]"]
  node_scheduler["Scheduled tasks<br/>[scheduler.py]"]
  node_database[("Database")]
end

node_user(("Library user"))
node_metadata_services["TMDB and TVDB"]
node_indexer_services["Indexer services"]
node_download_services["Download services"]
node_notification_services["Notification services"]

node_user -.->|"uses"| node_web
node_web -.->|"requests API"| node_app
node_app -->|"registers routes"| node_auth
node_app -->|"registers routes"| node_movies
node_app -->|"registers routes"| node_tv
node_app -->|"registers routes"| node_notification
node_shared -->|"uses search"| node_indexing
node_shared -->|"uses downloads"| node_torrent_service
node_shared -->|"sends alerts"| node_notification
node_movies -->|"delegates"| node_shared
node_tv -->|"delegates"| node_shared
node_movies -->|"searches releases"| node_indexing
node_tv -->|"searches releases"| node_indexing
node_movies -->|"persists movies"| node_movie_store
node_tv -->|"persists shows"| node_tv_store
node_movies -->|"starts downloads"| node_torrent_service
node_tv -->|"starts downloads"| node_torrent_service
node_movies -.->|"gets metadata"| node_metadata
node_tv -.->|"gets metadata"| node_metadata
node_metadata -.->|"queries providers"| node_metadata_services
node_indexing -->|"dispatches searches"| node_indexer_adapters
node_indexer_adapters -.->|"queries"| node_indexer_services
node_torrent_service -->|"dispatches downloads"| node_download_manager
node_download_manager -->|"uses clients"| node_download_services
node_torrent_service -->|"saves torrents"| node_torrent_store
node_notification -->|"sends notifications"| node_notification_services
node_movie_store -.->|"stores records"| node_database
node_tv_store -.->|"stores records"| node_database
node_torrent_store -.->|"stores records"| node_database
node_app -->|"starts tasks"| node_scheduler

click node_web "https://github.com/maxdorninger/mediamanager/tree/master/web/src/routes"
click node_app "https://github.com/maxdorninger/mediamanager/blob/master/media_manager/main.py"
click node_auth "https://github.com/maxdorninger/mediamanager/tree/master/media_manager/auth"
click node_movies "https://github.com/maxdorninger/mediamanager/blob/master/media_manager/movies/service.py"
click node_tv "https://github.com/maxdorninger/mediamanager/blob/master/media_manager/tv/service.py"
click node_shared "https://github.com/maxdorninger/mediamanager/blob/master/media_manager/common/service.py"
click node_metadata "https://github.com/maxdorninger/mediamanager/tree/master/media_manager/metadataProvider"
click node_movie_store "https://github.com/maxdorninger/mediamanager/blob/master/media_manager/movies/repository.py"
click node_tv_store "https://github.com/maxdorninger/mediamanager/blob/master/media_manager/tv/repository.py"
click node_indexing "https://github.com/maxdorninger/mediamanager/blob/master/media_manager/indexer/service.py"
click node_indexer_adapters "https://github.com/maxdorninger/mediamanager/tree/master/media_manager/indexer/indexers"
click node_torrent_service "https://github.com/maxdorninger/mediamanager/blob/master/media_manager/torrent/service.py"
click node_download_manager "https://github.com/maxdorninger/mediamanager/blob/master/media_manager/torrent/manager.py"
click node_torrent_store "https://github.com/maxdorninger/mediamanager/blob/master/media_manager/torrent/repository.py"
click node_notification "https://github.com/maxdorninger/mediamanager/blob/master/media_manager/notification/manager.py"
click node_scheduler "https://github.com/maxdorninger/mediamanager/blob/master/media_manager/scheduler.py"
click node_database "https://github.com/maxdorninger/mediamanager/tree/master/media_manager/database"

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_web,node_user toneBlue
class node_app,node_auth toneAmber
class node_movies,node_tv,node_shared,node_metadata toneMint
class node_indexing,node_indexer_adapters,node_torrent_service,node_download_manager toneRose
class node_movie_store,node_tv_store,node_torrent_store,node_notification,node_scheduler,node_database,node_metadata_services,node_indexer_services,node_download_services,node_notification_services toneIndigo
```

## Components

### User interface

- [Web application](https://github.com/maxdorninger/mediamanager/tree/master/web/src/routes): `web/src/routes`

### API and identity

- [API application](https://github.com/maxdorninger/mediamanager/blob/master/media_manager/main.py): `media_manager/main.py`
- [Authentication](https://github.com/maxdorninger/mediamanager/tree/master/media_manager/auth): `media_manager/auth`

### Media workflows

- [Movie workflow](https://github.com/maxdorninger/mediamanager/blob/master/media_manager/movies/service.py): `media_manager/movies/service.py`
- [TV workflow](https://github.com/maxdorninger/mediamanager/blob/master/media_manager/tv/service.py): `media_manager/tv/service.py`
- [Shared media service](https://github.com/maxdorninger/mediamanager/blob/master/media_manager/common/service.py): `media_manager/common/service.py`
- [Metadata providers](https://github.com/maxdorninger/mediamanager/tree/master/media_manager/metadataProvider): `media_manager/metadataProvider`

### Search and downloads

- [Indexer search](https://github.com/maxdorninger/mediamanager/blob/master/media_manager/indexer/service.py): `media_manager/indexer/service.py`
- [Indexer adapters](https://github.com/maxdorninger/mediamanager/tree/master/media_manager/indexer/indexers): `media_manager/indexer/indexers`
- [Download workflow](https://github.com/maxdorninger/mediamanager/blob/master/media_manager/torrent/service.py): `media_manager/torrent/service.py`
- [Download clients](https://github.com/maxdorninger/mediamanager/blob/master/media_manager/torrent/manager.py): `media_manager/torrent/manager.py`

### State and automation

- [Movie persistence](https://github.com/maxdorninger/mediamanager/blob/master/media_manager/movies/repository.py): `media_manager/movies/repository.py`
- [TV persistence](https://github.com/maxdorninger/mediamanager/blob/master/media_manager/tv/repository.py): `media_manager/tv/repository.py`
- [Torrent persistence](https://github.com/maxdorninger/mediamanager/blob/master/media_manager/torrent/repository.py): `media_manager/torrent/repository.py`
- [Notifications](https://github.com/maxdorninger/mediamanager/blob/master/media_manager/notification/manager.py): `media_manager/notification/manager.py`
- [Scheduled tasks](https://github.com/maxdorninger/mediamanager/blob/master/media_manager/scheduler.py): `media_manager/scheduler.py`
- [Database](https://github.com/maxdorninger/mediamanager/tree/master/media_manager/database): `media_manager/database`

### Other components

- **Library user**
- **TMDB and TVDB**
- **Indexer services**
- **Download services**
- **Notification services**

## Connections

- Library user → Web application: uses (evidence: `README.md`)
- Web application → API application: requests API
- API application → Authentication: registers routes (evidence: `media_manager/main.py`)
- API application → Movie workflow: registers routes (evidence: `media_manager/main.py`)
- API application → TV workflow: registers routes (evidence: `media_manager/main.py`)
- API application → Notifications: registers routes (evidence: `media_manager/main.py`)
- Shared media service → Indexer search: uses search (evidence: `media_manager/common/service.py`)
- Shared media service → Download workflow: uses downloads (evidence: `media_manager/common/service.py`)
- Shared media service → Notifications: sends alerts (evidence: `media_manager/common/service.py`)
- Movie workflow → Shared media service: delegates (evidence: `media_manager/movies/service.py`)
- TV workflow → Shared media service: delegates (evidence: `media_manager/tv/service.py`)
- Movie workflow → Indexer search: searches releases (evidence: `media_manager/movies/service.py`)
- TV workflow → Indexer search: searches releases (evidence: `media_manager/tv/service.py`)
- Movie workflow → Movie persistence: persists movies (evidence: `media_manager/movies/service.py`)
- TV workflow → TV persistence: persists shows (evidence: `media_manager/tv/service.py`)
- Movie workflow → Download workflow: starts downloads (evidence: `media_manager/movies/service.py`)
- TV workflow → Download workflow: starts downloads (evidence: `media_manager/tv/service.py`)
- Movie workflow → Metadata providers: gets metadata (evidence: `media_manager/movies/service.py`)
- TV workflow → Metadata providers: gets metadata (evidence: `media_manager/tv/service.py`)
- Metadata providers → TMDB and TVDB: queries providers (evidence: `README.md`)
- Indexer search → Indexer adapters: dispatches searches (evidence: `media_manager/indexer/service.py`)
- Indexer adapters → Indexer services: queries
- Download workflow → Download clients: dispatches downloads (evidence: `media_manager/torrent/service.py`)
- Download clients → Download services: uses clients (evidence: `media_manager/torrent/manager.py`)
- Download workflow → Torrent persistence: saves torrents (evidence: `media_manager/torrent/service.py`)
- Notifications → Notification services: sends notifications (evidence: `media_manager/notification/manager.py`)
- Movie persistence → Database: stores records
- TV persistence → Database: stores records
- Torrent persistence → Database: stores records (evidence: `media_manager/torrent/repository.py`)
- API application → Scheduled tasks: starts tasks (evidence: `media_manager/main.py`)
