# 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 | التشغيل باستخدام دوكر
```bash
docker compose up --build -d
```
The API will be available at `http://localhost:3001/api`.
سيكون الـ API متاحاً على الرابط أعلاه.

### 4. Running Locally | التشغيل محلياً
```bash
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 | خارطة الطريق المستقبلية

1. **Multi-tenancy**: Support for multiple users and organizations.
2. **Database Persistence**: Saving historical data using PostgreSQL & Prisma.
3. **Background Jobs**: Periodic data syncing using BullJS.
4. **AI Insights**: Integration with LLMs (like Gemini) for deep marketing recommendations.
5. **Google & TikTok**: Adding more ad platforms using the established normalization layer.