# المعمارية

المستند الإنجليزي الكامل: [architecture.md](../architecture.md)

## نظرة سريعة

المشروع مبني على ٣ طبقات رئيسية:

1. **FastAPI Gateway** — بوابة HTTP مع middleware للسجلات و CORS و request-id
2. **Pipeline / Agents** — المرحلتان 8 و 9 كوكلاء مستقلين + منسقين يجمعانهم
3. **LLM Router** — يوزّع كل مهمة على أفضل مزود مع سلسلة احتياط

كل الإعدادات تأتي من `.env` فقط عبر pydantic-settings. لا يوجد أي مفتاح مكتوب داخل الكود.

## هيكل المجلدات

```
ai-company-saudi/
├── core/                         # الأساس
│   ├── config/                   # الإعدادات + جدول التوجيه
│   ├── llm/                      # عملاء المزودين + الموجّه
│   ├── agents/                   # الوكيل الأساسي + المنسّق
│   └── prompts/                  # prompts وسكربتات مبيعات
├── auto_client_acquisition/      # المرحلة 8
├── autonomous_growth/            # المرحلة 9
├── integrations/                 # التكاملات الخارجية
├── api/                          # FastAPI
├── db/                           # قاعدة البيانات
├── tests/                        # الاختبارات
└── docs/                         # التوثيق
```

## قرارات التصميم الرئيسية

### ١. تحميل الإعدادات من `.env` فقط

كل الأسرار تُحمَّل في `core/config/settings.py` وتُغلَّف بـ `SecretStr`. لا يقرأ أي module متغير بيئة مباشرة.

### ٢. توجيه المهام مع احتياط

`core/config/models.py` يحدد جدول توجيه لكل `Task` إلى `Provider` رئيسي + سلسلة احتياط. الموجّه يجرّب الرئيسي ثم الاحتياطات بالترتيب.

### ٣. الوكلاء يشتركون في فئة أساسية

`BaseAgent` يوفر: سجل مهيكل مع سياق الوكيل، وصولاً للموجّه، ودالة قوية لتحليل JSON من خرج LLM.

### ٤. القمع كمنسِّق لا ككتلة واحدة

كل خطوة مغلّفة بـ try/except خاص. فشل خطوة لا يوقف القمع — يظهر في `warnings`.

### ٥. ثنائية اللغة من الصميم

- اكتشاف اللغة من الـ Unicode
- المهام العربية تُوجَّه لـ GLM افتراضياً
- سكربتات المبيعات و prompts متوفرة بالعربية والإنجليزية

### ٦. الأمن افتراضياً

- `.gitignore` يمنع `.env*` ماعدا `.env.example`
- pre-commit يشغّل gitleaks + detect-secrets
- CI يضيف trufflehog
- LinkedIn معطّل افتراضياً (التزام بالشروط)
- Docker يعمل بمستخدم غير جذري