SaaS Meta Ads Analytics Backend — منصة تحليلات إعلانات ميتا
[Arabic Version Below | النسخة العربية في الأسفل]
🇺🇸 English Overview
Welcome to the SaaS Meta Ads Analytics Backend. This project is a production-ready foundation for a marketing analytics platform. It is built with NestJS and Docker, focusing on scalability, clean architecture, and ease of use.
Features
- Meta Ads Integration: Direct connection to Meta Marketing API.
- Data Normalization: Transforms complex external data into a simple internal schema.
- Smart Analytics: Automated calculation of CTR, CPC, CPM and generation of insights.
- Docker Ready: Standardized environment for local development and server deployment.
- Swagger Docs: Fully documented REST API.
- Bilingual Code: Arabic & English comments throughout the codebase.
🇸🇦 نظرة عامة بالعربية
مرحباً بك في الخلفية البرمجية لمنصة تحليلات إعلانات ميتا. هذا المشروع هو حجر أساس جاهز للإنتاج لمنصة تحليلات تسويقية. تم بناؤه باستخدام NestJS و Docker، مع التركيز على قابليتة التوسع، الهندسة النظيفة، وسهولة الاستخدام.
المميزات
- التكامل مع إعلانات ميتا: اتصال مباشر مع واجهة ميتا للتسويق (Meta Marketing API).
- توحيد البيانات (Normalization): تحويل البيانات الخارجية المعقدة إلى هيكل داخلي بسيط.
- تحليلات ذكية: حساب تلقائي لمقاييس CTR و CPC و CPM وتوليد رؤى ذكية.
- جاهز للدوكر: بيئة موحدة للتطوير المحلي والنشر على الخادم.
- توثيق Swagger: واجهة برمجة تطبيقات (REST API) موثقة بالكامل.
- كود ثنائي اللغة: تعليقات عربية وانجليزية في جميع أنحاء الكود.
🚀 Getting Started | ابدأ من هنا
1. Prerequisites | المتطلبات الأساسية
- Node.js LTS (v20+)
- Docker & Docker Compose (Recommended | مستحسن)
2. Environment Setup | إعداد البيئة
Copy .env.example to .env and fill in your Meta credentials.
قم بنسخ ملف .env.example إلى .env وقم بتعبئة بيانات ميتا الخاصة بك.
3. Running with Docker | التشغيل باستخدام دوكر
docker compose up --build -d
The API will be available at http://localhost:3001/api.
سيكون الـ API متاحاً على الرابط أعلاه.
4. Running Locally | التشغيل محلياً
npm install
npm run start:dev
📂 Architecture | هيكلية المشروع
src/config: Environment validation and configuration logic.src/common: Global filters (errors) and interceptors (logging).src/health: Service monitoring endpoint.src/meta-ads: Core logic for fetching and normalizing Meta API data.src/analytics: Smart engine for metric analysis and insight generation.
📑 API Endpoints | نقاط نهاية الـ API
| Path | Method | Description |
|---|---|---|
/api/health |
GET | Check service status |
/api/meta/insights |
POST | Fetch raw normalized Meta data |
/api/analyze/meta |
POST | Fetch Meta data + Smart analysis |
/api/analyze/sample |
POST | Test analysis with sample data |
🛠 Future Roadmap | خارطة الطريق المستقبلية
- Multi-tenancy: Support for multiple users and organizations.
- Database Persistence: Saving historical data using PostgreSQL & Prisma.
- Background Jobs: Periodic data syncing using BullJS.
- AI Insights: Integration with LLMs (like Gemini) for deep marketing recommendations.
- Google & TikTok: Adding more ad platforms using the established normalization layer.