# yuutara/illustration-archive architecture

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

- Interactive diagram: https://gitdiagram.com/yuutara/illustration-archive
- Repository: https://github.com/yuutara/illustration-archive

## Overview

Illustration Archive is a local-first personal illustration catalog: users import image files, browse paginated galleries, open artwork details, and manage metadata. The main flow validates and stores image content, deduplicates it, persists illustration and asset records, and generates thumbnails; browsing resolves stored assets through content APIs. Separate capabilities cover author/tag management and X Likes synchronization into a reviewable import inbox. The README documents the architecture and capabilities; sampled code confirms selected import, storage, author-search, and X-sync paths, while some subsystem wiring is documented but not sampled.

Main entry points: [`src/main/resources/static/app.js`](https://github.com/yuutara/illustration-archive/blob/master/src/main/resources/static/app.js) (Browser UI), [`src/main/java/com/yuutara/illustrationarchive/service/IllustrationImportService.java`](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/IllustrationImportService.java) (File import), [`src/main/java/com/yuutara/illustrationarchive/service/IllustrationDeleteService.java`](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/IllustrationDeleteService.java) (Deletion workflow), [`src/main/java/com/yuutara/illustrationarchive/service/XLikeSyncService.java`](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/XLikeSyncService.java) (Likes synchronization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_gallery_api["Gallery API"]
  node_detail_api["Detail API"]
  node_asset_api["Asset content API"]
  node_import_api["File import API"]
  node_update_api["Metadata update API"]
  node_delete_api["Delete API"]
  node_author_api["Author API"]
  node_tag_api["Tag API<br/>[TagController.java]"]
  node_x_api["X import API"]
end

subgraph group_catalog["Illustration catalog"]
  node_gallery_service["Gallery queries"]
  node_detail_service["Illustration details"]
  node_import_service["File import"]
  node_batch_service["Batch import"]
  node_persistence_service["Illustration persistence"]
  node_update_service["Metadata editing"]
  node_delete_service["Deletion workflow"]
  node_db_delete["Database deletion"]
  node_author_service["Author management<br/>[AuthorService.java]"]
  node_tag_service["Tag management<br/>[TagService.java]"]
end

subgraph group_xlikes["X Likes archive"]
  node_x_sync["Likes synchronization"]
  node_x_client["X API client<br/>[XApiClient.java]"]
  node_x_persistence["Likes persistence"]
  node_x_import["Inbox import"]
  node_x_download["Photo download"]
  node_x_post["Post persistence"]
end

subgraph group_persistence["Persistence and files"]
  node_repos["SQL repositories"]
  node_author_repo["Author repository"]
  node_tag_repo["Tag repository<br/>[TagRepository.java]"]
  node_x_repos["X repositories"]
  node_file_storage["File storage"]
  node_thumbnail["Thumbnail service"]
end

node_browser(("Browser UI<br/>[app.js]"))
node_mysql[("MySQL")]
node_x_platform(("X platform<br/>external system"))

node_browser -->|"requests gallery"| node_gallery_api
node_browser -->|"uploads files"| node_import_api
node_browser -->|"requests detail"| node_detail_api
node_browser -->|"loads images"| node_asset_api
node_browser -->|"manages inbox"| node_x_api
node_gallery_api -->|"calls"| node_gallery_service
node_detail_api -->|"calls"| node_detail_service
node_asset_api -->|"loads content"| node_file_storage
node_import_api -->|"calls batch"| node_batch_service
node_import_api -->|"calls single"| node_import_service
node_batch_service -->|"imports each"| node_import_service
node_import_service -->|"stores files"| node_file_storage
node_import_service -->|"persists record"| node_persistence_service
node_import_service -->|"generates thumbnail"| node_thumbnail
node_gallery_service -->|"queries page"| node_repos
node_detail_service -->|"queries detail"| node_repos
node_update_api -->|"calls"| node_update_service
node_delete_api -->|"calls"| node_delete_service
node_delete_service -->|"deletes record"| node_db_delete
node_db_delete -->|"reads assets"| node_repos
node_delete_service -->|"cleans thumbnails"| node_thumbnail
node_delete_service -->|"cleans originals"| node_file_storage
node_author_api -->|"calls"| node_author_service
node_author_service -->|"searches and writes"| node_author_repo
node_tag_api -->|"calls"| node_tag_service
node_tag_service -->|"manages tags"| node_tag_repo
node_x_api -->|"syncs and lists"| node_x_sync
node_x_api -->|"imports selection"| node_x_import
node_x_sync -->|"fetches pages"| node_x_client
node_x_sync -->|"saves pages"| node_x_persistence
node_x_sync -->|"reads inbox state"| node_x_repos
node_x_import -->|"downloads photos"| node_x_download
node_x_import -->|"persists posts"| node_x_post
node_x_download -->|"stores photos"| node_file_storage
node_x_client -.->|"calls X"| node_x_platform
node_repos -->|"executes SQL"| node_mysql
node_author_repo -->|"executes SQL"| node_mysql
node_tag_repo -->|"executes SQL"| node_mysql
node_x_repos -->|"executes SQL"| node_mysql

click node_browser "https://github.com/yuutara/illustration-archive/blob/master/src/main/resources/static/app.js"
click node_gallery_api "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/controller/IllustrationGalleryController.java"
click node_detail_api "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/controller/IllustrationDetailController.java"
click node_asset_api "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/controller/AssetContentController.java"
click node_import_api "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/controller/IllustrationImportController.java"
click node_update_api "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/controller/IllustrationUpdateController.java"
click node_delete_api "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/controller/IllustrationDeleteController.java"
click node_author_api "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/controller/AuthorController.java"
click node_tag_api "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/controller/TagController.java"
click node_x_api "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/controller/XImportController.java"
click node_gallery_service "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/IllustrationGalleryService.java"
click node_detail_service "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/IllustrationDetailService.java"
click node_import_service "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/IllustrationImportService.java"
click node_batch_service "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/IllustrationBatchImportService.java"
click node_persistence_service "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/IllustrationPersistenceService.java"
click node_update_service "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/IllustrationUpdateService.java"
click node_delete_service "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/IllustrationDeleteService.java"
click node_db_delete "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/IllustrationDatabaseDeleteService.java"
click node_author_service "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/AuthorService.java"
click node_tag_service "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/TagService.java"
click node_x_sync "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/XLikeSyncService.java"
click node_x_client "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/XApiClient.java"
click node_x_persistence "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/XLikePersistenceService.java"
click node_x_import "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/XImportService.java"
click node_x_download "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/XPhotoDownloadService.java"
click node_x_post "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/XPostPersistenceService.java"
click node_repos "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/repository/IllustrationRepository.java"
click node_author_repo "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/repository/AuthorRepository.java"
click node_tag_repo "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/repository/TagRepository.java"
click node_x_repos "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/repository/XLikeRepository.java"
click node_file_storage "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/storage/FileStorageService.java"
click node_thumbnail "https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/storage/ThumbnailService.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_gallery_api,node_detail_api,node_asset_api,node_import_api,node_update_api,node_delete_api,node_author_api,node_tag_api,node_x_api,node_browser toneBlue
class node_gallery_service,node_detail_service,node_import_service,node_batch_service,node_persistence_service,node_update_service,node_delete_service,node_db_delete,node_author_service,node_tag_service,node_mysql toneAmber
class node_x_sync,node_x_client,node_x_persistence,node_x_import,node_x_download,node_x_post toneMint
class node_repos,node_author_repo,node_tag_repo,node_x_repos,node_file_storage,node_thumbnail toneRose
class node_x_platform toneIndigo
```

## Components

### Web experience

- [Gallery API](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/controller/IllustrationGalleryController.java): `src/main/java/com/yuutara/illustrationarchive/controller/IllustrationGalleryController.java`
- [Detail API](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/controller/IllustrationDetailController.java): `src/main/java/com/yuutara/illustrationarchive/controller/IllustrationDetailController.java`
- [Asset content API](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/controller/AssetContentController.java): `src/main/java/com/yuutara/illustrationarchive/controller/AssetContentController.java`
- [File import API](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/controller/IllustrationImportController.java): `src/main/java/com/yuutara/illustrationarchive/controller/IllustrationImportController.java`
- [Metadata update API](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/controller/IllustrationUpdateController.java): `src/main/java/com/yuutara/illustrationarchive/controller/IllustrationUpdateController.java`
- [Delete API](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/controller/IllustrationDeleteController.java): `src/main/java/com/yuutara/illustrationarchive/controller/IllustrationDeleteController.java`
- [Author API](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/controller/AuthorController.java): `src/main/java/com/yuutara/illustrationarchive/controller/AuthorController.java`
- [Tag API](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/controller/TagController.java): `src/main/java/com/yuutara/illustrationarchive/controller/TagController.java`
- [X import API](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/controller/XImportController.java): `src/main/java/com/yuutara/illustrationarchive/controller/XImportController.java`

### Illustration catalog

- [Gallery queries](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/IllustrationGalleryService.java): `src/main/java/com/yuutara/illustrationarchive/service/IllustrationGalleryService.java`
- [Illustration details](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/IllustrationDetailService.java): `src/main/java/com/yuutara/illustrationarchive/service/IllustrationDetailService.java`
- [File import](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/IllustrationImportService.java): `src/main/java/com/yuutara/illustrationarchive/service/IllustrationImportService.java`
- [Batch import](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/IllustrationBatchImportService.java): `src/main/java/com/yuutara/illustrationarchive/service/IllustrationBatchImportService.java`
- [Illustration persistence](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/IllustrationPersistenceService.java): `src/main/java/com/yuutara/illustrationarchive/service/IllustrationPersistenceService.java`
- [Metadata editing](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/IllustrationUpdateService.java): `src/main/java/com/yuutara/illustrationarchive/service/IllustrationUpdateService.java`
- [Deletion workflow](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/IllustrationDeleteService.java): `src/main/java/com/yuutara/illustrationarchive/service/IllustrationDeleteService.java`
- [Database deletion](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/IllustrationDatabaseDeleteService.java): `src/main/java/com/yuutara/illustrationarchive/service/IllustrationDatabaseDeleteService.java`
- [Author management](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/AuthorService.java): `src/main/java/com/yuutara/illustrationarchive/service/AuthorService.java`
- [Tag management](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/TagService.java): `src/main/java/com/yuutara/illustrationarchive/service/TagService.java`

### X Likes archive

- [Likes synchronization](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/XLikeSyncService.java): `src/main/java/com/yuutara/illustrationarchive/service/XLikeSyncService.java`
- [X API client](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/XApiClient.java): `src/main/java/com/yuutara/illustrationarchive/service/XApiClient.java`
- [Likes persistence](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/XLikePersistenceService.java): `src/main/java/com/yuutara/illustrationarchive/service/XLikePersistenceService.java`
- [Inbox import](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/XImportService.java): `src/main/java/com/yuutara/illustrationarchive/service/XImportService.java`
- [Photo download](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/XPhotoDownloadService.java): `src/main/java/com/yuutara/illustrationarchive/service/XPhotoDownloadService.java`
- [Post persistence](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/service/XPostPersistenceService.java): `src/main/java/com/yuutara/illustrationarchive/service/XPostPersistenceService.java`

### Persistence and files

- [SQL repositories](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/repository/IllustrationRepository.java): `src/main/java/com/yuutara/illustrationarchive/repository/IllustrationRepository.java`
- [Author repository](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/repository/AuthorRepository.java): `src/main/java/com/yuutara/illustrationarchive/repository/AuthorRepository.java`
- [Tag repository](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/repository/TagRepository.java): `src/main/java/com/yuutara/illustrationarchive/repository/TagRepository.java`
- [X repositories](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/repository/XLikeRepository.java): `src/main/java/com/yuutara/illustrationarchive/repository/XLikeRepository.java`
- [File storage](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/storage/FileStorageService.java): `src/main/java/com/yuutara/illustrationarchive/storage/FileStorageService.java`
- [Thumbnail service](https://github.com/yuutara/illustration-archive/blob/master/src/main/java/com/yuutara/illustrationarchive/storage/ThumbnailService.java): `src/main/java/com/yuutara/illustrationarchive/storage/ThumbnailService.java`

### Other components

- [Browser UI](https://github.com/yuutara/illustration-archive/blob/master/src/main/resources/static/app.js): `src/main/resources/static/app.js`
- **MySQL**
- **X platform**: external system

## Connections

- Browser UI → Gallery API: requests gallery
- Browser UI → File import API: uploads files
- Browser UI → Detail API: requests detail
- Browser UI → Asset content API: loads images
- Browser UI → X import API: manages inbox
- Gallery API → Gallery queries: calls
- Detail API → Illustration details: calls
- Asset content API → File storage: loads content
- File import API → Batch import: calls batch
- File import API → File import: calls single
- Batch import → File import: imports each
- File import → File storage: stores files
- File import → Illustration persistence: persists record
- File import → Thumbnail service: generates thumbnail
- Gallery queries → SQL repositories: queries page
- Illustration details → SQL repositories: queries detail
- Metadata update API → Metadata editing: calls
- Delete API → Deletion workflow: calls
- Deletion workflow → Database deletion: deletes record
- Database deletion → SQL repositories: reads assets
- Deletion workflow → Thumbnail service: cleans thumbnails
- Deletion workflow → File storage: cleans originals
- Author API → Author management: calls
- Author management → Author repository: searches and writes
- Tag API → Tag management: calls
- Tag management → Tag repository: manages tags
- X import API → Likes synchronization: syncs and lists
- X import API → Inbox import: imports selection
- Likes synchronization → X API client: fetches pages
- Likes synchronization → Likes persistence: saves pages
- Likes synchronization → X repositories: reads inbox state
- Inbox import → Photo download: downloads photos
- Inbox import → Post persistence: persists posts
- Photo download → File storage: stores photos
- X API client → X platform: calls X
- SQL repositories → MySQL: executes SQL
- Author repository → MySQL: executes SQL
- Tag repository → MySQL: executes SQL
- X repositories → MySQL: executes SQL