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