# suwayomi/suwayomi-webui architecture

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

- Interactive diagram: https://gitdiagram.com/suwayomi/suwayomi-webui
- Repository: https://github.com/suwayomi/suwayomi-webui

## Overview

##### Project Type and Purpose
- The Suwayomi-WebUI is a full-featured client application for manga management, reading, and library control. It is bundled with the Suwayomi-Server and communicates (largely via GraphQL) to provide a rich user interface for browsing manga, reading chapters, handling downloads, and more.

##### Analyzing the File Structure
- The top-level directories and files indicate standard configurations (.eslint, .prettierrc, tsconfig, vite.config.ts) along with a “public” folder (for static assets) and a very modular “src” directory.
- Within “src” you see many subdirectories such as:
– “modules” (which contain domain-specific functionality e.g., reader, manga, chapter, category, settings, etc.),
– “lib” (utility libraries for GraphQL, mui styles, requests, storage, and more),
– “i18n” (for internationalization),
– Supporting directories for assets, utilities, and tooling.
- This structure suggests a component-driven, possibly MVC-inspired or modular layered architecture where views, services, and data handling are clearly separated.

##### Main Components
a. User Interface (UI) Layer:
– Present modules (Library, Reader, Category, Chapter, Downloads, Settings, Sources, Tracker, Themes, etc.). Each module folder (e.g., “modules/reader”, “modules/manga”, “modules/chapter”) can be represented as separate “feature blocks” within the UI.
b. Data Access and API Integration:
– GraphQL integration is central. There’s a dedicated “src/lib/graphql” directory which handles queries, mutations, subscriptions, and generated code. Represent this as an API integration layer.
– Also note the “src/lib/requests/client” which includes REST and GraphQL clients.
c. Utility and Supporting Libraries:
– There are various “lib” and “util” directories that provide supporting functionalities like promise control, dayjs configuration for date handling, queue management, and storage.
– Context providers (inside modules like “core”, “device”, “theme”, “reader”, etc.) are used to maintain state across the application. Include an “Application State & Context” component.
d. External Services & Build/Dev Tools:
– The project uses external tools and workflows (GitHub workflows under “.github“) and build scripts for deployment.
– Also include external integrations like translations (with Weblate) and dependency on the Suwayomi-Server.

##### Relationships and Data Flow
- That context providers and state management layers (e.g., from “modules/core/contexts”, “modules/reader/contexts”, “modules/theme/contexts”, etc.) interconnect with UI modules, providing global state.
- Interactions between utility libraries (e.g., functions in “src/lib”, “src/util”) that serve both the UI and the data modules.
- That build scripts and configuration files are responsible for bundling the app, while GitHub workflows manage CI/CD for updates and releases.

##### Architectural Patterns & Design Principles
- Modularity: Separate features into distinct modules (library, reader, settings, etc.), each with its own components, hooks, and services.
- Clear separation of concerns between UI rendering, business logic (services and hooks), state management (contexts), and data fetching (GraphQL/REST clients).
- Utilize dependency injection via context providers/higher-order components ("hoc" in “modules/core/hoc/withPropsFrom.tsx”) to share functionality.
- That the system follows best practices in internationalization (numerous locales in “public/locales” and “src/i18n”) and robust error handling (ErrorBoundary components).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface (UI) Modules
    subgraph "User Interface (UI) Modules"
        UI1["Reader Module"]:::ui
        UI2["Library Module"]:::ui
        UI3["Settings Module"]:::ui
    end

    %% Data Access & API Integration
    subgraph "Data Access & API Integration"
        DA1["GraphQL Client"]:::dataAccess
        DA2["REST Client"]:::dataAccess
        DA3["Request Manager"]:::dataAccess
    end

    %% Utility Libraries & Helpers
    subgraph "Utility Libraries & Helpers"
        UL1["General Utilities"]:::utility
        UL2["Day.js Utility"]:::utility
        UL3["Additional Utilities"]:::utility
    end

    %% Application State & Context Providers
    subgraph "Application State & Context Providers"
        SC1["Core Context/HOC"]:::state
        SC2["Reader Context"]:::state
        SC3["Theme Context"]:::state
        SC4["Library Context"]:::state
    end

    %% Internationalization
    subgraph "Internationalization"
        INT1["Locale Files"]:::intl
        INT2["i18n Config"]:::intl
    end

    %% External Services & Build/Dev Tools
    subgraph "External Services & Build/Dev Tools"
        EX1["CI/CD Workflows"]:::build
        EX2["Build Configurations"]:::build
        EX3["GraphQL Codegen"]:::build
    end

    %% External Dependency
    EXTERNAL["Suwayomi-Server"]:::external

    %% UI Modules to Data Access
    UI1 -->|"calls_API"| DA1
    UI2 -->|"calls_API"| DA1
    UI3 -->|"calls_API"| DA2

    %% UI Modules to State Providers
    UI1 -->|"uses_state"| SC2
    UI2 -->|"uses_state"| SC4
    UI3 -->|"uses_state"| SC1

    %% UI Modules and Internationalization
    UI1 -->|"i18n"| INT2
    UI2 -->|"i18n"| INT2
    UI3 -->|"i18n"| INT2

    %% Utility Libraries supporting UI and Data Access
    UL1 --> UI1
    UL1 --> UI2
    UL1 --> UI3
    UL1 --> DA3

    %% Data Access using Request Manager
    DA1 -->|"uses_manager"| DA3

    %% Data Access communicating with External Server
    DA1 -->|"GraphQL_query/mutation"| EXTERNAL

    %% External Services interconnection
    EX1 -->|"configures"| EX2
    EX2 -->|"integrates_with"| EX3

    %% State Providers interconnections (shared contexts)
    SC1 --- SC2
    SC1 --- SC3
    SC1 --- SC4

    %% Click Events
    click UI1 "https://github.com/suwayomi/suwayomi-webui/tree/master/src/modules/reader"
    click UI2 "https://github.com/suwayomi/suwayomi-webui/tree/master/src/modules/library"
    click UI3 "https://github.com/suwayomi/suwayomi-webui/tree/master/src/modules/settings"
    click DA1 "https://github.com/suwayomi/suwayomi-webui/tree/master/src/lib/graphql"
    click DA2 "https://github.com/suwayomi/suwayomi-webui/blob/master/src/lib/requests/client/RestClient.ts"
    click DA3 "https://github.com/suwayomi/suwayomi-webui/blob/master/src/lib/requests/RequestManager.ts"
    click UL1 "https://github.com/suwayomi/suwayomi-webui/tree/master/src/lib"
    click UL2 "https://github.com/suwayomi/suwayomi-webui/tree/master/src/lib/dayjs"
    click UL3 "https://github.com/suwayomi/suwayomi-webui/tree/master/src/util"
    click SC1 "https://github.com/suwayomi/suwayomi-webui/tree/master/src/modules/core/contexts"
    click SC2 "https://github.com/suwayomi/suwayomi-webui/tree/master/src/modules/reader/contexts"
    click SC3 "https://github.com/suwayomi/suwayomi-webui/tree/master/src/modules/theme/contexts"
    click SC4 "https://github.com/suwayomi/suwayomi-webui/tree/master/src/modules/library/contexts"
    click INT1 "https://github.com/suwayomi/suwayomi-webui/tree/master/public/locales"
    click INT2 "https://github.com/suwayomi/suwayomi-webui/tree/master/src/i18n"
    click EX1 "https://github.com/suwayomi/suwayomi-webui/tree/master/.github/workflows"
    click EX2 "https://github.com/suwayomi/suwayomi-webui/blob/master/vite.config.ts"
    click EX3 "https://github.com/suwayomi/suwayomi-webui/blob/master/gql_codegen.ts"

    %% Styles / color definitions
    classDef ui fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef dataAccess fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef utility fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef state fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef intl fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef external fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef build fill:#fefefe,stroke:#6c757d,stroke-width:2px;
```
