# drdon1234/jav-pilot architecture

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

- Interactive diagram: https://gitdiagram.com/drdon1234/jav-pilot
- Repository: https://github.com/drdon1234/jav-pilot

## Overview

JAV Pilot is a local-first web application for searching media sources, managing downloads, and organizing a media library. The main workflow runs from browser search through the HTTP API and source indexers, then into either qBittorrent or Web downloads; completed media is organized and enriched for media-server use. The README also documents rankings, resource search, translation, site diagnostics, and notifications. Some subsystem links reflect documented behavior and tree structure; unsampled implementation details are not asserted.

Main entry points: [`jav_pilot/api/server.py`](https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/api/server.py) (HTTP server), [`jav_pilot/api/services/torrents.py`](https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/api/services/torrents.py) (Torrent service), [`jav_pilot/web_download/manager.py`](https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/web_download/manager.py) (Web download manager), [`jav_pilot/media_metadata/manager.py`](https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/media_metadata/manager.py) (Metadata manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_app["Application routes<br/>[App.tsx]"]
  node_frontend_api["API client<br/>[api.ts]"]
end

subgraph group_api["API and services"]
  node_http["HTTP server<br/>[server.py]"]
  node_route_search["Search routes<br/>[search.py]"]
  node_search_service["Search service<br/>[search_stream.py]"]
  node_resource_route["Resource API<br/>[resource_search.py]"]
  node_downloads_route["Download routes<br/>[downloads.py]"]
  node_web_route["Web download routes<br/>[web_downloads.py]"]
  node_translation["Translation<br/>[translation.py]"]
  node_diagnostics["Site diagnostics"]
  node_notifications["Notifications<br/>[notifications.py]"]
end

subgraph group_discovery["Search and discovery"]
  node_engine["Search engine<br/>[engine.py]"]
  node_indexers["Source indexers"]
  node_rankings["Rankings"]
  node_resource_search["Resource search<br/>[manager.py]"]
end

subgraph group_downloads["Downloads"]
  node_qb_service["Torrent service<br/>[torrents.py]"]
  node_web_batches["Batch manager<br/>[manager.py]"]
  node_web_manager["Web download manager<br/>[manager.py]"]
end

subgraph group_library["Library and metadata"]
  node_organizer["Completed organizer<br/>[organizer.py]"]
  node_library[("Media library")]
  node_metadata["Metadata manager<br/>[manager.py]"]
  node_review["Metadata review<br/>[manager.py]"]
end

node_user(("Browser user"))
node_qbittorrent["qBittorrent"]
node_video_sites["Video sites"]
node_media_server["Media servers"]
node_ai_services["Translation providers"]
node_notification_sinks["Notification sinks"]

node_user -->|"uses"| node_app
node_app -->|"requests data"| node_frontend_api
node_frontend_api -->|"HTTP requests"| node_http
node_http -->|"dispatches"| node_route_search
node_route_search -->|"starts search"| node_search_service
node_search_service -->|"runs search"| node_engine
node_engine -->|"queries sources"| node_indexers
node_indexers -->|"returns results"| node_user
node_http -->|"dispatches"| node_resource_route
node_resource_route -->|"manages sessions"| node_resource_search
node_http -->|"dispatches"| node_downloads_route
node_downloads_route -->|"submits torrents"| node_qb_service
node_qb_service -->|"controls tasks"| node_qbittorrent
node_http -->|"dispatches"| node_web_route
node_web_route -->|"manages batches"| node_web_batches
node_web_batches -->|"submits jobs"| node_web_manager
node_web_manager -->|"downloads media"| node_video_sites
node_qb_service -->|"completed tasks"| node_organizer
node_web_manager -->|"completed media"| node_organizer
node_organizer -->|"archives media"| node_library
node_library -->|"provides media"| node_metadata
node_metadata -->|"publishes NFO and artwork"| node_media_server
node_metadata -->|"supports review"| node_review
node_http -->|"serves rankings"| node_rankings
node_http -->|"dispatches translation"| node_translation
node_translation -.->|"translates titles"| node_ai_services
node_http -->|"runs diagnostics"| node_diagnostics
node_diagnostics -->|"checks sites"| node_indexers
node_http -->|"dispatches events"| node_notifications
node_notifications -->|"pushes alerts"| node_notification_sinks

click node_app "https://github.com/drdon1234/jav-pilot/blob/main/frontend/src/App.tsx"
click node_frontend_api "https://github.com/drdon1234/jav-pilot/blob/main/frontend/src/lib/api.ts"
click node_http "https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/api/server.py"
click node_route_search "https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/api/routes/search.py"
click node_search_service "https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/api/services/search_stream.py"
click node_engine "https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/search/engine.py"
click node_indexers "https://github.com/drdon1234/jav-pilot/tree/main/jav_pilot/indexers"
click node_rankings "https://github.com/drdon1234/jav-pilot/tree/main/jav_pilot/search/rankings"
click node_resource_search "https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/search/resources/manager.py"
click node_resource_route "https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/api/routes/resource_search.py"
click node_downloads_route "https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/api/routes/downloads.py"
click node_qb_service "https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/api/services/torrents.py"
click node_web_route "https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/api/routes/web_downloads.py"
click node_web_batches "https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/web_download/batches/manager.py"
click node_web_manager "https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/web_download/manager.py"
click node_organizer "https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/torrent/organizer.py"
click node_metadata "https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/media_metadata/manager.py"
click node_review "https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/media_metadata/review/manager.py"
click node_translation "https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/api/services/translation.py"
click node_diagnostics "https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/api/services/site_diagnostics.py"
click node_notifications "https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/api/services/notifications.py"

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_frontend_api,node_user toneBlue
class node_http,node_route_search,node_search_service,node_resource_route,node_downloads_route,node_web_route,node_translation,node_diagnostics,node_notifications toneAmber
class node_engine,node_indexers,node_rankings,node_resource_search,node_media_server toneMint
class node_qb_service,node_web_batches,node_web_manager toneRose
class node_organizer,node_library,node_metadata,node_review,node_qbittorrent,node_video_sites,node_ai_services,node_notification_sinks toneIndigo
```

## Components

### Web interface

- [Application routes](https://github.com/drdon1234/jav-pilot/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/drdon1234/jav-pilot/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### API and services

- [HTTP server](https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/api/server.py): `jav_pilot/api/server.py`
- [Search routes](https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/api/routes/search.py): `jav_pilot/api/routes/search.py`
- [Search service](https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/api/services/search_stream.py): `jav_pilot/api/services/search_stream.py`
- [Resource API](https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/api/routes/resource_search.py): `jav_pilot/api/routes/resource_search.py`
- [Download routes](https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/api/routes/downloads.py): `jav_pilot/api/routes/downloads.py`
- [Web download routes](https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/api/routes/web_downloads.py): `jav_pilot/api/routes/web_downloads.py`
- [Translation](https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/api/services/translation.py): `jav_pilot/api/services/translation.py`
- [Site diagnostics](https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/api/services/site_diagnostics.py): `jav_pilot/api/services/site_diagnostics.py`
- [Notifications](https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/api/services/notifications.py): `jav_pilot/api/services/notifications.py`

### Search and discovery

- [Search engine](https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/search/engine.py): `jav_pilot/search/engine.py`
- [Source indexers](https://github.com/drdon1234/jav-pilot/tree/main/jav_pilot/indexers): `jav_pilot/indexers`
- [Rankings](https://github.com/drdon1234/jav-pilot/tree/main/jav_pilot/search/rankings): `jav_pilot/search/rankings`
- [Resource search](https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/search/resources/manager.py): `jav_pilot/search/resources/manager.py`

### Downloads

- [Torrent service](https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/api/services/torrents.py): `jav_pilot/api/services/torrents.py`
- [Batch manager](https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/web_download/batches/manager.py): `jav_pilot/web_download/batches/manager.py`
- [Web download manager](https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/web_download/manager.py): `jav_pilot/web_download/manager.py`

### Library and metadata

- [Completed organizer](https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/torrent/organizer.py): `jav_pilot/torrent/organizer.py`
- **Media library**
- [Metadata manager](https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/media_metadata/manager.py): `jav_pilot/media_metadata/manager.py`
- [Metadata review](https://github.com/drdon1234/jav-pilot/blob/main/jav_pilot/media_metadata/review/manager.py): `jav_pilot/media_metadata/review/manager.py`

### Other components

- **Browser user**
- **qBittorrent**
- **Video sites**
- **Media servers**
- **Translation providers**
- **Notification sinks**

## Connections

- Browser user → Application routes: uses
- Application routes → API client: requests data
- API client → HTTP server: HTTP requests
- HTTP server → Search routes: dispatches
- Search routes → Search service: starts search
- Search service → Search engine: runs search
- Search engine → Source indexers: queries sources
- Source indexers → Browser user: returns results
- HTTP server → Resource API: dispatches
- Resource API → Resource search: manages sessions
- HTTP server → Download routes: dispatches
- Download routes → Torrent service: submits torrents
- Torrent service → qBittorrent: controls tasks
- HTTP server → Web download routes: dispatches
- Web download routes → Batch manager: manages batches
- Batch manager → Web download manager: submits jobs
- Web download manager → Video sites: downloads media
- Torrent service → Completed organizer: completed tasks
- Web download manager → Completed organizer: completed media
- Completed organizer → Media library: archives media
- Media library → Metadata manager: provides media
- Metadata manager → Media servers: publishes NFO and artwork
- Metadata manager → Metadata review: supports review
- HTTP server → Rankings: serves rankings
- HTTP server → Translation: dispatches translation
- Translation → Translation providers: translates titles
- HTTP server → Site diagnostics: runs diagnostics
- Site diagnostics → Source indexers: checks sites
- HTTP server → Notifications: dispatches events
- Notifications → Notification sinks: pushes alerts