mateusz-bak/openreads

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.