# gotson/komga architecture

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

- Interactive diagram: https://gitdiagram.com/gotson/komga
- Repository: https://github.com/gotson/komga

## Overview

##### Main Components
- Frontend (komga-webui): This is the client-facing part, built using modern web technologies (Vue.js, TypeScript, etc.). It communicates with the backend via RESTful endpoints and also supports OPDS feeds.
- Backend (komga): The central server implemented in Kotlin. It is organized using a rich domain-driven design. Notice the “domain”, “application”, “infrastructure”, and “interfaces” packages that clearly show the layered structure.
- Komga Tray: A desktop tray application that wraps around some UI aspects for local usage. It has its own source set and libraries.
- Database & Migrations: With numerous Flyway migration scripts and configuration files, it appears that a relational database (likely SQLite by default) is in use.
- External Integrations:
– API integrations for external clients (readers, Kobo sync, KOReader sync, OPDS endpoints).
– Messaging and event-driven subsystems (e.g., SSE endpoints, tasks, and JMS-based components) provide asynchronous processing.
– Metadata handling components for comic and ebook metadata retrieval from comicrack, mylar, local artwork libraries, etc.
- Utilities & Infrastructure: Infrastructure packages include caching, security (including API key, OAuth2, and session management), search (using Lucene for full-text and multilingual search), and file system scanning for duplicate files or pages.

##### Relationships and Data Flows
- The Frontend communicates via REST API calls to the Backend (which is also responsible for serving OPDS feeds).
- The Backend’s “interfaces” layer exposes REST, SOAP, OPDS, and SSE endpoints. Note the clear separation with dedicated packages for REST controllers, API DTOs, and API security.
- The “domain” layer models the business logic of libraries, series, books, users, and tasks. Services in this layer are orchestrated by application service classes and call into the “infrastructure” layer for persistence and external integrations.
- The Infrastructure layer handles concerns such as:
– Database access via persistence repositories (Jooq, Spring Data, or similar).
– External resources; e.g., file system, media type detection, metadata extraction, and hash calculations.
– Caching and security operations.
- Background tasks and schedulers (in the application layer) coordinate operations like library scans, metadata updates, and maintenance tasks.
- The Komga Tray likely acts as a client connecting directly to the backend or wrapping portions of the frontend code for desktop-specific functionality.

##### Architectural Patterns and Design Principles
- Layered / Hexagonal architecture: The clear division between Domain, Application, Infrastructure, and Interfaces indicates Domain-Driven Design.
- Micro-modular and plug-in based: The “plugins” directory in the frontend and modular services in the backend suggest extensibility.
- Event-driven: Use of event publishers, SSE endpoints, and asynchronous scheduling reflects that the application reacts to internal events.
- RESTful design: Based on the controllers and DTOs provided.

##### Detail What to Highlight
– Stress the layered architecture (interfaces → application → domain → infrastructure).
– Emphasize critical functions such as library scanning, metadata aggregation, and user management.
– Call out external integrations (Kobo / KOReader sync, OPDS support, etc.) in separate blocks.
– Optionally, add a “Utility Components” section for error logging, caching, and search indexing.
– Additionally, if desired, include a small inset that shows the process flow for a typical user request (from login through to reading a book).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FE("Web UI (komga-webui)"):::frontend
    end

    %% Desktop Component
    subgraph "Desktop Client"
        KT("Komga Tray"):::tray
    end

    %% Backend Services
    subgraph "Backend Services"
        INT("Interfaces (REST,OPDS,SSE)"):::interfaces
        AS("Application Services"):::appServices
        DM("Domain Layer"):::domain
        INF("Infrastructure Layer"):::infrastructure
    end

    %% Database and Migrations
    subgraph "Database Layer"
        FK("Flyway Kotlin Migrations"):::migrations
        FS("Flyway SQL Migrations"):::migrations
        DB("Database (SQLite)"):::database
    end

    %% External Integrations and Utilities
    subgraph "Backend Utilities & External"
        EX("External OPDS Endpoints"):::external
        MP("Metadata Providers"):::external
        CA("Caching"):::utility
        SE("Security & OAuth2"):::utility
        FSCR("File System Scanning"):::utility
        SRCH("Search (Lucene)"):::utility
    end

    %% Connections between Frontend/Desktop and Backend
    FE -->|"HTTPREST"| INT
    KT -->|"DirectCall"| INT

    %% Internal backend communication
    INT -->|"calls"| AS
    AS -->|"orchestrates"| DM
    AS -->|"invokes"| INF

    %% Database connections
    INF -->|"updatesSchema"| FK
    INF -->|"updatesSchema"| FS
    FK -->|"migrates"| DB
    FS -->|"migrates"| DB

    %% External integrations linked from Infrastructure
    INF -->|"integrates"| EX
    INF -->|"integrates"| MP
    INF -->|"manages"| CA
    INF -->|"handles"| SE
    DM -->|"triggers"| FSCR
    INF -->|"indexes"| SRCH

    %% Styling Classes
    classDef frontend fill:#a6cee3,stroke:#1f78b4,stroke-width:2px;
    classDef tray fill:#b2df8a,stroke:#33a02c,stroke-width:2px;
    classDef interfaces fill:#fb9a99,stroke:#e31a1c,stroke-width:2px;
    classDef appServices fill:#fdbf6f,stroke:#ff7f00,stroke-width:2px;
    classDef domain fill:#cab2d6,stroke:#6a3d9a,stroke-width:2px;
    classDef infrastructure fill:#ffff99,stroke:#b15928,stroke-width:2px;
    classDef database fill:#ccebc5,stroke:#006400,stroke-width:2px;
    classDef migrations fill:#ffed6f,stroke:#ff8c00,stroke-width:2px;
    classDef external fill:#ff9dc2,stroke:#d1001a,stroke-width:2px;
    classDef utility fill:#d9d9d9,stroke:#636363,stroke-width:2px;

    %% Click Events for Component Mapping
    click FE "https://github.com/gotson/komga/tree/master/komga-webui/"
    click KT "https://github.com/gotson/komga/tree/master/komga-tray/"
    click INT "https://github.com/gotson/komga/tree/master/komga/src/main/kotlin/org/gotson/komga/interfaces"
    click AS "https://github.com/gotson/komga/tree/master/komga/src/main/kotlin/org/gotson/komga/application"
    click DM "https://github.com/gotson/komga/tree/master/komga/src/main/kotlin/org/gotson/komga/domain"
    click INF "https://github.com/gotson/komga/tree/master/komga/src/main/kotlin/org/gotson/komga/infrastructure"
    click FK "https://github.com/gotson/komga/tree/master/komga/src/flyway/kotlin/db/migration/sqlite/"
    click FS "https://github.com/gotson/komga/tree/master/komga/src/flyway/resources/db/migration/sqlite/"
    click EX "https://github.com/gotson/komga/tree/master/komga/src/main/kotlin/org/gotson/komga/interfaces/api/opds/"
    click MP "https://github.com/gotson/komga/tree/master/komga/src/main/kotlin/org/gotson/komga/infrastructure/metadata"
    click CA "https://github.com/gotson/komga/tree/master/komga/src/main/kotlin/org/gotson/komga/infrastructure/cache/"
    click SE "https://github.com/gotson/komga/tree/master/komga/src/main/kotlin/org/gotson/komga/infrastructure/security/"
    click FSCR "https://github.com/gotson/komga/blob/master/komga/src/main/kotlin/org/gotson/komga/domain/service/FileSystemScanner.kt"
    click SRCH "https://github.com/gotson/komga/tree/master/komga/src/main/kotlin/org/gotson/komga/infrastructure/search/"
```
