# yash-dhanda/manhwamaniacs architecture

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

- Interactive diagram: https://gitdiagram.com/yash-dhanda/manhwamaniacs
- Repository: https://github.com/yash-dhanda/manhwamaniacs

## Overview

ManhwaManiacs is a self-hosted, multi-source manga/manhwa and novel reader. The main journey is to browse or search source catalogs, open a series and chapter, then read while retaining profile-specific follows and progress; clients can also save chapters for offline use. The backend exposes the API, coordinates source connectors and persists account/library data in SQLite. The README documents OCR, novels/audio, backups, and mobile clients as additional capabilities. Sampled source is partial, so the graph shows documented subsystem boundaries without asserting unsampled internal call wiring.

Main entry points: [`backend/routes`](https://github.com/yash-dhanda/manhwamaniacs/tree/master/backend/routes) (API routes), [`backend/main.py`](https://github.com/yash-dhanda/manhwamaniacs/blob/master/backend/main.py) (FastAPI app), [`backend/database`](https://github.com/yash-dhanda/manhwamaniacs/tree/master/backend/database) (SQLite database), [`backend/services/browse_service.py`](https://github.com/yash-dhanda/manhwamaniacs/blob/master/backend/services/browse_service.py) (Browse and source services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Reader clients"]
  node_reader["Reader<br/>[page.tsx]"]
  node_library_ui["Library and search"]
  node_novel_ui["Novel reader"]
  node_offline["Offline reading"]
  node_profile["Profile preferences"]
end

subgraph group_api["API and domain"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_api_routes["API routes"]
  node_auth["Authentication<br/>[auth_service.py]"]
  node_browse["Browse and source services<br/>[browse_service.py]"]
  node_reader_service["Reading services<br/>[reader_service.py]"]
  node_ocr["OCR ingest and search"]
  node_novel_service["Novel and audio services<br/>[novel_service.py]"]
  node_backup["Backup and restore<br/>[backup_service.py]"]
  node_render_service["Novel render queue"]
end

subgraph group_sources["Source ingestion"]
  node_connectors["Source connectors"]
  node_registry["Connector registry<br/>[registry.py]"]
end

subgraph group_state["Persistence and jobs"]
  node_database[("SQLite database")]
  node_render_worker["Audio render worker<br/>[render_worker.py]"]
end

node_user(("Household reader"))
node_external_sources(("External catalogs"))

node_user -->|"reads chapters"| node_reader
node_user -->|"browses library"| node_library_ui
node_user -->|"reads novels"| node_novel_ui
node_user -->|"saves chapters"| node_offline
node_library_ui -->|"requests catalog"| node_api_app
node_reader -->|"requests chapters"| node_api_app
node_novel_ui -->|"requests novels"| node_api_app
node_offline -->|"downloads chapters"| node_api_app
node_profile -->|"manages profiles"| node_api_app
node_api_app -->|"dispatches requests"| node_api_routes
node_api_routes -->|"authenticates"| node_auth
node_api_routes -->|"browses sources"| node_browse
node_api_routes -->|"serves reading"| node_reader_service
node_api_routes -->|"handles OCR"| node_ocr
node_api_routes -->|"serves novels"| node_novel_service
node_api_routes -->|"handles backups"| node_backup
node_browse -->|"resolves connectors"| node_registry
node_registry -->|"selects source"| node_connectors
node_connectors -->|"fetches metadata"| node_external_sources
node_auth -->|"reads and writes"| node_database
node_browse -->|"caches catalog"| node_database
node_reader_service -->|"stores progress"| node_database
node_ocr -->|"stores OCR text"| node_database
node_novel_service -->|"stores novel state"| node_database
node_backup -->|"backs up data"| node_database
node_api_routes -->|"queues rendering"| node_render_service
node_render_worker -.->|"polls and reports"| node_api_app

click node_reader "https://github.com/yash-dhanda/manhwamaniacs/blob/master/frontend/src/app/reader/%5BsourceId%5D/%5BseriesKey%5D/%5B...chapterKey%5D/page.tsx"
click node_library_ui "https://github.com/yash-dhanda/manhwamaniacs/tree/master/frontend/src/features/library"
click node_novel_ui "https://github.com/yash-dhanda/manhwamaniacs/tree/master/frontend/src/features/novels"
click node_offline "https://github.com/yash-dhanda/manhwamaniacs/tree/master/frontend/src/features/offline"
click node_api_app "https://github.com/yash-dhanda/manhwamaniacs/blob/master/backend/main.py"
click node_api_routes "https://github.com/yash-dhanda/manhwamaniacs/tree/master/backend/routes"
click node_auth "https://github.com/yash-dhanda/manhwamaniacs/blob/master/backend/services/auth_service.py"
click node_browse "https://github.com/yash-dhanda/manhwamaniacs/blob/master/backend/services/browse_service.py"
click node_reader_service "https://github.com/yash-dhanda/manhwamaniacs/blob/master/backend/services/reader_service.py"
click node_ocr "https://github.com/yash-dhanda/manhwamaniacs/blob/master/backend/services/ocr_ingest_service.py"
click node_novel_service "https://github.com/yash-dhanda/manhwamaniacs/blob/master/backend/services/novel_service.py"
click node_backup "https://github.com/yash-dhanda/manhwamaniacs/blob/master/backend/services/backup_service.py"
click node_connectors "https://github.com/yash-dhanda/manhwamaniacs/tree/master/backend/connectors"
click node_registry "https://github.com/yash-dhanda/manhwamaniacs/blob/master/backend/connectors/registry.py"
click node_database "https://github.com/yash-dhanda/manhwamaniacs/tree/master/backend/database"
click node_profile "https://github.com/yash-dhanda/manhwamaniacs/tree/master/frontend/src/features/profiles"
click node_render_worker "https://github.com/yash-dhanda/manhwamaniacs/blob/master/tools/tts/render_worker.py"
click node_render_service "https://github.com/yash-dhanda/manhwamaniacs/blob/master/backend/services/novel_render_queue.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_library_ui,node_novel_ui,node_offline,node_profile toneBlue
class node_api_app,node_api_routes,node_auth,node_browse,node_reader_service,node_ocr,node_novel_service,node_backup,node_render_service toneAmber
class node_connectors,node_registry toneMint
class node_database,node_render_worker toneRose
class node_user,node_external_sources toneIndigo
```

## Components

### Reader clients

- [Reader](https://github.com/yash-dhanda/manhwamaniacs/blob/master/frontend/src/app/reader/%5BsourceId%5D/%5BseriesKey%5D/%5B...chapterKey%5D/page.tsx): `frontend/src/app/reader/[sourceId]/[seriesKey]/[...chapterKey]/page.tsx`
- [Library and search](https://github.com/yash-dhanda/manhwamaniacs/tree/master/frontend/src/features/library): `frontend/src/features/library`
- [Novel reader](https://github.com/yash-dhanda/manhwamaniacs/tree/master/frontend/src/features/novels): `frontend/src/features/novels`
- [Offline reading](https://github.com/yash-dhanda/manhwamaniacs/tree/master/frontend/src/features/offline): `frontend/src/features/offline`
- [Profile preferences](https://github.com/yash-dhanda/manhwamaniacs/tree/master/frontend/src/features/profiles): `frontend/src/features/profiles`

### API and domain

- [FastAPI app](https://github.com/yash-dhanda/manhwamaniacs/blob/master/backend/main.py): `backend/main.py`
- [API routes](https://github.com/yash-dhanda/manhwamaniacs/tree/master/backend/routes): `backend/routes`
- [Authentication](https://github.com/yash-dhanda/manhwamaniacs/blob/master/backend/services/auth_service.py): `backend/services/auth_service.py`
- [Browse and source services](https://github.com/yash-dhanda/manhwamaniacs/blob/master/backend/services/browse_service.py): `backend/services/browse_service.py`
- [Reading services](https://github.com/yash-dhanda/manhwamaniacs/blob/master/backend/services/reader_service.py): `backend/services/reader_service.py`
- [OCR ingest and search](https://github.com/yash-dhanda/manhwamaniacs/blob/master/backend/services/ocr_ingest_service.py): `backend/services/ocr_ingest_service.py`
- [Novel and audio services](https://github.com/yash-dhanda/manhwamaniacs/blob/master/backend/services/novel_service.py): `backend/services/novel_service.py`
- [Backup and restore](https://github.com/yash-dhanda/manhwamaniacs/blob/master/backend/services/backup_service.py): `backend/services/backup_service.py`
- [Novel render queue](https://github.com/yash-dhanda/manhwamaniacs/blob/master/backend/services/novel_render_queue.py): `backend/services/novel_render_queue.py`

### Source ingestion

- [Source connectors](https://github.com/yash-dhanda/manhwamaniacs/tree/master/backend/connectors): `backend/connectors`
- [Connector registry](https://github.com/yash-dhanda/manhwamaniacs/blob/master/backend/connectors/registry.py): `backend/connectors/registry.py`

### Persistence and jobs

- [SQLite database](https://github.com/yash-dhanda/manhwamaniacs/tree/master/backend/database): `backend/database`
- [Audio render worker](https://github.com/yash-dhanda/manhwamaniacs/blob/master/tools/tts/render_worker.py): `tools/tts/render_worker.py`

### Other components

- **Household reader**
- **External catalogs**

## Connections

- Household reader → Reader: reads chapters
- Household reader → Library and search: browses library
- Household reader → Novel reader: reads novels
- Household reader → Offline reading: saves chapters
- Library and search → FastAPI app: requests catalog
- Reader → FastAPI app: requests chapters
- Novel reader → FastAPI app: requests novels
- Offline reading → FastAPI app: downloads chapters
- Profile preferences → FastAPI app: manages profiles
- FastAPI app → API routes: dispatches requests
- API routes → Authentication: authenticates
- API routes → Browse and source services: browses sources
- API routes → Reading services: serves reading
- API routes → OCR ingest and search: handles OCR
- API routes → Novel and audio services: serves novels
- API routes → Backup and restore: handles backups
- Browse and source services → Connector registry: resolves connectors
- Connector registry → Source connectors: selects source
- Source connectors → External catalogs: fetches metadata
- Authentication → SQLite database: reads and writes
- Browse and source services → SQLite database: caches catalog
- Reading services → SQLite database: stores progress
- OCR ingest and search → SQLite database: stores OCR text
- Novel and audio services → SQLite database: stores novel state
- Backup and restore → SQLite database: backs up data
- API routes → Novel render queue: queues rendering
- Audio render worker → FastAPI app: polls and reports