TrendHawk

1. الفكرة العامة

TrendHawk هو مركز تحكّم ذكي لتحليل الترندات والمنتجات والمنافسين. الخلفية (Backend) مبنية بـ FastAPI وتقدم خدمات REST متعددة، والواجهة تعتمد على Streamlit (مودرن دارك ثيم) لعرض كل المعلومات بطريقة احترافية وسهلة الفهم. كل شيء مترابط: Streamlit يطلب بيانات من FastAPI، والـ API يولّد بيانات شبه حقيقية (حالياً) ويمكن لاحقاً ربطه بمصادر حقيقية أو نماذج AI.

2. بنية فولدرات المشروع

backend/: يحتوي كل ملفات FastAPI.

app/main.py: يخلق التطبيق ويضمّن الـ routers (chat, trends, analyze, competitors, reports, products).

app/api/v1/endpoints/: كل ملف فيه مجموعة API (مثلاً trends.py, products.py, chat.py…).

app/services/: منطق العمل لكل خدمة (trend_service.py, chat_service.py, …).

frontend/: موجود لكن يتم تجاهله حالياً.

streamlit_app.py: الواجهة العملية الحالية.

وثائق المساعدة مثل APPLICATION_READY.md, QUICK_START.md.

3. أهم مكتبات وتقنيات

FastAPI (خلفية) + Uvicorn للتشغيل.

Pydantic للنماذج والتحقق.

Streamlit للواجهة.

Requests لربط Streamlit بالـ API.

مكتبات إضافية في Streamlit: Charts، Tabs، Chat components.

4. الـ APIs المستخدمة

جميعها تحت http://localhost:8000/api...:

GET /trends/, /trends/hot, /trends/search/{keyword}: بيانات الترندات (عربي/إنجليزي)، مع نقاط نمو وروابط TikTok/Instagram.

GET /products/, /products/categories: منتجات رقمية ومادية، متاجر مفضلة (Amazon، Etsy، ...)، هامش ربح، نصائح.

POST /chat/message: المساعد الذكي. يفهم الأسئلة العامة أو يستقبل question_id من الأسئلة الجاهزة.

GET /chat/questions: لإظهار فئات الأسئلة في Streamlit.

POST /analyze/url, /analyze/text, /analyze/competitors, /analyze/content-ideas: المود التحليلي (روابط، نصوص، منافسين، أفكار محتوى).

GET /reports/, POST /reports/generate: التقارير.

POST /competitors/: خطة تحليل منافس.

5. منطق الخدمات المهمة

TrendService: يولّد ترندات واقعية (أسماء، أرقام، روابط). نفس الخدمة تستخدم أيضاً لاستخراج منتجات ترند في التجارة الإلكترونية مع منصة مناسبة و tips جاهزة.

ChatService:

يحدد لغة/نية السؤال (عربي فصيح، عامية، إنجليزي).

عند وجود question_id يسترجع رد ديناميكي (مثلاً “شو الترندات الضاربة اليوم؟” -> Top trends مع روابط TikTok/Reels).

الأسئلة الحرة تمر على intent detection وإذا كان intent معروف (ترندات، منتجات، محتوى، منافسين، سوق) يستدعي handler مناسب ويرجع رد مكتوب بأسلوب إنساني مع بيانات حديثة.

fallback ذكي يعطي snapshot عن آخر ترند وآخر منتج ساخن.

6. واجهة Streamlit (Modern Dark Theme)

Sidebar: اختيار الصفحة + رابط الـ API.

Dashboard: حالة السيرفر، أقوى ترند، بطاقة “كيف تستخدم TrendHawk”.

استكشاف الترندات: فلاتر (منصة، نوع، إطار زمني)، بطاقات ترند مع شارات نمو وروابط مباشرة.

سوق المنتجات: فلاتر فئوية، الترتيب حسب اليوم/الأسبوع/الشهر، بطاقات تحتوي هامش الربح، نمو الطلب، روابط المتاجر الحقيقية، نصائح للتاجر.

المحلل الذكي: تبويبات لتحليل رابط/نص/أفكار محتوى، تعرض النتائج كنص منسق.

المنافسون: إرسال دومين واستخراج نقاط قوة/ضعف.

التقارير: عرض التقارير المتولدة، وزر “ولّد تقرير” يبين استدعاء الـ API.

المساعد الذكي: يعرض فئات الأسئلة الجاهزة (ترندات، منتجات، إستراتيجيات). أي زر يستدعي /chat/message ويظهر الرد داخل نفس نافذة الشات مع القدرة على كتابة سؤال حر. الردود جاهزة بنبرة بشرية.

7. كيفية التشغيل

Backend:

cd "C:\our project\TrendHawk\backend" .\venv\Scripts\Activate.ps1 uvicorn app.main:app --reload --port 8000

واجهة Streamlit:

cd "C:\our project\TrendHawk" streamlit run streamlit_app.py

(مع ضبط API_BASE_URL إذا لزم)

8. ما الذي تم إنجازه حتى الآن؟

شات شبه AI يرد بأسلوب طبيعي، مع بيانات “تبدو حقيقية” تتغير باستمرار.

صفحات ترندات/منتجات/تقارير كاملة التصميم بالداكن الحديث.

نظام تحليل للمحتوى/النصوص/المنافسين، وتقارير تتولّد من الـ API.

إعداد كامل لتوسيع المشروع لاحقاً (ربط API حقيقية، LLM فعلي، أو تخزين DB).

9. ما الذي يمكن ذكره في العرض؟

المقاربة التقنية: FastAPI + Streamlit + REST.

مرونة النظام: معمارية services/routers تجعل إضافة مصادر حقيقية أو AI سهلة لاحقاً.

التجربة: UI داكن، بطاقات أنيقة، روابط مباشرة، ومساعد تفاعلي.

الخطوات القادمة: ربط بمصدر بيانات حقيقي، استخدام LLM فعلي، بناء dashboard إضافية (مثلاً تنبيهات، تخزين المستخدمين…).

بهذا الشكل، تقدر تعرض المشروع كمركز ذكاء رقمي شبه واقعي جاهز لإطلاق MVP أو Demo مباشر.