# volcyano42/novel-downloader architecture

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

- Interactive diagram: https://gitdiagram.com/volcyano42/novel-downloader
- Repository: https://github.com/volcyano42/novel-downloader

## Overview

Novel-downloader supports CLI and web clients for searching novels, selecting sources, downloading chapters, managing a bookshelf/reader, and exporting books. Its central web path routes frontend requests through FastAPI task and engine management into source-specific parsers, then persists chapter data for bookshelf and reading operations. The CLI is a separate user entry into the shared library. README navigation names source capabilities and configuration as major features; frontend details and several router interactions are inferred from the tree, so only documented or indexed relationships are solidly connected.

Main entry points: [`backend/main.py`](https://github.com/volcyano42/novel-downloader/blob/main/backend/main.py) (FastAPI app), [`frontend/src/api/client.ts`](https://github.com/volcyano42/novel-downloader/blob/main/frontend/src/api/client.ts) (API client), [`backend/routers/storage.py`](https://github.com/volcyano42/novel-downloader/blob/main/backend/routers/storage.py) (Bookshelf API), [`backend/services/engine_manager.py`](https://github.com/volcyano42/novel-downloader/blob/main/backend/services/engine_manager.py) (Engine manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User interfaces"]
  node_reader["Reader<br/>[Reader.tsx]"]
  node_bookshelf["Bookshelf UI<br/>[BookshelfPage.tsx]"]
  node_detail["Book details<br/>[DetailPage.tsx]"]
  node_webui["Web UI<br/>[App.tsx]"]
  node_cli["CLI<br/>[main.py]"]
end

subgraph group_web["Web application"]
  node_api["API client<br/>[client.ts]"]
  node_webserver["FastAPI app<br/>[main.py]"]
  node_download_route["Download API<br/>[download.py]"]
  node_taskmgr["Task manager<br/>[task_manager.py]"]
  node_enginemgr["Engine manager<br/>[engine_manager.py]"]
  node_export_route["Export API<br/>[export.py]"]
  node_config_route["Config API<br/>[config.py]"]
  node_history_route["History API<br/>[history.py]"]
  node_storage_route["Bookshelf API<br/>[storage.py]"]
end

subgraph group_domain["Novel runtime"]
  node_downloader["Download workflow<br/>[downloader.py]"]
  node_engine["Fetch engines<br/>[engine.py]"]
  node_models["Novel models<br/>[novel.py]"]
  node_storage[("Novel storage<br/>[storage.py]")]
  node_exporters["Book exporters<br/>[exporter.py]"]
end

subgraph group_sources["Source adapters"]
  node_source_registry["Source registry<br/>[source.py]"]
  node_source_manifest["Source manifests<br/>[manifest.py]"]
  node_adapters["Source adapters"]
end

subgraph group_data["Configuration and data"]
  node_config["Runtime config<br/>[config.py]"]
  node_user_data[("User library data<br/>[user_data.py]")]
end

node_actor(("User"))

node_actor -.->|"uses"| node_webui
node_actor -.->|"runs"| node_cli
node_webui -.->|"requests"| node_api
node_api -.->|"HTTP calls"| node_webserver
node_webserver -->|"mounts"| node_download_route
node_webserver -->|"mounts"| node_export_route
node_webserver -->|"mounts"| node_config_route
node_webserver -->|"mounts"| node_history_route
node_webserver -->|"mounts"| node_storage_route
node_download_route -->|"manages tasks"| node_taskmgr
node_download_route -->|"requests engines"| node_enginemgr
node_taskmgr -->|"gets engines"| node_enginemgr
node_taskmgr -->|"creates store"| node_storage
node_enginemgr -->|"loads settings"| node_config
node_enginemgr -->|"creates engine"| node_engine
node_engine -.->|"dispatches capabilities"| node_source_registry
node_source_registry -->|"loads manifests"| node_source_manifest
node_source_registry -->|"loads adapter"| node_adapters
node_cli -->|"calls workflows"| node_downloader
node_downloader -->|"fetches source data"| node_engine
node_downloader -.->|"builds results"| node_models
node_export_route -->|"reads book data"| node_storage
node_export_route -->|"selects format"| node_exporters
node_storage_route -->|"reads and writes"| node_storage
node_storage_route -->|"tracks sources"| node_user_data
node_history_route -->|"reads history"| node_user_data
node_config_route -->|"reads settings"| node_config
node_config_route -->|"validates sources"| node_source_registry
node_bookshelf -.->|"requests data"| node_api
node_detail -.->|"requests details"| node_api
node_reader -.->|"requests chapters"| node_api
node_storage_route -->|"serializes metadata"| node_models

click node_reader "https://github.com/volcyano42/novel-downloader/blob/main/frontend/src/features/reader/Reader.tsx"
click node_bookshelf "https://github.com/volcyano42/novel-downloader/blob/main/frontend/src/features/bookshelf/BookshelfPage.tsx"
click node_detail "https://github.com/volcyano42/novel-downloader/blob/main/frontend/src/features/detail/DetailPage.tsx"
click node_webui "https://github.com/volcyano42/novel-downloader/blob/main/frontend/src/App.tsx"
click node_cli "https://github.com/volcyano42/novel-downloader/blob/main/cli/main.py"
click node_api "https://github.com/volcyano42/novel-downloader/blob/main/frontend/src/api/client.ts"
click node_webserver "https://github.com/volcyano42/novel-downloader/blob/main/backend/main.py"
click node_download_route "https://github.com/volcyano42/novel-downloader/blob/main/backend/routers/download.py"
click node_taskmgr "https://github.com/volcyano42/novel-downloader/blob/main/backend/services/task_manager.py"
click node_enginemgr "https://github.com/volcyano42/novel-downloader/blob/main/backend/services/engine_manager.py"
click node_export_route "https://github.com/volcyano42/novel-downloader/blob/main/backend/routers/export.py"
click node_config_route "https://github.com/volcyano42/novel-downloader/blob/main/backend/routers/config.py"
click node_history_route "https://github.com/volcyano42/novel-downloader/blob/main/backend/routers/history.py"
click node_storage_route "https://github.com/volcyano42/novel-downloader/blob/main/backend/routers/storage.py"
click node_downloader "https://github.com/volcyano42/novel-downloader/blob/main/novelbase/core/downloader.py"
click node_engine "https://github.com/volcyano42/novel-downloader/blob/main/novelbase/core/engine.py"
click node_models "https://github.com/volcyano42/novel-downloader/blob/main/novelbase/models/novel.py"
click node_storage "https://github.com/volcyano42/novel-downloader/blob/main/novelbase/core/storage.py"
click node_exporters "https://github.com/volcyano42/novel-downloader/blob/main/novelbase/exporter.py"
click node_source_registry "https://github.com/volcyano42/novel-downloader/blob/main/novelbase/source.py"
click node_source_manifest "https://github.com/volcyano42/novel-downloader/blob/main/novelbase/sources/manifest.py"
click node_adapters "https://github.com/volcyano42/novel-downloader/tree/main/novelbase/sources"
click node_config "https://github.com/volcyano42/novel-downloader/blob/main/shared/config.py"
click node_user_data "https://github.com/volcyano42/novel-downloader/blob/main/shared/user_data.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_reader,node_bookshelf,node_detail,node_webui,node_cli,node_actor toneBlue
class node_api,node_webserver,node_download_route,node_taskmgr,node_enginemgr,node_export_route,node_config_route,node_history_route,node_storage_route toneAmber
class node_downloader,node_engine,node_models,node_storage,node_exporters toneMint
class node_source_registry,node_source_manifest,node_adapters toneRose
class node_config,node_user_data toneIndigo
```

## Components

### User interfaces

- [Reader](https://github.com/volcyano42/novel-downloader/blob/main/frontend/src/features/reader/Reader.tsx): `frontend/src/features/reader/Reader.tsx`
- [Bookshelf UI](https://github.com/volcyano42/novel-downloader/blob/main/frontend/src/features/bookshelf/BookshelfPage.tsx): `frontend/src/features/bookshelf/BookshelfPage.tsx`
- [Book details](https://github.com/volcyano42/novel-downloader/blob/main/frontend/src/features/detail/DetailPage.tsx): `frontend/src/features/detail/DetailPage.tsx`
- [Web UI](https://github.com/volcyano42/novel-downloader/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [CLI](https://github.com/volcyano42/novel-downloader/blob/main/cli/main.py): `cli/main.py`

### Web application

- [API client](https://github.com/volcyano42/novel-downloader/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [FastAPI app](https://github.com/volcyano42/novel-downloader/blob/main/backend/main.py): `backend/main.py`
- [Download API](https://github.com/volcyano42/novel-downloader/blob/main/backend/routers/download.py): `backend/routers/download.py`
- [Task manager](https://github.com/volcyano42/novel-downloader/blob/main/backend/services/task_manager.py): `backend/services/task_manager.py`
- [Engine manager](https://github.com/volcyano42/novel-downloader/blob/main/backend/services/engine_manager.py): `backend/services/engine_manager.py`
- [Export API](https://github.com/volcyano42/novel-downloader/blob/main/backend/routers/export.py): `backend/routers/export.py`
- [Config API](https://github.com/volcyano42/novel-downloader/blob/main/backend/routers/config.py): `backend/routers/config.py`
- [History API](https://github.com/volcyano42/novel-downloader/blob/main/backend/routers/history.py): `backend/routers/history.py`
- [Bookshelf API](https://github.com/volcyano42/novel-downloader/blob/main/backend/routers/storage.py): `backend/routers/storage.py`

### Novel runtime

- [Download workflow](https://github.com/volcyano42/novel-downloader/blob/main/novelbase/core/downloader.py): `novelbase/core/downloader.py`
- [Fetch engines](https://github.com/volcyano42/novel-downloader/blob/main/novelbase/core/engine.py): `novelbase/core/engine.py`
- [Novel models](https://github.com/volcyano42/novel-downloader/blob/main/novelbase/models/novel.py): `novelbase/models/novel.py`
- [Novel storage](https://github.com/volcyano42/novel-downloader/blob/main/novelbase/core/storage.py): `novelbase/core/storage.py`
- [Book exporters](https://github.com/volcyano42/novel-downloader/blob/main/novelbase/exporter.py): `novelbase/exporter.py`

### Source adapters

- [Source registry](https://github.com/volcyano42/novel-downloader/blob/main/novelbase/source.py): `novelbase/source.py`
- [Source manifests](https://github.com/volcyano42/novel-downloader/blob/main/novelbase/sources/manifest.py): `novelbase/sources/manifest.py`
- [Source adapters](https://github.com/volcyano42/novel-downloader/tree/main/novelbase/sources): `novelbase/sources`

### Configuration and data

- [Runtime config](https://github.com/volcyano42/novel-downloader/blob/main/shared/config.py): `shared/config.py`
- [User library data](https://github.com/volcyano42/novel-downloader/blob/main/shared/user_data.py): `shared/user_data.py`

### Other components

- **User**

## Connections

- User → Web UI: uses
- User → CLI: runs
- Web UI → API client: requests
- API client → FastAPI app: HTTP calls
- FastAPI app → Download API: mounts (evidence: `backend/main.py`)
- FastAPI app → Export API: mounts (evidence: `backend/main.py`)
- FastAPI app → Config API: mounts (evidence: `backend/main.py`)
- FastAPI app → History API: mounts (evidence: `backend/main.py`)
- FastAPI app → Bookshelf API: mounts (evidence: `backend/main.py`)
- Download API → Task manager: manages tasks (evidence: `backend/routers/download.py`)
- Download API → Engine manager: requests engines (evidence: `backend/routers/download.py`)
- Task manager → Engine manager: gets engines (evidence: `backend/services/task_manager.py`)
- Task manager → Novel storage: creates store (evidence: `backend/services/task_manager.py`)
- Engine manager → Runtime config: loads settings (evidence: `backend/services/engine_manager.py`)
- Engine manager → Fetch engines: creates engine (evidence: `backend/services/engine_manager.py`)
- Fetch engines → Source registry: dispatches capabilities
- Source registry → Source manifests: loads manifests (evidence: `novelbase/source.py`)
- Source registry → Source adapters: loads adapter (evidence: `novelbase/source.py`)
- CLI → Download workflow: calls workflows (evidence: `cli/main.py`)
- Download workflow → Fetch engines: fetches source data (evidence: `novelbase/__init__.py`)
- Download workflow → Novel models: builds results
- Export API → Novel storage: reads book data (evidence: `backend/routers/export.py`)
- Export API → Book exporters: selects format (evidence: `backend/routers/export.py`)
- Bookshelf API → Novel storage: reads and writes (evidence: `backend/routers/storage.py`)
- Bookshelf API → User library data: tracks sources (evidence: `backend/routers/storage.py`)
- History API → User library data: reads history (evidence: `backend/routers/history.py`)
- Config API → Runtime config: reads settings (evidence: `backend/routers/config.py`)
- Config API → Source registry: validates sources (evidence: `backend/routers/config.py`)
- Bookshelf UI → API client: requests data
- Book details → API client: requests details
- Reader → API client: requests chapters
- Bookshelf API → Novel models: serializes metadata (evidence: `backend/routers/storage.py`)
