Hamza/Siro
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update: 2026-06-10 18:11:50

Browse Source
This commit is contained in:
Hamza-Ayed
2026-06-10 18:11:50 +03:00
parent a0473a8b0f
commit 977adfe99d
27 changed files with 3946 additions and 206 deletions
Download Patch File Download Diff File Expand all files Collapse all files

253
knowledge/SYSTEM_ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,253 @@
# SYSTEM_ARCHITECTURE.md — Full System Architecture
## Layer Architecture
```
┌────────────────────────────────────────────────────────────────────┐
│ UI LAYER (Flutter Widgets) │
│ │
│ siro_rider: │
│ Routes: /, /shareApp, /wallet, /profile, /contactSupport │
│ Screens: SplashScreen, LoginPage, MapPagePassenger, Wallet, etc. │
│ │
│ siro_driver: │
│ Routes: /, /OrderRequestPage, /passenger-location-map │
│ Screens: SplashScreen, LoginPage, PassengerLocationMapPage, etc. │
│ │
│ siro_admin: │
│ Routes: /login, /admin/dashboard, /admin/captain, /admin/rides │
│ │
│ siro_service: │
│ Service agent app for driver registration & management │
└──────────────────────┬─────────────────────────────────────────────┘
│ GetX (Get.find, Get.put, Obx)
┌──────────────────────┴─────────────────────────────────────────────┐
│ STATE LAYER (GetX Controllers) │
│ │
│ Controllers are registered in: AppBindings (permanent) │
│ │
│ Rider: │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ MapEngineController → Map rendering, camera, markers │ │
│ │ MapSocketController → WebSocket lifecycle management │ │
│ │ RideLifecycleController → Ride state machine (RideState enum)│ │
│ │ LocationSearchController → Place search & autocomplete │ │
│ │ NearbyDriversController → Nearby driver list management │ │
│ │ UiInteractionsController → Bottom sheets, dialogs │ │
│ │ LoginController → Auth & JWT management │ │
│ │ PaymentController → Payment processing │ │
│ │ SplashScreenController → App init & auth check │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ Driver: │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ HomeCaptainController → Online/offline, ride management │ │
│ │ MapSocketController → WebSocket ride offers │ │
│ │ NavigationController → Turn-by-turn navigation │ │
│ │ BackgroundServiceHelper → Android foreground service │ │
│ │ LocationController → GPS tracking │ │
│ └─────────────────────────────────────────────────────────────┘ │
└──────────────────────┬─────────────────────────────────────────────┘
│ Dependency Injection via GetX
┌──────────────────────┴─────────────────────────────────────────────┐
│ REPOSITORY LAYER (CRUD + Services) │
│ │
│ CRUD class (siro_rider/lib/controller/functions/crud.dart) │
│ - post() → Main API POST with JWT + Device-FP headers │
│ - get() → API GET (POST method) with retry logic │
│ - postWallet() → Payment server POST with JWT + HMAC + FP │
│ - getWallet() → Payment server GET with JWT + HMAC + FP │
│ - sendWhatsAppAuth() → WhatsApp OTP delivery │
│ - getAgoraToken() → Agora voice/video call tokens │
│ - getLlama() → Llama AI data extraction │
│ - getChatGPT() → OpenAI GPT data extraction │
│ - arabicTextExtractByVisionAndAI() → Azure OCR │
│ - getGoogleApi() → Google Maps API wrapper │
│ - getHereMap() → Here Maps API wrapper │
│ - getMapSaas()/postMapSaas() → Custom map service │
│ - sendVerificationRequest() → Twilio verification │
│ - postPayMob() → PayMob payment gateway │
│ │
│ NetGuard (network/connection_check.dart) → Internet monitoring │
└──────────────────────┬─────────────────────────────────────────────┘
│ HTTP Calls
┌──────────────────────┴─────────────────────────────────────────────┐
│ SERVICE LAYER (PHP Backend) │
│ │
│ Main API: api.intaleq.xyz/intaleq_v3 │
│ Ride API: rides.intaleq.xyz/intaleq │
│ Location API: location.intaleq.xyz/intaleq/ride/location │
│ Payment API: walletintaleq.intaleq.xyz/v2/main │
│ Map SaaS: map-saas.intaleqapp.com/api │
│ OSRM Route: routec.intaleq.xyz / routesy.intaleq.xyz │
└──────────────────────┬─────────────────────────────────────────────┘
│ MySQL + WebSocket
┌──────────────────────┴─────────────────────────────────────────────┐
│ DATA LAYER (MySQL Databases) │
│ │
│ Database: intaleqDB1 (primary) │
│ Database: intaleq-ridesDB (ride-specific) │
│ Tables: 60+ tables covering users, rides, payments, etc. │
└─────────────────────────────────────────────────────────────────────┘
```
---
## Dependency Graph
```
Rider App (siro_rider) ───→ Main API ─────→ intaleqDB1
├──→ Map SaaS ───────→ Custom Map Service
├──→ OSRM ───────────→ OpenStreetMap
├──→ Payment API ────→ Wallet DB
├──→ Firebase ───────→ FCM
├──→ WebSocket ──────→ Ride Socket Server
└──→ Google Maps ────→ Google APIs
Driver App (siro_driver) ───→ Main API ─────→ intaleqDB1
├──→ Location API ───→ car_locations
├──→ Payment API ────→ Wallet DB
├──→ WebSocket ──────→ Driver Socket Server
├──→ Firebase ───────→ FCM
└──→ Google Maps ────→ Google APIs
Admin App (siro_admin) ────→ Main API ─────→ intaleqDB1
├──→ Payment API
├──→ Firebase
└──→ Internal Services
Socket Server (socket_intaleq) ──→ MySQL
├──→ driver_socket.php ──→ Driver Socket.IO
└──→ passenger_socket.php ──→ Passenger Socket.IO
Ride Server (rides.intaleq.xyz) ──→ MySQL (intaleq-ridesDB)
Location Server (location.intaleq.xyz) ──→ MySQL (car_locations)
Payment Server (walletintaleq.intaleq.xyz) ──→ Wallet MySQL
```
---
## External Services
| Service | Integration Point | Auth Method | Purpose |
|---------|-----------------|-------------|---------|
| **Google Maps** | `https://maps.googleapis.com/maps/api/` | API Key | Map rendering, geocoding |
| **Here Maps** | `https://autosuggest.search.hereapi.com/v1/autosuggest` | API Key | Place autocomplete |
| **Map SaaS** | `https://map-saas.intaleqapp.com/api/` | x-api-key | Custom routing, geocoding |
| **OSRM Server** | `https://routec.intaleq.xyz/route` | None | OpenStreetMap routing |
| **Firebase** | Firebase SDK | google-services.json | FCM, Analytics, Crashlytics |
| **PayMob** | PayMob SDK | API Key + HMAC | Payment gateway (Visa/Mastercard) |
| **Twilio** | Twilio Verify API | Account SID + Auth Token | SMS OTP verification |
| **WhatsApp Cloud** | Graph API | OAuth Token | WhatsApp OTP delivery |
| **Azure OCR** | `https://ocrhamza.cognitiveservices.azure.com/` | Subscription Key | Document text extraction |
| **OpenAI** | OpenAI API | API Key | Document data extraction (GPT-3.5) |
| **Llama AI** | Llama API | Bearer Token | Document data extraction |
| **Agora** | Agora SDK | App Certificate | Voice/video calls |
| **SMS Kazumi** | `https://sms.kazumi.me/api/` | API Key | SMS provider (Egypt) |
---
## Security Architecture
### Authentication
| Mechanism | Implementation |
|-----------|---------------|
| **JWT** | Custom JWT tokens issued at login, validated on each request |
| **Fingerprint** | Device fingerprint hashed with SHA-256, stored in JWT payload |
| **HMAC** | HMAC authentication for payment server requests |
| **Bearer Tokens** | Standard Bearer token in Authorization header |
| **Social Auth** | Google Sign-In, Apple Sign-In |
### Authorization
- **Role-based**: Passenger, Driver, Admin, Service Agent
- **Device Binding**: X-Device-FP header verified against JWT fingerprint claim
- **Wallet Auth**: Separate JWT + HMAC for payment operations
### Token Handling
| Token | Storage | Expiry | Refresh |
|-------|---------|--------|---------|
| JWT (main) | GetStorage | 1 hour (default) | `getJWT()` auto-refresh on 401 |
| JWT (wallet) | GetStorage | 1 hour | `getJwtWallet()` auto-refresh |
| FCM Token | GetStorage + DB | Firebase-managed | On app start |
| Refresh Token | FlutterSecureStorage | Long-lived | On login |
### Encryption
- **AES-256-CBC**: Custom encrypt/decrypt for sensitive data
- **SHA-256**: Device fingerprint hashing
- **Base64**: Basic auth credentials encoding
- **SSL/TLS**: All API calls over HTTPS
### Secure Storage
| Data | Storage Method |
|------|---------------|
| JWT tokens | GetStorage (encrypted box) |
| Refresh tokens | FlutterSecureStorage (Keychain/Keystore) |
| Fingerprint | GetStorage (encrypted) |
| HMAC keys | GetStorage (encrypted) |
### Session Management
- Auto-logout on token expiry (401 response)
- Fingerprint migration tools in admin panel
- Login attempt rate limiting (`login_attempts` table)
---
## Caching Strategy
| Cache Type | Implementation | Data Cached |
|-----------|---------------|-------------|
| **GetStorage** (Local) | Key-value store in app sandbox | JWT, user ID, preferences, ride state |
| **FlutterSecureStorage** | OS-level encrypted storage | Refresh tokens, sensitive data |
| **SQLite (DbSql)** | Local SQLite database | Offline maps, ride history |
| **Memory Cache** | GetX controller state | Active ride data, driver list, map markers |
| **Server Cache** | MySQL + Query Cache | Driver locations (car_locations), places |
| **In-Memory (NetGuard)** | Singleton notification state | Network error debouncing |
---
## WebSocket Architecture
```
┌──────────────┐ ┌──────────────────┐ ┌──────────────┐
│ Rider App │◄───────►│ Passenger Socket │◄───────►│ MySQL DB │
│ │ │ (PHP) │ │ │
└──────────────┘ └──────────────────┘ └──────────────┘
│
│ (Internal IPC)
│
┌──────────────┐ ┌──────────────────┐ ┌──────────────┐
│ Driver App │◄───────►│ Driver Socket │◄───────►│ MySQL DB │
│ │ │ (PHP) │ │ │
└──────────────┘ └──────────────────┘ └──────────────┘
```
**Socket Events:**
- `driver_location_update` — Real-time driver GPS to passenger
- `ride_accepted` — Driver accepted notification
- `ride_cancelled` — Ride cancellation event
- `ride_finished` — Ride completion event
- `passenger_location` — Passenger location (for driver)
- `driver_online` / `driver_offline` — Online status changes
---
## Admin Module Structure
| Module | Controller | Views |
|--------|-----------|-------|
| Dashboard | `DashboardController`, `DashboardV2Controller` | `admin_home_page.dart` |
| Captain Management | `CaptainAdminController` | `captain.dart`, `captain_details.dart` |
| Passenger Management | `PassengerAdminController` | `passenger.dart`, `passenger_details_page.dart` |
| Ride Management | `RideAdminController`, `RideLookupController` | `rides.dart`, `ride_lookup_page.dart` |
| Financial | `FinancialV2Controller` | `financial_v2_page.dart` |
| Analytics | `AnalyticsV2Controller`, `StaticController` | `advanced_analytics_page.dart` |
| Complaints | `ComplaintController` | `complaint_list_page.dart` |
| Pricing/Kazan | `KazanController` | `kazan_editor_page.dart` |
| Promotions | `PromoController` | `promo_management_page.dart` |
| Wallet | `WalletAdminController` | `wallet.dart` |
| Driver Docs | `DriverDocsController` | `driver_documents_review_page.dart` |
| Security | `SecurityV2Controller` | `audit_logs_page.dart` |
| Quality | `QualityController` | `blacklist_page.dart`, `driver_scorecard_page.dart` |
| Staff | `StaffController` | `add_staff_page.dart`, `pending_admins_page.dart` |
| Server Monitor | `ServerMonitorController` | `monitor_server_page.dart` |
| Invoices | `GetAllInvoiceController` | `invoice_list_page.dart` |