# makinuki/makidoku architecture

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

- Interactive diagram: https://gitdiagram.com/makinuki/makidoku
- Repository: https://github.com/makinuki/makidoku

## Overview

MakiDoku is a local manga library, source-plugin host, downloader, and reader served as a single Go daemon with an embedded React UI. The main workflow is to browse or search installed sources, add titles to the library, download chapters, and read them while recording progress; progress can enqueue tracker updates. Separate branches cover source installation, backups, and settings. The README documents these capabilities, but several backend handlers and subsystems were not sampled, so uncertain internal wiring is omitted.

Main entry points: [`web/src/App.tsx`](https://github.com/makinuki/makidoku/blob/master/web/src/App.tsx) (React workspace), [`internal/engine/engine.go`](https://github.com/makinuki/makidoku/blob/master/internal/engine/engine.go) (WASM source engine), [`internal/db/repository.go`](https://github.com/makinuki/makidoku/blob/master/internal/db/repository.go) (Domain repository), [`internal/downloader/queue.go`](https://github.com/makinuki/makidoku/blob/master/internal/downloader/queue.go) (Queue and workers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web workspace"]
  node_webapp["React workspace<br/>[App.tsx]"]
  node_webapi["Web API client<br/>[api.ts]"]
  node_reader["Reader and progress<br/>[ReaderPage.tsx]"]
  node_progress["Progress client"]
  node_settings["Settings UI and API"]
end

subgraph group_api["Daemon API"]
  node_server["HTTP daemon<br/>[server.go]"]
  node_handlers["REST and events<br/>[api.go]"]
  node_sourcesapi["Source endpoints<br/>[sources.go]"]
  node_downloadapi["Download endpoints<br/>[downloader.go]"]
  node_libraryapi["Library endpoints<br/>[library.go]"]
  node_backupapi["Backup endpoints<br/>[backup.go]"]
end

subgraph group_sources["Source plugins"]
  node_engine["WASM source engine<br/>[engine.go]"]
  node_registry["Plugin registry<br/>[registry.go]"]
  node_pluginhost["Plugin fetch and host<br/>[fetch.go]"]
end

subgraph group_library["Library and reader"]
  node_repository["Domain repository<br/>[repository.go]"]
  node_database[("SQLite state<br/>[database.go]")]
end

subgraph group_downloads["Downloads"]
  node_queue["Queue and workers<br/>[queue.go]"]
  node_artifacts["Chapter artifacts<br/>[artifact.go]"]
end

subgraph group_data["Tracking and backups"]
  node_tracker["Tracker sync<br/>[sync.go]"]
  node_providers["Tracker providers<br/>[registry.go]"]
  node_backup["Backup import/export<br/>[export.go]"]
end

node_person(("Reader / operator"))
node_catalog["Source catalog"]
node_mangasources["Manga sources"]
node_trackerservice["Tracking services"]

node_person -->|"uses"| node_webapp
node_webapp -->|"requests"| node_webapi
node_webapi -->|"calls HTTP API"| node_handlers
node_server -->|"mounts routes"| node_handlers
node_server -->|"serves UI"| node_webapp
node_person -->|"manages sources"| node_sourcesapi
node_sourcesapi -->|"installs and lists"| node_engine
node_engine -->|"fetches plugins"| node_registry
node_registry -->|"reads catalog"| node_catalog
node_engine -->|"runs plugins"| node_pluginhost
node_pluginhost -->|"fetches source data"| node_mangasources
node_webapp -->|"browses library"| node_libraryapi
node_libraryapi -->|"requests source data"| node_engine
node_libraryapi -->|"reads and writes"| node_repository
node_repository -->|"persists state"| node_database
node_webapp -->|"opens chapters"| node_reader
node_reader -->|"samples reading"| node_progress
node_progress -->|"writes progress"| node_webapi
node_handlers -->|"records progress"| node_repository
node_person -->|"controls queue"| node_downloadapi
node_downloadapi -->|"enqueues and controls"| node_queue
node_queue -->|"claims queue items"| node_repository
node_queue -->|"fetches chapter pages"| node_engine
node_queue -->|"writes chapters"| node_artifacts
node_person -->|"starts sync"| node_tracker
node_tracker -->|"claims sync jobs"| node_repository
node_tracker -->|"dispatches updates"| node_providers
node_providers -->|"calls provider API"| node_trackerservice
node_person -->|"requests backup"| node_backupapi
node_backupapi -->|"imports and exports"| node_backup
node_backup -->|"stores backup data"| node_database
node_person -->|"changes preferences"| node_settings
node_settings -->|"saves settings"| node_webapi

click node_webapp "https://github.com/makinuki/makidoku/blob/master/web/src/App.tsx"
click node_webapi "https://github.com/makinuki/makidoku/blob/master/web/src/api.ts"
click node_server "https://github.com/makinuki/makidoku/blob/master/internal/app/server.go"
click node_handlers "https://github.com/makinuki/makidoku/blob/master/internal/api/api.go"
click node_sourcesapi "https://github.com/makinuki/makidoku/blob/master/internal/api/sources.go"
click node_downloadapi "https://github.com/makinuki/makidoku/blob/master/internal/api/downloader.go"
click node_engine "https://github.com/makinuki/makidoku/blob/master/internal/engine/engine.go"
click node_registry "https://github.com/makinuki/makidoku/blob/master/internal/engine/registry.go"
click node_pluginhost "https://github.com/makinuki/makidoku/blob/master/internal/engine/fetch.go"
click node_libraryapi "https://github.com/makinuki/makidoku/blob/master/internal/api/library.go"
click node_repository "https://github.com/makinuki/makidoku/blob/master/internal/db/repository.go"
click node_database "https://github.com/makinuki/makidoku/blob/master/internal/db/database.go"
click node_reader "https://github.com/makinuki/makidoku/blob/master/web/src/features/reader/ReaderPage.tsx"
click node_progress "https://github.com/makinuki/makidoku/blob/master/web/src/features/reader/useReaderProgress.ts"
click node_queue "https://github.com/makinuki/makidoku/blob/master/internal/downloader/queue.go"
click node_artifacts "https://github.com/makinuki/makidoku/blob/master/internal/downloader/artifact.go"
click node_tracker "https://github.com/makinuki/makidoku/blob/master/internal/tracker/sync.go"
click node_providers "https://github.com/makinuki/makidoku/blob/master/internal/tracker/registry.go"
click node_backupapi "https://github.com/makinuki/makidoku/blob/master/internal/api/backup.go"
click node_backup "https://github.com/makinuki/makidoku/blob/master/internal/backup/export.go"
click node_settings "https://github.com/makinuki/makidoku/blob/master/web/src/features/settings/SettingsIndexPage.tsx"

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_webapp,node_webapi,node_reader,node_progress,node_settings toneBlue
class node_server,node_handlers,node_sourcesapi,node_downloadapi,node_libraryapi,node_backupapi toneAmber
class node_engine,node_registry,node_pluginhost toneMint
class node_repository,node_database toneRose
class node_queue,node_artifacts,node_person,node_catalog,node_mangasources,node_trackerservice toneIndigo
class node_tracker,node_providers,node_backup toneTeal
```

## Components

### Web workspace

- [React workspace](https://github.com/makinuki/makidoku/blob/master/web/src/App.tsx): `web/src/App.tsx`
- [Web API client](https://github.com/makinuki/makidoku/blob/master/web/src/api.ts): `web/src/api.ts`
- [Reader and progress](https://github.com/makinuki/makidoku/blob/master/web/src/features/reader/ReaderPage.tsx): `web/src/features/reader/ReaderPage.tsx`
- [Progress client](https://github.com/makinuki/makidoku/blob/master/web/src/features/reader/useReaderProgress.ts): `web/src/features/reader/useReaderProgress.ts`
- [Settings UI and API](https://github.com/makinuki/makidoku/blob/master/web/src/features/settings/SettingsIndexPage.tsx): `web/src/features/settings/SettingsIndexPage.tsx`

### Daemon API

- [HTTP daemon](https://github.com/makinuki/makidoku/blob/master/internal/app/server.go): `internal/app/server.go`
- [REST and events](https://github.com/makinuki/makidoku/blob/master/internal/api/api.go): `internal/api/api.go`
- [Source endpoints](https://github.com/makinuki/makidoku/blob/master/internal/api/sources.go): `internal/api/sources.go`
- [Download endpoints](https://github.com/makinuki/makidoku/blob/master/internal/api/downloader.go): `internal/api/downloader.go`
- [Library endpoints](https://github.com/makinuki/makidoku/blob/master/internal/api/library.go): `internal/api/library.go`
- [Backup endpoints](https://github.com/makinuki/makidoku/blob/master/internal/api/backup.go): `internal/api/backup.go`

### Source plugins

- [WASM source engine](https://github.com/makinuki/makidoku/blob/master/internal/engine/engine.go): `internal/engine/engine.go`
- [Plugin registry](https://github.com/makinuki/makidoku/blob/master/internal/engine/registry.go): `internal/engine/registry.go`
- [Plugin fetch and host](https://github.com/makinuki/makidoku/blob/master/internal/engine/fetch.go): `internal/engine/fetch.go`

### Library and reader

- [Domain repository](https://github.com/makinuki/makidoku/blob/master/internal/db/repository.go): `internal/db/repository.go`
- [SQLite state](https://github.com/makinuki/makidoku/blob/master/internal/db/database.go): `internal/db/database.go`

### Downloads

- [Queue and workers](https://github.com/makinuki/makidoku/blob/master/internal/downloader/queue.go): `internal/downloader/queue.go`
- [Chapter artifacts](https://github.com/makinuki/makidoku/blob/master/internal/downloader/artifact.go): `internal/downloader/artifact.go`

### Tracking and backups

- [Tracker sync](https://github.com/makinuki/makidoku/blob/master/internal/tracker/sync.go): `internal/tracker/sync.go`
- [Tracker providers](https://github.com/makinuki/makidoku/blob/master/internal/tracker/registry.go): `internal/tracker/registry.go`
- [Backup import/export](https://github.com/makinuki/makidoku/blob/master/internal/backup/export.go): `internal/backup/export.go`

### Other components

- **Reader / operator**
- **Source catalog**
- **Manga sources**
- **Tracking services**

## Connections

- Reader / operator → React workspace: uses
- React workspace → Web API client: requests
- Web API client → REST and events: calls HTTP API
- HTTP daemon → REST and events: mounts routes
- HTTP daemon → React workspace: serves UI
- Reader / operator → Source endpoints: manages sources
- Source endpoints → WASM source engine: installs and lists
- WASM source engine → Plugin registry: fetches plugins
- Plugin registry → Source catalog: reads catalog
- WASM source engine → Plugin fetch and host: runs plugins
- Plugin fetch and host → Manga sources: fetches source data
- React workspace → Library endpoints: browses library
- Library endpoints → WASM source engine: requests source data
- Library endpoints → Domain repository: reads and writes
- Domain repository → SQLite state: persists state
- React workspace → Reader and progress: opens chapters
- Reader and progress → Progress client: samples reading
- Progress client → Web API client: writes progress
- REST and events → Domain repository: records progress
- Reader / operator → Download endpoints: controls queue
- Download endpoints → Queue and workers: enqueues and controls
- Queue and workers → Domain repository: claims queue items
- Queue and workers → WASM source engine: fetches chapter pages
- Queue and workers → Chapter artifacts: writes chapters
- Reader / operator → Tracker sync: starts sync
- Tracker sync → Domain repository: claims sync jobs
- Tracker sync → Tracker providers: dispatches updates
- Tracker providers → Tracking services: calls provider API
- Reader / operator → Backup endpoints: requests backup
- Backup endpoints → Backup import/export: imports and exports
- Backup import/export → SQLite state: stores backup data
- Reader / operator → Settings UI and API: changes preferences
- Settings UI and API → Web API client: saves settings