# readium/kotlin-toolkit architecture

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

- Interactive diagram: https://gitdiagram.com/readium/kotlin-toolkit
- Repository: https://github.com/readium/kotlin-toolkit

## Overview

##### Project Type and Purpose
- This is a multi‑module Android/Kotlin library toolkit (Readium Kotlin Toolkit) providing an ecosystem for reading ebooks, audiobooks, comics and catalogs.
- It is not a single application but a set of Gradle modules (shared core, parser/“streamer,” navigator UI, adapters for rendering engines, LCP DRM, OPDS catalog support) plus a `test‑app` demo that ties them together.

##### High‑Level Module Structure
- **readium-shared**: Core data types, utilities, resource loading, OPDS/Publication models – the foundation for all other modules.
- **readium-streamer**: Publication parser services (EPUB, PDF, CBZ, audio metadata), positions services. Depends on `shared`.
- **readium-navigator**: UI layer to display publications (epub, pdf, cbz) in Android WebViews/Fragments, input handling, pagination, preferences. Depends on `shared`, `streamer`.
- **readium-lcp**: License acquisition, decryption, persistent storage, authentication flows. Depends on `shared`.
- **readium-opds**: OPDS feed parsers (1 & 2), feed-to-model mapping. Depends on `shared`.
- **readium-adapters**: Plugins that connect navigator to third‑party engines
- ExoPlayer audio adapter
- PDFium & PSPDFKit document and navigator adapters
- (Each adapter is its own submodule that depends on core navigator interfaces.)
- **readium-navigators**: Alternate navigator implementations (common, demo, media audio, TTS, web) illustrating different patterns and driver services.
- **test-app**: Sample Android application demonstrating integration of the above modules in a complete reader app, with its own data layer, UI screens, navigation graph, persistent storage, ViewModels, and dependency wiring.

##### Essential Elements to Capture
- All major Kotlin modules as separate components
- Adapter modules hooking into navigator interfaces
- `test-app` at the top, showing it orchestrates modules into a working reader

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Demo Application
    TestApp["test-app\n(Demo Application)"]:::demo

    %% Navigator & UI Layer
    subgraph "Rendering & Navigation Layer"
        Navigator["readium-navigator\n(Base UI)"]:::ui
    end

    %% Adapters Layer
    subgraph "Adapter Plugins"
        ExoAudio["ExoPlayer Audio Adapter"]:::adapters
        PDFiumDoc["PDFium Document Adapter"]:::adapters
        PDFiumNav["PDFium Navigator Adapter"]:::adapters
        PSPDFDoc["PSPDFKit Document Adapter"]:::adapters
        PSPDFNav["PSPDFKit Navigator Adapter"]:::adapters
    end

    %% Alternative Navigators
    subgraph "Alternate Navigators"
        NavCommon["Common Navigator Implementation"]:::ui
        NavDemo["Demo Navigator Implementation"]:::ui
        NavMediaCommon["Media Common Utilities"]:::ui
        NavMediaAudio["Media Audio Navigator"]:::ui
        NavMediaTTS["Media TTS Navigator"]:::ui
        NavWeb["Web Navigator"]:::ui
    end

    %% Parser, DRM & Catalog Layers
    subgraph "Parser & Positions Services"
        Streamer["readium-streamer\n(Parser Layer)"]:::parser
    end
    subgraph "DRM Services"
        LCP["readium-lcp\n(DRM Layer)"]:::drm
    end
    subgraph "Catalog Services"
        OPDS["readium-opds\n(Catalog Layer)"]:::drm
    end

    %% Core Layer
    Shared["readium-shared\n(Core Layer)"]:::core

    %% Dependencies
    TestApp -->|"compile-time"| Navigator
    TestApp -->|"compile-time"| Streamer
    TestApp -->|"compile-time"| LCP
    TestApp -->|"compile-time"| OPDS
    TestApp -->|"compile-time"| Shared

    Navigator -->|"uses parser services"| Streamer
    Navigator -->|"uses DRM services"| LCP
    Navigator -->|"uses models"| Shared

    ExoAudio ---|runtime plugin| Navigator
    PDFiumDoc ---|runtime plugin| Navigator
    PDFiumNav ---|runtime plugin| Navigator
    PSPDFDoc ---|runtime plugin| Navigator
    PSPDFNav ---|runtime plugin| Navigator

    NavCommon ---|alternative navigator| Navigator
    NavDemo ---|alternative navigator| Navigator
    NavMediaCommon ---|alternative navigator| Navigator
    NavMediaAudio ---|alternative navigator| Navigator
    NavMediaTTS ---|alternative navigator| Navigator
    NavWeb ---|alternative navigator| Navigator

    OPDS -->|"produces models"| Navigator

    Streamer -->|"depends on"| Shared
    LCP -->|"depends on"| Shared
    OPDS -->|"depends on"| Shared

    %% Click Events
    click Shared "https://github.com/readium/kotlin-toolkit/tree/develop/readium/shared"
    click Streamer "https://github.com/readium/kotlin-toolkit/tree/develop/readium/streamer"
    click LCP "https://github.com/readium/kotlin-toolkit/tree/develop/readium/lcp"
    click OPDS "https://github.com/readium/kotlin-toolkit/tree/develop/readium/opds"
    click Navigator "https://github.com/readium/kotlin-toolkit/tree/develop/readium/navigator"
    click ExoAudio "https://github.com/readium/kotlin-toolkit/tree/develop/readium/adapters/exoplayer/audio"
    click PDFiumDoc "https://github.com/readium/kotlin-toolkit/tree/develop/readium/adapters/pdfium/document"
    click PDFiumNav "https://github.com/readium/kotlin-toolkit/tree/develop/readium/adapters/pdfium/navigator"
    click PSPDFDoc "https://github.com/readium/kotlin-toolkit/tree/develop/readium/adapters/pspdfkit/document"
    click PSPDFNav "https://github.com/readium/kotlin-toolkit/tree/develop/readium/adapters/pspdfkit/navigator"
    click NavCommon "https://github.com/readium/kotlin-toolkit/tree/develop/readium/navigators/common"
    click NavDemo "https://github.com/readium/kotlin-toolkit/tree/develop/readium/navigators/demo"
    click NavMediaCommon "https://github.com/readium/kotlin-toolkit/tree/develop/readium/navigators/media/common"
    click NavMediaAudio "https://github.com/readium/kotlin-toolkit/tree/develop/readium/navigators/media/audio"
    click NavMediaTTS "https://github.com/readium/kotlin-toolkit/tree/develop/readium/navigators/media/tts"
    click NavWeb "https://github.com/readium/kotlin-toolkit/tree/develop/readium/navigators/web"
    click TestApp "https://github.com/readium/kotlin-toolkit/tree/develop/test-app"

    %% Styles
    classDef core fill:#DDDDDD,stroke:#333,stroke-width:1px
    classDef parser fill:#AEDFF7,stroke:#333,stroke-width:1px
    classDef drm fill:#D3BBC8,stroke:#333,stroke-width:1px
    classDef ui fill:#C8E6C9,stroke:#333,stroke-width:1px
    classDef adapters fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef demo fill:#FFCDD2,stroke:#333,stroke-width:1px
```
