# uxjulia/crossink architecture

> Architecture diagram of the GitHub repository uxjulia/crossink, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/uxjulia/crossink
- Repository: https://github.com/uxjulia/crossink

## Overview

CrossInk is an e-ink ebook-reader firmware fork centered on browsing books and reading EPUB, text, and XTC files, with typography and lightweight reading-stat enhancements. The primary path is home/file browsing, opening a book through the activity manager, parsing and rendering it, and saving reader state. The README also documents dictionary lookup, saved items, themes, device-to-device sync, and network transfer. Activity routing is visible in the sampled manager; several feature links are based on documented capabilities and the repository tree, not sampled implementation details.

Main entry points: [`src/activities/reader/EpubReaderActivity.cpp`](https://github.com/uxjulia/crossink/blob/main/src/activities/reader/EpubReaderActivity.cpp) (Book reader screens), [`lib/hal/HalStorage.cpp`](https://github.com/uxjulia/crossink/blob/main/lib/hal/HalStorage.cpp) (SD storage), [`lib/GfxRenderer/GfxRenderer.cpp`](https://github.com/uxjulia/crossink/blob/main/lib/GfxRenderer/GfxRenderer.cpp) (Graphics renderer), [`src/activities/home/HomeActivity.cpp`](https://github.com/uxjulia/crossink/blob/main/src/activities/home/HomeActivity.cpp) (Home and browsing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Device UI"]
  node_reader["Reader<br/>[main.cpp]"]
  node_activity_manager["Activity manager"]
  node_home["Home and browsing<br/>[HomeActivity.cpp]"]
  node_input["Mapped input"]
end

subgraph group_reading["Reading"]
  node_reader_activity["Book reader screens"]
  node_epub["EPUB engine<br/>[Epub.cpp]"]
  node_text_reader["Text reader"]
  node_xtc_reader["XTC reader"]
  node_dictionary["Dictionary lookup"]
end

subgraph group_state["Reader state"]
  node_clippings["Clippings"]
  node_bookmarks["Bookmarks<br/>[BookmarkStore.cpp]"]
  node_stats["Reading statistics"]
  node_settings["Settings"]
  node_storage["SD storage<br/>[HalStorage.cpp]"]
end

subgraph group_connectivity["Connectivity"]
  node_opds["OPDS browsing"]
  node_sync_activity["Sync activities"]
  node_sync_client["KOReader sync"]
  node_web_transfer["Web and book transfer"]
end

subgraph group_rendering["Typography and display"]
  node_font_system["Font system<br/>[EpdFontFamily.cpp]"]
  node_renderer["Graphics renderer<br/>[GfxRenderer.cpp]"]
  node_display["E-ink display<br/>[HalDisplay.cpp]"]
end

node_user(("Reader"))
node_peer(("Other device"))
node_network(("Network service"))

node_user -->|"browse books"| node_home
node_home -->|"open book"| node_activity_manager
node_activity_manager -->|"launch reader"| node_reader_activity
node_reader_activity -->|"load EPUB"| node_epub
node_reader_activity -.->|"open text"| node_text_reader
node_reader_activity -.->|"open XTC"| node_xtc_reader
node_reader_activity -->|"read book"| node_storage
node_epub -->|"read archive"| node_storage
node_reader_activity -->|"render pages"| node_renderer
node_epub -->|"provide page content"| node_renderer
node_renderer -->|"resolve glyphs"| node_font_system
node_renderer -->|"draw frame"| node_display
node_user -->|"press controls"| node_input
node_input -->|"deliver actions"| node_reader_activity
node_reader_activity -.->|"save bookmarks"| node_bookmarks
node_reader_activity -.->|"save highlights"| node_clippings
node_reader_activity -.->|"record reading"| node_stats
node_bookmarks -.->|"persist"| node_storage
node_clippings -->|"write clipping"| node_storage
node_stats -.->|"persist stats"| node_storage
node_reader_activity -.->|"look up word"| node_dictionary
node_dictionary -.->|"read dictionary"| node_storage
node_user -->|"configure reader"| node_settings
node_settings -.->|"save settings"| node_storage
node_home -.->|"browse catalog"| node_opds
node_opds -.->|"request catalog"| node_network
node_user -.->|"start sync"| node_sync_activity
node_sync_activity -.->|"synchronize progress"| node_sync_client
node_sync_client -.->|"exchange progress"| node_peer
node_user -.->|"transfer books"| node_web_transfer
node_web_transfer -.->|"serve transfer"| node_network
node_web_transfer -.->|"access book files"| node_storage

click node_reader "https://github.com/uxjulia/crossink/blob/main/src/main.cpp"
click node_activity_manager "https://github.com/uxjulia/crossink/blob/main/src/activities/ActivityManager.cpp"
click node_home "https://github.com/uxjulia/crossink/blob/main/src/activities/home/HomeActivity.cpp"
click node_input "https://github.com/uxjulia/crossink/blob/main/src/MappedInputManager.cpp"
click node_reader_activity "https://github.com/uxjulia/crossink/blob/main/src/activities/reader/EpubReaderActivity.cpp"
click node_epub "https://github.com/uxjulia/crossink/blob/main/lib/Epub/Epub.cpp"
click node_text_reader "https://github.com/uxjulia/crossink/blob/main/src/activities/reader/TxtReaderActivity.cpp"
click node_xtc_reader "https://github.com/uxjulia/crossink/blob/main/src/activities/reader/XtcReaderActivity.cpp"
click node_dictionary "https://github.com/uxjulia/crossink/blob/main/src/util/DictionaryLookupController.cpp"
click node_clippings "https://github.com/uxjulia/crossink/blob/main/src/clippings/ClippingsManager.cpp"
click node_bookmarks "https://github.com/uxjulia/crossink/blob/main/src/BookmarkStore.cpp"
click node_stats "https://github.com/uxjulia/crossink/blob/main/src/activities/reader/BookReadingStats.cpp"
click node_settings "https://github.com/uxjulia/crossink/blob/main/src/CrossPointSettings.cpp"
click node_storage "https://github.com/uxjulia/crossink/blob/main/lib/hal/HalStorage.cpp"
click node_font_system "https://github.com/uxjulia/crossink/blob/main/lib/EpdFont/EpdFontFamily.cpp"
click node_renderer "https://github.com/uxjulia/crossink/blob/main/lib/GfxRenderer/GfxRenderer.cpp"
click node_display "https://github.com/uxjulia/crossink/blob/main/lib/hal/HalDisplay.cpp"
click node_opds "https://github.com/uxjulia/crossink/blob/main/src/activities/browser/OpdsBookBrowserActivity.cpp"
click node_sync_activity "https://github.com/uxjulia/crossink/blob/main/src/activities/reader/NearbyBookPositionSyncActivity.cpp"
click node_sync_client "https://github.com/uxjulia/crossink/blob/main/lib/KOReaderSync/KOReaderSyncClient.cpp"
click node_web_transfer "https://github.com/uxjulia/crossink/blob/main/src/activities/network/CrossPointWebServerActivity.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_reader,node_activity_manager,node_home,node_input toneBlue
class node_reader_activity,node_epub,node_text_reader,node_xtc_reader,node_dictionary toneAmber
class node_clippings,node_bookmarks,node_stats,node_settings,node_storage toneMint
class node_opds,node_sync_activity,node_sync_client,node_web_transfer toneRose
class node_font_system,node_renderer,node_display,node_user,node_peer,node_network toneIndigo
```

## Components

### Device UI

- [Reader](https://github.com/uxjulia/crossink/blob/main/src/main.cpp): `src/main.cpp`
- [Activity manager](https://github.com/uxjulia/crossink/blob/main/src/activities/ActivityManager.cpp): `src/activities/ActivityManager.cpp`
- [Home and browsing](https://github.com/uxjulia/crossink/blob/main/src/activities/home/HomeActivity.cpp): `src/activities/home/HomeActivity.cpp`
- [Mapped input](https://github.com/uxjulia/crossink/blob/main/src/MappedInputManager.cpp): `src/MappedInputManager.cpp`

### Reading

- [Book reader screens](https://github.com/uxjulia/crossink/blob/main/src/activities/reader/EpubReaderActivity.cpp): `src/activities/reader/EpubReaderActivity.cpp`
- [EPUB engine](https://github.com/uxjulia/crossink/blob/main/lib/Epub/Epub.cpp): `lib/Epub/Epub.cpp`
- [Text reader](https://github.com/uxjulia/crossink/blob/main/src/activities/reader/TxtReaderActivity.cpp): `src/activities/reader/TxtReaderActivity.cpp`
- [XTC reader](https://github.com/uxjulia/crossink/blob/main/src/activities/reader/XtcReaderActivity.cpp): `src/activities/reader/XtcReaderActivity.cpp`
- [Dictionary lookup](https://github.com/uxjulia/crossink/blob/main/src/util/DictionaryLookupController.cpp): `src/util/DictionaryLookupController.cpp`

### Reader state

- [Clippings](https://github.com/uxjulia/crossink/blob/main/src/clippings/ClippingsManager.cpp): `src/clippings/ClippingsManager.cpp`
- [Bookmarks](https://github.com/uxjulia/crossink/blob/main/src/BookmarkStore.cpp): `src/BookmarkStore.cpp`
- [Reading statistics](https://github.com/uxjulia/crossink/blob/main/src/activities/reader/BookReadingStats.cpp): `src/activities/reader/BookReadingStats.cpp`
- [Settings](https://github.com/uxjulia/crossink/blob/main/src/CrossPointSettings.cpp): `src/CrossPointSettings.cpp`
- [SD storage](https://github.com/uxjulia/crossink/blob/main/lib/hal/HalStorage.cpp): `lib/hal/HalStorage.cpp`

### Connectivity

- [OPDS browsing](https://github.com/uxjulia/crossink/blob/main/src/activities/browser/OpdsBookBrowserActivity.cpp): `src/activities/browser/OpdsBookBrowserActivity.cpp`
- [Sync activities](https://github.com/uxjulia/crossink/blob/main/src/activities/reader/NearbyBookPositionSyncActivity.cpp): `src/activities/reader/NearbyBookPositionSyncActivity.cpp`
- [KOReader sync](https://github.com/uxjulia/crossink/blob/main/lib/KOReaderSync/KOReaderSyncClient.cpp): `lib/KOReaderSync/KOReaderSyncClient.cpp`
- [Web and book transfer](https://github.com/uxjulia/crossink/blob/main/src/activities/network/CrossPointWebServerActivity.cpp): `src/activities/network/CrossPointWebServerActivity.cpp`

### Typography and display

- [Font system](https://github.com/uxjulia/crossink/blob/main/lib/EpdFont/EpdFontFamily.cpp): `lib/EpdFont/EpdFontFamily.cpp`
- [Graphics renderer](https://github.com/uxjulia/crossink/blob/main/lib/GfxRenderer/GfxRenderer.cpp): `lib/GfxRenderer/GfxRenderer.cpp`
- [E-ink display](https://github.com/uxjulia/crossink/blob/main/lib/hal/HalDisplay.cpp): `lib/hal/HalDisplay.cpp`

### Other components

- **Reader**
- **Other device**
- **Network service**

## Connections

- Reader → Home and browsing: browse books
- Home and browsing → Activity manager: open book
- Activity manager → Book reader screens: launch reader
- Book reader screens → EPUB engine: load EPUB
- Book reader screens → Text reader: open text
- Book reader screens → XTC reader: open XTC
- Book reader screens → SD storage: read book
- EPUB engine → SD storage: read archive
- Book reader screens → Graphics renderer: render pages
- EPUB engine → Graphics renderer: provide page content
- Graphics renderer → Font system: resolve glyphs
- Graphics renderer → E-ink display: draw frame
- Reader → Mapped input: press controls
- Mapped input → Book reader screens: deliver actions
- Book reader screens → Bookmarks: save bookmarks
- Book reader screens → Clippings: save highlights
- Book reader screens → Reading statistics: record reading
- Bookmarks → SD storage: persist
- Clippings → SD storage: write clipping
- Reading statistics → SD storage: persist stats
- Book reader screens → Dictionary lookup: look up word
- Dictionary lookup → SD storage: read dictionary
- Reader → Settings: configure reader
- Settings → SD storage: save settings
- Home and browsing → OPDS browsing: browse catalog
- OPDS browsing → Network service: request catalog
- Reader → Sync activities: start sync
- Sync activities → KOReader sync: synchronize progress
- KOReader sync → Other device: exchange progress
- Reader → Web and book transfer: transfer books
- Web and book transfer → Network service: serve transfer
- Web and book transfer → SD storage: access book files