# folioreader/folioreaderkit architecture

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

- Interactive diagram: https://gitdiagram.com/folioreader/folioreaderkit
- Repository: https://github.com/folioreader/folioreaderkit

## Overview

##### Project type and purpose
- FolioReaderKit is an iOS framework (CocoaPod/Carthage) written in Swift that parses and renders ePub files, provides UI for reading, highlights, TTS, Media Overlays, and exposes delegate hooks to the host app.

##### File structure
- Top-level “Source” folder: contains Swift source code organized by feature (EPUBCore parser, UI components, models, resources, extensions).
- “Example” folder: sample apps demonstrating programmatic and storyboard integration.
- “Vendor” & “docs”: packaged JavaScript bridge, CSS, Jazzy documentation.
- Config, Podspec, Package.swift: define packaging/dependency setup.
- Tests: unit tests for parsing and sharing provider.

##### Key insights from README
- Core features: EPUB 2/3 parsing, custom fonts, highlights, themes, TTS, Media Overlays, multi-instance support.
- Usage patterns: call `FolioReader.presentReader`, subclass `FolioReaderContainer`, implement `FolioReaderDelegate` to receive events.

##### Main components to portray
a. Parsing Layer (green)
- FREpubParser → FRBook, FRSpine, FRResources, FRResource, FRMetadata, FRTocReference, FRSmilElement
- Media overlay sync (SMIL) feeds to audio player
b. Rendering & UI Layer (blue)
- FolioReaderContainer (UIViewController subclass)
- FolioReaderCenter (singleton/controller orchestrator)
- FolioReaderWebView (WKWebView + Bridge.js injection + Style.css)
- PageViewController / FolioReaderPage (UIPageViewController + page indicator)
- Menus: FontsMenu, PlayerMenu, ChapterList, HighlightList, QuoteShare
c. Audio & TTS (orange)
- FolioReaderAudioPlayer (AVFoundation for Media Overlays & TTS)
d. Models & Storage (yellow)
- Model, QuoteImage, UserDefaults wrapper (FolioReaderUserDefaults)
e. Host App Integration (purple)
- FolioReaderDelegate & FolioReaderCenterDelegate (protocols)
- Host passes epub path + config (FolioReaderConfig) → receives callbacks
f. Resources (gray)
- Bridge.js, CSS, Fonts, Images

##### Relationships & data flow
- Input: App provides `.epub` file → FREpubParser builds FRBook
- Parser outputs resources & HTML/CSS → loaded into WKWebView via FolioReaderWebView
- PageViewController drives navigation; UI menus invoke actions on FolioReaderCenter
- Bridge.js posts events (highlight tapped, location changed) back to Swift via message handlers
- FolioReaderAudioPlayer requests SMIL timings → plays audio overlay or TTS; updates UI via FolioReaderCenter
- Actions update model & persist via UserDefaults → reflected in UI
- Delegate callbacks propagate reading events back to host app

##### Architectural patterns & principles
- MVC / Coordinator: FolioReaderCenter coordinates between model (parser, highlights, audio) and view (webView, menus)
- Delegation: host integration via protocols
- Composition: container view controllers + child page controllers
- Bridge pattern: JavaScript ↔ Swift communication
- Single Responsibility: parser, UI, audio, storage each isolated

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Parsing Layer"
        Parser["FREpubParser"]:::parser
        Book["FRBook"]:::parser
        Spine["FRSpine"]:::parser
        ResourcesCore["FRResources"]:::parser
        Resource["FRResource"]:::parser
        Metadata["FRMetadata"]:::parser
        Toc["FRTocReference"]:::parser
        Smil["FRSmilElement & FRSmils"]:::parser
        MediaType["MediaType"]:::parser
    end

    subgraph "Rendering & UI Layer"
        Container["FolioReaderContainer"]:::ui
        Center["FolioReaderCenter"]:::ui
        WebView["FolioReaderWebView"]:::ui
        PageVC["PageViewController"]:::ui
        Page["FolioReaderPage"]:::ui
        Indicator["FolioReaderPageIndicator"]:::ui
        FontsMenu["FontsMenu"]:::ui
        PlayerMenu["PlayerMenu"]:::ui
        ChapterList["ChapterList"]:::ui
        HighlightList["HighlightList"]:::ui
        QuoteShare["QuoteShare"]:::ui
    end

    subgraph "Audio & TTS"
        Audio["FolioReaderAudioPlayer"]:::audio
    end

    subgraph "Models & Storage"
        Highlight["Highlight & Helper"]:::storage
        QuoteImage["QuoteImage"]:::storage
        StorageUD["FolioReaderUserDefaults"]:::storage
    end

    subgraph "Host App Integration"
        Config["FolioReaderConfig"]:::host
        Delegate["FolioReaderDelegate & CenterDelegate"]:::host
        Extensions["Extensions"]:::host
        ExampleProg["Programmatic Example"]:::host
        ExampleStory["Storyboard Example"]:::host
        ExampleMain["Main Example"]:::host
    end

    subgraph "Resources"
        Bridge["Bridge.js"]:::resources
        Style["Style.css"]:::resources
    end

    UIKit["UIKit/WebKit/AVFoundation"]:::external

    ExampleMain -->|uses| Config
    ExampleProg -->|uses| Config
    ExampleStory -->|uses| Config

    Config -->|provide epub file| Container
    Container -->|start reader| Center

    Center -->|parses| Parser
    Parser -->|builds| Book
    Book --> Spine
    Book --> ResourcesCore
    ResourcesCore --> Resource
    Book --> Metadata
    Book --> Toc
    Smil -->|SMIL data| Audio

    Resource -->|HTML/CSS| WebView
    Bridge -->|injected| WebView
    Style -->|applied| WebView

    WebView -->|events| Center
    Center -->|controls| PageVC
    PageVC --> Page
    PageVC --> Indicator

    Center -->|open menu| FontsMenu
    Center -->|open menu| PlayerMenu
    Center -->|open menu| ChapterList
    Center -->|open menu| HighlightList
    Center -->|open menu| QuoteShare

    Center -->|audio actions| Audio
    Audio -->|update UI| Center

    Center -->|update model| Highlight
    Center -->|persist| StorageUD
    Center -->|refresh| HighlightList

    Center -->|callbacks| Delegate
    Container -->|uses| UIKit
    Parser -->|uses| UIKit
    WebView -->|uses| UIKit
    Audio -->|uses| UIKit

    click Parser "https://github.com/folioreader/folioreaderkit/blob/master/Source/EPUBCore/FREpubParser.swift"
    click Book "https://github.com/folioreader/folioreaderkit/blob/master/Source/EPUBCore/FRBook.swift"
    click Spine "https://github.com/folioreader/folioreaderkit/blob/master/Source/EPUBCore/FRSpine.swift"
    click ResourcesCore "https://github.com/folioreader/folioreaderkit/blob/master/Source/EPUBCore/FRResources.swift"
    click Resource "https://github.com/folioreader/folioreaderkit/blob/master/Source/EPUBCore/FRResource.swift"
    click Metadata "https://github.com/folioreader/folioreaderkit/blob/master/Source/EPUBCore/FRMetadata.swift"
    click Toc "https://github.com/folioreader/folioreaderkit/blob/master/Source/EPUBCore/FRTocReference.swift"
    click Smil "https://github.com/folioreader/folioreaderkit/blob/master/Source/EPUBCore/FRSmilElement.swift"
    click MediaType "https://github.com/folioreader/folioreaderkit/blob/master/Source/EPUBCore/MediaType.swift"

    click Container "https://github.com/folioreader/folioreaderkit/blob/master/Source/FolioReaderContainer.swift"
    click Center "https://github.com/folioreader/folioreaderkit/blob/master/Source/FolioReaderCenter.swift"
    click WebView "https://github.com/folioreader/folioreaderkit/blob/master/Source/FolioReaderWebView.swift"
    click PageVC "https://github.com/folioreader/folioreaderkit/blob/master/Source/PageViewController.swift"
    click Page "https://github.com/folioreader/folioreaderkit/blob/master/Source/FolioReaderPage.swift"
    click Indicator "https://github.com/folioreader/folioreaderkit/blob/master/Source/FolioReaderPageIndicator.swift"
    click FontsMenu "https://github.com/folioreader/folioreaderkit/blob/master/Source/FolioReaderFontsMenu.swift"
    click PlayerMenu "https://github.com/folioreader/folioreaderkit/blob/master/Source/FolioReaderPlayerMenu.swift"
    click ChapterList "https://github.com/folioreader/folioreaderkit/blob/master/Source/FolioReaderChapterList.swift"
    click HighlightList "https://github.com/folioreader/folioreaderkit/blob/master/Source/FolioReaderHighlightList.swift"
    click QuoteShare "https://github.com/folioreader/folioreaderkit/blob/master/Source/FolioReaderQuoteShare.swift"

    click Audio "https://github.com/folioreader/folioreaderkit/blob/master/Source/FolioReaderAudioPlayer.swift"

    click Highlight "https://github.com/folioreader/folioreaderkit/blob/master/Source/Models/Highlight.swift"
    click QuoteImage "https://github.com/folioreader/folioreaderkit/blob/master/Source/QuoteImage.swift"
    click StorageUD "https://github.com/folioreader/folioreaderkit/blob/master/Source/FolioReaderUserDefaults.swift"

    click Config "https://github.com/folioreader/folioreaderkit/blob/master/Source/FolioReaderConfig.swift"
    click Delegate "https://github.com/folioreader/folioreaderkit/blob/master/docs/Protocols/FolioReaderDelegate.html"
    click Extensions "https://github.com/folioreader/folioreaderkit/blob/master/Source/Extensions.swift"
    click ExampleProg "https://github.com/folioreader/folioreaderkit/blob/master/Example/MultipleInstances-Example/CodeExample/CodeExampleViewController.swift"
    click ExampleStory "https://github.com/folioreader/folioreaderkit/blob/master/Example/Storyboard-Example/ExampleFolioReaderContainer.swift"
    click ExampleMain "https://github.com/folioreader/folioreaderkit/blob/master/Example/Example/ViewController.swift"

    click Bridge "https://github.com/folioreader/folioreaderkit/blob/master/Source/Resources/Bridge.js"
    click Style "https://github.com/folioreader/folioreaderkit/blob/master/Source/Resources/Style.css"

    classDef parser fill:#ccffcc,stroke:#333
    classDef ui fill:#cce5ff,stroke:#333
    classDef audio fill:#ffe5b4,stroke:#333
    classDef storage fill:#fff3b0,stroke:#333
    classDef host fill:#e5ccff,stroke:#333
    classDef resources fill:#e6e6e6,stroke:#333
    classDef external stroke-dasharray:5 5,stroke:#666,fill:none
```
