RUN.md

# 🚀 كيفية تشغيل HaramGuard

## المتطلبات الأساسية

1. Python 3.9+ مع virtual environment
2. Node.js 18+ (للفرونت إند)

---

## خطوات التشغيل

### 1️⃣ تشغيل Backend (FastAPI)

```bash
# الانتقال لمجلد backend
cd backend

# تفعيل البيئة الافتراضية (إن وجدت)
# إذا كان اسم البيئة HaramG:
source ../HaramG/bin/activate

# أو إنشاء بيئة جديدة:
# python -m venv venv
# source venv/bin/activate  # على macOS/Linux
# venv\Scripts\activate     # على Windows

# تثبيت المكتبات
pip install -r requirements.txt

# تشغيل الـ API Server
python api.py
```

**النتيجة:** سترى رسالة:
```
🚀 [API] HaramGuard REST API ready on http://0.0.0.0:8000
```

✅ Backend يعمل الآن على `http://127.0.0.1:8000`

---

### 2️⃣ تشغيل Frontend (React Dashboard)

**الطريقة الأسهل - استخدم script جاهز:**

```bash
cd frontend
./run-frontend.sh install  # أول مرة فقط
./run-frontend.sh dev      # لتشغيل الـ dev server
```

**أو يدوياً (في terminal جديد):**

```bash
# 1. تأكد أنك خارج virtual environment
deactivate  # إذا كنت داخل (HaramG)

# 2. أضف node إلى PATH
export PATH="/usr/local/bin:$PATH"

# 3. اذهب لمجلد frontend
cd frontend

# 4. ثبت المكتبات (أول مرة فقط)
npm install

# 5. شغل الـ dev server
npm run dev
```

**أو استخدم node مباشرة:**

```bash
cd frontend
/usr/local/bin/node /usr/local/lib/node_modules/npm/bin/npm-cli.js install
/usr/local/bin/node /usr/local/lib/node_modules/npm/bin/npm-cli.js run dev
```

**النتيجة:** سترى رسالة مثل:
```
  VITE v7.x.x  ready in xxx ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
```

✅ Frontend يعمل الآن على `http://localhost:5173`

---

### 3️⃣ فتح الداشبورد

افتح المتصفح واذهب إلى:
```
http://localhost:5173
```

سترى الداشبورد يعرض:
- 📹 فيديو مباشر مع detection
- 📊 Risk metrics (LOW/MEDIUM/HIGH)
- 🚨 Alerts والإجراءات المقترحة
- 🪞 ReflectionAgent statistics
- 🚪 حالة البوابات

---

## 🔧 استكشاف الأخطاء

### Backend لا يعمل؟

1. **تحقق من API Keys:**
   ```bash
   # افتح config.py وتأكد من وجود:
   # GROQ_API_KEY
   # ANTHROPIC_KEY (اختياري)
   ```

2. **تحقق من الفيديو:**
   ```bash
   # تأكد من وجود الملف:
   ls backend/hajj_real_video.mp4
   ```

3. **تحقق من المنافذ:**
   ```bash
   # تأكد أن port 8000 غير مستخدم:
   lsof -i :8000  # على macOS/Linux
   ```

### Frontend لا يتصل بالـ Backend؟

1. **تحقق من أن Backend يعمل:**
   ```bash
   curl http://127.0.0.1:8000/health
   # يجب أن يعيد: {"status":"ok","pipeline_ready":true}
   ```

2. **تحقق من CORS:** Backend مضبوط للسماح بجميع الأصول (`allow_origins=['*']`)

### npm لا يعمل (command not found أو env: node: No such file or directory)?

**المشكلة:** `node` غير موجود في PATH حتى بعد الخروج من virtual environment

**الحل الأسهل - استخدم script جاهز:**
```bash
cd frontend
./run-frontend.sh install
./run-frontend.sh dev
```

**الحلول اليدوية:**

1. **إضافة node إلى PATH ثم استخدام npm:**
   ```bash
   export PATH="/usr/local/bin:$PATH"
   cd frontend
   npm install
   npm run dev
   ```

2. **استخدام node مباشرة لتشغيل npm:**
   ```bash
   cd frontend
   /usr/local/bin/node /usr/local/lib/node_modules/npm/bin/npm-cli.js install
   /usr/local/bin/node /usr/local/lib/node_modules/npm/bin/npm-cli.js run dev
   ```

3. **إضافة PATH دائمياً في ~/.zshrc:**
   ```bash
   echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
   source ~/.zshrc
   ```

---

## 📝 ملاحظات

- **Backend** يعالج الفيديو في background thread
- **Frontend** يطلب state كل ثانية من `/api/realtime/state`
- البيانات تُحفظ تلقائياً في `backend/outputs/hajjflow_rt.db`

---

## 🧪 تشغيل Evaluation

```bash
cd backend
python evaluation.py
```

سيُنشئ:
- `outputs/plots/` - رسوم بيانية
- `outputs/eval/summary.json` - ملخص النتائج