# kent-lee/pixiv-scraper architecture

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

- Interactive diagram: https://gitdiagram.com/kent-lee/pixiv-scraper
- Repository: https://github.com/kent-lee/pixiv-scraper

## Overview

Pixiv Scraper is a command-line downloader for user artworks, bookmarks, and ranking results. The workflow starts with CLI options and persisted configuration, then logs in, fetches artwork metadata from Pixiv, detects already-downloaded items, downloads original images into categorized directories, and summarizes the result. The graph separates orchestration, configuration, Pixiv retrieval, and local file handling. README-described capabilities are included; implementation details beyond the excerpts are omitted where their relationships cannot be verified.

Main entry points: [`lib/pixiv.py`](https://github.com/kent-lee/pixiv-scraper/blob/master/lib/pixiv.py) (Pixiv API), [`main.py`](https://github.com/kent-lee/pixiv-scraper/blob/master/main.py) (CLI workflow), [`lib/config.py`](https://github.com/kent-lee/pixiv-scraper/blob/master/lib/config.py) (Settings manager), [`lib/cmd.py`](https://github.com/kent-lee/pixiv-scraper/blob/master/lib/cmd.py) (Command options)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and orchestration"]
  node_entry["CLI workflow<br/>[main.py]"]
  node_arguments["Command options<br/>[cmd.py]"]
  node_summary["Download summary<br/>[main.py]"]
end

subgraph group_settings["Configuration"]
  node_config["Settings manager<br/>[config.py]"]
  node_config_file["Config JSON<br/>[config.json]"]
end

subgraph group_pixiv["Pixiv access"]
  node_api["Pixiv API<br/>[pixiv.py]"]
  node_artwork_listing["User artwork listing<br/>[pixiv.py]"]
  node_bookmark_listing["Bookmark listing<br/>[pixiv.py]"]
  node_ranking_listing["Ranking listing<br/>[pixiv.py]"]
  node_artwork_detail["Artwork metadata<br/>[pixiv.py]"]
  node_image_download["Image download<br/>[pixiv.py]"]
end

subgraph group_storage["Local storage"]
  node_directories[("Artwork directories")]
  node_file_helpers["File utilities<br/>[utils.py]"]
end

node_user(("Operator"))
node_pixiv_service{{"Pixiv service"}}

node_user -->|"provides options"| node_arguments
node_entry -->|"parses via"| node_arguments
node_entry -->|"loads settings"| node_config
node_config -->|"reads and writes"| node_config_file
node_entry -->|"logs in and dispatches"| node_api
node_config -->|"validates user IDs"| node_api
node_api -->|"requests data"| node_pixiv_service
node_api -->|"fetches user artworks"| node_artwork_listing
node_api -->|"fetches bookmarks"| node_bookmark_listing
node_api -->|"fetches rankings"| node_ranking_listing
node_artwork_listing -->|"loads metadata"| node_artwork_detail
node_bookmark_listing -->|"loads metadata"| node_artwork_detail
node_ranking_listing -->|"loads metadata"| node_artwork_detail
node_artwork_detail -->|"provides image URLs"| node_image_download
node_image_download -->|"downloads originals"| node_pixiv_service
node_api -->|"checks and timestamps files"| node_file_helpers
node_config -->|"manages directories"| node_file_helpers
node_image_download -->|"writes artwork files"| node_directories
node_entry -->|"prints totals"| node_summary
node_api -->|"returns download totals"| node_summary

click node_entry "https://github.com/kent-lee/pixiv-scraper/blob/master/main.py"
click node_arguments "https://github.com/kent-lee/pixiv-scraper/blob/master/lib/cmd.py"
click node_config "https://github.com/kent-lee/pixiv-scraper/blob/master/lib/config.py"
click node_config_file "https://github.com/kent-lee/pixiv-scraper/blob/master/data/config.json"
click node_api "https://github.com/kent-lee/pixiv-scraper/blob/master/lib/pixiv.py"
click node_artwork_listing "https://github.com/kent-lee/pixiv-scraper/blob/master/lib/pixiv.py"
click node_bookmark_listing "https://github.com/kent-lee/pixiv-scraper/blob/master/lib/pixiv.py"
click node_ranking_listing "https://github.com/kent-lee/pixiv-scraper/blob/master/lib/pixiv.py"
click node_artwork_detail "https://github.com/kent-lee/pixiv-scraper/blob/master/lib/pixiv.py"
click node_image_download "https://github.com/kent-lee/pixiv-scraper/blob/master/lib/pixiv.py"
click node_file_helpers "https://github.com/kent-lee/pixiv-scraper/blob/master/lib/utils.py"
click node_summary "https://github.com/kent-lee/pixiv-scraper/blob/master/main.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_entry,node_arguments,node_summary toneBlue
class node_config,node_config_file toneAmber
class node_api,node_artwork_listing,node_bookmark_listing,node_ranking_listing,node_artwork_detail,node_image_download toneMint
class node_directories,node_file_helpers toneRose
class node_user,node_pixiv_service toneIndigo
```

## Components

### CLI and orchestration

- [CLI workflow](https://github.com/kent-lee/pixiv-scraper/blob/master/main.py): `main.py`
- [Command options](https://github.com/kent-lee/pixiv-scraper/blob/master/lib/cmd.py): `lib/cmd.py`
- [Download summary](https://github.com/kent-lee/pixiv-scraper/blob/master/main.py): `main.py`

### Configuration

- [Settings manager](https://github.com/kent-lee/pixiv-scraper/blob/master/lib/config.py): `lib/config.py`
- [Config JSON](https://github.com/kent-lee/pixiv-scraper/blob/master/data/config.json): `data/config.json`

### Pixiv access

- [Pixiv API](https://github.com/kent-lee/pixiv-scraper/blob/master/lib/pixiv.py): `lib/pixiv.py`
- [User artwork listing](https://github.com/kent-lee/pixiv-scraper/blob/master/lib/pixiv.py): `lib/pixiv.py`
- [Bookmark listing](https://github.com/kent-lee/pixiv-scraper/blob/master/lib/pixiv.py): `lib/pixiv.py`
- [Ranking listing](https://github.com/kent-lee/pixiv-scraper/blob/master/lib/pixiv.py): `lib/pixiv.py`
- [Artwork metadata](https://github.com/kent-lee/pixiv-scraper/blob/master/lib/pixiv.py): `lib/pixiv.py`
- [Image download](https://github.com/kent-lee/pixiv-scraper/blob/master/lib/pixiv.py): `lib/pixiv.py`

### Local storage

- **Artwork directories**
- [File utilities](https://github.com/kent-lee/pixiv-scraper/blob/master/lib/utils.py): `lib/utils.py`

### Other components

- **Operator**
- **Pixiv service**

## Connections

- Operator → Command options: provides options (evidence: `lib/cmd.py`)
- CLI workflow → Command options: parses via (evidence: `main.py`)
- CLI workflow → Settings manager: loads settings (evidence: `main.py`)
- Settings manager → Config JSON: reads and writes (evidence: `lib/config.py`)
- CLI workflow → Pixiv API: logs in and dispatches (evidence: `main.py`)
- Settings manager → Pixiv API: validates user IDs (evidence: `lib/config.py`)
- Pixiv API → Pixiv service: requests data (evidence: `lib/pixiv.py`)
- Pixiv API → User artwork listing: fetches user artworks (evidence: `lib/pixiv.py`)
- Pixiv API → Bookmark listing: fetches bookmarks (evidence: `lib/pixiv.py`)
- Pixiv API → Ranking listing: fetches rankings (evidence: `lib/pixiv.py`)
- User artwork listing → Artwork metadata: loads metadata (evidence: `lib/pixiv.py`)
- Bookmark listing → Artwork metadata: loads metadata (evidence: `lib/pixiv.py`)
- Ranking listing → Artwork metadata: loads metadata (evidence: `lib/pixiv.py`)
- Artwork metadata → Image download: provides image URLs (evidence: `lib/pixiv.py`)
- Image download → Pixiv service: downloads originals (evidence: `lib/pixiv.py`)
- Pixiv API → File utilities: checks and timestamps files (evidence: `lib/pixiv.py`)
- Settings manager → File utilities: manages directories (evidence: `lib/config.py`)
- Image download → Artwork directories: writes artwork files (evidence: `lib/pixiv.py`)
- CLI workflow → Download summary: prints totals (evidence: `main.py`)
- Pixiv API → Download summary: returns download totals (evidence: `main.py`)
