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.

4.0 KiB Raw Permalink Blame History