# litres/fb3reader architecture

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

- Interactive diagram: https://gitdiagram.com/litres/fb3reader
- Repository: https://github.com/litres/fb3reader

## Overview

##### Main Components
- Core Engine (FB3Reader): This is the heart of the project, located in the “src/Reader” directory (including FB3Reader.ts, FB3Reader.head.ts, FB3ReaderPage.ts, and related files). It handles rendering of the eBook and user interactions.
- Data Providers: Housed under “src/DataProvider”, these modules (FB3AjaxDataProvider.ts, FB3DataProvider.head.ts, and the AjaxGenerator’s XSL, Perl, and other scripts) are responsible for fetching and transforming book data (in FB2/FB3 formats) from AJAX sources.
- Storage and Caching: Under “src/Storage”, “src/TextCache”, “src/PagesPositionsCache”, and “src/MediaCache” are modules that manage in-browser storage and caching (using implementations based on IndexedDB and LocalStorage, plus caching strategies in “CacheStrategies”). This layer is critical for performance and offline capabilities.
- DOM and Document Tools: Found in “src/DOM”, these modules (e.g., FB3DOM.ts, DocumentTools.ts, and FB3DOMBlock.ts) abstract and manipulate the document object model for the eBook content.
- Additional Components:
– Bookmarks management is provided in “src/Bookmarks”.
– Site integration (FB3ReaderSite) that possibly configures or interacts with the surrounding web-page environment.
- Plugins: The “plugins” directory (for example “plugins/catalit-web”) indicates that the engine has an extension system. Plugins such as DataProvider extensions or UI customizations should be represented.
- Example Web App: Located in “example-app”, this component serves as a concrete application using the engine – useful for demonstrating interactions between the library, UI, and other components.
- Server and Build Components: The “server” directory along with multiple webpack and configuration files (webpack.config.js, tsconfig.json, etc.) show that there is a build process (using webpack and TypeScript) as well as server-side components which aid testing or deployment.

##### Relationships and Interactions
- The Example App communicates with the Core Engine to initialize and render eBooks.
- The Core Engine makes use of the Data Providers to fetch and convert book data (AJAX responses, XML-to-JSON transformations, etc.).
- The Storage modules are used throughout the engine to cache text, page positions, media, and other relevant data to enhance responsiveness.
- The DOM modules interact with the rendered content to enable features like bookmarks, navigation, and real-time updating.
- The Build/Server components are on the periphery (or behind the scenes) and should be diagrammed as a supporting layer indicating the bundling (webpack) and testing (Jest) processes.

##### Architectural Patterns and Design Principles
- Modular Design: The project is broken into clear modules (Reader, DataProvider, Storage, DOM, etc.) that encapsulate specific responsibilities.
- Separation of Concerns: By splitting responsibilities into directories like “DataProvider”, “Storage”, “Reader”, and “DOM”, the design adheres to the single responsibility principle.
- Extensibility through Plugins: The dedicated “plugins” directory recommends an architecture where new functionalities can be added without altering the core.
- Use of Modern Web Standards: The heavy reliance on TypeScript and the use of webpack for bundling shows that the project uses current web technologies for maintainability and performance.

##### Relevant Technologies and Frameworks
- TypeScript – for static typing and improved maintainability.
- JavaScript (compiled output) – for browser execution.
- webpack – to bundle and optimize the engine.
- Node.js/npm – for dependency management and build tasks.
- Jest – for unit and E2E testing (as indicated by both __tests__ and jest-puppeteer config files).
- AJAX/Data Transformation tools – such as XSL stylesheets and Perl scripts found in the DataProvider directory.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        EA["Example App"]:::presentation
        SI["Site Integration"]:::presentation
    end

    %% Core Engine Layer
    subgraph "Core Engine Layer"
        CR["FB3Reader Core"]:::core
    end

    %% Data & Caching Layer
    subgraph "Data & Caching Layer"
        DP["Data Providers"]:::data
        S["Storage"]:::storage
        TC["TextCache"]:::storage
        PPC["PagesPositionsCache"]:::storage
        MC["MediaCache"]:::storage
    end

    %% DOM & Bookmarks Layer
    subgraph "DOM & Bookmarks Layer"
        DOM["DOM Tools"]:::dom
        BM["Bookmarks Management"]:::dom
    end

    %% Extension Layer
    subgraph "Extension Layer"
        PL["Plugin Architecture"]:::plugin
    end

    %% Build/Deployment Layer
    subgraph "Build/Deployment Layer"
        BT["Build Tools"]:::build
        SC["Server Components"]:::build
    end

    %% Connections
    EA -->|"initializes"| CR
    SI -->|"configures"| CR

    CR -->|"fetchesData"| DP
    CR -->|"cachesData"| S
    CR -->|"cachesText"| TC
    CR -->|"cachesPages"| PPC
    CR -->|"cachesMedia"| MC
    CR -->|"rendersContent"| DOM
    CR -->|"integratesBookmarks"| BM

    DOM -->|"supportsBookmarks"| BM
    PL -->|"extends"| CR

    BT -->|"bundles"| CR
    BT -->|"buildsApp"| EA
    SC -->|"hosts"| EA

    %% Styles
    classDef presentation fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef core fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef data fill:#ffa07a,stroke:#000,stroke-width:2px;
    classDef storage fill:#d8bfd8,stroke:#000,stroke-width:2px;
    classDef dom fill:#ffffb3,stroke:#000,stroke-width:2px;
    classDef plugin fill:#ffb6c1,stroke:#000,stroke-width:2px;
    classDef build fill:#d3d3d3,stroke:#000,stroke-width:2px;

    %% Click Events
    click CR "https://github.com/litres/fb3reader/tree/master/src/Reader"
    click DP "https://github.com/litres/fb3reader/tree/master/src/DataProvider"
    click S "https://github.com/litres/fb3reader/tree/master/src/Storage"
    click TC "https://github.com/litres/fb3reader/tree/master/src/TextCache"
    click PPC "https://github.com/litres/fb3reader/tree/master/src/PagesPositionsCache"
    click MC "https://github.com/litres/fb3reader/tree/master/src/MediaCache"
    click DOM "https://github.com/litres/fb3reader/tree/master/src/DOM"
    click BM "https://github.com/litres/fb3reader/tree/master/src/Bookmarks"
    click SI "https://github.com/litres/fb3reader/tree/master/src/Site"
    click PL "https://github.com/litres/fb3reader/tree/master/plugins/catalit-web"
    click EA "https://github.com/litres/fb3reader/tree/master/example-app"
    click SC "https://github.com/litres/fb3reader/tree/master/server"
    click BT "https://github.com/litres/fb3reader/blob/master/webpack.config.js"
```
