# geometer/fbreaderj architecture

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

- Interactive diagram: https://gitdiagram.com/geometer/fbreaderj
- Repository: https://github.com/geometer/fbreaderj

## Overview

#### Purpose and runtime
This is a legacy Android FBReader e-book reader application. It combines Java Android UI/application code, a reusable ZLibrary reading stack, SQLite-backed local state, and JNI/C++ parsers for native book formats. The Android manifest and Ant project files are the packaging/build roots: `AndroidManifest.xml`, `build.xml`, `jni/Android.mk`.

#### Application entry and orchestration
Android launches the reader application/activity layer, centered on `FBReaderApplication.java` and `FBReaderMainActivity.java`; `FBReader.java` bridges Android lifecycle/UI events into the core reader. Reader commands are action objects, separating menus, gestures, selection, search, navigation, and external intents from the engine.
- `fbreader/app/src/main/java/org/geometerplus/android/fbreader/FBReaderApplication.java`
- `fbreader/app/src/main/java/org/geometerplus/android/fbreader/FBReaderMainActivity.java`
- `fbreader/app/src/main/java/org/geometerplus/android/fbreader/FBReader.java`

#### Core reading model and rendering pipeline
`FBReaderApp` owns reading state and actions; opening a book builds a `BookModel` with text, metadata, and TOC. `FBView` drives reader-level view behavior, while ZLibrary text models, cursor/layout, and Android paint/widget implementations paginate and render content. Input maps/tap zones and styles are asset-driven.
- `fbreader/app/src/main/java/org/geometerplus/fbreader/fbreader/FBReaderApp.java`
- `fbreader/app/src/main/java/org/geometerplus/fbreader/bookmodel/BookModel.java`
- `fbreader/app/src/main/java/org/geometerplus/zlibrary/text/view/ZLTextView.java`
- `fbreader/app/src/main/java/org/geometerplus/zlibrary/ui/android/view/MainView.java`
- `assets/default/tapzones/left_to_right.xml`

#### Format ingestion and native boundary
Format selection is abstracted by `PluginCollection`/`FormatPlugin`; Java supports built-in, native, and external plugins. JNI native code implements parsing and model construction for FB2, EPUB/OEB, HTML, DOC, RTF, PDB/Mobipocket, TXT, and related archive/XML handling. This Java↔C++ boundary is architecturally critical for book loading and metadata/cover extraction.
- `fbreader/app/src/main/java/org/geometerplus/fbreader/formats/PluginCollection.java`
- `fbreader/app/src/main/java/org/geometerplus/fbreader/formats/NativeFormatPlugin.java`
- `jni/NativeFormats/JavaNativeFormatPlugin.cpp`
- `jni/NativeFormats/fbreader/src/formats/oeb/OEBPlugin.cpp`

#### Local library, configuration, and persistence
Core book entities and collection interfaces are platform-neutral. Android services expose library and config operations through AIDL and persist to SQLite; activities/adapters present library trees, searching, book information, covers, bookmarks, and reading positions. These service boundaries allow UI clients to access durable state without owning database implementation.
- `fbreader/app/src/main/java/org/geometerplus/fbreader/book/BookCollection.java`
- `fbreader/app/src/main/java/org/geometerplus/android/fbreader/libraryService/LibraryService.java`
- `fbreader/app/src/main/java/org/geometerplus/android/fbreader/libraryService/SQLiteBooksDatabase.java`
- `fbreader/app/src/main/java/org/geometerplus/android/fbreader/config/SQLiteConfig.java`

#### Network catalogs, downloads, and synchronization
The network domain represents catalogs and books independently of Android. It supports OPDS/Atom/RSS discovery, custom catalogs, search, authenticated LitRes commerce, and downloads. Android activities/services provide authentication context, downloader execution, local network cache, and bookmark synchronization. External dependencies are remote OPDS/RSS/catalog endpoints, LitRes services, and Android browser/share integrations.
- `fbreader/app/src/main/java/org/geometerplus/fbreader/network/NetworkLibrary.java`
- `fbreader/app/src/main/java/org/geometerplus/fbreader/network/opds/OPDSNetworkLink.java`
- `fbreader/app/src/main/java/org/geometerplus/android/fbreader/network/BookDownloaderService.java`
- `fbreader/app/src/main/java/org/geometerplus/android/fbreader/sync/SyncService.java`

#### Platform services, assets, and integrations
ZLibrary supplies filesystem, resources, networking, options, images, XML, encodings, and text hyphenation abstractions; Android implementations adapt these to device APIs. Bundled assets provide translations, hyphenation/language recognition, format entities, styles, dictionaries, and plugin defaults. The app also exposes AIDL APIs and an embedded HTTP data service; dictionary lookup delegates to installed external dictionary apps/APIs.
- `fbreader/app/src/main/java/org/geometerplus/zlibrary/core/application/ZLApplication.java`
- `fbreader/app/src/main/java/org/geometerplus/android/fbreader/api/ApiService.java`
- `fbreader/app/src/main/java/org/geometerplus/android/fbreader/httpd/DataService.java`
- `assets/hyphenationPatterns/en.pattern`

Main entry points: [`fbreader/app/src/main/java/org/geometerplus/fbreader/fbreader/FBReaderApp.java`](https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/fbreader/fbreader/FBReaderApp.java) (Reading state), [`fbreader/app/src/main/java/org/geometerplus/fbreader/book/BookCollection.java`](https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/fbreader/book/BookCollection.java) (Book collection API), [`fbreader/app/src/main/java/org/geometerplus/android/fbreader/libraryService/LibraryService.java`](https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/android/fbreader/libraryService/LibraryService.java) (Library service), [`fbreader/app/src/main/java/org/geometerplus/android/fbreader/FBReaderMainActivity.java`](https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/android/fbreader/FBReaderMainActivity.java) (Application & activity UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_android["Android app"]
  node_android_ui["Application &amp; activity UI<br/>Android UI"]
  node_application["Reader application<br/>Android application"]
  node_fbreader_bridge["Lifecycle bridge<br/>Android reader controller<br/>[FBReader.java]"]
  node_commands["Reader actions<br/>command objects"]
end

subgraph group_reader["Reading engine"]
  node_reader_app["Reading state<br/>FBReaderApp<br/>[FBReaderApp.java]"]
  node_book_model["Book model<br/>reading model<br/>[BookModel.java]"]
  node_text_view["Text layout &amp; pagination<br/>ZLibrary text view<br/>[ZLTextView.java]"]
  node_android_view["Android reader rendering<br/>Android view<br/>[MainView.java]"]
end

subgraph group_formats["Format ingestion"]
  node_plugin_collection["Format plugin selection<br/>plugin registry"]
  node_native_plugin["Native format adapter<br/>JNI plugin"]
  node_native_parsers{{"C++ format parsers<br/>JNI/C++ parsers"}}
end

subgraph group_storage["Library &amp; state"]
  node_book_collection["Book collection API<br/>platform-neutral collection"]
  node_library_service["Library service<br/>AIDL service"]
  node_books_db[("Books SQLite database<br/>SQLite persistence")]
  node_config_db[("Configuration SQLite<br/>SQLite configuration<br/>[SQLiteConfig.java]")]
end

subgraph group_network["Network services"]
  node_network_library["Catalog domain<br/>network library"]
  node_opds["OPDS catalog links<br/>OPDS/RSS client"]
  node_downloader["Book downloader<br/>Android service"]
  node_sync["Bookmark synchronization<br/>Android sync service<br/>[SyncService.java]"]
end

subgraph group_platform["Platform &amp; build"]
  node_build["Android packaging build<br/>Ant / NDK build<br/>[build.xml]"]
  node_reading_assets["Tap zones &amp; language assets<br/>bundled assets<br/>[left_to_right.xml]"]
  node_api_service["External API service<br/>AIDL API<br/>[ApiService.java]"]
  node_data_service["Embedded data service<br/>HTTP service<br/>[DataService.java]"]
end

node_remote_catalogs(("Remote catalog services<br/>external endpoints"))

node_build -->|"packages"| node_android_ui
node_build -->|"builds via NDK"| node_native_parsers
node_application -->|"initializes"| node_android_ui
node_android_ui -->|"lifecycle events"| node_fbreader_bridge
node_fbreader_bridge -->|"controls"| node_reader_app
node_commands -->|"invoke"| node_reader_app
node_reader_app -->|"opens"| node_book_model
node_reader_app -->|"drives"| node_text_view
node_text_view -->|"renders through"| node_android_view
node_reading_assets -->|"styles and hyphenates"| node_text_view
node_reading_assets -->|"maps taps"| node_commands
node_reader_app -->|"loads books through"| node_plugin_collection
node_plugin_collection -->|"selects"| node_native_plugin
node_native_plugin -->|"JNI calls"| node_native_parsers
node_native_parsers -->|"constructs"| node_book_model
node_reader_app -->|"uses library"| node_book_collection
node_book_collection -->|"implemented by"| node_library_service
node_library_service -->|"persists"| node_books_db
node_application -->|"stores options"| node_config_db
node_network_library -->|"discovers via"| node_opds
node_opds -->|"requests"| node_remote_catalogs
node_network_library -->|"queues downloads"| node_downloader
node_downloader -->|"adds local books"| node_book_collection
node_sync -->|"syncs bookmarks"| node_library_service
node_api_service -->|"exposes library"| node_library_service
node_data_service -->|"serves book data"| node_book_collection

click node_build "https://github.com/geometer/fbreaderj/blob/master/build.xml"
click node_android_ui "https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/android/fbreader/FBReaderMainActivity.java"
click node_application "https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/android/fbreader/FBReaderApplication.java"
click node_fbreader_bridge "https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/android/fbreader/FBReader.java"
click node_reader_app "https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/fbreader/fbreader/FBReaderApp.java"
click node_book_model "https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/fbreader/bookmodel/BookModel.java"
click node_text_view "https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/zlibrary/text/view/ZLTextView.java"
click node_android_view "https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/zlibrary/ui/android/view/MainView.java"
click node_reading_assets "https://github.com/geometer/fbreaderj/blob/master/assets/default/tapzones/left_to_right.xml"
click node_plugin_collection "https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/fbreader/formats/PluginCollection.java"
click node_native_plugin "https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/fbreader/formats/NativeFormatPlugin.java"
click node_native_parsers "https://github.com/geometer/fbreaderj/blob/master/jni/NativeFormats/JavaNativeFormatPlugin.cpp"
click node_book_collection "https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/fbreader/book/BookCollection.java"
click node_library_service "https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/android/fbreader/libraryService/LibraryService.java"
click node_books_db "https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/android/fbreader/libraryService/SQLiteBooksDatabase.java"
click node_config_db "https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/android/fbreader/config/SQLiteConfig.java"
click node_network_library "https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/fbreader/network/NetworkLibrary.java"
click node_opds "https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/fbreader/network/opds/OPDSNetworkLink.java"
click node_downloader "https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/android/fbreader/network/BookDownloaderService.java"
click node_sync "https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/android/fbreader/sync/SyncService.java"
click node_api_service "https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/android/fbreader/api/ApiService.java"
click node_data_service "https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/android/fbreader/httpd/DataService.java"

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_android_ui,node_application,node_fbreader_bridge,node_commands toneBlue
class node_reader_app,node_book_model,node_text_view,node_android_view toneAmber
class node_plugin_collection,node_native_plugin,node_native_parsers toneMint
class node_book_collection,node_library_service,node_books_db,node_config_db toneRose
class node_network_library,node_opds,node_downloader,node_sync toneIndigo
class node_build,node_reading_assets,node_api_service,node_data_service toneTeal
class node_remote_catalogs toneNeutral
```

## Components

### Android app

- [Application & activity UI](https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/android/fbreader/FBReaderMainActivity.java): Android UI · `fbreader/app/src/main/java/org/geometerplus/android/fbreader/FBReaderMainActivity.java`
- [Reader application](https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/android/fbreader/FBReaderApplication.java): Android application · `fbreader/app/src/main/java/org/geometerplus/android/fbreader/FBReaderApplication.java`
- [Lifecycle bridge](https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/android/fbreader/FBReader.java): Android reader controller · Bridges Android lifecycle and UI events into the reader engine. · `fbreader/app/src/main/java/org/geometerplus/android/fbreader/FBReader.java`
- **Reader actions**: command objects · Menus, gestures, selection, search, navigation, and intents.

### Reading engine

- [Reading state](https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/fbreader/fbreader/FBReaderApp.java): FBReaderApp · Owns active reading state and actions. · `fbreader/app/src/main/java/org/geometerplus/fbreader/fbreader/FBReaderApp.java`
- [Book model](https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/fbreader/bookmodel/BookModel.java): reading model · Contains book text, metadata, and table of contents. · `fbreader/app/src/main/java/org/geometerplus/fbreader/bookmodel/BookModel.java`
- [Text layout & pagination](https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/zlibrary/text/view/ZLTextView.java): ZLibrary text view · `fbreader/app/src/main/java/org/geometerplus/zlibrary/text/view/ZLTextView.java`
- [Android reader rendering](https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/zlibrary/ui/android/view/MainView.java): Android view · `fbreader/app/src/main/java/org/geometerplus/zlibrary/ui/android/view/MainView.java`

### Format ingestion

- [Format plugin selection](https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/fbreader/formats/PluginCollection.java): plugin registry · Selects built-in, native, and external format handlers. · `fbreader/app/src/main/java/org/geometerplus/fbreader/formats/PluginCollection.java`
- [Native format adapter](https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/fbreader/formats/NativeFormatPlugin.java): JNI plugin · `fbreader/app/src/main/java/org/geometerplus/fbreader/formats/NativeFormatPlugin.java`
- [C++ format parsers](https://github.com/geometer/fbreaderj/blob/master/jni/NativeFormats/JavaNativeFormatPlugin.cpp): JNI/C++ parsers · Parses native formats and constructs models, metadata, and covers. · `jni/NativeFormats/JavaNativeFormatPlugin.cpp`

### Library & state

- [Book collection API](https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/fbreader/book/BookCollection.java): platform-neutral collection · `fbreader/app/src/main/java/org/geometerplus/fbreader/book/BookCollection.java`
- [Library service](https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/android/fbreader/libraryService/LibraryService.java): AIDL service · Exposes durable library operations to UI clients. · `fbreader/app/src/main/java/org/geometerplus/android/fbreader/libraryService/LibraryService.java`
- [Books SQLite database](https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/android/fbreader/libraryService/SQLiteBooksDatabase.java): SQLite persistence · `fbreader/app/src/main/java/org/geometerplus/android/fbreader/libraryService/SQLiteBooksDatabase.java`
- [Configuration SQLite](https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/android/fbreader/config/SQLiteConfig.java): SQLite configuration · `fbreader/app/src/main/java/org/geometerplus/android/fbreader/config/SQLiteConfig.java`

### Network services

- [Catalog domain](https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/fbreader/network/NetworkLibrary.java): network library · Represents catalogs and network books independently of Android. · `fbreader/app/src/main/java/org/geometerplus/fbreader/network/NetworkLibrary.java`
- [OPDS catalog links](https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/fbreader/network/opds/OPDSNetworkLink.java): OPDS/RSS client · `fbreader/app/src/main/java/org/geometerplus/fbreader/network/opds/OPDSNetworkLink.java`
- [Book downloader](https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/android/fbreader/network/BookDownloaderService.java): Android service · `fbreader/app/src/main/java/org/geometerplus/android/fbreader/network/BookDownloaderService.java`
- [Bookmark synchronization](https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/android/fbreader/sync/SyncService.java): Android sync service · `fbreader/app/src/main/java/org/geometerplus/android/fbreader/sync/SyncService.java`

### Platform & build

- [Android packaging build](https://github.com/geometer/fbreaderj/blob/master/build.xml): Ant / NDK build · Manifest, Ant, and NDK roots package Java and native code. · `build.xml`
- [Tap zones & language assets](https://github.com/geometer/fbreaderj/blob/master/assets/default/tapzones/left_to_right.xml): bundled assets · Controls gestures, styles, and hyphenation. · `assets/default/tapzones/left_to_right.xml`
- [External API service](https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/android/fbreader/api/ApiService.java): AIDL API · `fbreader/app/src/main/java/org/geometerplus/android/fbreader/api/ApiService.java`
- [Embedded data service](https://github.com/geometer/fbreaderj/blob/master/fbreader/app/src/main/java/org/geometerplus/android/fbreader/httpd/DataService.java): HTTP service · `fbreader/app/src/main/java/org/geometerplus/android/fbreader/httpd/DataService.java`

### Other components

- **Remote catalog services**: external endpoints · OPDS, RSS, custom catalogs, and LitRes services.

## Connections

- Android packaging build → Application & activity UI: packages
- Android packaging build → C++ format parsers: builds via NDK
- Reader application → Application & activity UI: initializes
- Application & activity UI → Lifecycle bridge: lifecycle events
- Lifecycle bridge → Reading state: controls
- Reader actions → Reading state: invoke
- Reading state → Book model: opens
- Reading state → Text layout & pagination: drives
- Text layout & pagination → Android reader rendering: renders through
- Tap zones & language assets → Text layout & pagination: styles and hyphenates
- Tap zones & language assets → Reader actions: maps taps
- Reading state → Format plugin selection: loads books through
- Format plugin selection → Native format adapter: selects
- Native format adapter → C++ format parsers: JNI calls
- C++ format parsers → Book model: constructs
- Reading state → Book collection API: uses library
- Book collection API → Library service: implemented by
- Library service → Books SQLite database: persists
- Reader application → Configuration SQLite: stores options
- Catalog domain → OPDS catalog links: discovers via
- OPDS catalog links → Remote catalog services: requests
- Catalog domain → Book downloader: queues downloads
- Book downloader → Book collection API: adds local books
- Bookmark synchronization → Library service: syncs bookmarks
- External API service → Library service: exposes library
- Embedded data service → Book collection API: serves book data