# suwayomi/suwayomi-server architecture

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

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

## Overview

##### Project’s Type and Purpose
- Suwayomi-Server is a backend application that serves as a manga library manager and extension host. Its primary purpose is to install, execute, and manage Tachiyomi extensions, support manga-related operations (searching, updating, downloading, backup/restore, tracking), and serve them to various client fronts (web UI, desktop apps, etc.).
- The README indicates cross-platform, multi-client support and integration with external trackers (e.g. MyAnimeList, AniList) and services (FlareSolverr).

##### Main Components from the File Structure
- Modules/Components:
- Server Module: Contains most of the main application code (in server/src/main/kotlin) with packages for:
- Core setup (e.g., App.kt, ServerSetup.kt, JavalinSetup.kt) to start and configure the HTTP server.
- API endpoints and controllers (GraphQL controllers, REST/HTTP endpoints, e.g., GlobalMetaController, BackupController, MangaController, etc.) to serve various functionalities.
- GraphQL Layer: Organized under packages like graphql/queries, graphql/mutations, graphql/server, and graphql/subscriptions. This layer handles incoming GraphQL requests and organizes data fetching (with DataLoader registries) and subscriptions.
- Database Management: Under server/database and database/migration – manages DB connections, executes migration scripts, and handles transactions via DBManager.
- Utility and service packages: For example, the network package (OkHttp, interceptors for Cloudflare bypass, progress response handling), file providers (download management and file retrieval), and compatibility modules.
- Domain Model: Located under packages like source/model and manga/model (data classes and table mapping for manga, chapters, categories, etc.).
- AndroidCompat Module: This module (in AndroidCompat and AndroidCompat/Config) provides compatibility support (e.g., modules for config, logging, database, shared preferences) to emulate parts of the Android API needed by Tachiyomi code.
- Build & Scripts: The gradle build files, Gradle wrapper, and scripts for docker, MSI, and package creation (e.g., packaging solution for various OS-es) are also present and show the considerations for multi-platform deployments.
- Tests: A wide array of tests (under server/src/test) ensure functional correctness of the controllers, utility classes, and migration scripts.

##### Core Architectural Patterns and Interactions
- The Server relies on a layered architecture:
- Presentation/API Layer: A web server (likely based on Javalin) exposing endpoints (via GraphQL and possibly REST) that are consumed by client front-ends.
- Business Logic Layer: Controllers and service classes that execute extension management, manga library management, updating logic, and scheduling (for updating chapters, backups, etc.).
- Data Access Layer: Database migration scripts and transaction management (with DBManager) controlling persistence.
- Compatibility Layer: AndroidCompat providing an abstraction or replacement for Android classes in a non-Android environment.
- External Service Integration: Modules to interface with third-party APIs like FlareSolverr for bypass operations and tracking services.
- The server functions are organized using dependency injection (notice references such as KoinGlobalHelper) and modular separation (different packages for network, storage, and utilities).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Interfaces
    subgraph "Client Interfaces"
        CI("Suwayomi-WebUI / VUI"):::client
    end

    %% Server Core
    subgraph "Server Core"
        SB("Server Bootstrap (App.kt)"):::server
        HTTP("HTTP Server (Javalin)"):::api
        API("API Endpoints & Controllers"):::api
        GQL("GraphQL API"):::api
        BL("Business Logic & Services"):::server
        UTIL("Utilities & Networking"):::server
        DB("Database Management (DBManager + Migrations)"):::db
        EXT("External Integrations"):::external
    end

    %% Android Compatibility Layer
    AC("AndroidCompat Module"):::compatibility

    %% CI/CD & Deployment
    subgraph "Build & Deployment (CI/CD)"
        CI_CD("Build Scripts & Packaging"):::ci
    end

    %% Tests
    TEST("Automated Tests"):::test

    %% Relationships
    CI -->|"API Calls"| HTTP
    HTTP -->|"Routes to"| API
    HTTP -->|"Routes to"| GQL
    API -->|"Executes"| BL
    GQL -->|"Executes"| BL
    BL -->|"Perform CRUD"| DB
    BL -->|"Uses"| UTIL
    BL -->|"Integrates"| EXT
    BL <-->|"Compatibility support"| AC
    CI_CD -->|"Deploys"| SB
    TEST -->|"Validates"| API
    TEST -->|"Validates"| BL

    %% Click Events (Component Mapping)
    click SB "https://github.com/suwayomi/suwayomi-server/blob/master/server/src/main/kotlin/eu/kanade/tachiyomi/App.kt"
    click SB "https://github.com/suwayomi/suwayomi-server/tree/master/server/src/main/kotlin/suwayomi/tachidesk/server"
    click API "https://github.com/suwayomi/suwayomi-server/tree/master/server/src/main/kotlin/suwayomi/tachidesk/global/controller"
    click API "https://github.com/suwayomi/suwayomi-server/tree/master/server/src/main/kotlin/suwayomi/tachidesk/manga/controller"
    click GQL "https://github.com/suwayomi/suwayomi-server/tree/master/server/src/main/kotlin/suwayomi/tachidesk/graphql"
    click DB "https://github.com/suwayomi/suwayomi-server/blob/master/server/src/main/kotlin/suwayomi/tachidesk/server/database/DBManager.kt"
    click DB "https://github.com/suwayomi/suwayomi-server/tree/master/server/src/main/kotlin/suwayomi/tachidesk/server/database/migration"
    click UTIL "https://github.com/suwayomi/suwayomi-server/tree/master/server/src/main/kotlin/suwayomi/tachidesk/manga/impl/download"
    click UTIL "https://github.com/suwayomi/suwayomi-server/tree/master/server/src/main/kotlin/eu/kanade/tachiyomi/network"
    click AC "https://github.com/suwayomi/suwayomi-server/tree/master/AndroidCompat"
    click AC "https://github.com/suwayomi/suwayomi-server/tree/master/AndroidCompat/Config"
    click CI_CD "https://github.com/suwayomi/suwayomi-server/blob/master/build.gradle.kts"
    click CI_CD "https://github.com/suwayomi/suwayomi-server/blob/master/AndroidCompat/build.gradle.kts"
    click CI_CD "https://github.com/suwayomi/suwayomi-server/tree/master/buildSrc"
    click CI_CD "https://github.com/suwayomi/suwayomi-server/tree/master/scripts"
    click CI_CD "https://github.com/suwayomi/suwayomi-server/tree/master/.github/workflows"
    click TEST "https://github.com/suwayomi/suwayomi-server/tree/master/server/src/test"

    %% Styles
    classDef client fill:#a3d5ff,stroke:#333,stroke-width:2px;
    classDef server fill:#bffcc6,stroke:#333,stroke-width:2px;
    classDef api fill:#ffe699,stroke:#333,stroke-width:2px;
    classDef db fill:#ffcccb,stroke:#333,stroke-width:2px;
    classDef external fill:#ffb366,stroke:#333,stroke-width:2px;
    classDef compatibility fill:#cfe2f3,stroke:#333,stroke-width:2px;
    classDef ci fill:#d9ead3,stroke:#333,stroke-width:2px;
    classDef test fill:#fce5cd,stroke:#333,stroke-width:2px;
```
