# theotherp/nzbhydra2 architecture

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

## Overview

NZBHydra 2 is a meta-search service for Usenet indexers and Torznab trackers, also exposing an indexer-compatible API to automation clients. Users search from the GUI or an external client; Hydra queries configured sources, aggregates and filters results, then presents them or supports downloading through configured downloaders. The README documents the main capabilities, but most backend search and download implementations were not sampled, so those relationships are cited to the README rather than inferred from imports.

Main entry points: [`core/src/main/java/org/nzbhydra/searching`](https://github.com/theotherp/nzbhydra2/tree/master/core/src/main/java/org/nzbhydra/searching) (Search orchestration), [`core/ui-react/src/features/config/routes.tsx`](https://github.com/theotherp/nzbhydra2/blob/master/core/ui-react/src/features/config/routes.tsx) (Configuration UI), [`core/src/main/java/org/nzbhydra/downloading`](https://github.com/theotherp/nzbhydra2/tree/master/core/src/main/java/org/nzbhydra/downloading) (Download handling), [`core/ui-react/src/App.tsx`](https://github.com/theotherp/nzbhydra2/blob/master/core/ui-react/src/App.tsx) (React application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and UI"]
  node_ui["React application<br/>[App.tsx]"]
  node_api["External API"]
  node_auth["Authentication"]
end

subgraph group_search["Search and results"]
  node_search["Search orchestration"]
  node_mapping["Query mapping"]
  node_media["Media ID lookup"]
  node_indexers["Indexer adapters"]
  node_results["Result aggregation"]
  node_resultstore[("Search result storage")]
end

subgraph group_delivery["Downloads and history"]
  node_stats["History and statistics"]
  node_download["Download handling"]
  node_downloaders["Downloader integrations"]
  node_torrent["Torrent handling"]
  node_statsui["History and stats UI<br/>[routes.tsx]"]
end

subgraph group_admin["Configuration and operations"]
  node_config["Configuration"]
  node_externaltools["External tool sync"]
  node_backup["Backup and restore"]
  node_configui["Configuration UI<br/>[routes.tsx]"]
end

node_user(("GUI user"))
node_automation(("Automation client"))

node_user -->|"searches"| node_ui
node_automation -->|"requests search"| node_api
node_ui -.->|"submits query"| node_search
node_api -.->|"routes search"| node_search
node_search -.->|"maps query"| node_mapping
node_search -->|"resolves media IDs"| node_media
node_search -->|"queries sources"| node_indexers
node_indexers -->|"returns matches"| node_results
node_results -.->|"persists results"| node_resultstore
node_results -->|"displays results"| node_ui
node_results -->|"serves results"| node_api
node_configui -.->|"edits settings"| node_config
node_search -.->|"uses settings"| node_config
node_statsui -.->|"requests history"| node_stats
node_stats -.->|"reads search data"| node_resultstore
node_user -->|"requests download"| node_download
node_download -->|"submits NZB"| node_downloaders
node_download -->|"handles torrents"| node_torrent
node_config -.->|"configures sync"| node_externaltools
node_configui -->|"configures tools"| node_externaltools
node_configui -.->|"manages backups"| node_backup

click node_ui "https://github.com/theotherp/nzbhydra2/blob/master/core/ui-react/src/App.tsx"
click node_api "https://github.com/theotherp/nzbhydra2/blob/master/core/src/main/java/org/nzbhydra/externalapi/ExternalApiV1Controller.java"
click node_auth "https://github.com/theotherp/nzbhydra2/blob/master/core/src/main/java/org/nzbhydra/auth/SecurityConfig.java"
click node_search "https://github.com/theotherp/nzbhydra2/tree/master/core/src/main/java/org/nzbhydra/searching"
click node_mapping "https://github.com/theotherp/nzbhydra2/blob/master/core/src/main/java/org/nzbhydra/searching/CustomQueryAndTitleMappingHandler.java"
click node_media "https://github.com/theotherp/nzbhydra2/tree/master/core/src/main/java/org/nzbhydra/mediainfo"
click node_indexers "https://github.com/theotherp/nzbhydra2/tree/master/core/src/main/java/org/nzbhydra/indexers"
click node_results "https://github.com/theotherp/nzbhydra2/tree/master/core/src/main/java/org/nzbhydra/searching"
click node_resultstore "https://github.com/theotherp/nzbhydra2/blob/master/core/src/main/java/org/nzbhydra/searching/db/SearchResultRepository.java"
click node_config "https://github.com/theotherp/nzbhydra2/blob/master/core/src/main/java/org/nzbhydra/config/ConfigProvider.java"
click node_stats "https://github.com/theotherp/nzbhydra2/tree/master/core/src/main/java/org/nzbhydra/historystats"
click node_download "https://github.com/theotherp/nzbhydra2/tree/master/core/src/main/java/org/nzbhydra/downloading"
click node_downloaders "https://github.com/theotherp/nzbhydra2/tree/master/core/src/main/java/org/nzbhydra/downloading/downloaders"
click node_torrent "https://github.com/theotherp/nzbhydra2/tree/master/core/src/main/java/org/nzbhydra/downloading/torrents"
click node_externaltools "https://github.com/theotherp/nzbhydra2/blob/master/core/src/main/java/org/nzbhydra/externaltools/ExternalToolsSyncService.java"
click node_backup "https://github.com/theotherp/nzbhydra2/blob/master/core/src/main/java/org/nzbhydra/backup/BackupAndRestore.java"
click node_configui "https://github.com/theotherp/nzbhydra2/blob/master/core/ui-react/src/features/config/routes.tsx"
click node_statsui "https://github.com/theotherp/nzbhydra2/blob/master/core/ui-react/src/features/stats/routes.tsx"

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_ui,node_api,node_auth,node_user,node_automation toneBlue
class node_search,node_mapping,node_media,node_indexers,node_results,node_resultstore toneAmber
class node_stats,node_download,node_downloaders,node_torrent,node_statsui toneMint
class node_config,node_externaltools,node_backup,node_configui toneRose
```

## Components

### Access and UI

- [React application](https://github.com/theotherp/nzbhydra2/blob/master/core/ui-react/src/App.tsx): `core/ui-react/src/App.tsx`
- [External API](https://github.com/theotherp/nzbhydra2/blob/master/core/src/main/java/org/nzbhydra/externalapi/ExternalApiV1Controller.java): `core/src/main/java/org/nzbhydra/externalapi/ExternalApiV1Controller.java`
- [Authentication](https://github.com/theotherp/nzbhydra2/blob/master/core/src/main/java/org/nzbhydra/auth/SecurityConfig.java): `core/src/main/java/org/nzbhydra/auth/SecurityConfig.java`

### Search and results

- [Search orchestration](https://github.com/theotherp/nzbhydra2/tree/master/core/src/main/java/org/nzbhydra/searching): `core/src/main/java/org/nzbhydra/searching`
- [Query mapping](https://github.com/theotherp/nzbhydra2/blob/master/core/src/main/java/org/nzbhydra/searching/CustomQueryAndTitleMappingHandler.java): `core/src/main/java/org/nzbhydra/searching/CustomQueryAndTitleMappingHandler.java`
- [Media ID lookup](https://github.com/theotherp/nzbhydra2/tree/master/core/src/main/java/org/nzbhydra/mediainfo): `core/src/main/java/org/nzbhydra/mediainfo`
- [Indexer adapters](https://github.com/theotherp/nzbhydra2/tree/master/core/src/main/java/org/nzbhydra/indexers): `core/src/main/java/org/nzbhydra/indexers`
- [Result aggregation](https://github.com/theotherp/nzbhydra2/tree/master/core/src/main/java/org/nzbhydra/searching): `core/src/main/java/org/nzbhydra/searching`
- [Search result storage](https://github.com/theotherp/nzbhydra2/blob/master/core/src/main/java/org/nzbhydra/searching/db/SearchResultRepository.java): `core/src/main/java/org/nzbhydra/searching/db/SearchResultRepository.java`

### Downloads and history

- [History and statistics](https://github.com/theotherp/nzbhydra2/tree/master/core/src/main/java/org/nzbhydra/historystats): `core/src/main/java/org/nzbhydra/historystats`
- [Download handling](https://github.com/theotherp/nzbhydra2/tree/master/core/src/main/java/org/nzbhydra/downloading): `core/src/main/java/org/nzbhydra/downloading`
- [Downloader integrations](https://github.com/theotherp/nzbhydra2/tree/master/core/src/main/java/org/nzbhydra/downloading/downloaders): `core/src/main/java/org/nzbhydra/downloading/downloaders`
- [Torrent handling](https://github.com/theotherp/nzbhydra2/tree/master/core/src/main/java/org/nzbhydra/downloading/torrents): `core/src/main/java/org/nzbhydra/downloading/torrents`
- [History and stats UI](https://github.com/theotherp/nzbhydra2/blob/master/core/ui-react/src/features/stats/routes.tsx): `core/ui-react/src/features/stats/routes.tsx`

### Configuration and operations

- [Configuration](https://github.com/theotherp/nzbhydra2/blob/master/core/src/main/java/org/nzbhydra/config/ConfigProvider.java): `core/src/main/java/org/nzbhydra/config/ConfigProvider.java`
- [External tool sync](https://github.com/theotherp/nzbhydra2/blob/master/core/src/main/java/org/nzbhydra/externaltools/ExternalToolsSyncService.java): `core/src/main/java/org/nzbhydra/externaltools/ExternalToolsSyncService.java`
- [Backup and restore](https://github.com/theotherp/nzbhydra2/blob/master/core/src/main/java/org/nzbhydra/backup/BackupAndRestore.java): `core/src/main/java/org/nzbhydra/backup/BackupAndRestore.java`
- [Configuration UI](https://github.com/theotherp/nzbhydra2/blob/master/core/ui-react/src/features/config/routes.tsx): `core/ui-react/src/features/config/routes.tsx`

### Other components

- **GUI user**
- **Automation client**

## Connections

- GUI user → React application: searches
- Automation client → External API: requests search
- React application → Search orchestration: submits query
- External API → Search orchestration: routes search (evidence: `core/src/main/java/org/nzbhydra/externalapi/ExternalApiV1Controller.java`)
- Search orchestration → Query mapping: maps query (evidence: `core/src/main/java/org/nzbhydra/searching/CustomQueryAndTitleMappingHandler.java`)
- Search orchestration → Media ID lookup: resolves media IDs
- Search orchestration → Indexer adapters: queries sources
- Indexer adapters → Result aggregation: returns matches
- Result aggregation → Search result storage: persists results
- Result aggregation → React application: displays results
- Result aggregation → External API: serves results (evidence: `core/src/main/java/org/nzbhydra/externalapi/ExternalApiV1Controller.java`)
- Configuration UI → Configuration: edits settings
- Search orchestration → Configuration: uses settings (evidence: `core/src/main/java/org/nzbhydra/searching/CustomQueryAndTitleMappingHandler.java`)
- History and stats UI → History and statistics: requests history
- History and statistics → Search result storage: reads search data
- GUI user → Download handling: requests download
- Download handling → Downloader integrations: submits NZB
- Download handling → Torrent handling: handles torrents
- Configuration → External tool sync: configures sync (evidence: `core/src/main/java/org/nzbhydra/externaltools/ExternalToolsSyncService.java`)
- Configuration UI → External tool sync: configures tools
- Configuration UI → Backup and restore: manages backups
