reverse-dictionary/DEPLOY.md

# 🚀 النشر على Streamlit Community Cloud (مجاني)

التطبيق ينشر برابط عام. الملفات الكبيرة (النماذج + الـ embeddings) تُخزَّن على
**Hugging Face Hub** (لأن GitHub المجاني يسمح بـ 1GB فقط)، والكود على **GitHub**،
والتقييمات في **Supabase**.

```
GitHub (الكود)  →  Streamlit Cloud (يشغّل التطبيق)
                         │
                         ├─ ينزّل النماذج/الـ embeddings من  Hugging Face Hub
                         └─ يحفظ التقييمات في  Supabase
```

---

## 1) رفع الملفات الكبيرة إلى Hugging Face Hub

1. أنشئي حساب على <https://huggingface.co> (مجاني).
2. أنشئي **Access Token**: الصورة الشخصية → Settings → Access Tokens → New token
   (نوع **Write**). انسخيه.
3. في الطرفية (من مجلد `reverse-dictionary/backend`):
   ```bash
   export HF_TOKEN=hf_xxxxxxxx                       # التوكن من الخطوة 2
   export HF_DATA_REPO="USERNAME/reverse-dictionary-assets"   # بدّلي USERNAME
   .venv/bin/python scripts/upload_assets.py
   ```
4. بعد الرفع: افتحي المستودع على HF → **Settings** → اجعليه **Public**.

> هذا يرفع ~1.7GB مرة واحدة. المستودع العام لا يحتاج توكن عند التنزيل.

---

## 2) إعداد قاعدة التقييمات (DATABASE_URL)

أنشئي قاعدة على **SQLite Cloud** <https://sqlitecloud.io> واحصلي على رابط
الاتصال (يبدأ بـ `sqlitecloud://...?apikey=...`). الجداول تُنشأ تلقائيًا.
(يدعم الكود أيضًا Supabase عبر رابط `postgresql://`.)

---

## 3) رفع الكود على GitHub

من جذر المشروع (`semantic-search-system`):
```bash
git add -A
git commit -m "تجهيز للنشر على Streamlit Cloud"
git branch -M main
git remote add origin https://github.com/USERNAME/REPO.git   # بدّلي
git push -u origin main
```
> الملفات الكبيرة مُستثناة من Git (في `.gitignore`) — لا تُرفع على GitHub.

---

## 4) النشر على Streamlit Cloud

1. ادخلي <https://share.streamlit.io> وسجّلي دخول بحساب GitHub.
2. **Create app** → **Deploy a public app from GitHub**.
3. عبّئي:
   - **Repository:** مستودعك على GitHub.
   - **Branch:** `main`.
   - **Main file path:** `reverse-dictionary/frontend/streamlit_app.py`
   - **Advanced settings → Python version:** `3.11`
4. في **Advanced settings → Secrets**، الصقي:
   ```toml
   HF_DATA_REPO = "USERNAME/reverse-dictionary-assets"
   DATABASE_URL = "postgresql://postgres.xxxx:PASSWORD@...pooler.supabase.com:6543/postgres"
   ```
5. **Deploy!**

> أول تشغيل بطيء: يثبّت المكتبات ثم ينزّل ~1.7GB من HF Hub. الإقلاعات اللاحقة أسرع.

---

## 5) متابعة التقييمات

من لوحة **Supabase → Table Editor → ratings** تشوفين كل التقييمات وتصدّرينها CSV.

---

## ⚠️ ملاحظات
- **الذاكرة:** Streamlit Cloud المجاني محدود الذاكرة. خفّفنا الاستهلاك (نماذج
  مُكمَّمة + `mmap` للـ embeddings). لو ظهر خطأ ذاكرة (الرسالة "Oh no"/إعادة تشغيل
  متكررة)، الحل الأأمن هو **Hugging Face Spaces** (ذاكرته 16GB) بنفس هذي الملفات.
- **عند تحديث الكود:** ادفعي على GitHub، و Streamlit Cloud يعيد النشر تلقائيًا.
- **عند تحديث النماذج/الـ embeddings:** أعيدي تشغيل `upload_assets.py`، ثم
  أعيدي تشغيل التطبيق من لوحة Streamlit Cloud (Reboot) لإعادة التنزيل.