fingerprint-app/Project Implementation Documents/00-architecture.md

# 🌙 تطبيق "أثر" — الخطة المعمارية الكاملة

> تطبيق محتوى قصير هادف، مستوحى من تجربة TikTok لكن بهدف نافع: محتوى ديني وتذكير يومي يترك أثرًا بدل ما يسرق العمر.

---

## 📌 جدول المحتويات
1. [نصيحة المنصة](#1-نصيحة-المنصة)
2. [الهيكل العام للنظام](#2-الهيكل-العام-للنظام)
3. [التقنيات (Tech Stack)](#3-التقنيات-tech-stack)
4. [قاعدة البيانات (Database Schema)](#4-قاعدة-البيانات-database-schema)
5. [الـ APIs والتكاملات](#5-الـ-apis-والتكاملات)
6. [شاشات التطبيق (User Flow)](#6-شاشات-التطبيق-user-flow)
7. [نظام الإدارة (Admin Panel)](#7-نظام-الإدارة-admin-panel)
8. [الجوانب القانونية مع YouTube](#8-الجوانب-القانونية-مع-youtube)
9. [خطة التنفيذ المرحلية](#9-خطة-التنفيذ-المرحلية)
10. [التكلفة التقديرية](#10-التكلفة-التقديرية)

---

## 1. نصيحة المنصة

**ابدأ بـ Web App أولاً (PWA)** ثم انتقل للموبايل. الأسباب:

| السبب | التفصيل |
|------|---------|
| 🚀 سرعة الإطلاق | تبني نسخة واحدة وتجربها مع مستخدمين حقيقيين خلال أسابيع |
| 💰 توفير التكلفة | مفيش رسوم Apple Developer ($99/سنة) ولا Google Play ($25 مرة واحدة) في البداية |
| 🛡️ تجنب الرفض | متاجر التطبيقات صارمة جدًا مع التطبيقات اللي محتواها من YouTube |
| 📱 PWA قوي | المستخدم يقدر "يثبت" الموقع على شاشته زي التطبيق العادي |
| 🔄 تحديثات فورية | متحتاجش تنتظر موافقة المتجر على كل تحديث |

**بعد ما تثبت الفكرة وتجمع 1000+ مستخدم نشط**، نعمل نسخة React Native للموبايل (نفس الكود يشتغل Android + iOS).

---

## 2. الهيكل العام للنظام

```
┌─────────────────────────────────────────────────────────────┐
│                    👤 المستخدم (Browser/App)                │
└────────────────────────┬────────────────────────────────────┘
                         │
            ┌────────────▼────────────┐
            │   Frontend (Next.js)    │
            │  • Feed عمودي swipe     │
            │  • YouTube IFrame Player│
            │  • أزرار تفاعل          │
            │  • أذكار / مواقيت صلاة  │
            └────────────┬────────────┘
                         │
        ┌────────────────┼────────────────┐
        │                │                │
┌───────▼──────┐ ┌───────▼──────┐ ┌──────▼───────┐
│  Supabase    │ │ YouTube APIs │ │ External APIs│
│  (Backend)   │ │              │ │              │
│              │ │ • IFrame     │ │ • Aladhan    │
│ • PostgreSQL │ │ • Data API v3│ │  (مواقيت)    │
│ • Auth       │ │              │ │ • أذكار JSON │
│ • Storage    │ │              │ │              │
│ • Realtime   │ │              │ │              │
└──────────────┘ └──────────────┘ └──────────────┘
        ▲
        │
┌───────┴────────┐
│  Admin Panel   │  ← إنت/المشرفين تختاروا الفيديوهات
│  (Next.js)     │
└────────────────┘
```

---

## 3. التقنيات (Tech Stack)

### الواجهة الأمامية (Frontend)
- **Next.js 14** (React + SSR) — يدعم PWA بسهولة
- **TailwindCSS** — تصميم سريع ومريح
- **Framer Motion** — انتقالات سلسة بين الفيديوهات (swipe up/down)
- **react-youtube** — مكتبة جاهزة لتضمين IFrame Player

### الخادم (Backend) — كله في Supabase
- **PostgreSQL** — قاعدة بيانات قوية
- **Supabase Auth** — تسجيل دخول (Google, Email, Anonymous)
- **Row Level Security (RLS)** — أمان على مستوى الصف
- **Edge Functions** — لو محتاج منطق سيرفر مخصص
- **Realtime** — التعليقات تظهر فورًا

### خدمات خارجية
- **YouTube IFrame Player API** — لتشغيل الفيديوهات (مجاني، بدون حدود)
- **YouTube Data API v3** — لجلب بيانات الفيديو تلقائيًا (10k طلب/يوم مجانًا)
- **Aladhan API** — مواقيت الصلاة (مجاني)
- **Vercel** — استضافة الـ Frontend (مجاني للبداية)

### أدوات إضافية
- **OneSignal** — Push notifications مجانية (للتذكير اليومي)
- **PostHog / Plausible** — تحليلات تحترم الخصوصية

---

## 4. قاعدة البيانات (Database Schema)

```sql
-- 👤 جدول المستخدمين (مدار من Supabase Auth)
users (
  id           uuid PRIMARY KEY,
  email        text,
  display_name text,
  avatar_url   text,
  created_at   timestamp,
  -- إعدادات شخصية
  daily_goal_minutes int DEFAULT 10,
  notification_time  time,
  city               text  -- لمواقيت الصلاة
)

-- 🎥 جدول الفيديوهات (إنت تضيفها يدويًا أو من Admin Panel)
videos (
  id               uuid PRIMARY KEY,
  youtube_id       text UNIQUE NOT NULL,   -- مثلاً: dQw4w9WgXcQ
  title            text,
  description      text,
  duration_seconds int,
  channel_name     text,
  channel_id       text,
  thumbnail_url    text,
  category         text,    -- 'قرآن' / 'حديث' / 'سيرة' / 'تزكية'
  tags             text[],
  scholar_name     text,    -- اسم الشيخ/الداعية
  is_approved      boolean DEFAULT false,  -- المشرف يوافق قبل النشر
  added_by         uuid REFERENCES users(id),
  created_at       timestamp,
  -- إحصائيات داخلية (مش من يوتيوب)
  views_count      int DEFAULT 0,
  likes_count      int DEFAULT 0,
  saves_count      int DEFAULT 0
)

-- ❤️ إعجابات (محلية في تطبيقك)
likes (
  user_id    uuid REFERENCES users(id),
  video_id   uuid REFERENCES videos(id),
  created_at timestamp,
  PRIMARY KEY (user_id, video_id)
)

-- 🔖 محفوظات
saves (
  user_id    uuid REFERENCES users(id),
  video_id   uuid REFERENCES videos(id),
  collection text DEFAULT 'default',  -- مجموعات: 'للمراجعة' / 'مفضلة'
  created_at timestamp,
  PRIMARY KEY (user_id, video_id)
)

-- 💬 تعليقات (محلية في تطبيقك)
comments (
  id         uuid PRIMARY KEY,
  user_id    uuid REFERENCES users(id),
  video_id   uuid REFERENCES videos(id),
  content    text,
  parent_id  uuid REFERENCES comments(id),  -- للردود
  is_hidden  boolean DEFAULT false,  -- للإشراف
  created_at timestamp
)

-- 📊 سجل المشاهدات (لمعرفة الفيديوهات اللي شافها المستخدم)
watch_history (
  user_id            uuid REFERENCES users(id),
  video_id           uuid REFERENCES videos(id),
  watched_seconds    int,
  completed          boolean,
  watched_at         timestamp,
  PRIMARY KEY (user_id, video_id, watched_at)
)

-- 📿 الأذكار اليومية
daily_remembrance (
  id       uuid PRIMARY KEY,
  category text,    -- 'صباح' / 'مساء' / 'نوم' / 'استيقاظ'
  arabic   text,
  translit text,
  meaning  text,
  source   text,
  count    int DEFAULT 1
)

-- 🎯 الرحلات التعليمية (Playlists منظمة)
journeys (
  id          uuid PRIMARY KEY,
  title       text,            -- "رحلة في السيرة النبوية"
  description text,
  cover_url   text,
  video_ids   uuid[],          -- مرتبة بالترتيب
  difficulty  text,            -- 'مبتدئ' / 'متوسط' / 'متقدم'
  estimated_minutes int
)

-- 📈 تتبع تقدم الرحلات
journey_progress (
  user_id           uuid REFERENCES users(id),
  journey_id        uuid REFERENCES journeys(id),
  completed_video_ids uuid[],
  started_at        timestamp,
  completed_at      timestamp,
  PRIMARY KEY (user_id, journey_id)
)
```

---

## 5. الـ APIs والتكاملات

### 🎥 YouTube IFrame Player API (الأهم)

**ده اللي بيعرض الفيديو جوه تطبيقك.**

```javascript
// مثال بسيط: عرض فيديو يوتيوب بشكل عمودي
import YouTube from 'react-youtube';

function VideoPlayer({ youtubeId, onEnd }) {
  const opts = {
    height: '100%',
    width: '100%',
    playerVars: {
      autoplay: 1,
      controls: 0,        // إخفاء أزرار يوتيوب
      modestbranding: 1,  // تقليل علامة يوتيوب
      rel: 0,             // عدم اقتراح فيديوهات أخرى
      playsinline: 1,
    },
  };

  return (
    <YouTube
      videoId={youtubeId}
      opts={opts}
      onEnd={onEnd}  // ينتقل تلقائيًا للفيديو التالي
    />
  );
}
```

**ملاحظات مهمة:**
- ✅ مجاني تمامًا، بدون حد طلبات
- ✅ المشاهدات تتحسب لصاحب الفيديو (عدل)
- ⚠️ لازم يظهر زر "YouTube" صغير (شرط من جوجل)
- ⚠️ ما تقدرش تخفي الإعلانات لو الفيديو فيه إعلانات

### 📊 YouTube Data API v3 (اختياري لكن مفيد)

لجلب بيانات الفيديو تلقائيًا (لما تضيف فيديو جديد):
```
GET https://www.googleapis.com/youtube/v3/videos
  ?part=snippet,contentDetails,statistics
  &id=VIDEO_ID
  &key=YOUR_API_KEY
```

### 🕌 Aladhan API — مواقيت الصلاة
```
GET https://api.aladhan.com/v1/timingsByCity
  ?city=Cairo&country=Egypt&method=5
```

### 🔔 OneSignal — إشعارات
- إشعار يومي: "وقت أذكار الصباح 🌅"
- إشعار قبل الصلاة بـ 10 دقائق
- إشعار للفيديو الأسبوعي الجديد

---

## 6. شاشات التطبيق (User Flow)

```
1. 🚪 شاشة الترحيب
   ↓
2. 🔐 تسجيل دخول (Google / Email / Skip كضيف)
   ↓
3. 🎯 اختيار الاهتمامات (قرآن / تزكية / سيرة / فقه...)
   ↓
4. 🏠 الشاشة الرئيسية — Vertical Feed
   ┌─────────────────────────┐
   │                         │
   │     🎥 فيديو يلعب       │
   │     تلقائيًا            │
   │                         │
   │ [اسم الشيخ]      ❤️ 245 │
   │ [العنوان]        💬  12 │
   │ [#تزكية]         🔖     │
   │                  📤     │
   └─────────────────────────┘
        ↑ swipe up = التالي
        ↓ swipe down = السابق
   ↓
5. 📿 تبويبات سفلية:
   [🏠 الرئيسية] [🛤️ رحلات] [📿 أذكار] [🔖 محفوظاتي] [👤 ملفي]
```

### الشاشات التفصيلية:

| الشاشة | الوصف |
|--------|------|
| 🏠 **Feed الرئيسي** | فيديوهات عمودية، swipe للتنقل، autoplay |
| 🛤️ **الرحلات** | سلاسل منظمة (مثال: "10 أيام في رياض الصالحين") |
| 📿 **الأذكار** | أذكار الصباح/المساء بشكل تفاعلي مع عداد |
| 🕌 **مواقيت الصلاة** | حسب موقع المستخدم + تذكيرات |
| 🔖 **محفوظاتي** | الفيديوهات اللي حفظها المستخدم |
| 👤 **ملفي الشخصي** | إحصائيات وقت المشاهدة، الرحلات المكتملة، إعدادات |
| ⚙️ **الإعدادات** | الوضع المريح للعين، حد يومي للمشاهدة، إشعارات |

### 🌙 ميزات "ضد الإدمان" (مهمة جدًا)
- **حد يومي**: المستخدم يحدد 10/20/30 دقيقة، التطبيق يقفل بعدها
- **رسالة بعد كل 5 فيديوهات**: "خد نفس، اشرب مياه، صلِّ على النبي ﷺ"
- **بدون عداد متابعين/لايكات مبالغ فيه**: علشان مفيش "سباق شهرة"
- **بدون scroll لا نهائي ليلًا**: بعد الـ 11م يظهر تذكير بالنوم

---

## 7. نظام الإدارة (Admin Panel)

لوحة بسيطة عشان إنت (أو فريقك) تضيفوا/تراجعوا المحتوى:

### الصفحات:
1. **➕ إضافة فيديو** — لصق رابط يوتيوب، البيانات تتجلب تلقائيًا، تختار التصنيف، وافق
2. **📋 قائمة الفيديوهات** — بحث، فلترة، حذف، تعديل
3. **🛤️ إدارة الرحلات** — إنشاء سلاسل من فيديوهات موجودة
4. **💬 إشراف التعليقات** — مراجعة وإخفاء التعليقات غير المناسبة
5. **👥 المستخدمون** — إحصائيات، حظر إذا لزم
6. **📊 لوحة التحليلات** — الفيديوهات الأكثر مشاهدة، أوقات الذروة، إلخ

---

## 8. الجوانب القانونية مع YouTube

### ✅ ما هو مسموح (شروط الخدمة):
- استخدام **IFrame Player API** لتضمين الفيديوهات
- بناء واجهة مخصصة حول المُشغّل
- جمع إعجابات/تعليقات على تطبيقك (منفصلة عن يوتيوب)
- اقتراح فيديوهات للمستخدمين

### ❌ ما هو ممنوع:
- تحميل الفيديو وإعادة استضافته
- إخفاء علامة يوتيوب تمامًا
- تعطيل الإعلانات
- استخدام طرق غير رسمية (yt-dlp, scraping)

### 📋 شروط لازم تلتزم بيها:
1. **اربط بـ ToS و Privacy** الخاصين بيوتيوب
2. **خلي زر "Watch on YouTube" ظاهر**
3. **متغيرش/متعدلش الفيديو نفسه**
4. **احترم حقوق الناشرين** (لو ناشر طلب إزالة فيديوه، شيله)

📖 المرجع الرسمي: [YouTube API Services Terms of Service](https://developers.google.com/youtube/terms/api-services-terms-of-service)

---

## 9. خطة التنفيذ المرحلية

### 🥇 المرحلة 1 — MVP (4-6 أسابيع)
- [ ] إعداد Next.js + Supabase + Tailwind
- [ ] تصميم شاشة الفيديو العمودي مع swipe
- [ ] تكامل YouTube IFrame
- [ ] تسجيل دخول (Google + Anonymous)
- [ ] إعجاب + حفظ
- [ ] Admin Panel بسيط لإضافة 30-50 فيديو مختار بعناية
- [ ] نشر كـ PWA على Vercel

### 🥈 المرحلة 2 — تفعيل المجتمع (4 أسابيع)
- [ ] التعليقات + الردود
- [ ] الإشعارات (OneSignal)
- [ ] أذكار الصباح/المساء
- [ ] مواقيت الصلاة
- [ ] حد يومي للمشاهدة + رسائل التذكير

### 🥉 المرحلة 3 — الرحلات والنمو (6 أسابيع)
- [ ] نظام الرحلات (Journeys)
- [ ] تتبع التقدم والشارات
- [ ] مشاركة الفيديوهات على واتساب/تويتر
- [ ] تحسين خوارزمية الاقتراحات

### 🏆 المرحلة 4 — تطبيقات الموبايل (8 أسابيع)
- [ ] React Native (نفس الـ Backend)
- [ ] نشر على Google Play
- [ ] نشر على App Store
- [ ] Deep Linking

---

## 10. التكلفة التقديرية

### في البداية (أول 1000 مستخدم) — **مجاني تقريبًا** 🎉
| الخدمة | التكلفة |
|--------|---------|
| Vercel (Hosting) | $0 |
| Supabase (Free tier) | $0 |
| YouTube APIs | $0 |
| Aladhan API | $0 |
| OneSignal | $0 |
| Domain (.com) | ~$12/سنة |
| **الإجمالي** | **~$1/شهر** |

### بعد النمو (10,000+ مستخدم نشط)
| الخدمة | التكلفة |
|--------|---------|
| Vercel Pro | $20/شهر |
| Supabase Pro | $25/شهر |
| OneSignal Growth | $9/شهر |
| **الإجمالي** | **~$54/شهر** |

### لو حبيت تطبيقات موبايل:
- Apple Developer: $99/سنة
- Google Play: $25 (مرة واحدة)

---

## 🌟 خلاصة

إنت معاك فكرة قوية، والتنفيذ التقني فيها **ممكن جدًا** ومش معقد. الأهم من الكود هو:

1. **اختيار المحتوى بعناية** — أنت أو لجنة شرعية تختار قنوات موثوقة
2. **التصميم اللي يحترم وقت المستخدم** — مش يدمنه
3. **بناء مجتمع نواة** — 100 مستخدم متفاعل خير من 10,000 خامل

---

## 🚀 الخطوة التالية

تحب نبدأ نبني الـ **Prototype** فعليًا؟ أقدر أعمل:
- صفحة HTML/JS شغّالة تعرض فيديو يوتيوب بشكل عمودي زي تيكتوك
- مع أزرار إعجاب وحفظ (تشتغل بـ localStorage في البداية)
- قول لي وابدأ.