Intelgx/IlearnQuranTesting

Fork 0

Lakhdar Aibout cbaa076fb1 Update README.md

2025-11-12 08:36:27 +00:00

13 KiB

Raw Blame History

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:

Download the APK file from the link above
Enable "Install from Unknown Sources" in your Android settings
Open the downloaded APK file
Follow the installation prompts
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

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
Bun (latest version) or npm
React Native CLI
Android Studio (for Android development)
Xcode (for iOS development, macOS only)

Installation

Clone the repository
```
git clone <repository-url>
cd ILQ
```
Install dependencies
```
bun install
# or
npm install
```
Install iOS dependencies (macOS only)
```
cd ios
pod install
cd ..
```
Start Metro bundler
```
bun start
# or
npm start
```

Run the app

For Android:

bun run android
# or
npm run android

For iOS:

bun run ios
# or
npm run ios

Build Scripts

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

# Testing
bun test               # Run tests
bun run lint           # Run ESLint

# Production
bun run build:android  # Build Android APK
bun run 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:

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
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 licensed under the MIT License - see the LICENSE file for details.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

🙏 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

13 KiB Raw Blame History