# mateusz-bak/openreads architecture

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

- Interactive diagram: https://gitdiagram.com/mateusz-bak/openreads
- Repository: https://github.com/mateusz-bak/openreads

## Overview

#### Purpose and Platforms
Openreads is a privacy-oriented Flutter mobile app for tracking personal books across finished, in-progress, later, and unfinished lists. It targets Android and iOS through Flutter hosts in `android/app/src/main/kotlin/com/example/openreads/MainActivity.kt` and `ios/Runner/AppDelegate.swift`.

#### Application Bootstrap
Flutter starts at `lib/main.dart`, which composes application-wide initialization, theming, localization, and the initial UI flow. Shared constants, locale definitions, and theme construction form cross-cutting boundaries in `lib/core/constants/constants.dart`, `lib/core/constants/locale.dart`, and `lib/core/themes/app_theme.dart`.

#### Domain and Persistence
Book tracking is centered on domain models for books, readings, annual challenges, and statistics: `lib/model/book.dart`, `lib/model/reading.dart`, and `lib/model/yearly_challenge.dart`. Local persistence is isolated behind the database layer—`lib/database/database_provider.dart` and `lib/database/database_controler.dart`—so UI and state logic should not directly own storage details. The app’s privacy model implies this local store is the system of record.

#### State and Application Logic
The app uses Bloc/Cubit state management as the control boundary between widgets and data operations. Book editing, selection, current-book state, and list preferences use Cubits in `lib/logic/cubit/book_cubit.dart`, `lib/logic/cubit/edit_book_cubit.dart`, and `lib/logic/cubit/selected_books_cubit.dart`. Event-driven flows cover Open Library access, statistics, challenges, migration, themes, and sorting, notably `lib/logic/bloc/open_library_search_bloc/open_library_search_bloc.dart`, `lib/logic/bloc/stats_bloc/stats_bloc.dart`, and `lib/logic/bloc/migration_v1_to_v2_bloc/migration_v1_to_v2_bloc.dart`.

#### User-Facing Flows
The home and book-list screens provide primary navigation, status lists, filtering, sorting, and multi-selection: `lib/ui/home_screen/home_screen.dart`, `lib/ui/books_screen/books_screen.dart`, and `lib/ui/search_page/search_page.dart`. Add/edit and detail flows operate on book state through `lib/ui/add_book_screen/add_book_screen.dart` and `lib/ui/book_screen/book_screen.dart`. Statistics and reading challenges are rendered separately in `lib/ui/statistics_screen/statistics_screen.dart`.

#### External Data and Import/Export
Open Library is the sole declared remote catalog provider. Network and availability boundaries live in `lib/resources/open_library_service.dart` and `lib/resources/connectivity_service.dart`; Open Library result models are in `lib/model/ol_search_result.dart`. Catalog search and edition selection are surfaced by `lib/ui/search_ol_screen/search_ol_screen.dart` and `lib/ui/search_ol_editions_screen/search_ol_editions_screen.dart`. Backup and migration logic supports app backup plus Openreads, Goodreads, and BookWyrm CSV interchange in `lib/core/helpers/backup/backup.dart`, `lib/core/helpers/backup/csv_import_goodreads.dart`, and `lib/core/helpers/backup/csv_export.dart`.

#### Localization and Delivery
Localization assets are bundled JSON translations under `assets/translations/en-US.json` and generated keys in `lib/generated/locale_keys.g.dart`; translation contributions are coordinated externally through Weblate. Android distribution is supported by Gradle and Google Play release automation in `android/app/build.gradle` and `.github/workflows/google_play_release.yml`; iOS is built through the Runner Xcode project at `ios/Runner.xcodeproj/project.pbxproj`.

Main entry points: [`lib/main.dart`](https://github.com/mateusz-bak/openreads/blob/master/lib/main.dart) (App bootstrap), [`lib/logic/cubit/book_cubit.dart`](https://github.com/mateusz-bak/openreads/blob/master/lib/logic/cubit/book_cubit.dart) (Book and selection Cubits), [`lib/logic/bloc/open_library_search_bloc/open_library_search_bloc.dart`](https://github.com/mateusz-bak/openreads/blob/master/lib/logic/bloc/open_library_search_bloc/open_library_search_bloc.dart) (Workflow Blocs), [`lib/database/database_provider.dart`](https://github.com/mateusz-bak/openreads/blob/master/lib/database/database_provider.dart) (Local database layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Flutter clients"]
  node_home_navigation["Home and book lists<br/>primary UI<br/>[home_screen.dart]"]
  node_book_flows["Book detail and editing<br/>book UI"]
  node_catalog_ui["Catalog search and editions<br/>catalog UI"]
  node_insights_ui["Statistics and challenges<br/>insights UI"]
end

subgraph group_application["Application"]
  node_flutter_app{{"App bootstrap<br/>Flutter entrypoint<br/>[main.dart]"}}
  node_app_foundation["Theme and locale foundation<br/>cross-cutting UI<br/>[app_theme.dart]"]
  node_book_state["Book and selection Cubits<br/>Cubit state<br/>[book_cubit.dart]"]
  node_workflow_blocs["Workflow Blocs<br/>Bloc state"]
  node_domain_models["Reading domain<br/>domain models<br/>[book.dart]"]
  node_translations["Translations<br/>localization assets<br/>[en-US.json]"]
end

subgraph group_data["Data and integrations"]
  node_database_layer[("Local database layer<br/>persistence boundary")]
  node_local_store[("Private local store<br/>system of record")]
  node_open_library_service["Open Library service<br/>remote catalog client"]
  node_open_library_models["Open Library results<br/>catalog models"]
  node_backup_interchange["Backup and CSV interchange<br/>import/export<br/>[backup.dart]"]
end

subgraph group_delivery["Platforms and delivery"]
  node_android_host["Android host<br/>Android runtime<br/>[MainActivity.kt]"]
  node_ios_host["iOS host<br/>iOS runtime<br/>[AppDelegate.swift]"]
  node_play_release["Google Play release<br/>release automation"]
end

node_android_host -->|"hosts"| node_flutter_app
node_ios_host -->|"hosts"| node_flutter_app
node_flutter_app -->|"initializes"| node_app_foundation
node_flutter_app -->|"starts"| node_home_navigation
node_app_foundation -->|"loads locale assets"| node_translations
node_home_navigation -->|"opens"| node_book_flows
node_home_navigation -->|"reads and updates"| node_book_state
node_book_flows -->|"edits through"| node_book_state
node_catalog_ui -->|"searches through"| node_workflow_blocs
node_insights_ui -->|"requests insights"| node_workflow_blocs
node_book_state -->|"manages"| node_domain_models
node_book_state -->|"persists through"| node_database_layer
node_workflow_blocs -->|"reads and writes through"| node_database_layer
node_workflow_blocs -->|"queries"| node_open_library_service
node_open_library_service -->|"returns"| node_open_library_models
node_database_layer -->|"stores locally"| node_local_store
node_backup_interchange -->|"imports and exports"| node_database_layer
node_play_release -->|"publishes"| node_android_host

click node_flutter_app "https://github.com/mateusz-bak/openreads/blob/master/lib/main.dart"
click node_app_foundation "https://github.com/mateusz-bak/openreads/blob/master/lib/core/themes/app_theme.dart"
click node_home_navigation "https://github.com/mateusz-bak/openreads/blob/master/lib/ui/home_screen/home_screen.dart"
click node_book_flows "https://github.com/mateusz-bak/openreads/blob/master/lib/ui/add_book_screen/add_book_screen.dart"
click node_catalog_ui "https://github.com/mateusz-bak/openreads/blob/master/lib/ui/search_ol_screen/search_ol_screen.dart"
click node_insights_ui "https://github.com/mateusz-bak/openreads/blob/master/lib/ui/statistics_screen/statistics_screen.dart"
click node_book_state "https://github.com/mateusz-bak/openreads/blob/master/lib/logic/cubit/book_cubit.dart"
click node_workflow_blocs "https://github.com/mateusz-bak/openreads/blob/master/lib/logic/bloc/open_library_search_bloc/open_library_search_bloc.dart"
click node_domain_models "https://github.com/mateusz-bak/openreads/blob/master/lib/model/book.dart"
click node_database_layer "https://github.com/mateusz-bak/openreads/blob/master/lib/database/database_provider.dart"
click node_open_library_service "https://github.com/mateusz-bak/openreads/blob/master/lib/resources/open_library_service.dart"
click node_open_library_models "https://github.com/mateusz-bak/openreads/blob/master/lib/model/ol_search_result.dart"
click node_backup_interchange "https://github.com/mateusz-bak/openreads/blob/master/lib/core/helpers/backup/backup.dart"
click node_translations "https://github.com/mateusz-bak/openreads/blob/master/assets/translations/en-US.json"
click node_android_host "https://github.com/mateusz-bak/openreads/blob/master/android/app/src/main/kotlin/com/example/openreads/MainActivity.kt"
click node_ios_host "https://github.com/mateusz-bak/openreads/blob/master/ios/Runner/AppDelegate.swift"
click node_play_release "https://github.com/mateusz-bak/openreads/blob/master/.github/workflows/google_play_release.yml"

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_home_navigation,node_book_flows,node_catalog_ui,node_insights_ui toneBlue
class node_flutter_app,node_app_foundation,node_book_state,node_workflow_blocs,node_domain_models,node_translations toneAmber
class node_database_layer,node_local_store,node_open_library_service,node_open_library_models,node_backup_interchange toneMint
class node_android_host,node_ios_host,node_play_release toneRose
```

## Components

### Flutter clients

- [Home and book lists](https://github.com/mateusz-bak/openreads/blob/master/lib/ui/home_screen/home_screen.dart): primary UI · Navigation, status lists, filtering, sorting, and selection. · `lib/ui/home_screen/home_screen.dart`
- [Book detail and editing](https://github.com/mateusz-bak/openreads/blob/master/lib/ui/add_book_screen/add_book_screen.dart): book UI · Add, edit, and inspect tracked books. · `lib/ui/add_book_screen/add_book_screen.dart`
- [Catalog search and editions](https://github.com/mateusz-bak/openreads/blob/master/lib/ui/search_ol_screen/search_ol_screen.dart): catalog UI · Searches Open Library and selects editions. · `lib/ui/search_ol_screen/search_ol_screen.dart`
- [Statistics and challenges](https://github.com/mateusz-bak/openreads/blob/master/lib/ui/statistics_screen/statistics_screen.dart): insights UI · `lib/ui/statistics_screen/statistics_screen.dart`

### Application

- [App bootstrap](https://github.com/mateusz-bak/openreads/blob/master/lib/main.dart): Flutter entrypoint · Initializes the app and initial UI flow. · `lib/main.dart`
- [Theme and locale foundation](https://github.com/mateusz-bak/openreads/blob/master/lib/core/themes/app_theme.dart): cross-cutting UI · Shared constants, locale definitions, and theme construction. · `lib/core/themes/app_theme.dart`
- [Book and selection Cubits](https://github.com/mateusz-bak/openreads/blob/master/lib/logic/cubit/book_cubit.dart): Cubit state · Controls book edits, selection, and current-book state. · `lib/logic/cubit/book_cubit.dart`
- [Workflow Blocs](https://github.com/mateusz-bak/openreads/blob/master/lib/logic/bloc/open_library_search_bloc/open_library_search_bloc.dart): Bloc state · Coordinates catalog search, statistics, challenges, migration, themes, and sorting. · `lib/logic/bloc/open_library_search_bloc/open_library_search_bloc.dart`
- [Reading domain](https://github.com/mateusz-bak/openreads/blob/master/lib/model/book.dart): domain models · Books, readings, yearly challenges, and statistics. · `lib/model/book.dart`
- [Translations](https://github.com/mateusz-bak/openreads/blob/master/assets/translations/en-US.json): localization assets · Bundled JSON translations and generated locale keys. · `assets/translations/en-US.json`

### Data and integrations

- [Local database layer](https://github.com/mateusz-bak/openreads/blob/master/lib/database/database_provider.dart): persistence boundary · Isolates local storage access from UI and state logic. · `lib/database/database_provider.dart`
- **Private local store**: system of record · On-device source of truth for personal tracking data.
- [Open Library service](https://github.com/mateusz-bak/openreads/blob/master/lib/resources/open_library_service.dart): remote catalog client · Network boundary for the sole remote catalog provider. · `lib/resources/open_library_service.dart`
- [Open Library results](https://github.com/mateusz-bak/openreads/blob/master/lib/model/ol_search_result.dart): catalog models · `lib/model/ol_search_result.dart`
- [Backup and CSV interchange](https://github.com/mateusz-bak/openreads/blob/master/lib/core/helpers/backup/backup.dart): import/export · Supports backups plus Openreads, Goodreads, and BookWyrm CSV data. · `lib/core/helpers/backup/backup.dart`

### Platforms and delivery

- [Android host](https://github.com/mateusz-bak/openreads/blob/master/android/app/src/main/kotlin/com/example/openreads/MainActivity.kt): Android runtime · `android/app/src/main/kotlin/com/example/openreads/MainActivity.kt`
- [iOS host](https://github.com/mateusz-bak/openreads/blob/master/ios/Runner/AppDelegate.swift): iOS runtime · `ios/Runner/AppDelegate.swift`
- [Google Play release](https://github.com/mateusz-bak/openreads/blob/master/.github/workflows/google_play_release.yml): release automation · `.github/workflows/google_play_release.yml`

## Connections

- Android host → App bootstrap: hosts
- iOS host → App bootstrap: hosts
- App bootstrap → Theme and locale foundation: initializes
- App bootstrap → Home and book lists: starts
- Theme and locale foundation → Translations: loads locale assets
- Home and book lists → Book detail and editing: opens
- Home and book lists → Book and selection Cubits: reads and updates
- Book detail and editing → Book and selection Cubits: edits through
- Catalog search and editions → Workflow Blocs: searches through
- Statistics and challenges → Workflow Blocs: requests insights
- Book and selection Cubits → Reading domain: manages
- Book and selection Cubits → Local database layer: persists through
- Workflow Blocs → Local database layer: reads and writes through
- Workflow Blocs → Open Library service: queries
- Open Library service → Open Library results: returns
- Local database layer → Private local store: stores locally
- Backup and CSV interchange → Local database layer: imports and exports
- Google Play release → Android host: publishes