RUN.md

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

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

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

---

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

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

# الانتقال لمجلد 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 جاهز:

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

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

# 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 مباشرة:

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:

   # افتح config.py وتأكد من وجود:
   # GROQ_API_KEY
   # ANTHROPIC_KEY (اختياري)
   

2. تحقق من الفيديو:

   # تأكد من وجود الملف:
   ls backend/hajj_real_video.mp4
   

3. تحقق من المنافذ:

   # تأكد أن port 8000 غير مستخدم:
   lsof -i :8000  # على macOS/Linux
   

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

1. تحقق من أن Backend يعمل:

   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 جاهز:

cd frontend
./run-frontend.sh install
./run-frontend.sh dev

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

1. إضافة node إلى PATH ثم استخدام npm:

   export PATH="/usr/local/bin:$PATH"
   cd frontend
   npm install
   npm run dev
   

2. استخدام node مباشرة لتشغيل npm:

   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:

   echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
   source ~/.zshrc
   

---

📝 ملاحظات

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

---

🧪 تشغيل Evaluation

cd backend
python evaluation.py

سيُنشئ:

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