crosspoint-reader-mod/mod/docs/file-structure.md

CrossPoint Reader -- Project File Structure

This document maps the repository layout and describes where key pieces of code can be found.

Root Directory

crosspoint-reader-mod/
├── platformio.ini          # PlatformIO build config (environments, flags, deps)
├── partitions.csv          # ESP32 flash partition table
├── .clang-format           # C++ code formatting rules (clang-format 21)
├── .clangd                 # Language server configuration
├── .gitmodules             # Git submodule reference (open-x4-sdk)
├── README.md               # Project overview and getting started
├── LICENSE                 # MIT License
├── GOVERNANCE.md           # Community governance principles
├── SCOPE.md                # Project vision and feature scope
├── USER_GUIDE.md           # End-user manual
├── bin/                    # Developer scripts
├── docs/                   # Upstream documentation
├── lib/                    # Project libraries (HAL, EPUB, fonts, etc.)
├── src/                    # Main application source code
├── scripts/                # Build and utility scripts (Python)
├── test/                   # Unit/evaluation tests
├── open-x4-sdk/            # Hardware SDK (git submodule)
├── include/                # PlatformIO include directory (empty)
├── mod/                    # Local modifications workspace
└── .github/                # CI workflows, templates, funding

src/ -- Application Source

The main firmware application code. Entry point is main.cpp.

src/
├── main.cpp                    # Arduino setup()/loop(), activity routing, font init
├── CrossPointSettings.cpp/.h   # User settings (load/save to SD, defaults)
├── CrossPointState.cpp/.h      # Runtime application state (open book, sleep tracking)
├── MappedInputManager.cpp/.h   # User-remappable button abstraction over HalGPIO
├── Battery.h                   # Global BatteryMonitor instance
├── fontIds.h                   # Numeric font family identifiers
├── SettingsList.h              # Setting definitions and enums
├── RecentBooksStore.cpp/.h     # Recently opened books persistence
├── WifiCredentialStore.cpp/.h  # Saved WiFi network credentials
│
├── activities/                 # UI screens (Activity pattern, see below)
├── components/                 # Shared UI components and themes
├── network/                    # Web server, HTTP, OTA updater
├── images/                     # Logo assets (SVG, PNG, compiled header)
└── util/                       # String and URL utility functions

src/activities/ -- UI Activity System

Each screen is an Activity subclass with onEnter(), onExit(), and loop() lifecycle methods. Activities are swapped by the routing functions in main.cpp.

activities/
├── Activity.h                              # Base Activity interface
├── ActivityWithSubactivity.cpp/.h          # Composition: activity that hosts a child
│
├── boot_sleep/
│   ├── BootActivity.cpp/.h                 # Boot splash screen
│   └── SleepActivity.cpp/.h               # Sleep screen (cover image, clock, etc.)
│
├── browser/
│   └── OpdsBookBrowserActivity.cpp/.h      # OPDS catalog browsing and download
│
├── home/
│   ├── HomeActivity.cpp/.h                 # Main menu / home screen
│   ├── MyLibraryActivity.cpp/.h            # File browser for books on SD card
│   └── RecentBooksActivity.cpp/.h          # Recently opened books list
│
├── network/
│   ├── CrossPointWebServerActivity.cpp/.h  # Web server file transfer mode
│   ├── CalibreConnectActivity.cpp/.h       # Calibre wireless device connection
│   ├── NetworkModeSelectionActivity.cpp/.h # WiFi/AP/Calibre mode picker
│   └── WifiSelectionActivity.cpp/.h        # WiFi network scanner and connector
│
├── reader/
│   ├── ReaderActivity.cpp/.h               # Format dispatcher (EPUB, TXT, XTC)
│   ├── EpubReaderActivity.cpp/.h           # EPUB reading engine
│   ├── EpubReaderMenuActivity.cpp/.h       # In-reader menu overlay
│   ├── EpubReaderChapterSelectionActivity.cpp/.h   # Table of contents navigation
│   ├── EpubReaderPercentSelectionActivity.cpp/.h   # Jump-to-percentage navigation
│   ├── TxtReaderActivity.cpp/.h            # Plain text reader
│   ├── XtcReaderActivity.cpp/.h            # XTC format reader
│   ├── XtcReaderChapterSelectionActivity.cpp/.h    # XTC chapter navigation
│   └── KOReaderSyncActivity.cpp/.h         # KOReader reading progress sync
│
├── settings/
│   ├── SettingsActivity.cpp/.h             # Main settings screen
│   ├── ButtonRemapActivity.cpp/.h          # Front button remapping UI
│   ├── CalibreSettingsActivity.cpp/.h      # Calibre server configuration
│   ├── ClearCacheActivity.cpp/.h           # Cache clearing utility
│   ├── KOReaderAuthActivity.cpp/.h         # KOReader auth credential entry
│   ├── KOReaderSettingsActivity.cpp/.h     # KOReader sync settings
│   └── OtaUpdateActivity.cpp/.h            # Over-the-air firmware update UI
│
└── util/
    ├── FullScreenMessageActivity.cpp/.h    # Full-screen status/error messages
    └── KeyboardEntryActivity.cpp/.h        # On-screen keyboard for text input

src/components/ -- UI Components and Themes

components/
├── UITheme.cpp/.h              # Theme manager singleton
└── themes/
    ├── BaseTheme.cpp/.h        # Default theme implementation
    └── lyra/
        └── LyraTheme.cpp/.h   # Alternative "Lyra" theme

src/network/ -- Networking

network/
├── CrossPointWebServer.cpp/.h  # HTTP web server (file management, upload, settings)
├── HttpDownloader.cpp/.h       # HTTP/HTTPS file downloader
├── OtaUpdater.cpp/.h           # OTA firmware update client
└── html/
    ├── HomePage.html           # Web UI home page
    ├── FilesPage.html          # Web UI file browser / upload page
    └── SettingsPage.html       # Web UI settings page

HTML files are minified at build time by scripts/build_html.py into PROGMEM C++ headers (.generated.h).

src/util/ -- Utilities

util/
├── StringUtils.cpp/.h          # String manipulation helpers
└── UrlUtils.cpp/.h             # URL encoding/decoding

lib/ -- Project Libraries

PlatformIO-managed libraries local to the project.

lib/hal/ -- Hardware Abstraction Layer

The HAL wraps the SDK drivers behind a stable API the rest of the firmware consumes.

File	Purpose
HalDisplay.cpp/.h	E-ink display control (refresh, buffer ops, grayscale, sleep)
HalGPIO.cpp/.h	Button input, battery reading, USB detection, deep sleep, wakeup
HalStorage.cpp/.h	SD card file operations (Storage singleton)

lib/Epub/ -- EPUB Library

The core document parsing and rendering engine.

Epub/
├── Epub.cpp/.h                     # Top-level EPUB interface
├── Epub/
│   ├── Page.cpp/.h                 # Single rendered page
│   ├── Section.cpp/.h              # Book section (chapter)
│   ├── ParsedText.cpp/.h           # Parsed text representation
│   ├── BookMetadataCache.cpp/.h    # Metadata caching to SD card
│   │
│   ├── blocks/
│   │   ├── Block.h                 # Base block type
│   │   ├── BlockStyle.h            # Block styling
│   │   └── TextBlock.cpp/.h       # Text block rendering
│   │
│   ├── css/
│   │   ├── CssParser.cpp/.h       # CSS subset parser
│   │   └── CssStyle.h             # Parsed CSS style representation
│   │
│   ├── hyphenation/
│   │   ├── Hyphenator.cpp/.h       # Main hyphenation API
│   │   ├── LiangHyphenation.cpp/.h # Liang algorithm implementation
│   │   ├── HyphenationCommon.cpp/.h # Shared types
│   │   ├── LanguageHyphenator.h    # Per-language interface
│   │   ├── LanguageRegistry.cpp/.h # Language detection and routing
│   │   ├── SerializedHyphenationTrie.h # Trie data format
│   │   └── generated/             # Pre-built hyphenation tries
│   │       ├── hyph-de.trie.h     # German
│   │       ├── hyph-en.trie.h     # English
│   │       ├── hyph-es.trie.h     # Spanish
│   │       ├── hyph-fr.trie.h     # French
│   │       └── hyph-ru.trie.h     # Russian
│   │
│   └── parsers/
│       ├── ChapterHtmlSlimParser.cpp/.h  # Chapter HTML content parser
│       ├── ContainerParser.cpp/.h        # META-INF/container.xml parser
│       ├── ContentOpfParser.cpp/.h       # content.opf (spine, manifest) parser
│       ├── TocNavParser.cpp/.h           # EPUB3 nav TOC parser
│       └── TocNcxParser.cpp/.h           # EPUB2 NCX TOC parser

lib/EpdFont/ -- Font Rendering

EpdFont/
├── EpdFont.cpp/.h              # Font rendering engine
├── EpdFontData.h               # Raw font data structure
├── EpdFontFamily.cpp/.h        # Font family (regular, bold, italic, bold-italic)
├── builtinFonts/
│   ├── all.h                   # Aggregate include for all built-in fonts
│   ├── bookerly_*.h            # Bookerly at sizes 12, 14, 16, 18
│   ├── notosans_*.h            # Noto Sans at sizes 8, 12, 14, 16, 18
│   ├── opendyslexic_*.h        # OpenDyslexic at sizes 8, 10, 12, 14
│   ├── ubuntu_*.h              # Ubuntu at sizes 10, 12 (UI font)
│   └── source/                 # Original TTF/OTF font files
└── scripts/
    ├── fontconvert.py          # TTF/OTF to compiled header converter
    ├── convert-builtin-fonts.sh # Batch conversion script
    ├── build-font-ids.sh       # Generate fontIds.h
    └── requirements.txt        # Python dependencies for font tools

Other Libraries

Library	Path	Purpose
expat/	lib/expat/	XML parser (used by EPUB parsers)
miniz/	lib/miniz/	Compression/decompression (ZIP support)
ZipFile/	lib/ZipFile/	ZIP file reading (EPUB is a ZIP)
picojpeg/	lib/picojpeg/	Lightweight JPEG decoder
JpegToBmpConverter/	lib/JpegToBmpConverter/	JPEG to bitmap conversion for display
GfxRenderer/	lib/GfxRenderer/	Graphics renderer, bitmap helpers
Txt/	lib/Txt/	Plain text (.txt) file reader
Xtc/	lib/Xtc/	XTC format parser and types
OpdsParser/	lib/OpdsParser/	OPDS feed XML parser and streaming
KOReaderSync/	lib/KOReaderSync/	KOReader sync client, credential store, progress mapping
Utf8/	lib/Utf8/	UTF-8 string utilities
Serialization/	lib/Serialization/	Binary serialization helper
FsHelpers/	lib/FsHelpers/	File system utility functions

open-x4-sdk/ -- Hardware SDK (Git Submodule)

Community SDK providing low-level hardware drivers. Referenced in .gitmodules from https://github.com/open-x4-epaper/community-sdk.git.

Supplies four libraries linked as symlinks in platformio.ini:

Library	SDK Path	Purpose
BatteryMonitor	libs/hardware/BatteryMonitor	Battery voltage ADC reading
InputManager	libs/hardware/InputManager	Physical button GPIO management
EInkDisplay	libs/display/EInkDisplay	E-ink display SPI driver
SDCardManager	libs/hardware/SDCardManager	SD card SPI initialization

scripts/ -- Build and Utility Scripts

Script	Language	Purpose
build_html.py	Python	Pre-build step. Minifies HTML files in src/ into PROGMEM C++ headers (.generated.h). Strips comments, collapses whitespace, preserves <pre>, <code>, <script>, <style> content.
generate_hyphenation_trie.py	Python	Generates serialized hyphenation trie headers from TeX hyphenation patterns.
debugging_monitor.py	Python	Enhanced serial monitor for debugging output.

test/ -- Tests

test/
├── README                              # PlatformIO test directory info
├── run_hyphenation_eval.sh             # Test runner script
└── hyphenation_eval/
    ├── HyphenationEvaluationTest.cpp   # Hyphenation accuracy evaluation
    └── resources/
        ├── english_hyphenation_tests.txt
        ├── french_hyphenation_tests.txt
        ├── german_hyphenation_tests.txt
        ├── russian_hyphenation_tests.txt
        ├── spanish_hyphenation_tests.txt
        └── generate_hyphenation_test_data.py

docs/ -- Upstream Documentation

File	Topic
comparison.md	Feature comparison with stock firmware
file-formats.md	Supported document formats
hyphenation-trie-format.md	Hyphenation trie binary format specification
troubleshooting.md	Common issues and fixes
webserver.md	Web server feature guide
webserver-endpoints.md	Web server HTTP API reference
images/	Screenshots and cover image

.github/ -- GitHub Configuration

.github/
├── workflows/
│   ├── ci.yml                      # Main CI: format check, cppcheck, build
│   ├── release.yml                 # Tag-triggered release build
│   ├── release_candidate.yml       # Manual RC build (release/* branches)
│   └── pr-formatting-check.yml     # Semantic PR title validation
├── PULL_REQUEST_TEMPLATE.md        # PR template (summary, context, AI usage)
├── ISSUE_TEMPLATE/
│   └── bug_report.yml              # Bug report form
└── FUNDING.yml                     # GitHub Sponsors configuration

bin/ -- Developer Tools

Script	Purpose
clang-format-fix	Runs clang-format on all tracked .c, .cpp, .h, .hpp files (excluding generated font headers). Pass -g to format only modified files.