---

🌟 Life Solutions from the Holy Quran — AI Platform

An intelligent platform that helps you find Quranic guidance for any topic in your life, using Artificial Intelligence and Natural Language Processing.

---

✨ Features

• 🤖 AI-powered Q&A — Ask any question in Arabic and get Quranic guidance
• 📖 Quran Reader — Browse the Quran in Uthmani script with beautiful typography
• 🔬 Scientific Miracles — Explore scientific facts mentioned in the Quran
• 🗂️ 8 Life Categories — Medicine, Work, Science, Family, Self-Development, Law, Environment, General
• 📝 Tafsir Panel — Multiple scholar interpretations for each verse
• 🔍 Smart Search — Search through Quran verses by keywords
• 🌐 RTL Arabic UI — Full Arabic right-to-left interface

---

🏗️ Tech Stack

---

🚀 Quick Start

Prerequisites

• Node.js 18+
• Python 3.11+
• Docker & Docker Compose (optional)

Option 1: With Docker (Recommended)

# Clone the repository
git clone <repo-url>
cd Interpreting-the-Quran-using-artificial-intelligence

# Setup environment file, then edit .env and add your API keys
make setup

# Build all Docker images
make build

# Start all services
make up

Access:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs

Useful commands:

make logs    # stream logs from all services
make ps      # show container status
make down    # stop all services
make clean   # stop and delete all data
make help    # show all available commands

Option 2: Local Development

Frontend

cd frontend
npm install
npm run dev
# Access at http://localhost:3000

Backend

cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Start without database (demo mode)
uvicorn main:app --reload --port 8000

---

🚀 Deploy Frontend to GitHub Pages

1. In GitHub, open Settings → Pages and set Source to GitHub Actions.
2. Ensure the default branch is main (the deployment workflow triggers on pushes to main).
3. (Recommended) Add repository variable NEXT_PUBLIC_API_URL under Settings → Secrets and variables → Actions → Variables.
4. Push your changes to main; workflow .github/workflows/nextjs.yml will build and deploy frontend/out automatically.

Notes:

• For project pages (owner/repo), the frontend auto-uses /<repo> as base path during Pages export.
• For user/organization pages (<name>.github.io), it automatically deploys from root /.

---

🔑 Environment Variables

Copy .env.example to .env and fill in:

Note: The platform works in demo mode without any API keys — it returns pre-defined example responses.

---

📡 API Documentation

Ask Quran

POST /api/ask-quran
Content-Type: application/json

{
  "question": "كيف يرشدنا القرآن في موضوع الصحة؟",
  "category": "medicine"
}

Search Verses

GET /api/quran/search?q=الصبر

Get Categories

GET /api/categories

Get Scientific Miracles

GET /api/miracles

Full API docs available at /docs when backend is running.

---

📁 Project Structure

.
├── frontend/          # Next.js 14 + TypeScript + Tailwind CSS
│   └── src/
│       ├── app/       # App router pages
│       ├── components/ # React components
│       ├── lib/       # API client
│       └── types/     # TypeScript interfaces
├── backend/           # Python FastAPI
│   ├── routers/      # API route handlers
│   ├── models/       # SQLAlchemy models
│   ├── schemas/      # Pydantic schemas
│   ├── services/     # Business logic
│   └── data/         # Static data
├── ai-engine/         # AI/RAG pipeline
│   ├── quran_solver.py
│   ├── worker.py
│   ├── prompts/      # Domain-specific prompts
│   └── data/         # Miracle maps
├── database/          # SQL schema & seed data
├── docker-compose.yml
├── .env.example
└── README.md

---

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

---

⚠️ Disclaimer

هذه المنصة مخصصة للتوجيه العام والاستئناس فقط، وليست بديلاً عن الفتاوى الشرعية المعتمدة من العلماء المتخصصين. يُرجى الرجوع إلى أهل العلم الموثوقين في المسائل الدينية الدقيقة.

This platform is intended for general guidance only and is not a substitute for authoritative religious rulings from qualified scholars. Please consult certified Islamic scholars for precise religious matters.

---

📄 License

MIT License — See LICENSE for details.