253 lines
16 KiB
Markdown
253 lines
16 KiB
Markdown
# 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` | |