The Holy Qur'an app: a Flutter reader that caches the whole text offline

The data comes from an API, then lives on the device

The application is described as an application of the Holy book of Muslims, Al-Qur'an, developed using Flutter, and the data story is stated in one line: the data is fetched using API and now the offline mode is available, so you need internet for the first time only.

That is the whole architecture, and it is a sensible one for a reference text. The source is alquran.cloud, and the API Information section names the endpoint directly. The repository is built on top of that API rather than shipping the text in the binary, which means the app can be small and the content can be corrected at the source without a release.

The offline layer is the interesting part. The data goes over Dio, which is the HTTP client, and is cached with Hive CE, and the models are Freezed, which is the code generation approach that gives value equality and copy-with for free.

The caching is what makes the app usable in the conditions its users are likely to be in, which for a reference text used for reading and recitation is often a place with poor connectivity. The features list marks Offline Mode as improved, and pairs it with search by Surah, search by Juz, and bookmarks, plus other fixes from a previous version.

So the value proposition is a readable text, searchable by two of the traditional divisions, with bookmarking, that keeps working when the connection does not. That is a modest, well-scoped product, and the documentation does not claim more than that.

Two local packages split the data layer from the app

The tech stack line is dense, and the part that matters for anyone extending the project is the package split.

The data stack is alquran.cloud over Dio, cached offline with Hive CE, with Freezed models, and it is split into packages/al_quran_api, which holds the client, the models, the data provider and the code generation, and packages/al_quran_repo, which holds the repositories. The state management is flutter_bloc together with provider and get_it.

The split is the interesting decision. The API package is a self-contained thing that knows how to talk to alquran.cloud and produce typed models, and the repo package sits on top and exposes repositories to the application. That means the network and model layer can be reused in another Flutter application without dragging the UI along, and the codegen for the models lives in the package that owns the models rather than in the app.

Having three state management dependencies at once, bloc, provider and get_it, is a thing to note rather than a thing to criticise. get_it is a service locator, and using it for dependency injection alongside a bloc for state and provider where convenient is a common enough shape in a mid-sized Flutter application, but it does mean a new contributor has three idioms to learn. The documentation does not explain the division of labour between them, so that is a question for the docs directory rather than something you can infer from the dependency list.

On the platform side, the README is unusually candid. Android uses the Kotlin DSL Gradle build with AGP 9.1 and Gradle 9.3, targeting and compiling against SDK 36 with a minimum SDK of 24. iOS targets 15 or newer and is described as buildable but not published. The web build is described as currently broken.

Getting the project running takes four commands

The installation steps are given concretely, with the toolchain pinned.

The requirement is Flutter 3.47.3, which is Dart 3.13, pinned with FVM via a .fvmrc file. The Android target and compile SDK is 36 with a minimum SDK of 24, and iOS needs 15 or newer. FVM is the Flutter Version Management tool, and pinning the version in a file is what makes a Flutter project buildable by more than one person, since the Flutter SDK moves quickly enough that a version that worked last month may not today.

The clone and run sequence is:

git clone https://github.com/mhmzdev/the-holy-quran-app.git
cd the-holy-quran-app
fvm install
fvm flutter pub get
fvm flutter run

fvm install reads the .fvmrc and fetches the pinned SDK, fvm flutter pub get resolves the Dart dependencies, and fvm flutter run launches the app on a connected device or emulator.

The development section then gives the day to day commands, and the first one is a gate rather than a convenience:

fvm flutter analyze && fvm flutter test                          # gates before a PR
cd packages/al_quran_api && fvm dart run build_runner build      # after changing models
fvm flutter build appbundle --release                            # Play Store bundle (needs android/key.properties)
fvm flutter build apk --release                                  # sideload/test build

The first line is what runs before a pull request, and the second only needs to be run after changing models, because the Freezed models are generated and the codegen lives in the api package.

The two build commands at the end are the release path and the test path. The appbundle is what the Play Store wants, and it needs an android/key.properties file for signing. The apk is for sideloading or testing, and needs no signing key, which makes it the one to reach for when you just want the app on a phone.

The documentation moved out of the README on purpose

The first line of the README is a date and a pointer: updated 2026-09-10, and the maintained, in-depth documentation lives in the docs directory.

That is a deliberate structure, and the repository listing backs it. There is a docs directory with an index, an AGENTS.md, a CLAUDE.md, an .agents directory, a .claude directory, a _templates directory, a .hygen.js file, an analysis_options.yaml, a build.yaml and a scripts directory.

The docs directory is described as holding architecture, conventions, ADRs, domain notes and the release process, and the AGENTS.md holds AI-agent guidance with path-scoped rules and skills under .agents. So the project has separated three things that usually get mixed into a README: the reference documentation, the reasoning behind decisions, and the instructions for automated tools. The ADRs are the part that tells you why the architecture is shaped the way it is, which is what you want when you are about to change it.

The .hygen.js file and the _templates directory point to a template based generator, which is a convention for scaffolding new files from templates, and the build.yaml at the root suggests the build configuration is declarative rather than a Gradle file.

The last push to the repository was on 2026-09-10, matching the date in the README, and the repository is not archived. There are no GitHub releases, which for a Flutter application is normal because the distribution channel is the Play Store rather than GitHub, and the Play Store listing is the project home page.

The licence is MIT, with the file named LICENSE.md, and the project also ships a Privacy_Policy.md, which is worth noticing for an application that fetches religious content from a third party API and stores it on the device.

What the user actually gets, and what is missing

The features list is short and the README does not embellish it. Offline Mode, improved. Search Surah. Search Juz. Bookmarks. And other fixes from a previous version.

There is a light mode theme with its own screenshot set, and the screenshots show a reading interface with the text, some kind of navigation and a reading position, and there is a promo video linked from the README.

What is absent from that list is as informative as what is present. There is no mention of audio, no recitation playback, no tajweed rules, no translation, no tafsir commentary, no hadith, no prayer times, no qibla direction, and no account or sync system. For a reference application that is a coherent boundary: it is a text reader with search and bookmarks, and the offline promise is the guarantee that the text is there when the connection is not.

The absence of an account system also means the bookmarks live on the device, which is the usual trade for a local reader and also the reason the offline caching matters so much. There is nothing to sync them to.

The screenshots in the README show a light mode theme, and the repository has a fonts directory and an assets directory, so the typography is part of the project rather than a system default. Given the subject, that is a deliberate choice, and the presence of a dedicated fonts directory rather than relying on the platform typeface suggests the type is being controlled by the project.

Where this app is the wrong answer

Three situations rule it out, and the README itself flags two of them.

The first is iOS, and this is a distribution problem rather than a code problem. The documentation says iOS 15 or newer is buildable but not published. So the code compiles for iOS, and yet there is no App Store listing to install. Anyone whose users are on iPhones has no way to distribute this application other than building and signing it themselves, which for a Play Store project is a substantial extra step.

The second is web. The web build is described as currently broken. Flutter applications usually reach the web because it is nearly free to do, so this closes off what would otherwise be the easiest distribution channel, and it means the app is effectively Android and iOS only.

The third is dependency on a third party API. The text comes from alquran.cloud, and the app is a client for it. That is a deliberate design that keeps the binary small and lets the content be corrected centrally, but it means the app's core function depends on a service the project does not control, and the offline mode exists precisely to insulate the user from that dependency. Anyone building on packages/al_quran_api inherits the same dependency, and the documentation does not describe a fallback if the API changes shape or goes away.

A fourth point is about the domain rather than the code. An application presenting a religious text has a responsibility around the accuracy of what it displays, and the model layer is generated from an external API, so the correctness of the text is the API's guarantee and not the project's. For a reader this is fine as long as the reader trusts the source, and the documentation is clear about which source is used. For a project that needs to guarantee its own text, that is a different requirement and this is not the tool for it.

An application with a version pin and a documented release process

The maintenance picture is more current than the release list suggests, and the release list is empty.

There are no GitHub releases, which is normal for a Flutter application distributed through the Play Store, and the recent releases list is correspondingly blank. What there is instead is the README date, the docs directory with a release process described in it, and the last push on 2026-09-10, which puts the work within the last few weeks rather than months.

The Flutter version pin is the detail that tells you about the project's discipline. Flutter 3.47.3 with Dart 3.13, pinned in .fvmrc, is a specific and recent pairing, and pinning it means the build is reproducible for anyone who clones the repository. The Android build configuration is equally specific, with the Kotlin DSL rather than the older Groovy DSL, AGP 9.1 and Gradle 9.3, targeting SDK 36 with a minimum of 24. A project that pins its SDK, its Flutter version, its Android Gradle Plugin and its Gradle version is a project that expects to build on more than one machine.

The Android build uses the Kotlin DSL Gradle setup, and the iOS and web directories exist in the repository, so the platform shells are all there even where the output is not shipped. That is the same pattern as the packages split: the unsupported platforms are stubbed rather than removed, which means bringing them up is a matter of work rather than of archaeology.

The privacy policy file in the repository root is a small but sensible presence for an application that pulls content from a third party server and writes it to local storage, and the offline mode is what keeps the later use of that content independent of the network.

Editorial conclusion

The Holy Qur'an app fits a developer who wants a readable, offline-first Qur'an application in Flutter and is prepared to contribute, because the repository has a maintained docs directory, agent guidance and a package split that makes the data layer reusable. It is the wrong choice if you need a published iOS app today, since the documentation says iOS is buildable but not published, and it is the wrong choice if you need a web build, since the web build is currently broken. Before adopting the code, read the docs directory rather than the README, check the pinned Flutter version against your toolchain, and confirm the API you depend on still serves the endpoints the packages/al_quran_api client expects.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. mhmzdev/the-holy-quran-app on GitHub
4. Project website
5. README