From 1cef598fc5d6ee69e51cc4281bb0236377fc9c2a Mon Sep 17 00:00:00 2001
From: Hamza-Ayed <hamzaayedflutter@gmail.com>
Date: Thu, 23 Jul 2026 02:19:01 +0300
Subject: [PATCH] Update: 2026-07-23 02:19:01

---
 ...ystem_architecture_and_whitelabel_guide.md | 67 ++++++++++++++++++-
 1 file changed, 66 insertions(+), 1 deletion(-)

diff --git a/docs/system_architecture_and_whitelabel_guide.md b/docs/system_architecture_and_whitelabel_guide.md
index a596eee5..ef8ab6c7 100644
--- a/docs/system_architecture_and_whitelabel_guide.md
+++ b/docs/system_architecture_and_whitelabel_guide.md
@@ -39,7 +39,72 @@
 
 ---
 
-## 2. 📐 التوسع الأفقي وفصل السيرفرات (Horizontal Scaling & Architecture Decoupling)
+## 2. 📐 المعمارية الرسمية للنظام (System Architecture & Mermaid Diagram)
+
+يتكون نظام سيرو الحالي من بنية متكاملة عالية الأداء تعيش على سيرفر فيزيائي موحد، ومقسمة إلى حاويات دكر متخصصة مترابطة عبر شبكة دكر الداخلية:
+
+```mermaid
+graph TD
+    subgraph Clients["📱 تطبيقات الهواتف المحمولة (Clients)"]
+        RiderApp["تطبيق الراكب (Rider App)"]
+        DriverApp["تطبيق السائق (Driver App)"]
+    end
+
+    subgraph Server["🖥️ السيرفر الموحد (Docker Compose Infrastructure - siro)"]
+        subgraph NginxEntry["🌐 بوابة Nginx المركزية (Port 80 / 8080)"]
+            Nginx["Nginx Reverse Proxy"]
+        end
+
+        subgraph FPMContainer["⚡ حاوية المعالجة الرئيسية (PHP-FPM: php:9000)"]
+            BackendAPI["الباك إند الرئيسي (/var/www/backend)"]
+            PaymentAPI["سيرفر المدفوعات (/var/www/v2)"]
+            LocationAPI["سيرفر المواقع (/var/www/loction_server)"]
+        end
+
+        subgraph SocketDriver["🔌 حاوية سوكيت السائقين (socket_driver)"]
+            DriverWS["Workerman WS Server (Port 2020)"]
+            DriverInternalHTTP["مستقبل الإشعارات الداخلي (Port 2021)"]
+        end
+
+        subgraph SocketPassenger["🔌 حاوية سوكيت الركاب (socket_passenger)"]
+            PassengerWS["Workerman WS Server (Port 3030)"]
+            PassengerInternalHTTP["مستقبل الإشعارات الداخلي (Port 3031)"]
+        end
+
+        subgraph DataStorage["💾 قواعد البيانات والكاش المحلي"]
+            MySQL[("MySQL 8.4 Database")]
+            Redis[("Redis 7.2 GEO & Pub/Sub")]
+        end
+    end
+
+    %% اتصالات العملاء
+    RiderApp -- "HTTPS REST API" --> Nginx
+    DriverApp -- "HTTPS REST API" --> Nginx
+    DriverApp -- "WebSocket (Port 2020)" --> DriverWS
+    RiderApp -- "WebSocket (Port 3030)" --> PassengerWS
+
+    %% توجيه Nginx الداخلي (FastCGI)
+    Nginx -- "FastCGI /backend/..." --> BackendAPI
+    Nginx -- "FastCGI /v2/main/..." --> PaymentAPI
+    Nginx -- "FastCGI /loction_server/..." --> LocationAPI
+
+    %% الاتصالات الداخلية السريعة (Server-to-Server)
+    BackendAPI -- "cURL (http://nginx/v2/main/...)" --> PaymentAPI
+    BackendAPI -- "cURL (http://nginx/loction_server/driver_socket.php)" --> DriverInternalHTTP
+    LocationAPI -- "cURL (http://nginx/loction_server/passenger_socket.php)" --> PassengerInternalHTTP
+
+    %% قواعد البيانات والـ Redis
+    BackendAPI --> MySQL
+    PaymentAPI --> MySQL
+    BackendAPI --> Redis
+    LocationAPI --> Redis
+    DriverWS --> Redis
+    PassengerWS --> Redis
+```
+
+---
+
+### أ. التوسع الأفقي وفصل السيرفرات عند الحاجة (Horizontal Scaling)
 
 عند الحاجة للتوسع الضخم (أكثر من 50,000 رحلة في الساعة)، تم تصميم نظام سيرو ليدعم الفصل الفوري إلى **سيرفرين أو أكثر** عبر حاويات الدوكر المستقلة: