# readium/swift-toolkit architecture

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

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

## Overview

##### Project type and purpose
- This is a **modular Swift toolkit** for ebook/audiobook/comic reading. It exposes multiple independent frameworks (Shared, Streamer, Navigator, OPDS, LCP, plus Adapters).
- A **TestApp** demonstrates how to compose these frameworks into a reading application.

##### File structure
- **Sources/** houses the core Swift modules:
- Adapters (GCDWebServer, LCPSQLite)
- Internal (utility extensions, JSON, Measure, etc.)
- Shared (low-level toolkit: HTTP, ZIP, format sniffers, XML, URL, archive, logging)
- Streamer (publication parsing: EPUB, PDF, audio, Readium webpub)
- OPDS (catalog parsing)
- LCP (license management, DRM workflows, passphrase, licensing service)
- Navigator (UI rendering: EPUB, PDF, CBZ, audio; preferences; input; decoration)
- **TestApp/** – an example iOS application with MVC components that consumes these modules.
- Package manifests (`Package.swift`), Carthage and CocoaPods specs, plus build tools.

##### README for additional insights
- Lists the modules and which features each provides.
- Describes dependencies between modules (e.g. Navigator → Shared, Streamer, Internal; Streamer → Shared; OPDS → Shared; LCP → Shared).
- Mentions external frameworks (R2LCPClient, SQLite.swift, GCDWebServer).

- **TestApp (iOS App)**
- **ReadiumShared** (core toolkit: HTTPClient, ZIP, format sniffers, logging)
- **ReadiumStreamer** (publication parser)
- **ReadiumOPDS** (catalog parser)
- **ReadiumLCP** (DRM license management)
- **ReadiumNavigator** (UI rendering engine)
- **Adapters**: GCDWebServer adapter, LCPSQLite adapter
- **External Services**: SQLite database, HTTP server, R2LCPClient.framework
- TestApp → Navigator, OPDS, LCP, Streamer, Shared
- Navigator → Streamer (requests parsed publications)
- Navigator → Shared (logging, resource loading, HTTP client)
- Streamer → Shared (archive & format services, HTTP for webpub)
- OPDS → Shared (HTTP, XML parsing)
- LCP → Shared (crypto, network)
- Adapters → Shared (database via SQLite, HTTP server)
- LCP → Adapters (stores license in SQLite)
- TestApp → Adapters (starts local HTTP server for debugging)
c. Architectural patterns & principles:
- **Layered architecture**:
Shared (foundation) → Streamer/OPDS/LCP → Navigator → TestApp
- **Adapter pattern**: GCDWebServer and SQLite adapters implement abstract toolkit interfaces.
- **Dependency injection**: modules accept protocol-based clients (HTTPClient, Database).
- **Modularity**: each Readium library can be used independently.
d. Technologies & frameworks:
- Swift Package Manager / Carthage / CocoaPods
- Swift 5.10+ / iOS 13.4+
- Fuzi (XML) / ZIPFoundation / Minizip / CryptoSwift
- GCDWebServer / SQLite.swift / R2LCPClient

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Foundation Layer
    subgraph "Foundation"
        Shared["ReadiumShared"] 
        Internal["Internal"]
    end

    %% Parsing Modules
    subgraph "Parsing Modules"
        Streamer["ReadiumStreamer"]
        OPDS["ReadiumOPDS"]
    end

    %% DRM Module
    subgraph "DRM Module"
        LCP["ReadiumLCP"]
    end

    %% UI Layer
    subgraph "UI Layer"
        Navigator["ReadiumNavigator"]
        TestApp["TestApp (iOS App)"]
    end

    %% Adapters
    subgraph "Adapters"
        GCDWebServer["GCDWebServer Adapter"]
        LCPSQLite["LCPSQLite Adapter"]
    end

    %% External Services
    subgraph "External Services"
        HTTPServer["HTTP Server"]
        SQLiteDB["SQLite DB"]
        R2LCPClient["R2LCPClient.framework"]
    end

    %% Build & Tooling
    subgraph "Build & Tooling"
        PackageSwift["Package Manifest"]
        Carthage["Carthage Support"]
        CocoaPods["CocoaPods Specs"]
    end

    %% Connections - Application
    TestApp -->|uses| Navigator
    TestApp -->|uses| Streamer
    TestApp -->|uses| OPDS
    TestApp -->|uses| LCP
    TestApp -->|uses| Shared
    TestApp -->|starts| GCDWebServer

    %% Navigator Dependencies
    Navigator -->|requests publications| Streamer
    Navigator -->|uses| Shared

    %% Parsing Dependencies
    Streamer -->|uses| Shared
    OPDS -->|uses| Shared

    %% DRM Dependencies
    LCP -->|uses| Shared
    LCP -->|fetches license| R2LCPClient
    LCP -->|stores license| LCPSQLite

    %% Adapter Dependencies
    GCDWebServer -->|implements HTTP| Shared
    GCDWebServer -->|serves| HTTPServer
    LCPSQLite -->|implements Database| Shared
    LCPSQLite -->|stores data| SQLiteDB

    %% Build & Tooling usage
    PackageSwift -->|defines packages| Shared
    PackageSwift -->|defines packages| Streamer
    PackageSwift -->|defines packages| OPDS
    PackageSwift -->|defines packages| LCP
    PackageSwift -->|defines packages| Navigator
    Carthage -->|schemes| Shared
    Carthage -->|schemes| Streamer
    CocoaPods -->|podspecs| Shared
    CocoaPods -->|podspecs| Streamer

    %% Styling
    classDef foundation fill:#dddddd,stroke:#333
    classDef parsing fill:#bbdefb,stroke:#333
    classDef drm fill:#ffcdd2,stroke:#333
    classDef ui fill:#c8e6c9,stroke:#333
    classDef adapters fill:#ffe0b2,stroke:#333
    classDef external fill:#fff9c4,stroke:#333

    class Shared,Internal foundation
    class Streamer,OPDS parsing
    class LCP drm
    class Navigator,TestApp ui
    class GCDWebServer,LCPSQLite adapters
    class HTTPServer,SQLiteDB,R2LCPClient external
    class PackageSwift,Carthage,CocoaPods external

    %% Click Events
    click TestApp "https://github.com/readium/swift-toolkit/tree/develop/TestApp/Sources"
    click Shared "https://github.com/readium/swift-toolkit/tree/develop/Sources/Shared"
    click Internal "https://github.com/readium/swift-toolkit/tree/develop/Sources/Internal"
    click Streamer "https://github.com/readium/swift-toolkit/tree/develop/Sources/Streamer"
    click OPDS "https://github.com/readium/swift-toolkit/tree/develop/Sources/OPDS"
    click LCP "https://github.com/readium/swift-toolkit/tree/develop/Sources/LCP"
    click Navigator "https://github.com/readium/swift-toolkit/tree/develop/Sources/Navigator"
    click GCDWebServer "https://github.com/readium/swift-toolkit/tree/develop/Sources/Adapters/GCDWebServer"
    click LCPSQLite "https://github.com/readium/swift-toolkit/tree/develop/Sources/Adapters/LCPSQLite"
    click PackageSwift "https://github.com/readium/swift-toolkit/blob/develop/Package.swift"
    click Carthage "https://github.com/readium/swift-toolkit/tree/develop/Support/Carthage"
    click CocoaPods "https://github.com/readium/swift-toolkit/tree/develop/Support/CocoaPods"
```
