An advanced web application that uses AI to analyze your emotions and provide contextually relevant Quranic verses, authentic supplications, and personalized support messages.

---

sakina.mp4

---

✨ Features

🧠 Intelligent Emotion Analysis

• AI-powered analysis using GPT-4o-mini
• Understands Arabic with various dialects
• 8 emotion categories with multi-level analysis
• Fallback local analysis when AI is unavailable
• Confidence scoring for accuracy measurement

📖 Authentic Islamic Content

• 50 carefully selected Quranic verses
• 30 authentic duas from Quran and Sunnah
• Verified tafsir based on Al-Tafsir Al-Muyassar and Ibn Kathir
• Professional English translations of meanings
• Documented sources for every dua (Sahih Bukhari, Muslim, etc.)

🎯 Smart Selection System

• Score-based selection (not purely random)
• User history tracking to avoid repetition
• Multi-emotion support (detects multiple feelings)
• 15-20 verse variety before repeating for same user
• Weighted categories for better matching

💬 Personalized Support Messages

• AI-generated messages tailored to specific emotions
• Islamic perspective with encouragement
• Simple, clear Arabic (Fusha) language
• 2-3 sentences for easy reading

---

🚀 Quick Start

Prerequisites

Node.js v18 or higher
npm or yarn
OpenAI API Key

Installation

# 1. Clone the repository
git clone https://github.com/yourusername/quran-emotions.git
cd quran-emotions

# 2. Install backend dependencies
npm install

# 3. Create environment file
touch .env

# 4. Add your OpenAI API key to .env
echo "OPENAI_API_KEY=sk-your-actual-key-here" >> .env
echo "PORT=3001" >> .env

# 5. Start the server
npm start

Server will run on http://localhost:3001

Frontend Setup (React App)

The React component is provided as a standalone file that can be:

• Used with Claude.ai Artifacts
• Integrated into your React application
• Deployed separately

---

🔑 Getting OpenAI API Key

1. Visit: https://platform.openai.com/api-keys
2. Click "Create new secret key"
3. Copy the key (starts with sk-)
4. Add it to .env file

Important: Use a regular Secret Key (sk-...), NOT a Project Key (sk-proj-...)

---

💰 Cost Estimation

GPT-4o-mini Pricing

• Per search: ~$0.001 - $0.002 (less than a penny!)
• 100 searches: ~$0.10 - $0.20 (very affordable)
• 1,000 searches: ~$1 - $2 (highly economical)

Breakdown per Request

• Emotion analysis: ~$0.0005 (short text input)
• Support message generation: ~$0.0008 (150-200 words output)
• Total per complete search: ~$0.0013

Note: GPT-4o-mini is 60x cheaper than GPT-4!

---

🎯 How It Works

1. Emotion Detection

User submits their emotional expression in Arabic. The system analyzes and classifies into 8 categories:

• gratitude - thankfulness, joy, happiness
• sadness - grief, sorrow, depression
• anxiety - worry, fear, stress
• anger - rage, frustration, annoyance
• despair - hopelessness, severe discouragement
• guidance - confusion, need for direction
• weak_faith - spiritual weakness, distance from Allah
• illness - physical pain, sickness

2. Content Selection Algorithm

Smart Scoring System:

// Example: User feels sadness and anxiety
Primary emotion: sadness (score: 100)
Secondary emotions: anxiety (score: 50)

// Each verse is scored based on category match
Verse 1 (categories: [sadness, despair]) → score: 100 × 10 = 1000
Verse 2 (categories: [anxiety, sadness]) → score: 100 × 10 + 50 × 10 = 1500
Verse 3 (categories: [gratitude]) → score: 0

// Top 5 verses selected, then random pick from them
// This ensures relevance while maintaining variety

No Repetition Logic:

• System tracks last 15 verses shown to each user
• Excludes them from next selection
• After 15 different verses, oldest ones become available again

3. AI-Generated Support

GPT-4o-mini generates a compassionate message that:

• Acknowledges the specific feeling
• Provides Islamic comfort and hope
• Encourages trust in Allah
• Offers practical spiritual guidance

---

📁 Project Structure

quran-emotions/
├── server.js                    # Main Express server
├── QuranEmotions.jsx           # React frontend component
├── package.json                # Dependencies
├── .env                        # Environment variables (not in git)
├── .env.example               # Environment template
└── README.md                  # This file

server.js contains:
├── verses[]                   # 50 Quranic verses with tafsir
├── duas[]                     # 30 authentic supplications
├── emotionCategories{}        # 8 categories with keywords
├── analyzeWithAI()           # GPT-4o-mini emotion analysis
├── analyzeEmotionLocally()   # Fallback keyword analysis
├── selectBestVerse()         # Smart verse selection
├── selectBestDua()           # Smart dua selection
├── generateSupportMessage()  # AI support message
└── POST /api/analyze         # Main API endpoint

---

🔧 API Documentation

POST /api/analyze

Request:

{
  "emotionText": "أشعر بالحزن والضيق"
}

Response:

{
  "analysis": {
    "category": "sadness",
    "categories": ["sadness", "anxiety"],
    "intensity": "high",
    "confidence": 85
  },
  "verse": {
    "arabic": "فَإِنَّ مَعَ الْعُسْرِ يُسْرًا",
    "english": "Indeed, with hardship comes ease.",
    "tafsir": "الله يطمئن عباده...",
    "surah": "الشرح",
    "verse": "5-6"
  },
  "dua": {
    "arabic": "اللَّهُمَّ إِنَّي أَعُوذُ بِكَ...",
    "english": "O Allah, I seek refuge...",
    "source": "صحيح البخاري (6363)"
  },
  "supportMessage": "نسأل الله أن يفرج همك...",
  "meta": {
    "processingTime": "1250ms",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

GET /api/health

Returns server status:

{
  "status": "healthy",
  "verses": 50,
  "duas": 30
}

GET /api/stats

Returns database statistics:

{
  "verses": 50,
  "duas": 30,
  "categories": ["sadness", "anxiety", ...]
}

---

🛡️ Security & Privacy

• ✅ OpenAI API key stored in .env (never exposed to client)
• ✅ Server-side API calls only
• ✅ No user data stored or logged
• ✅ No cookies or tracking
• ✅ CORS enabled for specified domains only
• ✅ Input validation and sanitization
• ✅ Rate limiting (can be configured)

---

📊 Technical Stack

Backend

• Node.js - JavaScript runtime
• Express - Web framework
• OpenAI API - GPT-4o-mini for AI analysis
• CORS - Cross-origin resource sharing
• dotenv - Environment variable management

Frontend

• React 18+ - UI library with hooks
• Lucide React - Icon library
• Tailwind CSS - Utility-first styling
• Google Fonts - Amiri & Cairo Arabic fonts

AI & Analysis

• GPT-4o-mini - Emotion analysis & support messages
• Structured JSON outputs - Reliable response format
• Fallback local analysis - Regex-based keyword matching
• Multi-emotion detection - Primary + secondary categories

---

🎨 Customization

Adding New Verses

// In server.js, add to verses array:
{
  id: 51,
  arabic: "...",
  english: "...",
  tafsir: "...",
  surah: "...",
  verse: "...",
  categories: ["sadness", "hope"],
  weight: 9
}

Adding New Duas

// In server.js, add to duas array:
{
  id: 31,
  arabic: "...",
  english: "...",
  source: "صحيح البخاري (1234)",
  categories: ["anxiety", "trust"],
  weight: 10
}

Adjusting Emotion Keywords

// In emotionCategories object:
sadness: {
  keywords: ["حزن", "حزين", "add-more-keywords"],
  weight: 1.2  // Higher = more importance
}

---

🧪 Testing

Manual Testing

# Test emotion analysis endpoint
curl -X POST http://localhost:3001/api/analyze \
  -H "Content-Type: application/json" \
  -d '{"emotionText": "أشعر بالحزن"}'

# Check server health
curl http://localhost:3001/api/health

# View statistics
curl http://localhost:3001/api/stats

Testing Different Emotions

// Test cases:
"فزت في المسابقة والحمد لله"; // → gratitude
"أشعر بالحزن الشديد"; // → sadness
"قلقان من المستقبل"; // → anxiety
"غضبان جداً من هذا الموقف"; // → anger
"يئست من كل شيء"; // → despair
"لا أعرف ماذا أفعل"; // → guidance
"بعدت عن الله وضعف إيماني"; // → weak_faith
"مريض وأشعر بألم"; // → illness

---

🙏 Acknowledgments

• Quranic verses from authentic Islamic sources
• Tafsir based on Al-Tafsir Al-Muyassar and Ibn Kathir
• Hadiths from Sahih Bukhari and Sahih Muslim
• OpenAI for GPT-4o-mini API
• Islamic scholars for their invaluable work

---

📧 Contact & Support

• GitHub Issues: For bugs and feature requests
• Discussions: For questions and ideas
• Email: your-email@example.com

---

📖 Islamic Content Sources

Quranic Verses

• Al-Tafsir Al-Muyassar (التفسير الميسر)
• Tafsir Ibn Kathir (تفسير ابن كثير)
• English translations reviewed by Islamic scholars

Authentic Duas

• Sahih al-Bukhari (صحيح البخاري)
• Sahih Muslim (صحيح مسلم)
• Sunan Abu Dawud (سنن أبي داود)
• Sunan al-Tirmidhi (سنن الترمذي)
• Sunan an-Nasa'i (سنن النسائي)
• Sunan Ibn Majah (سنن ابن ماجه)
• Quranic duas

---

⚠️ Disclaimer

This application is designed to provide spiritual comfort and Islamic guidance. It is not a substitute for:

• Professional mental health counseling
• Medical advice for physical or mental conditions
• Islamic scholarly consultation for complex religious matters

If you're experiencing severe emotional distress or mental health issues, please seek help from qualified professionals.

---

📊 Project Stats

• 50 Quranic Verses carefully selected
• 30 Authentic Duas with sources
• 8 Emotion Categories with 150+ keywords
• Smart Selection Algorithm with scoring
• No Repetition System (15-verse buffer)
• AI + Local Fallback for reliability
• Multi-language Support (Arabic + English)

---