# 0xh4ku/comix-downloader architecture

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

- Interactive diagram: https://gitdiagram.com/0xh4ku/comix-downloader
- Repository: https://github.com/0xh4ku/comix-downloader

## Overview

comix-dl is a comix.to manga search and download application. Users enter through the scriptable or interactive CLI, or the optional TUI; these interfaces share an application session for lookup and downloads. The main domain stages are series resolution, chapter selection and deduplication, parallel image retrieval, and optional conversion, with resume state and history supporting recovery. The README documents several capabilities whose implementation was not sampled; those are represented only where the repository tree supports a path, and uncertain internal wiring is omitted.

Main entry points: [`src/comix_dl/core/application/session.py`](https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/application/session.py) (Application session), [`src/comix_dl/core/cli/flows.py`](https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/cli/flows.py) (CLI flows), [`src/comix_dl/core/application/download_usecase.py`](https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/application/download_usecase.py) (Download use case), [`src/comix_dl/sites/comix_to.py`](https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/sites/comix_to.py) (Site adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI flows<br/>[flows.py]"]
  node_tui["TUI shell<br/>[app.py]"]
  node_tui_screens["TUI screens"]
  node_tui_controller["TUI controller<br/>[controller.py]"]
end

subgraph group_application["Application workflow"]
  node_session["Application session<br/>[session.py]"]
  node_query["Series queries<br/>[query_usecase.py]"]
  node_download_uc["Download use case"]
  node_cleanup["Cleanup use case<br/>[cleanup_usecase.py]"]
end

subgraph group_site["comix.to integration"]
  node_site_adapter["Site adapter<br/>[comix_to.py]"]
  node_site_api["Site API<br/>[comix_to_api.py]"]
  node_site_parsing["Site parsing"]
  node_site_dedup["Chapter dedup<br/>[comix_to_dedup.py]"]
end

subgraph group_download["Download and files"]
  node_downloader["Image downloader<br/>[downloader.py]"]
  node_conversion["File conversion<br/>[converters.py]"]
  node_fileio["Download files<br/>[fileio.py]"]
end

subgraph group_runtime["Browser and state"]
  node_browser["CDP browser<br/>[cdp_browser.py]"]
  node_browser_session["Browser lifecycle<br/>[browser_session.py]"]
  node_history["Download history<br/>[history.py]"]
  node_settings["Settings<br/>[settings.py]"]
end

node_user(("User"))
node_chrome["Chrome browser"]
node_comix["comix.to"]
node_filesystem["Local filesystem"]

node_user -->|"runs commands"| node_cli
node_user -.->|"opens interface"| node_tui
node_tui -->|"shows panes"| node_tui_screens
node_tui_screens -->|"requests actions"| node_tui_controller
node_tui_controller -->|"opens session"| node_session
node_cli -->|"opens session"| node_session
node_session -->|"runs lookup"| node_query
node_session -->|"runs download"| node_download_uc
node_query -->|"requests series data"| node_site_adapter
node_site_adapter -->|"uses API"| node_site_api
node_site_adapter -->|"parses responses"| node_site_parsing
node_site_adapter -->|"deduplicates chapters"| node_site_dedup
node_site_api -->|"requests metadata"| node_comix
node_download_uc -->|"downloads chapters"| node_downloader
node_downloader -->|"fetches images"| node_browser
node_browser -->|"uses lifecycle"| node_browser_session
node_browser_session -->|"connects by CDP"| node_chrome
node_browser -->|"accesses site"| node_comix
node_download_uc -->|"converts chapters"| node_conversion
node_downloader -->|"manages download files"| node_fileio
node_conversion -->|"writes converted files"| node_fileio
node_fileio -->|"reads and writes"| node_filesystem
node_cli -->|"requests cleanup"| node_cleanup
node_cleanup -->|"removes raw files"| node_filesystem
node_session -->|"loads settings"| node_settings
node_cli -->|"views history"| node_history
node_download_uc -->|"records results"| node_history

click node_cli "https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/cli/flows.py"
click node_tui "https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/tui/app.py"
click node_tui_screens "https://github.com/0xh4ku/comix-downloader/tree/main/src/comix_dl/core/tui/screens"
click node_tui_controller "https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/tui/controller.py"
click node_session "https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/application/session.py"
click node_query "https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/application/query_usecase.py"
click node_download_uc "https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/application/download_usecase.py"
click node_cleanup "https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/application/cleanup_usecase.py"
click node_site_adapter "https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/sites/comix_to.py"
click node_site_api "https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/sites/comix_to_api.py"
click node_site_parsing "https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/sites/comix_to_parsing.py"
click node_site_dedup "https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/sites/comix_to_dedup.py"
click node_downloader "https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/downloader.py"
click node_conversion "https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/converters.py"
click node_fileio "https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/fileio.py"
click node_browser "https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/engines/cdp_browser.py"
click node_browser_session "https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/engines/browser_session.py"
click node_history "https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/history.py"
click node_settings "https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/settings.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_cli,node_tui,node_tui_screens,node_tui_controller,node_user,node_chrome toneBlue
class node_session,node_query,node_download_uc,node_cleanup toneAmber
class node_site_adapter,node_site_api,node_site_parsing,node_site_dedup toneMint
class node_downloader,node_conversion,node_fileio toneRose
class node_browser,node_browser_session,node_history,node_settings,node_comix,node_filesystem toneIndigo
```

## Components

### User interfaces

- [CLI flows](https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/cli/flows.py): `src/comix_dl/core/cli/flows.py`
- [TUI shell](https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/tui/app.py): `src/comix_dl/core/tui/app.py`
- [TUI screens](https://github.com/0xh4ku/comix-downloader/tree/main/src/comix_dl/core/tui/screens): `src/comix_dl/core/tui/screens`
- [TUI controller](https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/tui/controller.py): `src/comix_dl/core/tui/controller.py`

### Application workflow

- [Application session](https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/application/session.py): `src/comix_dl/core/application/session.py`
- [Series queries](https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/application/query_usecase.py): `src/comix_dl/core/application/query_usecase.py`
- [Download use case](https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/application/download_usecase.py): `src/comix_dl/core/application/download_usecase.py`
- [Cleanup use case](https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/application/cleanup_usecase.py): `src/comix_dl/core/application/cleanup_usecase.py`

### comix.to integration

- [Site adapter](https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/sites/comix_to.py): `src/comix_dl/sites/comix_to.py`
- [Site API](https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/sites/comix_to_api.py): `src/comix_dl/sites/comix_to_api.py`
- [Site parsing](https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/sites/comix_to_parsing.py): `src/comix_dl/sites/comix_to_parsing.py`
- [Chapter dedup](https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/sites/comix_to_dedup.py): `src/comix_dl/sites/comix_to_dedup.py`

### Download and files

- [Image downloader](https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/downloader.py): `src/comix_dl/core/downloader.py`
- [File conversion](https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/converters.py): `src/comix_dl/core/converters.py`
- [Download files](https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/fileio.py): `src/comix_dl/core/fileio.py`

### Browser and state

- [CDP browser](https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/engines/cdp_browser.py): `src/comix_dl/core/engines/cdp_browser.py`
- [Browser lifecycle](https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/engines/browser_session.py): `src/comix_dl/core/engines/browser_session.py`
- [Download history](https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/history.py): `src/comix_dl/core/history.py`
- [Settings](https://github.com/0xh4ku/comix-downloader/blob/main/src/comix_dl/core/settings.py): `src/comix_dl/core/settings.py`

### Other components

- **User**
- **Chrome browser**
- **comix.to**
- **Local filesystem**

## Connections

- User → CLI flows: runs commands
- User → TUI shell: opens interface
- TUI shell → TUI screens: shows panes
- TUI screens → TUI controller: requests actions
- TUI controller → Application session: opens session
- CLI flows → Application session: opens session
- Application session → Series queries: runs lookup
- Application session → Download use case: runs download
- Series queries → Site adapter: requests series data
- Site adapter → Site API: uses API
- Site adapter → Site parsing: parses responses
- Site adapter → Chapter dedup: deduplicates chapters
- Site API → comix.to: requests metadata
- Download use case → Image downloader: downloads chapters
- Image downloader → CDP browser: fetches images
- CDP browser → Browser lifecycle: uses lifecycle
- Browser lifecycle → Chrome browser: connects by CDP
- CDP browser → comix.to: accesses site
- Download use case → File conversion: converts chapters
- Image downloader → Download files: manages download files
- File conversion → Download files: writes converted files
- Download files → Local filesystem: reads and writes
- CLI flows → Cleanup use case: requests cleanup
- Cleanup use case → Local filesystem: removes raw files
- Application session → Settings: loads settings
- CLI flows → Download history: views history
- Download use case → Download history: records results