# 01 — البنية العامة

## المخطط العلوي

```
┌─────────────────────────────────────────────────────────────────┐
│                        عملاء التطبيق (Flutter)                     │
│   راكب        سائق         مشغّل (Dispatch)      إدارة (Web/Admin)  │
└──────┬──────────┬──────────────┬────────────────────┬────────────┘
       │ REST     │ REST + WS    │ REST + WS          │ REST
       ▼          ▼              ▼                    ▼
┌─────────────────────────────────────────────────────────────────┐
│                      API Gateway / NestJS                         │
│  Guards (Auth, Tenant, Roles) → Interceptors (Usage, Logging)     │
│  ┌──────────┬──────────┬──────────┬──────────┬──────────────┐    │
│  │ auth     │ trips    │ tariff   │ dispatch │ billing      │    │
│  │ tenants  │ drivers  │ payments │ maps     │ notifications│    │
│  └──────────┴──────────┴──────────┴──────────┴──────────────┘    │
│               WebSocket Gateway (Socket.IO)                       │
└──────┬─────────────────┬────────────────┬───────────────┬────────┘
       ▼                 ▼                ▼               ▼
┌────────────┐   ┌──────────────┐   ┌──────────┐   ┌──────────────┐
│ PostgreSQL │   │    Redis     │   │  انطلق    │   │  BullMQ       │
│ + PostGIS  │   │ presence/    │   │ Maps:     │   │ (jobs queue) │
│ tenant_id  │   │ matching/    │   │ Martin/   │   │ إشعارات/تقارير│
│ everywhere │   │ pub-sub      │   │ geocode/  │   │ /تسويات       │
└────────────┘   └──────────────┘   │ routing   │   └──────────────┘
                                     └──────────┘
       ▲
       │ Adapters (country pack يفعّلها)
┌──────┴───────────────────────────────────────────────────────────┐
│ الدفع (كاش/CliQ/زين/سيرياتيل/MTN/Binance) · SMS/OTP · واجهة المنظّم │
└──────────────────────────────────────────────────────────────────┘
```

## الطبقات (من الخارج للداخل)
1. **العملاء (Flutter):** 4 واجهات من كود موحّد + flavor لكل مستأجر. تفاصيل: [03-mobile-plan](03-mobile-plan.md).
2. **API Gateway (NestJS):** كل طلب يمر بـ Guards ثم Interceptors. تفاصيل: [02-backend-plan](02-backend-plan.md).
3. **الطبقة الحية (Socket.IO):** موقع السائق، العروض، التتبع، لوحة dispatch. تفاصيل: [09-realtime](09-realtime.md).
4. **التخزين:** PostgreSQL/PostGIS (مصدر الحقيقة) + Redis (حالة لحظية) + BullMQ (مهام غير متزامنة).
5. **الخرائط:** انطلق ذاتي (بلاطات/ترميز/توجيه). طبقة تجريد تسمح بتبديل المزوّد.
6. **التكاملات:** محوّلات (Adapters) يفعّلها الـ country pack. تفاصيل: [07-integrations](07-integrations.md).

## تدفق نموذجي — «طلب رحلة»
```
1. الراكب يطلب  → POST /trips  (Guard: Auth+Tenant → Interceptor: Usage++)
2. الباك إند   → tariff.quote()  يحسب السعر المقفول
3. الباك إند   → matching (Redis GEO) يجد أقرب سائقين مؤهلين
4. Socket      → يبث العرض للسائقين المرشحين (Bloc عرض السائق)
5. سائق يقبل   → trip.assign()  → Postgres + Socket للراكب (Bloc دورة الرحلة)
6. تتبع حي     → Socket كل 3–5 ثوانٍ (موقع السائق مجمّع)
7. إنهاء       → tariff.finalize()  → دفع كاش  → تقييم
8. BullMQ      → تسوية GMV + قياس usage للفوترة الشهرية
```

## حدود المسؤولية
- **مصدر الحقيقة الدائم:** PostgreSQL فقط. Redis حالة عابرة قابلة لإعادة البناء.
- **قياس الاستخدام (Usage):** Interceptor يسجّل كل رحلة مكتملة → يغذّي [الفوترة](05-pricing-billing.md).
- **العزل بين المستأجرين:** `tenant_id` إلزامي في كل استعلام عبر نطاق على مستوى الـ Repository. تفاصيل: [06-tenant-model](06-tenant-model.md).

← السابق: [00-overview](00-overview.md) · التالي: [02-backend-plan](02-backend-plan.md)