IlearnQuranTesting/README.md

ILearn Quran 📖

AI-Powered Quran Learning & Recitation Correction

Download APK • Website • Report Bug

---

📱 About

ILearn Quran is a mobile application designed to help users learn and perfect their Quranic recitation with the power of artificial intelligence. The app provides real-time pronunciation evaluation, word-level audio synchronization, and comprehensive progress tracking.

✨ Key Features

• 🎙️ AI-Powered Pronunciation Evaluation - Get instant feedback on your recitation accuracy
• 📖 Complete Quran Access - Browse all 114 Suras with verse-by-verse navigation
• 🎵 Professional Audio Recitation - Listen to high-quality Quranic audio
• 🔊 Voice Recording & Playback - Record your recitation and compare it with the original
• 🎯 Word-Level Highlighting - Follow along with real-time word synchronization
• 📊 Progress Tracking - Monitor your learning journey with detailed statistics
• 🌍 Bilingual Support - Available in Arabic and English
• 🌓 Dark/Light Themes - Comfortable reading in any lighting condition
• 📝 Transliteration - Phonetic pronunciation guide for non-Arabic speakers
• 💾 Offline Progress - Your progress is saved locally on your device

---

🚀 Download & Installation

For Users

Android APK (Latest Release v1.0.6)

📥 Download ILearn Quran APK

Installation Steps:

1. Download the APK file from the link above
2. Enable "Install from Unknown Sources" in your Android settings
3. Open the downloaded APK file
4. Follow the installation prompts
5. Launch the app and start learning!

---

🛠️ Tech Stack

Core Technologies

• React Native 0.76.5 - Cross-platform mobile framework
• TypeScript 5.0.4 - Type-safe JavaScript
• React 18.3.1 - UI library

State Management & Data

• Zustand 5.0.8 - Lightweight state management with persistence
• Apollo Client 3.13.5 - GraphQL client
• AsyncStorage - Local data persistence

Navigation & UI

• React Navigation 7.x - Navigation library
• React Native Reanimated 3.17 - Smooth animations
• React Native Vector Icons - Material Design icons
• React Native SVG - SVG support

Audio & Media

• react-native-audio-recorder-player - Audio recording & playback
• react-native-sound-player - Audio playback
• react-native-fast-image - Optimized image loading

Internationalization

• react-i18next - Multi-language support (Arabic/English)

---

💻 Development Setup

Prerequisites

• Node.js >= 18
• Yarn 4.7.0 or npm
• React Native CLI
• Android Studio (for Android development)
• Xcode (for iOS development, macOS only)

Installation

1. Clone the repository

   git clone <repository-url>
   cd ILQ
   

2. Install dependencies

   yarn install
   # or
   npm install
   

3. Install iOS dependencies (macOS only)

   cd ios
   pod install
   cd ..
   

4. Start Metro bundler

   yarn start
   # or
   npm start
   

5. Run the app

   For Android:

   yarn android
   # or
   npm run android
   

   For iOS:

   yarn ios
   # or
   npm run ios
   

Build Scripts

# Development
yarn start              # Start Metro bundler
yarn android            # Run on Android
yarn ios                # Run on iOS

# Testing
yarn test               # Run tests
yarn lint               # Run ESLint

# Production
yarn build:android      # Build Android APK
yarn build:ios          # Build iOS IPA

---

📁 Project Structure

ILQ/
├── src/
│   ├── api/                    # External API integrations
│   │   ├── quran_mp3.ts       # Quran audio URL provider
│   │   └── pexels.js          # Image API client
│   ├── assets/                 # Static assets (fonts, images)
│   ├── components/             # Reusable UI components
│   │   ├── AudioRecorder.tsx   # Voice recording component
│   │   ├── VersePlayer.tsx     # Audio playback + text sync
│   │   ├── ArabicTextDisplay.tsx # Text with evaluation overlay
│   │   └── AnimatedArabicWord.tsx # Word-level animations
│   ├── gql/                    # GraphQL queries & mutations
│   │   ├── queries.ts          # SORAT, AYAT, AYA queries
│   │   ├── mutations.ts        # EVALUATE mutation
│   │   └── types.d.ts          # GraphQL type definitions
│   ├── hooks/                  # Custom React hooks
│   ├── i18n/                   # Internationalization
│   │   ├── config.ts           # i18next setup
│   │   └── locales/            # Translation files (ar.json, en.json)
│   ├── routes/                 # Navigation structure
│   ├── screens/                # Screen components
│   │   ├── AyaPage.tsx         # Verse learning/practice screen
│   │   ├── SoratScreen.tsx     # Chapter carousel browser
│   │   ├── ProgressScreen.tsx  # Learning statistics
│   │   └── SettingsScreen.tsx  # App settings
│   ├── services/               # Business logic
│   │   └── progressService.ts  # Progress tracking & analytics
│   ├── stores/                 # Zustand state management
│   │   ├── useLanguageStore.ts # Language preference
│   │   ├── useThemeStore.ts    # Theme mode
│   │   └── useVersePlayerStore.ts # Audio playback state
│   ├── theme/                  # Design system
│   │   ├── colors.ts           # Light/dark color palettes
│   │   └── styleHelpers.ts     # Style utilities
│   ├── types/                  # TypeScript definitions
│   └── utils/                  # Utility functions
├── android/                    # Android native code
├── ios/                        # iOS native code
├── App.tsx                     # Root component
└── index.js                    # App entry point

---

🎯 How It Works

1. Browse Quran Chapters

Navigate through 114 Suras with a beautiful carousel interface featuring background images and smooth animations.

2. Learn Verses

• Listen to professional Quranic recitation
• Follow along with word-by-word highlighting
• View transliteration for pronunciation help
• Read verse meanings in English

3. Practice Recitation

• Record your recitation using the microphone button
• AI analyzes your pronunciation against the original text
• Get word-level accuracy scores (0-100%)
• Review detailed feedback on mispronounced words

4. Track Progress

• View statistics on total words practiced
• Monitor mispronunciation percentage
• See most practiced Suras and verses
• Track improvement over time

---

🔑 Key Components

AyaPage (Verse Learning Screen)

The main practice screen where users:

• Listen to verse audio with synchronized highlighting
• Record and evaluate their recitation
• View evaluation results with color-coded accuracy
• Access verse meanings and transliteration

AudioRecorder

Handles voice recording with:

• High-quality audio capture (44.1kHz, 128kbps)
• Real-time recording timer
• Automatic upload to evaluation backend
• Playback of recorded audio

VersePlayer

Manages audio playback with:

• Word-level synchronization using time segments
• Play/pause/replay controls
• Animated word highlighting
• Progress tracking

AnimatedArabicWord

Provides:

• Smooth scale and highlight animations
• Samsung device compatibility fixes
• Background highlight for visibility
• Touchable word navigation

---

🌐 Backend Integration

GraphQL Endpoint: https://be.ilearnquran.org/graphql

Main Queries

• SORAT - Fetch all Quranic chapters
• AYAT - Fetch verses for a chapter
• AYA - Fetch single verse details

Mutations

• EVALUATE - Submit audio for AI pronunciation evaluation

---

🎨 Design Principles

• Accessibility First - Compact headers, finger-friendly buttons, optimized spacing
• Performance - Smooth 60fps animations using Reanimated
• Responsive Design - Works on all screen sizes
• Dark Mode Support - Comfortable reading in any environment
• RTL Support - Proper right-to-left text rendering for Arabic
• Offline-First - Local storage for progress and preferences

---

📊 Features Roadmap

• AI pronunciation evaluation
• Word-level audio synchronization
• Progress tracking
• Dark/Light themes
• Bilingual support (Arabic/English)
• Audio recording & playback
• iOS release
• User accounts & cloud sync
• Social features (share progress)
• Advanced statistics dashboard
• Bookmarking favorite verses
• Daily practice reminders

---

🤝 Contributing

We welcome contributions! If you'd like to contribute to ILearn Quran:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📄 Terms & Conditions

Purpose

This program is designed to help you learn the correct recitation of the Holy Quran. Do not use it for any other purpose.

Guarantees

• This application uses artificial intelligence to evaluate pronunciation
• We strive for maximum accuracy but provide no guarantees
• ILearnQuran.org is not a substitute for a qualified human teacher
• We welcome feedback, suggestions, and constructive criticism

Data Collection

• We do not collect any personal data
• With your permission, we collect anonymous audio recordings to train and evaluate the AI system

Subscription

• The use of this app is completely free of charge
• For investment inquiries, contact Dr. Ahmed Khorsi via Telegram

---

👥 Contact & Support

• Website: https://ilearnquran.org
• Founder: Dr. Ahmed Khorsi
• Email: Support via website contact form
• WhatsApp: Available through the app
• Telegram: Available through the app
• Messenger: Available through the app

---

📜 License

This project is free to use for educational and religious purposes. For commercial use or investment opportunities, please contact the project founder.

---

🙏 Acknowledgments

• Quran audio recitations from professional Qaris
• Arabic font: Nabi by Hossein Zahedi (ParsFont)
• UI fonts: El Messiri
• Icons: Material Design Icons
• Community feedback and testing

---

Made with ❤️ for the Muslim Ummah

"The best among you are those who learn the Quran and teach it." - Prophet Muhammad (ﷺ)

⬆ Back to Top