tripz-llc/docs/01-architecture.md

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.
2. API Gateway (NestJS): كل طلب يمر بـ Guards ثم Interceptors. تفاصيل: 02-backend-plan.
3. الطبقة الحية (Socket.IO): موقع السائق، العروض، التتبع، لوحة dispatch. تفاصيل: 09-realtime.
4. التخزين: PostgreSQL/PostGIS (مصدر الحقيقة) + Redis (حالة لحظية) + BullMQ (مهام غير متزامنة).
5. الخرائط: انطلق ذاتي (بلاطات/ترميز/توجيه). طبقة تجريد تسمح بتبديل المزوّد.
6. التكاملات: محوّلات (Adapters) يفعّلها الـ country pack. تفاصيل: 07-integrations.

تدفق نموذجي — «طلب رحلة»

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 يسجّل كل رحلة مكتملة → يغذّي الفوترة.
• العزل بين المستأجرين: tenant_id إلزامي في كل استعلام عبر نطاق على مستوى الـ Repository. تفاصيل: 06-tenant-model.

← السابق: 00-overview · التالي: 02-backend-plan