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

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

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

---

📌 جدول المحتويات

1. نصيحة المنصة
2. الهيكل العام للنظام
3. التقنيات (Tech Stack)
4. قاعدة البيانات (Database Schema)
5. الـ APIs والتكاملات
6. شاشات التطبيق (User Flow)
7. نظام الإدارة (Admin Panel)
8. الجوانب القانونية مع YouTube
9. خطة التنفيذ المرحلية
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)

-- 👤 جدول المستخدمين (مدار من 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 (الأهم)

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

// مثال بسيط: عرض فيديو يوتيوب بشكل عمودي
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

---

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 في البداية)
• قول لي وابدأ.