GetBible App — help build the native reader

The GetBible App is the cross-platform Flutter project for Android, iOS, web, Windows, macOS, and Linux. It brings the GetBible reader experience into native controls with local Scripture caching and study data.

Repository · Support · All projects

Under development. The app currently uses Bible API v2. Store publication, complete feature parity, and physical-device verification are still ahead. Bible API v3, dictionaries, commentaries, and broader study integration are future priorities, not released features. Developers and testers can help move the project toward those goals.

Supported targets#

Target	Development/test command	Distribution output
Android	`flutter run -d android`	APK or Play Store AAB
iOS/iPadOS	`flutter run -d ios`	Xcode archive/App Store package
Web	`flutter run -d chrome`	Static files in `build/web`
Windows	`flutter run -d windows`	Windows runner bundle
macOS	`flutter run -d macos`	macOS application bundle
Linux	`flutter run -d linux`	Linux runner bundle

Requirements#

Flutter stable 3.44.6 or newer
Dart 3.12.2 or newer
Android Studio/SDK for Android builds
macOS with Xcode for iOS builds

Start developing#

git clone https://github.com/getbible/app.git
cd app
flutter doctor -v
flutter pub get
flutter run

The application ID and iOS bundle ID are life.getbible.mobile. No API key is required for the public GetBible API.

Test the application#

The fastest interactive test is the web target:

flutter pub get
flutter run -d chrome

For Android, enable developer mode/USB debugging or start an emulator, then run flutter devices followed by flutter run. GitHub Actions also publishes two downloadable artifacts after a successful main build:

getBible-live-debug-apk for installation on an Android test device.
getBible-live-web, containing the compiled static web application.

Open the successful workflow run’s Artifacts section to download them. Web files must be served by an HTTP server; opening index.html directly is not supported. A permanent GitHub Pages preview can be enabled later after the repository is public and Pages is configured to deploy from GitHub Actions.

pub.dev is not an application testing service. It is Dart and Flutter’s public package registry. This application is not intended to be published there as a reusable package. Test builds belong in GitHub Actions artifacts, GitHub Pages, TestFlight, Play Console internal testing, or locally attached Flutter devices.

Quality checks#

dart format --output=none --set-exit-if-changed .
flutter analyze
flutter test
flutter build apk --debug

CI runs the same checks and uploads an unsigned debug APK plus a compiled web build. Consult testing before merging reader, storage, backup, or cache changes.

Release builds#

Android:

flutter build apk --release
flutter build appbundle --release

iOS, on macOS:

flutter build ios --release --no-codesign

Signing keys and provisioning profiles must never be committed. Complete instructions are in deployment and distribution.

Architecture#

The code is divided into domain models/contracts, data adapters, application state, services, and presentation. SQLite is accessed through Drift's executor; network responses are parsed into strongly typed immutable models. Opened chapters are cached, their SHA endpoints are checked, and usable cached Scripture remains available when verification cannot reach the network.

lib/
  application/       lifecycle and reader state
  core/              errors, JSON validation, starter groups
  data/api/          GetBible API v2 client
  data/database/     local SQLite schema and platform executors
  data/repositories/ cache and persistence implementations
  domain/models/     versioned data contracts
  domain/repositories/abstract persistence contracts
  presentation/      native Flutter reader UI
  services/          backup, search, Markdown

See architecture and data contracts.

Privacy#

Notes, markings, preferences, cached Scripture, and reading position are stored locally. The app has no accounts, advertising, analytics, or tracking. Network traffic is limited to resources required for Scripture and daily-passage retrieval. See privacy policy draft.

Branding#

All platform launchers, favicons, splash artwork, window icons, and in-app identity use the approved GetBible artwork in assets/branding/. CI validates a committed checksum manifest so generated Flutter template icons cannot silently return. The source artwork must be replaced only with explicitly approved GetBible assets.

Documentation index#

License#

The existing repository license is retained in LICENSE. Scripture translations remain subject to the license and copyright metadata returned by GetBible API v2; the application license does not relicense translation content.

Feature-parity ledger#

Status meanings: Implemented exists in source; Partial needs remaining UX/integration work; Pending verification requires platform/device confirmation.

Area	Status	Implementation / remaining gate
Typed API v2 and dynamic indexes	Implemented	`GetBibleApiClient`, `CachedBibleRepository`
SQLite notes/markings/preferences/cache	Implemented	`LocalDatabase` and SQL repositories
SHA verification and offline chapter fallback	Implemented	Three freshness states shown by reader
Native line/paragraph reader	Implemented	`ReaderScreen`; no WebView
Translation/book/chapter selection	Implemented	Dynamic selectors
Last passage persistence	Implemented	Exact verse restoration/centering needs expanded widget integration
Swipe and cross-book navigation	Implemented core	Shared cross-book turn operation, horizontal swipe, Alt+arrow shortcuts, arrows/mobile row, and tested deliberate double-boundary intent; device gesture QA remains
Deep links/shareable links	Partial	Parser exists; GoRouter/platform association needs integration tests
RTL and appearance modes	Implemented	Device selection behavior still requires QA
Contextual selection toolbar	Partial	Verse-number and native selected-text menus expose the active group, searchable compact all-group palette, note/removal actions, and preserve native copy controls; exact overlay-positioning widget tests remain
Whole/text markings and overlap rules	Implemented core	Whole-verse recolor/removal, selected-range marking/removal, overlap rendering, active group memory, searchable Study card grid, per-marking open/delete, and add/edit/recolor/delete group UI exist; full journey tests and backup UI remain
Inline notes	Implemented core	Add/edit/delete editor opens under its verse and saved note folds inline; keyboard-shortcut and full widget journey tests remain
Search modes and isolate execution	Partial	Full filter UI, total-result count, isolate search, and progressive 20-result rendering exist; cooperative corpus parsing, match highlighting, seven-second arrival emphasis, and cancellation tests remain
Website-compatible backups	Implemented core	Model validation/merge exists; native file picker/share UI remains
Markdown generation	Implemented core	Native copy/share/save UI remains
Complete website localization	Partial	All 69 compact website locale packs are mirrored and contract-tested; Flutter runtime message loading and full widget adoption remain
Approved GetBible branding	Implemented	Supplied artwork is installed for Android, iOS, macOS, Windows, Linux, web, splash, and the reader header; CI verifies exact hashes
Accessibility	Partial	Safe area, semantics, scaling foundations; full focus/screen-reader audit remains
CI	Implemented	Format, analyze, tests, Android debug artifact
Signed store distribution	External	Requires Apple/Google credentials and store review

This ledger is intentionally candid. “Ready for distribution” means every Partial row applicable to mobile is completed, automated checks pass, release artifacts build, and the manual QA matrix is signed off.

GetBible API and cache workflow#

Base URL: https://api.getbible.net/v2.

Resource	Endpoint	Cache behavior
Translations	`/translations.json`	Refresh after seven days; changed translation SHA invalidates subordinate indexes/corpus.
Books	`/{translation}/books.json`	Dynamic; changed book SHA invalidates that book.
Chapters	`/{translation}/{book}/chapters.json`	Dynamic; changed chapter SHA invalidates only that chapter.
Chapter	`/{translation}/{book}/{chapter}.json`	Cached after opening.
Chapter SHA	`/{translation}/{book}/{chapter}.sha`	Checked before using a network-verified cached chapter.
Full translation	`/{translation}.json`	Download only for deliberate search/offline workflows; bind cache to translation SHA.

Freshness states are fresh, cachedVerified, and cachedUnverified. A failed network/hash check must not erase a valid cached chapter. Malformed cached JSON is discarded. Storage bookkeeping failure must not hide usable Scripture already fetched or verified.

Chapter activation uses the MCP consistency sequence: read the chapter SHA, download and fully parse the chapter, then read the SHA again. If the source rotated, retry once from the new SHA. Only a payload bracketed by identical hashes is activated. SQLite's single-row upsert is the atomic activation point; the previous row remains the last-known-good value on any preceding failure.

API responses must remain dynamically discovered; never hard-code available translations, book names, chapter counts, or verse counts. Timeouts, non-2xx responses, malformed UTF-8/JSON, and empty resources are typed failures.

Support and source documentation#

For questions about this project, installation, unexpected output, or contributing, use the single GetBible support desk. Include the project, installed release or commit, operating system, relevant API version, and a minimal reproduction. General enquiries can be sent to [email protected].

This guide follows the repository README and FEATURE PARITY, API AND CACHE. Scripture and study resources retain their own source licences; a software licence does not relicense the texts.