# ILearn Quran 📖
**AI-Powered Quran Learning & Recitation Correction**
[](https://git.intelgx.com/Intelgx/IlearnQuranTesting/releases)
[](https://reactnative.dev/)
[](https://www.typescriptlang.org/)
[](LICENSE)
[Download APK](https://git.intelgx.com/Intelgx/IlearnQuranTesting/releases/download/IlearnQuran/IlearnQuran-release-v1.0.6-1.apk) • [Website](https://ilearnquran.org) • [Report Bug](https://github.com/anthropics/claude-code/issues)
---
## 📱 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](https://git.intelgx.com/Intelgx/IlearnQuranTesting/releases/download/IlearnQuran/IlearnQuran-release-v1.0.6-1.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](https://reactnative.dev/)** - Cross-platform mobile framework
- **[TypeScript 5.0.4](https://www.typescriptlang.org/)** - Type-safe JavaScript
- **[React 18.3.1](https://react.dev/)** - UI library
### State Management & Data
- **[Zustand 5.0.8](https://github.com/pmndrs/zustand)** - Lightweight state management with persistence
- **[Apollo Client 3.13.5](https://www.apollographql.com/docs/react/)** - GraphQL client
- **[AsyncStorage](https://react-native-async-storage.github.io/async-storage/)** - Local data persistence
### Navigation & UI
- **[React Navigation 7.x](https://reactnavigation.org/)** - Navigation library
- **[React Native Reanimated 3.17](https://docs.swmansion.com/react-native-reanimated/)** - Smooth animations
- **[React Native Vector Icons](https://github.com/oblador/react-native-vector-icons)** - Material Design icons
- **[React Native SVG](https://github.com/software-mansion/react-native-svg)** - SVG support
### Audio & Media
- **[react-native-audio-recorder-player](https://github.com/hyochan/react-native-audio-recorder-player)** - Audio recording & playback
- **[react-native-sound-player](https://github.com/johnsonsu/react-native-sound-player)** - Audio playback
- **[react-native-fast-image](https://github.com/DylanVann/react-native-fast-image)** - Optimized image loading
### Internationalization
- **[react-i18next](https://react.i18next.com/)** - 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
1. **Clone the repository**
```bash
git clone
cd ILQ
```
2. **Install dependencies**
```bash
bun install
# or
npm install
```
3. **Install iOS dependencies** (macOS only)
```bash
cd ios
pod install
cd ..
```
4. **Start Metro bundler**
```bash
bun start
# or
npm start
```
5. **Run the app**
**For Android:**
```bash
bun run android
# or
npm run android
```
**For iOS:**
```bash
bun run ios
# or
npm run ios
```
### Build Scripts
```bash
# 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
- [x] AI pronunciation evaluation
- [x] Word-level audio synchronization
- [x] Progress tracking
- [x] Dark/Light themes
- [x] Bilingual support (Arabic/English)
- [x] 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](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](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](#ilearn-quran-)