Update README.md
This commit is contained in:
parent
50d47cd889
commit
a11c8e6004
376
README.md
376
README.md
@ -1,3 +1,375 @@
|
|||||||
# IlearnQuranTesting
|
# ILearn Quran 📖
|
||||||
|
|
||||||
This Repository For IlearnQuran Testers
|
<div align="center">
|
||||||
|
|
||||||
|
**AI-Powered Quran Learning & Recitation Correction**
|
||||||
|
|
||||||
|
[](https://git.intelgx.com/Intelgx/IlearnQuranTesting/releases)
|
||||||
|
[](https://reactnative.dev/)
|
||||||
|
[](https://www.typescriptlang.org/)
|
||||||
|
[](https://ilearnquran.org)
|
||||||
|
|
||||||
|
[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)
|
||||||
|
|
||||||
|
</div>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📱 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
|
||||||
|
- **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**
|
||||||
|
```bash
|
||||||
|
git clone <repository-url>
|
||||||
|
cd ILQ
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Install dependencies**
|
||||||
|
```bash
|
||||||
|
yarn install
|
||||||
|
# or
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Install iOS dependencies** (macOS only)
|
||||||
|
```bash
|
||||||
|
cd ios
|
||||||
|
pod install
|
||||||
|
cd ..
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **Start Metro bundler**
|
||||||
|
```bash
|
||||||
|
yarn start
|
||||||
|
# or
|
||||||
|
npm start
|
||||||
|
```
|
||||||
|
|
||||||
|
5. **Run the app**
|
||||||
|
|
||||||
|
**For Android:**
|
||||||
|
```bash
|
||||||
|
yarn android
|
||||||
|
# or
|
||||||
|
npm run android
|
||||||
|
```
|
||||||
|
|
||||||
|
**For iOS:**
|
||||||
|
```bash
|
||||||
|
yarn ios
|
||||||
|
# or
|
||||||
|
npm run ios
|
||||||
|
```
|
||||||
|
|
||||||
|
### Build Scripts
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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
|
||||||
|
|
||||||
|
- [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 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
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<div align="center">
|
||||||
|
|
||||||
|
**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-)
|
||||||
|
|
||||||
|
</div>
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user