The Operational Mandate
Context & High-Stakes Constraints
In the digital era, having immediate, peaceful, and barrier-free access to the Holy Quran is essential for millions of Muslims worldwide. Quran App was designed and developed as a sleek, modern mobile application delivering the complete 114 surahs into an intuitive, responsive interface.
The primary architectural goals were zero-latency navigation, instant dual-attribute search across Latin titles and chapter numbers, authentic verse-by-verse recitation reading with Arabic script and HTML-formatted transliteration, personalized bookmarking, and seamless theme switching for comfortable day and night reading.
02MOBILE AL-QURAN READER & DEVOTIONAL PLATFORM
The Quran App Experience in Action
Explore the peaceful and high-performance digital Quran experience — featuring complete 114 surah indexing, instant multi-attribute search, full verse reader with Arabic script & Indonesian transliteration, and reactive bookmark management.
🔒app.quran.mobile
01 / 04Brand Presentation
Official Quran App Showcase & Device Suite
Comprehensive presentation showcase displaying Quran App's multi-device mobile architecture, presenting surah indexing, deep ayat reading, and personalized bookmark rosters across modern mobile displays.
◆ Flutter 3.x Cross-Platform Client◆ GetX Reactive State Architecture◆ 114 Surah RESTful Ingestion
03CAPABILITIES & WORKFLOW
Core Architectural Capabilities
A breakdown of the engineering building blocks powering Quran App's responsive scripture delivery, reactive UI updates, and offline bookmarking.
RESTful Scripture Ingestion Engine
Asynchronous HTTP client consuming Quranic surah and ayat data from https://quran-api.santrikoding.com/api/surah/ with dynamic surah number querying (/api/surah/{number}) and JSON array mapping.
GetX Reactive State & Theme Architecture
Clean controller-based pattern utilizing QuranController extending GetxController, managing reactive observables (url.obs, isTheme.obs, search.obs, bookMarks.obs) with granular Obx widget rebuilders.
Multi-Attribute Search & Dynamic Grid Layout
Dual-attribute client-side filtering matching lowercase Latin names (nama_latin) and surah sequence numbers (nomor) rendered through an adaptive SliverGridDelegateWithMaxCrossAxisExtent grid.
Rich Typography & HTML Transliteration Parser
Integration with flutter_html: ^3.0.0 parsing HTML-formatted pronunciation markup alongside authentic Arabic typography (item['ar']) and circular verse counters.
6 Mission-Critical Modules
Each module is engineered with robust transactional boundaries, modular isolation, and comprehensive audit trails.
MODULE // 01 OF 06Scripture Corpus
Complete 114 Surah Directory & Responsive Grid
High-throughput surah directory displaying all 114 Quranic chapters with authentic Arabic calligraphy, Latin titles, and verse metrics.
- Adaptive Grid Architecture: SliverGridDelegateWithMaxCrossAxisExtent renders a 3/2 aspect ratio responsive card grid across mobile viewports.
- Dual Typography Render: Simultaneously displays authentic Arabic script (nama) and localized phonetic Latin transliterations (nama_latin).
- Instant Surah Routing: Tapping any surah card triggers Get.to(QuranDetail(surah: item)) with zero navigation latency.
- Embedded Bookmark Controls: Each card contains an Obx bookmark toggle button reflecting real-time saved state.
Scripture Ingestion & Reader Lifecycle
From remote Quranic REST API query through GetX reactive transformation to reader bookmarking — every surah and ayat flows through a structured, responsive pipeline.
Stage 01Remote Scripture Ingestion
API Endpoint Query & Handshake
QuranController.getSurah() executes asynchronous HTTP GET to /api/surah/ endpoint, validating status codes.
HTTP Ingestion & Status Validation
Stage 02JSON Deserialization
Surah Array Parsing & Typing
Decodes raw response body into structured List<Map<String, dynamic>> records preserving Arabic and Latin names.
Model Deserialization & Normalization
Stage 03Reactive Controller Binding
Observable Query Synchronization
TextField inputs immediately mutate search.obs, triggering fine-grained Obx rebuilds across the surah grid.
Dual-Attribute Stream Filtering
Stage 04Deep Ayat Retrieval
Surah Detail & Verse Resolution
QuranController.getDetail(number) queries /api/surah/{number} to fetch the complete array of verses.
Surah Verse Array Ingestion
Stage 05Editorial Scripture Delivery
Arabic Typography & HTML Transliteration
QuranDetail renders Arabic calligraphy paired with flutter_html transliteration and circular counters.
HTML & Arabic Calligraphy Rendering
Stage 06Bookmark Curation
Personalized Reading Persistence
Users tap bookmark actions to atomically add or evict surahs from bookMarks.obs with instant UI updates.
Reactive Bookmark Synchronization
Immutable Surah Reference & Deduplication Guard
All bookmark operations perform equality verification on surah map payloads before mutating the observable bookMarks.obs collection, preventing duplicate records and guaranteeing state consistency.
04SYSTEM ANATOMY & ARCHITECTURE
Application Architecture & Data Flow
Layered system design decoupling network transport, reactive state control, and responsive UI components.
Pattern: Controller-Based Reactive Client Architecture (GetX) + RESTful Microservices
Protocol: HTTPS REST (JSON) + Dart Observables (.obs) + GetX Route Manager
Presentation Layer (Flutter 3.x)
Dart ^3.8.1 + Material 3Three primary screens (QuranScreen, QuranDetail, QuranBookmark) bound to GetX controller state via Obx rebuilders.
Reactive State & Logic (lib/controller/)
GetxController + ObservablesQuranController managing observables (url.obs, isTheme.obs, search.obs, bookMarks.obs) and bookmarking algorithms.
Service & Ingestion Layer (lib/api/)
HTTP 1.5.0 + dart:convertNetwork methods getSurah() and getDetail() executing asynchronous REST requests with HTTP 200 validation.
Scripture Typography & Parser Engine
flutter_html 3.0.0 + Arabic FontsSpecialized text rendering combining Arabic Uthmani calligraphy with HTML transliteration parsing.
Routing & Overlay Manager
GetMaterialApp + Route ManagerDeclarative navigation via Get.to() and context-free system theme management via Get.changeTheme().
Cross-Platform Mobile Engine
Flutter Engine + Skia / ImpellerHigh-performance native rendering compiling to Android ART and iOS ARM binaries with 60 FPS scroll performance.
Curated Technology Stack
A modern engineering stack combining high-throughput user interfaces, modular backend architecture, and resilient data layers.
Mobile Application & UI
Flutter 3.xCross-Platform Mobile Framework
Dart ^3.8.1Strongly Typed Client Programming Language
Material 3Modern Android & iOS Design System
Cupertino IconsiOS Style Iconography Library
GridViewResponsive Surah Directory Card Layout
State Management & Architecture
GetX 4.7.2Reactive State & Dependency Injection
GetxControllerBusiness Logic Component Controller
Obx RebuilderSurgical Micro-Update Widget Rebuilder
Rx ObservablesReactive State Containers (.obs)
Get NavigationContext-Free Declarative Route Manager
Networking & Scripture Ingestion
HTTP 1.5.0Asynchronous HTTP REST Client
dart:convertHigh-Performance JSON Deserialization
SantriKoding APISyndicated Quranic REST Scripture Stream
FutureBuilderAsynchronous Concurrency State Machine
Rendering & Media Engine
flutter_html 3.0.0HTML Pronunciation Transliteration Parser
Arabic Uthmani FontAuthentic Quranic Calligraphy Rendering
CircleAvatarNumbered Verse Badge Identification
GitDistributed Version Control System
Codebase Structure & Data Models
Clear boundary separation between system components, paired with modular schemas and structured repositories.
📁 lib/ (Core Application Architecture)
├──main.dart — App bootstrap and GetMaterialApp configuration
├──controller/quran_controller.dart — GetX controller managing API requests, search, themes, bookmarks
├──screens/quran_screen.dart — Home surah grid with search bar and bookmark navigation
├──screens/quran_detail.dart — Full verse reader with Arabic text and HTML transliteration
├──screens/quran_bookmark.dart — Dedicated bookmark repository with one-tap reader navigation
Database Entities & Schema Models
Data Model: Surah Record (Index)
Structured representation of a Quran chapter: nomor (int), nama (Arabic string), nama_latin (string), jumlah_ayat (int), tempat_turun (string), and arti (string).
Data Model: Ayat Record (Verse Detail)
Structured representation of a Quran verse: id (int), surah (int), nomor (int), ar (Arabic calligraphy text), tr (HTML transliteration text), and idn (translation).
Reactive Store: QuranController State
GetxController reactive store holding url.obs, isTheme.obs, search.obs, and bookMarks.obs collection.
05SECURITY, API & PRODUCTION IMPACT
API Reliability & Client-Side Resiliency
Architectural safeguards ensuring uninterrupted scripture reading, graceful exception containment, and offline data stability.
API Endpoints & Routing Architecture
Remote Scripture Ingestion
GEThttps://quran-api.santrikoding.com/api/surah/Fetches complete index array containing all 114 Quranic chapters with Arabic and Latin names
GEThttps://quran-api.santrikoding.com/api/surah/{number}Fetches comprehensive chapter detail including complete verse array, Arabic text, and HTML transliteration
Client-Side Reactive Filtering
CLIENTQuranController.search.valueZero-latency case-insensitive dual-attribute search querying Latin titles and numerical surah indices
CLIENTQuranController.bookMarks.obsReactive in-memory observable collection managing personalized reading bookmarks with duplicate prevention
Enterprise Security & Governance Standards
Asynchronous FutureBuilder Error Intercept
Surrounds asynchronous data ingestion with snapshot.hasError evaluation, rendering descriptive error indicators and preventing application unhandled exceptions.
HTML Transliteration Sanitization & Parsing
Uses flutter_html to safely parse Latin phonetic transliterations and accent marks without rendering raw HTML tags or causing text layout overflow.
Null-Safe Type Boundary Enforcement
Enforces strict Dart 3.8 null-safety across all dynamic JSON map responses, protecting against missing fields or unexpected network payloads.
Deduplicated In-Memory Bookmark Integrity
Applies contains() equality validation on surah map objects before appending to bookMarks.obs, preventing duplicate bookmarks and maintaining clean state.
Engineering Challenges & Production Results
How critical technical bottlenecks were overcome and verified under real production conditions.
Challenge // 01
Handling remote API availability, rate limiting, and unexpected network timeouts. Solved by integrating comprehensive FutureBuilder error boundaries that capture connection states and display graceful error states rather than crashing the view.
Challenge // 02
Balancing bi-directional text presentation between right-to-left (RTL) Arabic Quranic calligraphy and left-to-right (LTR) phonetic Latin transliteration. Solved by decoupling the verse title from the transliteration subtitle and utilizing flutter_html to render phonetic styling accurately.
Challenge // 03
Providing an instantaneous, zero-latency bookmark experience. Solved by leveraging GetX's RxList, providing instant visual feedback on bookmark toggles and preventing duplicate entries with strict object equality checks.