How to Contribute to the alfaazplus/quranapp Project: A Complete Developer’s Guide

Contributing to the alfaazplus/quranapp project requires setting up Android Studio with Kotlin support, understanding the six-layer modular architecture, and submitting pull requests that follow the Kotlin coding conventions defined in kotlin_code_style.xml.

The alfaazplus/quranapp repository is an open-source Android application built with Kotlin and Jetpack Compose that enables users to read, explore, and interact with the Qur’an. Whether you aim to fix bugs, add new translations, or implement UI improvements, understanding how to contribute to the alfaazplus/quranapp project begins with mastering its layered architecture and established contribution workflows.

Understanding the QuranApp Architecture

The codebase is organized into six specialized layers that enforce separation of concerns. Each layer has distinct responsibilities, reference implementations, and specific file locations within the repository.

App Core Layer

The App Core handles Android UI components, activities, fragments, and Jetpack Compose themes. The entry point resides in app/src/main/java/com/quranapp/android/QukanApp.kt, which initializes Dagger/Hilt, DataStore, and sets the application theme. Reader functionality is managed by app/src/main/java/com/quranapp/android/activities/ActivityReaderIndexPage.kt, while theme definitions and color schemes are defined in app/src/main/java/com/quranapp/android/compose/theme/Theme.kt.

Data and Persistence Layer

This layer manages local storage using Room database helpers and Jetpack DataStore for caching user preferences and content. Translation database operations are handled by app/src/main/java/com/quranapp/android/db/translation/QuranTranslDBHelper.kt, while persistent app settings are managed through app/src/main/java/com/quranapp/android/compose/utils/shared_preference/DataStoreManager.kt.

Network Layer

Retrofit-based API clients handle remote resource fetching for translations, recitations, and app updates. The app/src/main/java/com/quranapp/android/api/RetrofitInstance.kt file configures the base URL and JSON converter, while app/src/main/java/com/quranapp/android/api/AlfaazPlusApi.kt defines the service interfaces. API response models, such as app/src/main/java/com/quranapp/android/api/models/translation/TranslationBookInfoModel.kt, provide type-safe data structures for network responses.

Parsers and Utilities

Kotlin parsers convert raw JSON assets into in-memory domain models. The app/src/main/java/com/quranapp/android/utils/quran/parser/QuranParser.kt processes the main verses JSON, while specialized parsers like QuranProphetParser.kt and MajorSinVersesParser.kt handle prophet biographies and religious guideline content respectively.

Background Workers

WorkManager implementations manage asynchronous downloads and storage cleanup. The app/src/main/java/com/quranapp/android/utils/workers/TranslationDownloadWorker.kt handles translation file fetching with proper error handling for network states, while TafsirDownloadWorker.kt manages commentary downloads. These workers implement CoroutineWorker and must catch NoInternetException for retry logic.

Resources and Assets

Static content resides in app/src/main/assets/, including prebuilt translations (prebuilt_translations/), verse structures (verses/type2/*.json), and science topic HTML files (science/topics/*.html).

Setting Up Your Development Environment

Before you contribute to the alfaazplus/quranapp project, configure your local environment:

1. Install Android Studio Arctic Fox or newer with the Android SDK and Kotlin plugins.
2. Clone the repository and open the project—the Gradle wrapper is preconfigured in build.gradle.kts at the repository root.
3. Execute ./gradlew assembleDebug from the terminal to build the debug APK and verify the configuration.
4. Launch the application using Android Studio’s Run button on either an emulator or physical device running Android API level 21 or higher.

Contribution Pathways

The repository accepts multiple contribution types, each following specific technical patterns and file locations.

Code Contributions

Submit bug fixes, UI improvements, or architectural refactoring by forking the repository, creating a descriptive feature branch, and opening a pull request. The CONTRIBUTING.md file at the repository root outlines branch naming conventions, commit message standards, and the complete pull request workflow.

Translation Contributions

Add or improve Qur’an translations by contributing JSON files to inventory/translations/. Each translation requires a manifest file and data files placed in app/src/main/assets/prebuilt_translations/[translation_id]/. The files must follow the JSON schema used by QuranParser.kt for proper ingestion.

Recitation Additions

Submit new free API URLs to inventory/recitations/available_recitations_info.json to expand the audio recitation options available to users. Ensure the URLs point to publicly accessible, properly licensed content.

UI Localization

Translate the application interface by modifying string resources in app/src/main/res/values-<lang>/strings.xml, or join the Weblate project for collaborative translation management of UI elements, menus, and user prompts.

Implementing New Features

When adding functionality to the alfaazplus/quranapp source code, follow these implementation patterns derived from the existing architecture.

Adding a Quran Translation

Create a data class structure matching your JSON schema, then register the translation in the repository layer:

data class MyNewTranslation(val suras: List<Sura>)
data class Sura(val index: Int, val ayas: List<Aya>)
data class Aya(val id: Int, val index: Int, val translation: String)

// Registration in the repository
val translationInfo = TranslationInfo(
    id = "en_mynewtranslation",
    name = "My New English Translation",
    language = "en",
    path = "prebuilt_translations/en_mynewtranslation/en_mynewtranslation.json"
)
TranslationRepository.addTranslation(translationInfo)

Place manifest files in app/src/main/assets/prebuilt_translations/[id]/manifest.json and data files alongside them, following the asset management pattern established in TranslationDownloadWorker.kt.

Creating Background Workers

Extend CoroutineWorker for any network operations that must survive configuration changes:

class MyFeatureDownloadWorker(
    ctx: Context,
    params: WorkerParameters
) : CoroutineWorker(ctx, params) {

    override suspend fun doWork(): Result = try {
        val url = inputData.getString("download_url")!!
        val json = NetworkHelper.get(url) // Uses RetrofitInstance
        FileHelper.saveJson(applicationContext, "my_feature.json", json)
        Result.success()
    } catch (e: NoInternetException) {
        Result.retry()
    } catch (e: HttpNotFoundException) {
        Result.failure()
    } catch (e: Exception) {
        Result.failure()
    }
}

Enqueue workers through WorkManager.getInstance(context) when users trigger downloads or toggle settings in the UI.

Building New Activities

Create new activities by extending AppCompatActivity and utilizing ViewBinding for view access:

class ActivityMyFeature : AppCompatActivity() {

    private val binding: ActivityMyFeatureBinding by lazy {
        ActivityMyFeatureBinding.inflate(layoutInflater)
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(binding.root)
        
        binding.btnDownload.setOnClickListener {
            val workRequest = OneTimeWorkRequestBuilder<MyFeatureDownloadWorker>()
                .setInputData(workDataOf("download_url" to "https://example.com/data.json"))
                .build()
            WorkManager.getInstance(this).enqueue(workRequest)
        }
    }
}

Declare all new activities in app/src/main/AndroidManifest.xml and create corresponding layout XML files in app/src/main/res/layout/.

Architectural Guidelines for Contributors

Follow these strict conventions when modifying the alfaazplus/quranapp codebase:

• Kotlin Coding Style: Adhere to the conventions defined in kotlin_code_style.xml at the repository root. The CI workflow enforces these standards automatically.
• Parser Patterns: Use existing parsers like QuranParser.kt as templates. Each JSON asset requires a matching parser class implementing ParserUtils conventions for consistency.
• Error Handling: Workers must distinguish between NoInternetException (triggering Result.retry()) and HttpNotFoundException (triggering Result.failure()).
• Testing Strategy: Place instrumentation tests for UI changes in app/src/androidTest/ and unit tests for core logic in app/src/test/.
• Documentation Updates: Modify README.md, FEATURES.md, and DeepWiki entries when adding public-facing features or changing user workflows.

Summary

Contributing to the alfaazplus/quranapp project requires understanding these critical technical elements:

• The architecture separates UI, data persistence, network communication, JSON parsing, and background processing into six distinct layers.
• TranslationDownloadWorker.kt and similar CoroutineWorker implementations handle all background downloads using WorkManager with specific exception handling.
• Translation contributions involve validated JSON files in inventory/translations/ and proper asset registration in the prebuilt translations directory.
• New activities must be declared in AndroidManifest.xml, use ViewBinding for view access, and follow the activity patterns established in ActivityReaderIndexPage.kt.
• The project maintains strict Kotlin coding conventions verified through the CI workflow defined in .github/workflows/ci.yml.

Frequently Asked Questions

What programming languages and frameworks power the alfaazplus/quranapp project?

The application is built exclusively with Kotlin for Android, utilizing Jetpack Compose for UI theming as implemented in Theme.kt, Room for local SQLite database persistence, Retrofit for REST API communication via RetrofitInstance.kt, and WorkManager for background processing. The project requires Android Studio Arctic Fox or newer to build successfully.

How do I add a new Quran translation to the application?

Create a JSON file containing the translation data formatted according to the schema used in QuranParser.kt, then place it in app/src/main/assets/prebuilt_translations/[unique_id]/. Define Kotlin data classes matching your JSON structure, then register the translation using TranslationRepository.addTranslation() with a TranslationInfo object specifying the ISO language code, display name, and relative file path.

Where should I implement background download logic in the codebase?

All background network operations belong in the Workers layer under app/src/main/java/com/quranapp/android/utils/workers/. Extend CoroutineWorker and implement doWork() with specific exception handling: catch NoInternetException to return Result.retry() and HttpNotFoundException for permanent failures. Register your worker with WorkManager and enqueue it from UI components after user action or setting changes.

How are pull requests reviewed and merged into the main branch?

Pull requests trigger the CI workflow defined in .github/workflows/ci.yml, which executes automated tests and validates Kotlin code style against kotlin_code_style.xml. Maintainers review for architectural consistency, proper error handling in worker classes, and adherence to parser utility patterns. Contributors must provide clear descriptions referencing related issues and ensure branches follow the fork-and-branch workflow outlined in CONTRIBUTING.md before merge approval.

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