# sukundev/matane architecture

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

- Interactive diagram: https://gitdiagram.com/sukundev/matane
- Repository: https://github.com/sukundev/matane

## Overview

Matane is a cross-platform desktop manga reader. The principal workflow is to browse extension-provided sources, open a manga, read its chapters, and retain progress; chapters can also be downloaded for offline reading. The renderer communicates with Electron’s main process through typed IPC, where domain services coordinate extensions, persistence, images, and downloads. The README documents additional branches including library updates, history, backups, statistics, settings, and extension-repository management. Some subsystem details are documented rather than sampled, so their links are shown only where evidence supports them.

Main entry points: [`apps/desktop/src/main/extensions/sources.ts`](https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/extensions/sources.ts) (Source browsing), [`apps/desktop/src/main/db/repositories/chapters.ts`](https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/db/repositories/chapters.ts) (Chapter repository), [`apps/desktop/src/main/extensions/service.ts`](https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/extensions/service.ts) (Extension service), [`apps/desktop/src/main/images/service.ts`](https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/images/service.ts) (Image service and cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_renderer["Desktop interface"]
  node_renderer["Renderer and routes<br/>[main.tsx]"]
end

subgraph group_domain["Manga workflows"]
  node_ipc["Typed IPC handlers<br/>[handlers.ts]"]
  node_contract["IPC contract<br/>[contract.ts]"]
  node_sources["Source browsing<br/>[sources.ts]"]
  node_library["Library service<br/>[service.ts]"]
  node_reading["Reading progress<br/>[service.ts]"]
  node_downloads["Download manager<br/>[manager.ts]"]
  node_updates["Library updates<br/>[updates.ts]"]
  node_backup["Backup service<br/>[service.ts]"]
  node_stats["Reading statistics<br/>[service.ts]"]
end

subgraph group_extensions["Extension ecosystem"]
  node_extension_service["Extension service<br/>[service.ts]"]
  node_extension_host["Sandbox host<br/>[host.ts]"]
  node_extension_runtime["Extension runtime<br/>[runtime.ts]"]
  node_sdk["Extension SDK<br/>[index.ts]"]
  node_network["Extension networking<br/>[manager.ts]"]
end

subgraph group_storage["Persistence and media"]
  node_manga_repo[("Manga repository<br/>[manga.ts]")]
  node_chapter_repo[("Chapter repository<br/>[chapters.ts]")]
  node_download_repo[("Download repository<br/>[downloads.ts]")]
  node_images["Image service and cache<br/>[service.ts]"]
  node_models["Shared domain models<br/>[models.ts]"]
  node_settings["Settings schema<br/>[settings.ts]"]
end

node_reader(("Matane user"))
node_sources_external(("Extension content sites"))

node_reader -->|"uses"| node_renderer
node_renderer -->|"invokes"| node_ipc
node_ipc -->|"implements"| node_contract
node_ipc -->|"dispatches"| node_sources
node_sources -->|"calls"| node_extension_service
node_extension_service -->|"requests"| node_network
node_network -->|"fetches"| node_sources_external
node_extension_service -->|"uses sandbox"| node_extension_host
node_extension_host -.->|"hosts"| node_extension_runtime
node_extension_service -->|"runs extensions"| node_extension_runtime
node_sources -->|"stores listings"| node_manga_repo
node_sources -->|"syncs chapters"| node_chapter_repo
node_library -->|"refreshes manga"| node_sources
node_library -->|"reads manga"| node_manga_repo
node_library -->|"lists chapters"| node_chapter_repo
node_downloads -->|"tracks jobs"| node_download_repo
node_downloads -->|"loads chapters"| node_chapter_repo
node_downloads -->|"gets pages"| node_images
node_reading -->|"uses chapter data"| node_chapter_repo
node_updates -.->|"checks sources"| node_sources
node_backup -->|"serializes data"| node_models
node_stats -->|"reads manga"| node_manga_repo
node_images -->|"loads manga"| node_manga_repo
node_images -->|"loads chapters"| node_chapter_repo
node_images -->|"restores images"| node_extension_runtime
node_sdk -->|"defines extension API"| node_extension_runtime
node_contract -->|"uses models"| node_models
node_contract -->|"uses settings"| node_settings

click node_renderer "https://github.com/sukundev/matane/blob/main/apps/desktop/src/renderer/src/main.tsx"
click node_ipc "https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/ipc/handlers.ts"
click node_contract "https://github.com/sukundev/matane/blob/main/packages/shared/src/ipc/contract.ts"
click node_sources "https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/extensions/sources.ts"
click node_library "https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/library/service.ts"
click node_reading "https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/reading/service.ts"
click node_downloads "https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/downloads/manager.ts"
click node_updates "https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/library/updates.ts"
click node_backup "https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/backup/service.ts"
click node_stats "https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/stats/service.ts"
click node_extension_service "https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/extensions/service.ts"
click node_extension_host "https://github.com/sukundev/matane/blob/main/apps/desktop/src/extension-host/host.ts"
click node_extension_runtime "https://github.com/sukundev/matane/blob/main/packages/extension-runtime/src/runtime.ts"
click node_sdk "https://github.com/sukundev/matane/blob/main/packages/extension-sdk/src/index.ts"
click node_network "https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/network/manager.ts"
click node_manga_repo "https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/db/repositories/manga.ts"
click node_chapter_repo "https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/db/repositories/chapters.ts"
click node_download_repo "https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/db/repositories/downloads.ts"
click node_images "https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/images/service.ts"
click node_models "https://github.com/sukundev/matane/blob/main/packages/shared/src/models.ts"
click node_settings "https://github.com/sukundev/matane/blob/main/packages/shared/src/settings.ts"

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_renderer,node_reader toneBlue
class node_ipc,node_contract,node_sources,node_library,node_reading,node_downloads,node_updates,node_backup,node_stats toneAmber
class node_extension_service,node_extension_host,node_extension_runtime,node_sdk,node_network toneMint
class node_manga_repo,node_chapter_repo,node_download_repo,node_images,node_models,node_settings toneRose
class node_sources_external toneIndigo
```

## Components

### Desktop interface

- [Renderer and routes](https://github.com/sukundev/matane/blob/main/apps/desktop/src/renderer/src/main.tsx): `apps/desktop/src/renderer/src/main.tsx`

### Manga workflows

- [Typed IPC handlers](https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/ipc/handlers.ts): `apps/desktop/src/main/ipc/handlers.ts`
- [IPC contract](https://github.com/sukundev/matane/blob/main/packages/shared/src/ipc/contract.ts): `packages/shared/src/ipc/contract.ts`
- [Source browsing](https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/extensions/sources.ts): `apps/desktop/src/main/extensions/sources.ts`
- [Library service](https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/library/service.ts): `apps/desktop/src/main/library/service.ts`
- [Reading progress](https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/reading/service.ts): `apps/desktop/src/main/reading/service.ts`
- [Download manager](https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/downloads/manager.ts): `apps/desktop/src/main/downloads/manager.ts`
- [Library updates](https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/library/updates.ts): `apps/desktop/src/main/library/updates.ts`
- [Backup service](https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/backup/service.ts): `apps/desktop/src/main/backup/service.ts`
- [Reading statistics](https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/stats/service.ts): `apps/desktop/src/main/stats/service.ts`

### Extension ecosystem

- [Extension service](https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/extensions/service.ts): `apps/desktop/src/main/extensions/service.ts`
- [Sandbox host](https://github.com/sukundev/matane/blob/main/apps/desktop/src/extension-host/host.ts): `apps/desktop/src/extension-host/host.ts`
- [Extension runtime](https://github.com/sukundev/matane/blob/main/packages/extension-runtime/src/runtime.ts): `packages/extension-runtime/src/runtime.ts`
- [Extension SDK](https://github.com/sukundev/matane/blob/main/packages/extension-sdk/src/index.ts): `packages/extension-sdk/src/index.ts`
- [Extension networking](https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/network/manager.ts): `apps/desktop/src/main/network/manager.ts`

### Persistence and media

- [Manga repository](https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/db/repositories/manga.ts): `apps/desktop/src/main/db/repositories/manga.ts`
- [Chapter repository](https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/db/repositories/chapters.ts): `apps/desktop/src/main/db/repositories/chapters.ts`
- [Download repository](https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/db/repositories/downloads.ts): `apps/desktop/src/main/db/repositories/downloads.ts`
- [Image service and cache](https://github.com/sukundev/matane/blob/main/apps/desktop/src/main/images/service.ts): `apps/desktop/src/main/images/service.ts`
- [Shared domain models](https://github.com/sukundev/matane/blob/main/packages/shared/src/models.ts): `packages/shared/src/models.ts`
- [Settings schema](https://github.com/sukundev/matane/blob/main/packages/shared/src/settings.ts): `packages/shared/src/settings.ts`

### Other components

- **Matane user**
- **Extension content sites**

## Connections

- Matane user → Renderer and routes: uses (evidence: `README.md`)
- Renderer and routes → Typed IPC handlers: invokes (evidence: `apps/desktop/src/renderer/src/main.tsx`)
- Typed IPC handlers → IPC contract: implements (evidence: `apps/desktop/src/main/ipc/handlers.ts`)
- Typed IPC handlers → Source browsing: dispatches (evidence: `apps/desktop/src/main/ipc/handlers.ts`)
- Source browsing → Extension service: calls (evidence: `apps/desktop/src/main/extensions/sources.ts`)
- Extension service → Extension networking: requests (evidence: `apps/desktop/src/main/extensions/service.ts`)
- Extension networking → Extension content sites: fetches (evidence: `README.md`)
- Extension service → Sandbox host: uses sandbox (evidence: `apps/desktop/src/main/extensions/service.ts`)
- Sandbox host → Extension runtime: hosts
- Extension service → Extension runtime: runs extensions (evidence: `apps/desktop/src/main/extensions/service.ts`)
- Source browsing → Manga repository: stores listings (evidence: `apps/desktop/src/main/extensions/sources.ts`)
- Source browsing → Chapter repository: syncs chapters (evidence: `apps/desktop/src/main/extensions/sources.ts`)
- Library service → Source browsing: refreshes manga (evidence: `apps/desktop/src/main/library/service.ts`)
- Library service → Manga repository: reads manga (evidence: `apps/desktop/src/main/library/service.ts`)
- Library service → Chapter repository: lists chapters (evidence: `apps/desktop/src/main/library/service.ts`)
- Download manager → Download repository: tracks jobs (evidence: `apps/desktop/src/main/downloads/manager.ts`)
- Download manager → Chapter repository: loads chapters (evidence: `apps/desktop/src/main/downloads/manager.ts`)
- Download manager → Image service and cache: gets pages (evidence: `apps/desktop/src/main/downloads/manager.ts`)
- Reading progress → Chapter repository: uses chapter data (evidence: `apps/desktop/src/main/reading/service.ts`)
- Library updates → Source browsing: checks sources
- Backup service → Shared domain models: serializes data (evidence: `apps/desktop/src/main/backup/service.ts`)
- Reading statistics → Manga repository: reads manga (evidence: `apps/desktop/src/main/stats/service.ts`)
- Image service and cache → Manga repository: loads manga (evidence: `apps/desktop/src/main/images/service.ts`)
- Image service and cache → Chapter repository: loads chapters (evidence: `apps/desktop/src/main/images/service.ts`)
- Image service and cache → Extension runtime: restores images (evidence: `apps/desktop/src/main/images/service.ts`)
- Extension SDK → Extension runtime: defines extension API (evidence: `packages/extension-runtime/src/runtime.ts`)
- IPC contract → Shared domain models: uses models (evidence: `packages/shared/src/ipc/contract.ts`)
- IPC contract → Settings schema: uses settings (evidence: `packages/shared/src/ipc/contract.ts`)
