How koreader/koreader-base works
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.