# sywyar/pixivdownloader architecture

> Architecture diagram of the GitHub repository sywyar/pixivdownloader, 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/sywyar/pixivdownloader
- Repository: https://github.com/sywyar/pixivdownloader

## Overview

PixivDownloader is a local Pixiv work discovery, download, and library-management application, with a web workbench, desktop GUI, and companion userscripts. The main workflow is to submit works or discover them through batch, user, search, series, or Pixiv-page inputs; process queued downloads; save media and metadata locally; and browse the resulting galleries. Other documented capabilities include scheduled downloads, novel translation and narration, duplicate detection, notifications, and plugin extensions. The README documents these branches, but excerpts do not establish all their internal call wiring, so uncertain links are omitted.

Main entry points: [`pixivdownload-app/src/main/java/top/sywyar/pixivdownload/core/download`](https://github.com/sywyar/pixivdownloader/tree/master/pixivdownload-app/src/main/java/top/sywyar/pixivdownload/core/download) (Download API), [`pixivdownload-app/src/main/java/top/sywyar/pixivdownload/core/db/PixivDatabase.java`](https://github.com/sywyar/pixivdownloader/blob/master/pixivdownload-app/src/main/java/top/sywyar/pixivdownload/core/db/PixivDatabase.java) (Local database), [`pixivdownload-app/src/main/java/top/sywyar/pixivdownload/core/hash/ArtworkHashService.java`](https://github.com/sywyar/pixivdownloader/blob/master/pixivdownload-app/src/main/java/top/sywyar/pixivdownload/core/hash/ArtworkHashService.java) (Duplicate detection), [`pixivdownload-plugin-download-workbench/src/main/java/top/sywyar/pixivdownload/schedule/ScheduleService.java`](https://github.com/sywyar/pixivdownloader/blob/master/pixivdownload-plugin-download-workbench/src/main/java/top/sywyar/pixivdownload/schedule/ScheduleService.java) (Scheduled downloads)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Discovery and input"]
  node_workbench["Web download workbench"]
  node_urlscript["URL batch script"]
  node_userscript["User batch script"]
  node_pagescript["Page scrape script"]
  node_toolboxscript["Pixiv toolbox script"]
  node_singlework["Single-work scripts"]
end

subgraph group_download["Download processing"]
  node_downloadapi["Download API"]
  node_pixivclient["Pixiv access"]
  node_imageprocess["Media conversion<br/>[UgoiraService.java]"]
  node_downloadhistory["Download history"]
end

subgraph group_library["Local library"]
  node_metadata["Work metadata"]
  node_database[("Local database<br/>[PixivDatabase.java]")]
  node_gallery["Work galleries"]
  node_hashing["Duplicate detection"]
end

subgraph group_extensions["Automation and extensions"]
  node_scheduler["Scheduled downloads"]
  node_novels["Novel capabilities"]
  node_plugins["Plugin lifecycle"]
  node_notifications["Notifications"]
end

subgraph group_experience["User experience"]
  node_desktop["Desktop GUI<br/>[GuiLauncher.java]"]
  node_backend["Application backend"]
end

node_user(("Pixiv user"))
node_pixiv(("Pixiv"))
node_localfiles[("Media files")]

node_user -->|"submits works"| node_workbench
node_user -->|"imports URLs"| node_urlscript
node_user -->|"selects user"| node_userscript
node_user -->|"scrapes pages"| node_pagescript
node_user -->|"uses tools"| node_toolboxscript
node_user -->|"downloads work"| node_singlework
node_workbench -->|"sends downloads"| node_downloadapi
node_urlscript -.->|"reads works"| node_pixiv
node_userscript -.->|"reads works"| node_pixiv
node_pagescript -.->|"scrapes pages"| node_pixiv
node_singlework -.->|"fetches media"| node_pixiv
node_downloadapi -->|"requests Pixiv"| node_pixivclient
node_pixivclient -->|"fetches works"| node_pixiv
node_downloadapi -.->|"converts media"| node_imageprocess
node_imageprocess -->|"writes outputs"| node_localfiles
node_downloadapi -->|"saves media"| node_localfiles
node_downloadapi -->|"records downloads"| node_downloadhistory
node_downloadhistory -->|"updates records"| node_database
node_metadata -->|"queries metadata"| node_database
node_gallery -->|"queries works"| node_metadata
node_hashing -->|"indexes hashes"| node_database
node_hashing -->|"checks images"| node_localfiles
node_scheduler -->|"stores schedules"| node_database
node_scheduler -.->|"runs downloads"| node_downloadapi
node_novels -->|"stores novel data"| node_database
node_user -->|"uses application"| node_desktop
node_desktop -->|"launches backend"| node_backend
node_plugins -->|"extends runtime"| node_backend
node_notifications -->|"stores inbox"| node_database

click node_workbench "https://github.com/sywyar/pixivdownloader/blob/master/pixivdownload-plugin-download-workbench/src/main/resources/static/pixiv-batch-alt/alt-engine-workers.js"
click node_urlscript "https://github.com/sywyar/pixivdownloader/blob/master/Pixiv%20URL%20%E6%89%B9%E9%87%8F%E5%AF%BC%E5%85%A5%E5%8D%95%E4%BD%9C%E5%93%81%E4%B8%8B%E8%BD%BD%E5%99%A8(URL%20Batch).user.js"
click node_userscript "https://github.com/sywyar/pixivdownloader/blob/master/Pixiv%20User%20%E6%89%B9%E9%87%8F%E4%B8%8B%E8%BD%BD%E5%99%A8(User%20Batch).user.js"
click node_pagescript "https://github.com/sywyar/pixivdownloader/blob/master/Pixiv%20%E9%A1%B5%E9%9D%A2%E6%89%B9%E9%87%8F%E4%B8%8B%E8%BD%BD%E5%99%A8(Page%20Scrape).user.js"
click node_toolboxscript "https://github.com/sywyar/pixivdownloader/blob/master/Pixiv%20%E4%BD%93%E9%AA%8C%E5%A2%9E%E5%BC%BA%E5%B7%A5%E5%85%B7%E7%AE%B1(Toolbox).user.js"
click node_singlework "https://github.com/sywyar/pixivdownloader/blob/master/Pixiv%20%E5%8D%95%E4%BD%9C%E5%93%81%E5%9B%BE%E7%89%87%E4%B8%8B%E8%BD%BD%E5%99%A8(Local%20Download).user.js"
click node_downloadapi "https://github.com/sywyar/pixivdownloader/tree/master/pixivdownload-app/src/main/java/top/sywyar/pixivdownload/core/download"
click node_pixivclient "https://github.com/sywyar/pixivdownloader/tree/master/pixivdownload-app/src/main/java/top/sywyar/pixivdownload/core/pixiv"
click node_imageprocess "https://github.com/sywyar/pixivdownloader/blob/master/pixivdownload-plugin-download-workbench/src/main/java/top/sywyar/pixivdownload/download/UgoiraService.java"
click node_downloadhistory "https://github.com/sywyar/pixivdownloader/blob/master/pixivdownload-app/src/main/java/top/sywyar/pixivdownload/core/download/DownloadedArtworkService.java"
click node_metadata "https://github.com/sywyar/pixivdownloader/blob/master/pixivdownload-app/src/main/java/top/sywyar/pixivdownload/core/metadata/CoreWorkQueryService.java"
click node_database "https://github.com/sywyar/pixivdownloader/blob/master/pixivdownload-app/src/main/java/top/sywyar/pixivdownload/core/db/PixivDatabase.java"
click node_gallery "https://github.com/sywyar/pixivdownloader/blob/master/pixivdownload-core-api/src/main/java/top/sywyar/pixivdownload/core/work/service/WorkQueryService.java"
click node_hashing "https://github.com/sywyar/pixivdownloader/blob/master/pixivdownload-app/src/main/java/top/sywyar/pixivdownload/core/hash/ArtworkHashService.java"
click node_scheduler "https://github.com/sywyar/pixivdownloader/blob/master/pixivdownload-plugin-download-workbench/src/main/java/top/sywyar/pixivdownload/schedule/ScheduleService.java"
click node_novels "https://github.com/sywyar/pixivdownloader/tree/master/pixivdownload-app/src/main/java/top/sywyar/pixivdownload/core/metadata/novel"
click node_plugins "https://github.com/sywyar/pixivdownloader/blob/master/pixivdownload-app/src/main/java/top/sywyar/pixivdownload/plugin/lifecycle/PluginLifecycleService.java"
click node_notifications "https://github.com/sywyar/pixivdownloader/blob/master/pixivdownload-plugin-notification/src/main/java/top/sywyar/pixivdownload/notificationbase/NotificationInboxService.java"
click node_desktop "https://github.com/sywyar/pixivdownloader/blob/master/pixivdownload-app/src/main/java/top/sywyar/pixivdownload/gui/GuiLauncher.java"
click node_backend "https://github.com/sywyar/pixivdownloader/blob/master/pixivdownload-app/src/main/java/top/sywyar/pixivdownload/PixivDownloadApplication.java"

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_workbench,node_urlscript,node_userscript,node_pagescript,node_toolboxscript,node_singlework,node_user toneBlue
class node_downloadapi,node_pixivclient,node_imageprocess,node_downloadhistory,node_localfiles toneAmber
class node_metadata,node_database,node_gallery,node_hashing toneMint
class node_scheduler,node_novels,node_plugins,node_notifications toneRose
class node_desktop,node_backend,node_pixiv toneIndigo
```

## Components

### Discovery and input

- [Web download workbench](https://github.com/sywyar/pixivdownloader/blob/master/pixivdownload-plugin-download-workbench/src/main/resources/static/pixiv-batch-alt/alt-engine-workers.js): `pixivdownload-plugin-download-workbench/src/main/resources/static/pixiv-batch-alt/alt-engine-workers.js`
- [URL batch script](https://github.com/sywyar/pixivdownloader/blob/master/Pixiv%20URL%20%E6%89%B9%E9%87%8F%E5%AF%BC%E5%85%A5%E5%8D%95%E4%BD%9C%E5%93%81%E4%B8%8B%E8%BD%BD%E5%99%A8(URL%20Batch).user.js): `Pixiv URL 批量导入单作品下载器(URL Batch).user.js`
- [User batch script](https://github.com/sywyar/pixivdownloader/blob/master/Pixiv%20User%20%E6%89%B9%E9%87%8F%E4%B8%8B%E8%BD%BD%E5%99%A8(User%20Batch).user.js): `Pixiv User 批量下载器(User Batch).user.js`
- [Page scrape script](https://github.com/sywyar/pixivdownloader/blob/master/Pixiv%20%E9%A1%B5%E9%9D%A2%E6%89%B9%E9%87%8F%E4%B8%8B%E8%BD%BD%E5%99%A8(Page%20Scrape).user.js): `Pixiv 页面批量下载器(Page Scrape).user.js`
- [Pixiv toolbox script](https://github.com/sywyar/pixivdownloader/blob/master/Pixiv%20%E4%BD%93%E9%AA%8C%E5%A2%9E%E5%BC%BA%E5%B7%A5%E5%85%B7%E7%AE%B1(Toolbox).user.js): `Pixiv 体验增强工具箱(Toolbox).user.js`
- [Single-work scripts](https://github.com/sywyar/pixivdownloader/blob/master/Pixiv%20%E5%8D%95%E4%BD%9C%E5%93%81%E5%9B%BE%E7%89%87%E4%B8%8B%E8%BD%BD%E5%99%A8(Local%20Download).user.js): `Pixiv 单作品图片下载器(Local Download).user.js`

### Download processing

- [Download API](https://github.com/sywyar/pixivdownloader/tree/master/pixivdownload-app/src/main/java/top/sywyar/pixivdownload/core/download): `pixivdownload-app/src/main/java/top/sywyar/pixivdownload/core/download`
- [Pixiv access](https://github.com/sywyar/pixivdownloader/tree/master/pixivdownload-app/src/main/java/top/sywyar/pixivdownload/core/pixiv): `pixivdownload-app/src/main/java/top/sywyar/pixivdownload/core/pixiv`
- [Media conversion](https://github.com/sywyar/pixivdownloader/blob/master/pixivdownload-plugin-download-workbench/src/main/java/top/sywyar/pixivdownload/download/UgoiraService.java): `pixivdownload-plugin-download-workbench/src/main/java/top/sywyar/pixivdownload/download/UgoiraService.java`
- [Download history](https://github.com/sywyar/pixivdownloader/blob/master/pixivdownload-app/src/main/java/top/sywyar/pixivdownload/core/download/DownloadedArtworkService.java): `pixivdownload-app/src/main/java/top/sywyar/pixivdownload/core/download/DownloadedArtworkService.java`

### Local library

- [Work metadata](https://github.com/sywyar/pixivdownloader/blob/master/pixivdownload-app/src/main/java/top/sywyar/pixivdownload/core/metadata/CoreWorkQueryService.java): `pixivdownload-app/src/main/java/top/sywyar/pixivdownload/core/metadata/CoreWorkQueryService.java`
- [Local database](https://github.com/sywyar/pixivdownloader/blob/master/pixivdownload-app/src/main/java/top/sywyar/pixivdownload/core/db/PixivDatabase.java): `pixivdownload-app/src/main/java/top/sywyar/pixivdownload/core/db/PixivDatabase.java`
- [Work galleries](https://github.com/sywyar/pixivdownloader/blob/master/pixivdownload-core-api/src/main/java/top/sywyar/pixivdownload/core/work/service/WorkQueryService.java): `pixivdownload-core-api/src/main/java/top/sywyar/pixivdownload/core/work/service/WorkQueryService.java`
- [Duplicate detection](https://github.com/sywyar/pixivdownloader/blob/master/pixivdownload-app/src/main/java/top/sywyar/pixivdownload/core/hash/ArtworkHashService.java): `pixivdownload-app/src/main/java/top/sywyar/pixivdownload/core/hash/ArtworkHashService.java`

### Automation and extensions

- [Scheduled downloads](https://github.com/sywyar/pixivdownloader/blob/master/pixivdownload-plugin-download-workbench/src/main/java/top/sywyar/pixivdownload/schedule/ScheduleService.java): `pixivdownload-plugin-download-workbench/src/main/java/top/sywyar/pixivdownload/schedule/ScheduleService.java`
- [Novel capabilities](https://github.com/sywyar/pixivdownloader/tree/master/pixivdownload-app/src/main/java/top/sywyar/pixivdownload/core/metadata/novel): `pixivdownload-app/src/main/java/top/sywyar/pixivdownload/core/metadata/novel`
- [Plugin lifecycle](https://github.com/sywyar/pixivdownloader/blob/master/pixivdownload-app/src/main/java/top/sywyar/pixivdownload/plugin/lifecycle/PluginLifecycleService.java): `pixivdownload-app/src/main/java/top/sywyar/pixivdownload/plugin/lifecycle/PluginLifecycleService.java`
- [Notifications](https://github.com/sywyar/pixivdownloader/blob/master/pixivdownload-plugin-notification/src/main/java/top/sywyar/pixivdownload/notificationbase/NotificationInboxService.java): `pixivdownload-plugin-notification/src/main/java/top/sywyar/pixivdownload/notificationbase/NotificationInboxService.java`

### User experience

- [Desktop GUI](https://github.com/sywyar/pixivdownloader/blob/master/pixivdownload-app/src/main/java/top/sywyar/pixivdownload/gui/GuiLauncher.java): `pixivdownload-app/src/main/java/top/sywyar/pixivdownload/gui/GuiLauncher.java`
- [Application backend](https://github.com/sywyar/pixivdownloader/blob/master/pixivdownload-app/src/main/java/top/sywyar/pixivdownload/PixivDownloadApplication.java): `pixivdownload-app/src/main/java/top/sywyar/pixivdownload/PixivDownloadApplication.java`

### Other components

- **Pixiv user**
- **Pixiv**
- **Media files**

## Connections

- Pixiv user → Web download workbench: submits works
- Pixiv user → URL batch script: imports URLs
- Pixiv user → User batch script: selects user
- Pixiv user → Page scrape script: scrapes pages
- Pixiv user → Pixiv toolbox script: uses tools
- Pixiv user → Single-work scripts: downloads work
- Web download workbench → Download API: sends downloads
- URL batch script → Pixiv: reads works
- User batch script → Pixiv: reads works
- Page scrape script → Pixiv: scrapes pages
- Single-work scripts → Pixiv: fetches media
- Download API → Pixiv access: requests Pixiv
- Pixiv access → Pixiv: fetches works
- Download API → Media conversion: converts media
- Media conversion → Media files: writes outputs
- Download API → Media files: saves media
- Download API → Download history: records downloads
- Download history → Local database: updates records
- Work metadata → Local database: queries metadata
- Work galleries → Work metadata: queries works
- Duplicate detection → Local database: indexes hashes
- Duplicate detection → Media files: checks images
- Scheduled downloads → Local database: stores schedules
- Scheduled downloads → Download API: runs downloads
- Novel capabilities → Local database: stores novel data
- Pixiv user → Desktop GUI: uses application
- Desktop GUI → Application backend: launches backend
- Plugin lifecycle → Application backend: extends runtime
- Notifications → Local database: stores inbox