"Verily, in the remembrance of Allah do hearts find rest." (Surah Ar-Ra'd, 13:28)
"Verily, in the remembrance of Allah do hearts find rest." — Surah Ar-Ra'd, 13:28
- Introduction
- The Motivation — A Ramadan Gift
- Live Demo
- Key Features
- Technical Architecture
- Installation & Local Setup
- Deployment Guide
- API Documentation
- Roadmap
- Contributing
- Code of Conduct
- License
- Author
- Acknowledgments
Reclaim Your Heart is a modern, interactive, and heart-centered web application designed to help Muslims and non-Muslims alike connect deeply with the Holy Quran and the beautiful teachings of Islam. Built with precision, care, and the latest full-stack technologies, this project serves as a digital companion — not just an information tool — for your spiritual journey.
In an age defined by digital noise, social distraction, and information overload, Reclaim Your Heart creates a quiet sanctuary — a beautifully designed, distraction-free environment where you can read, listen to, and understand the Word of Allah (ﷻ) with the aid of modern Artificial Intelligence.
Whether you are a lifelong Muslim seeking a richer Quranic experience, a new revert learning about the faith, a curious non-Muslim exploring Islam, or a parent wanting to share the Deen with their children — this platform was built for you.
This is not just an app. It is an act of worship, designed to help you draw closer to your Creator.
This project was born from the spiritual energy, reflection, and deep sense of purpose that defined the Holy Month of Ramazan.
Ramadan is not solely about abstaining from food and drink — it is a sacred time of reconnection, revelation, and renewal. It was in this blessed month that the Quran was first revealed to our Prophet Muhammad (ﷺ). Inspired by the spirit of giving, seeking knowledge, and earning continuous reward, this platform was built as a form of Sadaqah Jariyah (صدقة جارية) — an ongoing act of charity whose rewards continue even after its creator is gone.
The core philosophy that drove every decision was simple:
"To build an interface that feels crafted, not just coded."
To create a space where technology meets spirituality — where modern AI meets ancient wisdom — allowing users of all ages and backgrounds to explore the depths of Islamic knowledge in a respectful, authentic, and deeply engaging way.
Every function written, every component designed, and every line of TypeScript was penned with a single niyyah (intention):
To help others draw closer to their Creator.
The application is live and fully accessible at:
🔗 https://reclaimyourheart.vercel.app
No registration or account is required to explore the core features. Simply open the link and begin your journey.
The heart of the application is a robust, beautiful, and deeply thoughtful Quranic reading experience — designed with the same reverence one would bring to reading a physical Mushaf.
| Feature | Details |
|---|---|
| Arabic Script | High-quality Uthmani / Indo-Pak typography |
| English Translation | Sahih International |
| Urdu Translation | Jalandhry translation |
| Audio Recitation | World-renowned Qaris (e.g., Mishary Rashid Alafasy) |
| Verse-by-Verse Playback | For Tajweed practice and memorization |
| AI Tafseer | Click any Ayah for instant, in-depth explanation |
| Offline Mode | Download Surahs for offline reading |
Deep Dive — AI-Powered Tafseer:
When you tap any Ayah, the application generates a comprehensive explanation powered by Google Gemini. This includes:
- Tafseer (تفسير): A clear, accessible explanation of the verse's meaning, suitable for all audiences.
- Asbab al-Nuzul (أسباب النزول): The historical context and reason for the revelation of the verse.
- Fun Facts: Interesting and thought-provoking information related to the Surah or Ayah.
- Dynamic Quiz: A mini-quiz generated on-the-fly to test your comprehension and reinforce learning.
All generated Tafseer is cached locally using the browser's storage, meaning you can revisit explanations without an internet connection.
A friendly, knowledgeable, and safe conversational AI assistant powered by Google's Gemini models, designed to feel like a wise Muslim friend — not a cold search engine.
Example Questions You Can Ask:
"How do I pray Salah correctly?"
"What is the significance of Laylatul Qadr?"
"Explain the concept of Tawheed to a 5-year-old."
"What does Islam say about kindness to parents?"
"Who were the Companions of the Cave (Ashab al-Kahf)?"
Key Properties of the AI Companion:
- Safe & Sourced: Responses are grounded in authentic Islamic sources, maintaining a respectful, balanced, and gentle tone.
- Contextually Aware: The AI understands which Surah you are reading and can tailor responses accordingly.
- Non-Judgmental: Designed to welcome questions from all — Muslims and non-Muslims alike — without condescension.
- Markdown-Formatted Responses: Answers are well-structured and easy to read.
Consistent spiritual effort requires motivation. Reclaim Your Heart incorporates thoughtful, non-intrusive gamification to help you build and sustain a daily Quranic habit.
Hasanat Points System:
You earn Hasanat (حسنات — good deeds points) for every meaningful action on the platform:
| Action | Points Earned |
|---|---|
| Reading an Ayah | +1 Hasanah |
| Completing a Tafseer | +5 Hasanat |
| Finishing a Quiz | +10 Hasanat |
| Completing a full Surah | +25 Hasanat |
| Maintaining a daily streak | Bonus multiplier |
Badges & Achievements:
Unlock digital badges as milestones in your journey:
| Badge | Condition |
|---|---|
| 🌱 First Step | Complete your first full Surah |
| 📚 Scholar Junior | Read Tafseer for 10 Ayahs |
| 🔥 Consistent Reader | Maintain a 7-day reading streak |
| 🏅 Memorization Aspirant | Use audio playback 50 times |
| 🌙 Night of Power Seeker | Complete a session in the last 10 nights |
Progress Tracking:
Visual progress bars and indicators show your reading progress through the Quran — making the goal of completing the Quran feel achievable and celebrated.
A dedicated, welcoming section designed specifically for newcomers to the faith — whether non-Muslims, reverts, or young Muslims learning the basics.
The Five Pillars of Islam (أركان الإسلام):
Interactive, illustrated guides covering:
- Shahada — Declaration of Faith
- Salah — The Five Daily Prayers
- Zakat — Obligatory Charity
- Sawm — Fasting during Ramadan
- Hajj — The Pilgrimage to Makkah
The Six Articles of Faith (أركان الإيمان):
In-depth explanations of:
- Belief in Allah (ﷻ)
- Belief in the Angels
- Belief in the Divine Books
- Belief in the Prophets and Messengers
- Belief in the Day of Judgment
- Belief in Divine Decree (Qadr)
Science & Islam:
An illuminating section exploring the miraculous scientific facts mentioned in the Quran centuries before modern discovery, covering fields such as:
- Embryology — The stages of human creation
- Astronomy — The expanding universe
- Geology — The function of mountains
- Oceanography — Barriers between seas
| Layer | Technology |
|---|---|
| Frontend Framework | React 19 |
| Build Tool | Vite |
| Language | TypeScript (99.9%) |
| Styling | Tailwind CSS |
| Animations | Framer Motion |
| AI Engine | Google Gemini API |
| Backend | Node.js + Express (serverless) |
| Deployment | Vercel |
| Icons | Lucide React |
| HTTP Client | Axios |
| Technology | Version | Purpose |
|---|---|---|
| React | 19 | Core UI library |
| Vite | Latest | Ultra-fast build tooling |
| TypeScript | 5.x | Type safety across the entire codebase |
| Tailwind CSS | 3.x | Utility-first styling |
| Framer Motion | Latest | Smooth, production-grade animations |
| Lucide React | Latest | Beautiful, consistent iconography |
| React Context API | Built-in | Global state management |
| Local Storage | Browser API | Client-side persistence |
| Axios | Latest | Promise-based HTTP requests |
| Technology | Purpose |
|---|---|
| Node.js (v18+) | Server runtime |
| Express | API routing & local dev proxy |
| Google Gemini API | AI intelligence (Tafseer, Chat, Quiz) |
gemini-2.5-flash model |
Fast response generation |
gemini-pro model |
Complex multi-step reasoning |
| Vercel | Serverless function hosting & CDN |
ISLAM/
│
├── 📁 api/ # Serverless API functions (Vercel / Express)
│ ├── chat.ts # Conversational AI endpoint
│ ├── quiz.ts # Dynamic quiz generation endpoint
│ ├── surah-summary.ts # Surah overview generation endpoint
│ ├── tafseer-batch.ts # Batch Tafseer generation (offline download)
│ └── tafseer.ts # Single Ayah Tafseer generation endpoint
│
├── 📁 frontend/ # All frontend application source code
│ ├── 📁 public/ # Static assets (icons, manifest, images)
│ └── 📁 src/
│ ├── 📁 components/ # Reusable, composable UI components
│ │ ├── Buttons/
│ │ ├── Cards/
│ │ └── Modals/
│ ├── 📁 contexts/ # React Context providers
│ │ ├── GamificationContext.tsx # Points, badges, streaks
│ │ └── QuranContext.tsx # Active Surah/Ayah state
│ ├── 📁 pages/ # Top-level page components
│ │ ├── 📁 quran/ # Quran Reader module
│ │ │ ├── QuranReader.tsx # Core reader logic
│ │ │ ├── AyahCard.tsx # Individual Ayah display
│ │ │ └── TafseerPanel.tsx # AI Tafseer display
│ │ ├── Home.tsx # Landing page
│ │ └── DiscoverIslam.tsx # Discovery section
│ ├── App.tsx # Root application component & routing
│ ├── main.tsx # Application entry point
│ └── index.css # Global styles & Tailwind directives
│
├── 📁 scripts/ # Maintenance and utility scripts
├── .env.example # Template for environment configuration
├── .gitignore # Git ignore rules
├── LICENSE_NOTICE.md # Extended license information
├── metadata.json # Project metadata
├── package.json # Dependencies and npm scripts
├── package-lock.json # Dependency lock file
├── server.ts # Express server entry point (local dev)
├── tsconfig.json # TypeScript compiler configuration
├── vercel.json # Vercel deployment configuration
└── vite.config.ts # Vite bundler configuration
Follow these steps carefully to get a fully functional local development environment running on your machine.
Before cloning the repository, ensure you have the following installed:
| Tool | Minimum Version | Check Command |
|---|---|---|
| Node.js | v18.0.0 | node --version |
| npm | v9.0.0 | npm --version |
| Git | Any recent version | git --version |
You will also need a Google Gemini API Key to power the AI features. Get your free key at Google AI Studio — no credit card required.
Step 1 — Clone the Repository
git clone https://github.com/ibtesaamaslam/ISLAM.git
cd ISLAMStep 2 — Install All Dependencies
npm installThis installs all frontend and backend dependencies defined in package.json.
Step 3 — Configure Environment Variables
Copy the example environment file and populate it with your credentials:
cp .env.example .envOpen the newly created .env file in your editor and add your Google Gemini API key:
# .env — DO NOT commit this file to version control
GEMINI_API_KEY=your_google_gemini_api_key_here
⚠️ Security Notice: Never commit your.envfile to Git. It is already listed in.gitignoreto protect you.
Step 4 — Start the Development Server
npm run devThis command concurrently starts:
- The Express backend server (handles API proxying and serverless function simulation)
- The Vite frontend development server (with HMR — Hot Module Replacement)
Step 5 — Open the Application
Navigate to the following URL in your browser:
http://localhost:3000
The application will be fully functional, including AI-powered features, assuming your Gemini API key is correctly configured.
This project is architecturally optimized for seamless, zero-configuration deployment on Vercel.
Follow these steps for a production deployment in under 5 minutes:
-
Push your code to GitHub — Ensure your forked or cloned repository is pushed to your GitHub account.
-
Log in to Vercel — Visit vercel.com and sign in with your GitHub account.
-
Import the Project:
- Click "Add New..." → "Project"
- Select your
ISLAMrepository from the list
-
Configure Project Settings:
- Framework Preset: Vercel will auto-detect Vite — no changes needed
- Root Directory: Leave as
./(default) - Build Command:
npm run build(auto-detected) - Output Directory:
dist(auto-detected)
-
⚠️ Set Environment Variables (CRITICAL):- Expand the "Environment Variables" section before deploying
- Add the following:
Key Value GEMINI_API_KEYyour_google_gemini_api_key
-
Click "Deploy" — Vercel will build and deploy your application. You will receive a live URL within ~60 seconds.
| Variable | Description | Required | Where to Get |
|---|---|---|---|
GEMINI_API_KEY |
Google Gemini API key for all AI features | YES — Critical | Google AI Studio |
⚠️ Warning: WithoutGEMINI_API_KEY, the following features will not function in any environment: Tafseer generation, AI Chat companion, dynamic Quizzes, and Surah summaries.
The application communicates with a set of serverless functions located in the /api directory. These functions act as a secure proxy between the frontend and the Google Gemini API, ensuring your API key is never exposed to the client.
Generates a detailed, multi-part explanation for a specific Ayah using the Gemini AI model.
Request Body:
{
"surah": "Al-Fatiha",
"ayah": 1,
"arabic": "بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ",
"urduTranslation": "اللہ کے نام سے شروع جو بڑا مہربان نہایت رحم والا ہے",
"englishTranslation": "In the name of Allah, the Entirely Merciful, the Especially Merciful."
}Response Structure:
{
"explanation": "Detailed tafseer text...",
"history": "Asbab al-Nuzul — historical context...",
"funFact": "An interesting fact about this verse...",
"quiz": {
"question": "What does 'Bismillah' mean?",
"options": ["A", "B", "C", "D"],
"correctAnswer": "A"
}
}Handles the conversational AI interface. Accepts a user message and returns a markdown-formatted response.
Request Body:
{
"message": "How do I perform Wudu (ablution)?"
}Response:
{
"response": "**Wudu (Ablution)** is the Islamic ritual of purification...\n\n### Steps of Wudu:\n1. Make the intention (Niyyah)..."
}Generates a contextual overview of an entire Surah for the offline download feature.
Request Body:
{
"surahName": "Al-Baqarah",
"surahNumber": 2
}Response:
{
"summary": "Al-Baqarah, the longest chapter of the Quran...",
"themes": ["Guidance", "Covenant", "Prayer", "Fasting"],
"keyVerses": [2, 255, 285, 286]
}Generates Tafseer for all Ayahs of a Surah in a single request, used to pre-populate the offline cache when a user downloads a Surah.
Request Body:
{
"surahName": "Al-Ikhlas",
"surahNumber": 112,
"ayahs": [
{ "number": 1, "arabic": "...", "english": "...", "urdu": "..." }
]
}The following features and improvements are planned for future releases:
- v1.1 — Full 30-Juz Quran navigation with Juz/Hizb markers
- v1.2 — Word-by-word Arabic grammar and root analysis
- v1.3 — Prayer times integration based on user's geolocation
- v1.4 — 99 Names of Allah (Al-Asma ul-Husna) with audio and explanations
- v1.5 — Hadith explorer (Sahih Bukhari, Sahih Muslim)
- v2.0 — Mobile app (React Native)
- v2.1 — User accounts with cloud-synced progress
- v2.2 — Arabic reading and Tajweed lessons
Contributions are welcomed by invitation — from developers, designers, translators, and Islamic scholars. If you would like to contribute to this project, please reach out to the author via GitHub before submitting a pull request.
How to Contribute:
-
Fork the Repository
# Click the "Fork" button on GitHub, then clone your fork git clone https://github.com/YOUR_USERNAME/ISLAM.git -
Create a Feature Branch
git checkout -b feature/your-amazing-feature
-
Make Your Changes
- Follow the existing code style and naming conventions
- Write meaningful, descriptive commit messages
- Test your changes locally before submitting
-
Commit Your Changes
git commit -m "feat: add word-by-word Arabic analysis feature" -
Push to Your Branch
git push origin feature/your-amazing-feature
-
Open a Pull Request
- Go to the original repository on GitHub
- Click "New Pull Request"
- Provide a clear description of your changes and their purpose
Contribution Areas:
| Area | How You Can Help |
|---|---|
| 🛠️ Development | Bug fixes, new features, performance improvements |
| 🎨 Design | UI/UX improvements, accessibility, mobile responsiveness |
| 📝 Content | Tafseer accuracy review, translation corrections |
| 🌍 Translation | Adding new language support |
| 🐛 Testing | Finding and reporting bugs |
| 📚 Documentation | Improving this README or adding inline docs |
This project operates under the principle of Islamic Adab (أدب) — respectful, dignified, and courteous conduct in all interactions.
All contributors and users are expected to:
- Be respectful and inclusive toward people of all faiths, backgrounds, and levels of knowledge
- Engage in discussions with Hilm (forbearance) and good manners
- Avoid inflammatory, divisive, or offensive language
- Remember that the purpose of this project is to help people — not to debate or divide
Proprietary License — Commercial Use Restricted
Copyright (c) 2024 Ibtesaam Aslam
All Rights Reserved.
1. Grant of Limited License
This software and associated documentation files (the "Software") are provided for viewing, evaluation, and non-commercial educational purposes only.
You are granted a non-exclusive, non-transferable, revocable license to access and review the Software solely for personal reference.
2. Permitted Use
You may access and review the Software for personal learning, reference, and evaluation purposes only.
No other rights are granted unless explicitly stated in writing by the author.
3. Restrictions
Except as expressly permitted above, you are strictly prohibited from:
- Copying, reproducing, or redistributing the Software in whole or in part
- Modifying, adapting, reverse engineering, or creating derivative works
- Using the Software for commercial purposes, including but not limited to:
client work, freelance projects, SaaS, product development, or internal business use
- Selling, sublicensing, leasing, or monetizing the Software
- Removing or altering copyright notices
- Claiming the Software as your own
4. Commercial Use
Any commercial use of the Software requires prior written permission from the author.
Unauthorized commercial use constitutes a violation of this license and may result in legal action.
5. Ownership
All rights, title, and interest in and to the Software, including all intellectual property rights, remain the sole property of Ibtesaam Aslam.
This license does not grant any ownership rights.
6. Termination
This license is effective until terminated.
It will terminate automatically without notice if you violate any terms of this license. Upon termination, you must immediately cease all use of the Software and destroy any copies in your possession.
7. Disclaimer of Warranty
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 non-infringement.
8. Limitation of Liability
In no event shall the author be liable for any claim, damages, or other liability arising from, out of, or in connection with the Software or the use or other dealings in the Software.
9. Governing Law
This license shall be governed and construed in accordance with the applicable laws of the relevant jurisdiction.
By accessing or using this Software, you agree to be bound by the terms of this license.
This project is proprietary software — all rights reserved by the author. The source code is made visible on GitHub for transparency and portfolio purposes only. It is not open-source and may not be reused, forked for deployment, or redistributed without explicit written permission from the author.
See the full license terms in LICENSE_NOTICE.md.
This project stands on the shoulders of giants — both ancient scholars and modern open-source contributors. Deep gratitude is owed to:
| Contributor | Contribution |
|---|---|
| Al Quran Cloud API | Quran text, translations, and audio metadata |
| Islamic Network | Audio CDN for Quranic recitations |
| Google Gemini | AI intelligence powering Tafseer, Chat, and Quizzes |
| Vercel | Hosting, serverless functions, and global CDN |
| The Open-Source Community | React, Vite, Tailwind, Framer Motion, and all libraries used |
| The Scholars of Islam | Whose works of Tafseer and Hadith form the foundation of authentic knowledge |
"My Lord, increase me in knowledge." — Surah Ta-Ha, 20:114
Made with ❤️ and 🤲 during the blessed month of Ramazan.
May Allah (ﷻ) accept this as an act of worship and make it a source of benefit for the Ummah.
آمين يا رب العالمين
⭐ If this project benefits you, please consider starring the repository — it helps others discover it.
