# koreader/koreader-base architecture

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

- Interactive diagram: https://gitdiagram.com/koreader/koreader-base
- Repository: https://github.com/koreader/koreader-base

## Overview

##### Main Components
- Core Reader Engine: This is the heart of the system and includes the manually coded source files (for example, blitbuffer.c/h, cre.cpp/h, djvu.c/h, nnsvg.c/h, xtext.cpp/h, etc.). These components are responsible for document rendering and processing.
- Scripting Layer: Highlight the Lua integration (Lua scripts and FFI Lua modules found under the “ffi” directory). This layer interfaces with the core engine via the FFI bindings.
- FFI/C-binding Layer: Indicate the two directories “ffi” (Lua side) and “ffi-cdecl” (C declarations) which clearly abstract and bridge C libraries with Lua.
- Device and Input Abstraction: The “input” directory contains device input handlers, and parts of the code (like framebuffer handling in many “framebuffer_*.lua” files) abstract e-ink hardware and input devices.
- Emulation & UI Rendering: The device emulation using SDL2 (as detailed in the README) sits on top of the core engine to allow desktop development and testing. This component should be marked as an optional “device simulator” that mimics the hardware.
- External Libraries and Thirdparty Dependencies: Represent these as boxed components (e.g., MuPDF, djvulibre, CREngine, libk2pdfopt, and the extensive “thirdparty” folder) that are integrated with the main engine. Emphasize that these libraries are fetched/built as part of the build process and that their use is coordinated via CMake and Makefiles.

##### Relationships and Data Flow
- FFI layer as a mediator between the Lua side and the C/C++ core libraries.
- How the Input subsystem feeds events into the Core Engine, and how the Emulation layer (using SDL2) intercepts the display and input flows to simulate device behavior.
- Build/integration layer (CMake/Makefile) as a background/overlay element managing dependency integration and target-specific builds. While not part of the runtime, it’s key for understanding platform-specific configuration flow.

##### Architectural Patterns and Design Principles
- Layered Architecture: Distinguish between low-level rendering (native C/C++ code and external libraries), scripting (Lua, LuaJIT), and abstraction (FFI bindings).
- Cross-Platform Design: Show that different “targets” (Kindle, Kobo, etc.) are supported through compile-time parameters and conditional configurations—in the build system and possibly reflected in the input and framebuffer code.

##### Final Touches
- Every module gets a distinct visual treatment and all interdependencies (especially between FFI, native libraries, and Lua scripting) are clearly mapped.
- Avoid overcrowding by grouping tightly coupled thirdparty libraries together but note some key ones (MuPDF, djvulibre) if they are central to the rendering process.
- Don’t forget to document device-specific paths (target-specific build options from the README) to show how the same core architecture adapts to various hardware profiles.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Core Reader Engine
    subgraph "Core Reader Engine"
        core_blitbuffer_c["blitbuffer.c"]:::core
        core_blitbuffer_h["blitbuffer.h"]:::core
        core_cre_cpp["cre.cpp"]:::core
        core_cre_h["cre.h"]:::core
        core_djvu_c["djvu.c"]:::core
        core_djvu_h["djvu.h"]:::core
        core_nnsvg_c["nnsvg.c"]:::core
        core_nnsvg_h["nnsvg.h"]:::core
        core_xtext_cpp["xtext.cpp"]:::core
        core_xtext_h["xtext.h"]:::core
    end

    %% Lua Scripting & FFI
    subgraph "Lua Scripting & FFI"
        script_MD5["MD5.lua"]:::script
        script_blitbuffer["blitbuffer.lua"]:::script
        script_mupdf["mupdf.lua"]:::script
        script_framebuffer["framebuffer.lua"]:::script
        script_fb_sdl["framebuffer_SDL2_0.lua"]:::script
        script_fb_android["framebuffer_android.lua"]:::script
        script_sdl2["SDL2_0.lua"]:::script
        ffi_cdecl["ffi-cdecl"]:::ffi
    end

    %% Input & Device Abstraction
    subgraph "Input & Device Abstraction"
        input_c["input.c"]:::input
        input_h["input.h"]:::input
        input_kindle["input-kindle.h"]:::input
    end

    %% Device Emulation (SDL2)
    subgraph "Device Emulation (SDL2)"
        device_emul["Device Emulation"]:::emul
    end

    %% External Dependencies
    subgraph "External Dependencies"
        thirdparty_node["Thirdparty Libraries"]:::external
    end

    %% Build & CI Integration
    subgraph "Build & CI Integration"
        cmake_lists["CMakeLists.txt"]:::build
        makefile_node["Makefile"]:::build
        cmake_dir["cmake/"]:::build
        ci_node[".ci"]:::build
        circleci_node[".circleci"]:::build
        github_node[".github"]:::build
    end

    %% Relationships and Data Flow
    script_MD5 -->|"FFIcall"| core_blitbuffer_c
    ffi_cdecl -->|"bridge"| core_blitbuffer_c
    input_c -->|"inputEvents"| core_blitbuffer_c
    device_emul -->|"simInput"| input_c
    device_emul -->|"simDisplay"| core_blitbuffer_c
    core_blitbuffer_c -->|"delegatesRendering"| thirdparty_node
    cmake_lists -.->|"buildsCore"| core_blitbuffer_c
    cmake_lists -.->|"buildsDeps"| thirdparty_node

    %% Styles
    classDef core fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef script fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef ffi fill:#58D68D,stroke:#186A3B,stroke-width:2px;
    classDef input fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef emul fill:#F5CBA7,stroke:#A04000,stroke-width:2px;
    classDef external fill:#FADBD8,stroke:#922B21,stroke-width:2px;
    classDef build fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;

    %% Click Events for Core Reader Engine
    click core_blitbuffer_c "https://github.com/koreader/koreader-base/blob/master/blitbuffer.c"
    click core_blitbuffer_h "https://github.com/koreader/koreader-base/blob/master/blitbuffer.h"
    click core_cre_cpp "https://github.com/koreader/koreader-base/blob/master/cre.cpp"
    click core_cre_h "https://github.com/koreader/koreader-base/blob/master/cre.h"
    click core_djvu_c "https://github.com/koreader/koreader-base/blob/master/djvu.c"
    click core_djvu_h "https://github.com/koreader/koreader-base/blob/master/djvu.h"
    click core_nnsvg_c "https://github.com/koreader/koreader-base/blob/master/nnsvg.c"
    click core_nnsvg_h "https://github.com/koreader/koreader-base/blob/master/nnsvg.h"
    click core_xtext_cpp "https://github.com/koreader/koreader-base/blob/master/xtext.cpp"
    click core_xtext_h "https://github.com/koreader/koreader-base/blob/master/xtext.h"

    %% Click Events for Lua Scripting & FFI
    click script_MD5 "https://github.com/koreader/koreader-base/blob/master/ffi/MD5.lua"
    click script_blitbuffer "https://github.com/koreader/koreader-base/blob/master/ffi/blitbuffer.lua"
    click script_mupdf "https://github.com/koreader/koreader-base/blob/master/ffi/mupdf.lua"
    click script_framebuffer "https://github.com/koreader/koreader-base/blob/master/ffi/framebuffer.lua"
    click script_fb_sdl "https://github.com/koreader/koreader-base/blob/master/ffi/framebuffer_SDL2_0.lua"
    click script_fb_android "https://github.com/koreader/koreader-base/blob/master/ffi/framebuffer_android.lua"
    click script_sdl2 "https://github.com/koreader/koreader-base/blob/master/ffi/SDL2_0.lua"
    click ffi_cdecl "https://github.com/koreader/koreader-base/tree/master/ffi-cdecl"

    %% Click Events for Input & Device Abstraction
    click input_c "https://github.com/koreader/koreader-base/blob/master/input/input.c"
    click input_h "https://github.com/koreader/koreader-base/blob/master/input/input.h"
    click input_kindle "https://github.com/koreader/koreader-base/blob/master/input/input-kindle.h"

    %% Click Event for External Dependencies
    click thirdparty_node "https://github.com/koreader/koreader-base/tree/master/thirdparty"

    %% Click Events for Build & CI Integration
    click cmake_lists "https://github.com/koreader/koreader-base/blob/master/CMakeLists.txt"
    click makefile_node "https://github.com/koreader/koreader-base/tree/master/Makefile"
    click cmake_dir "https://github.com/koreader/koreader-base/tree/master/cmake/"
    click ci_node "https://github.com/koreader/koreader-base/blob/master/.ci"
    click circleci_node "https://github.com/koreader/koreader-base/blob/master/.circleci"
    click github_node "https://github.com/koreader/koreader-base/blob/master/.github"
```
