# 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. |