Understanding the Project Structure of alfaazplus/quranapp: Android Multi-Module Architecture

The alfaazplus/quranapp repository follows a clean Android Gradle multi-module architecture consisting of the main app module for core functionality, a reusable peacedesign UI library module, and an inventory directory for static JSON data assets.

The alfaazplus/quranapp is an open-source Android Quran application built with modern Android development practices and Jetpack libraries. Understanding its project structure is essential for contributors looking to navigate the codebase, debug issues, or extend functionality. This guide breaks down the multi-module Gradle setup, key source directories, and architectural decisions implemented in the repository.

Multi-Module Gradle Architecture

The project root contains standard Gradle configuration files that orchestrate the build across modules. The build.gradle.kts file at the repository root defines the Kotlin version (2.2.21) and plugins used across all modules, while settings.gradle.kts registers the two primary modules: :app and :peacedesign.

// settings.gradle.kts
include(":app", ":peacedesign")

This separation allows the Peacedesign UI toolkit to develop independently while being consumed as a library dependency by the main application.

The app Module: Core Application Structure

The app/ directory contains the primary Android application module where all user-facing functionality resides. This module follows standard Android source set conventions with src/main/ containing production code and resources.

Build Configuration and Dependencies

The app/build.gradle.kts file defines the application's dependency graph, integrating modern Android stack components including the Compose BOM for declarative UI, ExoPlayer for audio streaming, WorkManager for background tasks, Retrofit for networking, and Kotlinx Serialization for JSON handling.

// app/build.gradle.kts
implementation(libs.compose.material3)
implementation(libs.exoplayerCore)
implementation(libs.workManager)
implementation(libs.retrofit)

Additional utilities include Guava, Apache Commons, and SmoothRefreshLayout for enhanced UI interactions.

Android Manifest and Entry Points

The app/src/main/AndroidManifest.xml declares the complete application structure, including the entry point at MainActivity, the reader interface via ActivityReader, background services like RecitationService, and broadcast receivers for widgets and system events.

Key declarations include:

• com.quranapp.android.activities.MainActivity – The launcher activity
• com.quranapp.android.utils.services.RecitationService – Foreground service for audio playback
• Various receivers for widget updates, boot events, and crash reporting

Source Code Organization

The Kotlin source code under app/src/main/java/com/quranapp/android/ follows package-based separation of concerns:

• activities/ – UI screens including MainActivity.kt, ActivityReader, settings, and reference activities
• utils/ – Helper classes for networking, WorkManager workers, background services, and custom broadcast receivers
• components/ – Data models for translations, tafsir, and verse references
• widgets/ – Custom UI widgets built atop the Peacedesign library

Assets and Static Resources

The app/src/main/assets/ directory houses runtime JSON data including quran_meta.json (containing chapter metadata), while app/src/main/res/ contains Android resources such as layouts, drawables, and values/strings.xml with translation placeholders. The xml/searchable.xml file configures the Android search framework integration.

The peacedesign Library Module

The peacedesign/ module is an independent UI component library providing reusable widgets throughout the application. Located at peacedesign/src/main/java/com/peacedesign/, this library abstracts common UI patterns into maintainable components.

Key implementations include:

• PeaceBottomSheetDialog – Customizable bottom sheet dialogs with theming support
• PeaceDialog – Alert dialog variations with consistent styling
• Custom radio groups, checkboxes, and spinners using the library's attribute system

The library maintains its own resources under peacedesign/src/main/res/values/ for styles (styles.xml) and custom attributes (attrs.xml), ensuring visual consistency across the app.

// Using Peacedesign components
val sheet = PeaceBottomSheetDialog(context).apply {
    setTitle("Choose Translation")
    setAdapter(translationAdapter)
    setOnItemClickListener { position ->
        // handle selection
        dismiss()
    }
}
sheet.show()

Data Management with the inventory Directory

The inventory/ directory at the project root serves as an external data repository shipped with the application. This structure separates volatile data assets from source code:

• inventory/translations/ – JSON language packs for Quranic translations
• inventory/versions/ – Version tracking files including app_updates.json for in-app update prompts
• inventory/tafsir/ – Tafsir (exegesis) metadata indexes
• inventory/fonts/ – Custom Quranic typography assets

The application loads these resources at runtime via preference helpers like SPAppConfigs, allowing offline-first functionality without hardcoding linguistic data.

Background Processing Architecture

The app implements robust background execution through a combination of deferred work and foreground services.

WorkManager for Deferred Tasks

WorkManager handles on-demand downloads of language packs and tafsir content through dedicated worker classes. The TranslationDownloadWorker.kt and TafsirDownloadWorker.kt files in app/src/main/java/com/quranapp/android/utils/workers/ encapsulate download logic with retry policies and progress reporting.

// Scheduling a translation download
val downloadRequest = OneTimeWorkRequestBuilder<TranslationDownloadWorker>()
    .setInputData(workDataOf("lang" to "en"))
    .build()

WorkManager.getInstance(context).enqueue(downloadRequest)

Foreground Services for Audio

For continuous audio playback, the app utilizes foreground services declared in the manifest. The RecitationService.kt manages streaming of Quranic recitations, while RecitationChapterDownloadService handles chapter-by-chapter offline caching without interrupting the user experience.

CI/CD and Release Infrastructure

The repository includes comprehensive automation for quality assurance and distribution:

• .github/workflows/ci.yml – GitHub Actions workflow running unit tests, linting, and APK builds on every push
• fastlane/metadata/android/ – Play Store assets including localized descriptions, screenshots, and changelogs for automated releases
• repo_assets/ – Widget icons, screenshots, and archived APKs for distribution outside the Play Store

Summary

• The project uses a multi-module Gradle structure with :app and :peacedesign modules for separation of concerns
• Modern Android architecture leverages Jetpack Compose, ExoPlayer, WorkManager, and Retrofit as defined in app/build.gradle.kts
• Source code organizes UI, utilities, and data models into distinct packages under com.quranapp.android
• The inventory/ directory externalizes translation data, fonts, and version metadata from the main source tree
• Background operations combine WorkManager for deferred downloads and foreground services for audio streaming
• Fastlane and GitHub Actions provide automated CI/CD pipelines for testing and Play Store deployment

Frequently Asked Questions

What modules make up the alfaazplus/quranapp project?

The project consists of two Gradle modules: the :app module containing the main Android application with all UI and business logic, and the :peacedesign module serving as a reusable UI component library. The root settings.gradle.kts registers both modules for compilation.

Where are the Quran translations stored in the project?

Translation files reside in the inventory/translations/ directory as JSON language packs, separate from the application source code. The app loads these at runtime from the assets directory, with metadata indexes helping the TranslationDownloadWorker manage on-demand downloads via WorkManager.

How does the app handle background downloads of recitations and translations?

The app uses WorkManager for deferred, reliable downloads of text resources through TranslationDownloadWorker and TafsirDownloadWorker. For audio recitations, it implements foreground services like RecitationService and RecitationChapterDownloadService declared in AndroidManifest.xml to maintain persistent downloads without interruption.

What is the purpose of the peacedesign module?

The peacedesign module is a standalone UI toolkit providing reusable components such as PeaceBottomSheetDialog and custom form controls. This library approach ensures consistent theming and behavior across different screens while allowing independent development and testing of UI components.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}