88 lines
4.0 KiB
Markdown
88 lines
4.0 KiB
Markdown
# 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.
|