Siro/knowledge/AI_CONTEXT.md

# AI_CONTEXT.md — Siro (Siro) Ride-Hailing Platform

## Core Architecture
- **4 Flutter apps** (rider, driver, admin, service) + **PHP backend** + **MySQL** + **WebSocket**
- **State Management**: GetX (permanent controllers in AppBindings)
- **Maps**: Siro Maps (custom Flutter plugin) + Google Maps + Map SaaS + OSRM
- **Domain**: siromove.com | **API**: api.intaleq.xyz/siro_v3 | **Ride**: rides.intaleq.xyz | **Location**: location.intaleq.xyz | **Payment**: walletintaleq.intaleq.xyz

## Passenger Flow (siro_rider)
```
Splash → Auth check → MapScreen (permanent map controllers) 
→ Enter destination → Price calc → Ride request (waitingRides)
→ Searching (WebSocket polling + timer) → Driver accepts (RideState.driverApplied)
→ Driver arrives (RideState.driverArrived) → Ride begins (RideState.inProgress)
→ Ride finishes → Rating + Payment → Back to map
```
- **RideState enum**: noRide, cancelled, preCheckReview, searching, driverApplied, driverArrived, inProgress, finished
- **Key Controller**: `RideLifecycleController` (4600 lines) — state machine, deviation detection, ETA calculation
- **Deviation Guard**: 50m threshold, re-routes if off path
- **Local ETA**: Route trimming by closest point, percentage-based time calculation

## Driver Flow (siro_driver)
```
Splash → Auth → MapScreen → Go Online (location streaming)
→ Ride offer via FCM + Android native overlay (TripOverlayPlugin)
→ Accept → Navigate to pickup → Arrived → Begin ride → Active ride → End ride
→ Rate passenger + Payment → Go Offline
```
- **Background**: Android foreground service for GPS + FCM background handler
- **Overlay**: Custom native plugin shows trip data with accept/reject (auto-close 15s)
- **Data package**: 33-index array (passengerLat/Lng, destination, fare, distance, name, phone, etc.)

## API Endpoints (59+ discovered)
### Auth
| Endpoint | Caller |
|----------|--------|
| POST `$server/auth/login.php` | LoginController |
| POST `$authCaptin/login.php` | Driver login |
| POST `$server/auth/signup.php` | RegisterController |
| POST `$server/loginJwtRider.php` | JWT refresh (401 handler) |

### Ride
| Endpoint | Caller |
|----------|--------|
| POST `$rideServerSide/ride/rides/add.php` | Ride request |
| POST `$rideServerSide/rides/acceptRide.php` | Driver accept |
| POST `$rideServerSide/ride/rides/updateStausFromSpeed.php` | Status updates (Arrived/Begin/Finished) |
| POST `$rideServerSide/ride/rides/getRideStatus.php` | Polling fallback |
| POST `$server/ride/rides/getRideStatusFromStartApp.php` | App restore check |

### Location
| Endpoint | Caller |
|----------|--------|
| POST `$location/{getSpeed,getComfort,getBalash,...}.php` | Nearby drivers by car type |
| POST `$location/getDriverCarsLocationToPassengerAfterApplied.php` | Driver GPS after accept |

### Payment
| Endpoint | Caller |
|----------|--------|
| POST `$paymentServer/ride/payment/add.php` | Ride payment |
| POST `$paymentServer/ride/payMob/{wallet,card}/payWithPayMob.php` | Visa/Mastercard |
| POST `$paymentServer/ride/mtn/passenger/{start,confirm}_payment.php` | MTN mobile money |
| POST `$paymentServer/ride/syriatel/passenger/{start,confirm}_payment.php` | Syriatel mobile money |
| POST `$paymentServer/ecash/payWithEcash.php` | E-Cash |

### Other
| Endpoint | Caller |
|----------|--------|
| POST `$server/ride/rate/addRateToDriver.php` | Passenger rating |
| POST `$server/ride/rate/addRateToPassenger.php` | Driver rating |
| POST `$wallet/getWalletByPassenger.php` | Wallet balance |
| POST `$walletDriver/getWalletByDriver.php` | Driver wallet |
| POST `$promo/getPromoBytody.php` | Promo code check |
| POST `$server/ride/invitor/get_unified_code.php` | Referral code |

## Database (60+ tables in intaleqDB1 + intaleq-ridesDB)
### Core Tables
| Table | PK | Key Relationships |
|-------|----|-------------------|
| `passengers` | id (varchar) | → ride, waitingRides, payments, passengerWallet, tokens, ratingDriver, notifications |
| `driver` | idn (auto) + id (varchar) | → ride, car_locations, payments, driverWallet, driverToken, driver_orders |
| `ride` | id (auto) | passenger_id → passengers, driver_id → driver |
| `waitingRides` | id (varchar) | passenger_id → passengers, SPATIAL indexes on lat/lng |
| `car_locations` | driver_id (varchar) | SPATIAL idx_location_point (POINT), BTREE idx_loc_status_time |
| `payments` | id (varchar) | passengerID, driverID, rideId |
| `ratingDriver` | id (auto) | driver_id, passenger_id, UNIQUE ride_id |

### Key Indexes
- `car_locations.location_point` — SPATIAL index for GIS queries
- `waitingRides` — idx_location_status (lat,lng,status,created_at)
- `palces11` — FULLTEXT on name/name_ar/name_en/address/category

## Real-time Systems
- **WebSocket**: PHP Socket.IO server (socket_intaleq/{driver,passenger}_socket.php)
- **Events**: `driver_location_update`, `ride_accepted`, `ride_cancelled`, `ride_finished`
- **Polling fallback**: HTTP polling every N seconds when WebSocket disconnects
- **3 reliable updates**: Stops polling after 3 consecutive WebSocket location updates

## Notifications
- **Push**: Firebase Cloud Messaging (FCM) — `FirebaseMessagesController`
- **Local**: `NotificationController` with custom channels
- **iOS Live Activity**: `IosLiveActivityService` + SwiftUI RideWidget
- **Background**: Android overlay (TripOverlayPlugin) for driver ride offers
- **Types**: Order (ride offer), OrderSpeed, ride status updates

## GIS Logic
- **Routing**: Map SaaS (`map-saas.intaleqapp.com/api/maps/route`) or OSRM (`routesy.intaleq.xyz`)
- **Geocoding**: Map SaaS reverse geocoding + search
- **ETA**: Local algorithm in `RideLifecycleController.updateRemainingRoute()` — finds closest route point, trims polyline, recalculates percentage
- **Deviation**: `checkAndRecalculateIfDeviated()` — 50m threshold, consecutive heading check
- **Driver Tracking**: `handleDriverLocationUpdate()` — camera follows driver, zoom by speed
- **Marker Rotation**: Updates driver car icon rotation based on heading

## Wallet Logic
- **Passenger Wallet**: `passengerWallet` table, deduct on ride, top-up via PayMob/MTN/Syriatel
- **Driver Wallet**: `driverWallet` table, credit after ride, withdraw
- **Payment Methods**: Cash (default), Visa (PayMob), Wallet, MTN, Syriatel, E-Cash
- **Kazan**: Percentage-based commission per country (kazan table: comfortPrice, speedPrice, familyPrice, etc.)
- **Tips**: `tips` table linked to ride/driver/passenger

## State Management Map
### Rider App Controllers (permanent in AppBindings)
| Controller | States | Dependencies |
|-----------|--------|-------------|
| RideLifecycleController | RideState enum (8 states) | CRUD, MapEngine, MapSocket, UiInteractions, NearbyDrivers |
| MapSocketController | connected/disconnected | WebSocket, RideLifecycle |
| MapEngineController | map ready/loading | SiroMaps, markers, polylines |
| LocationSearchController | idle/searching/result | Map SaaS API |
| NearbyDriversController | empty/populated | Location API |
| UiInteractionsController | sheet states | All ride widgets |
| LoginController | logged out/authenticating/logged in | CRUD, JWT |
| SplashScreenController | animating/checking/navigating | GetStorage, CRUD |

### Driver App
| Controller | States | Dependencies |
|-----------|--------|-------------|
| HomeCaptainController | offline/online/in-ride | LocationService, WebSocket, CRUD |
| NavigationController | idle/navigating/recalculating | Map, TTS |
| BackgroundServiceHelper | running/stopped | Android service |

## Security
- **JWT** with device fingerprint (SHA-256) in payload
- **X-Device-FP** header validated against JWT fingerprint claim
- **HMAC** for payment server (X-HMAC-Auth header)
- **401 auto-refresh**: `LoginController.getJWT()` retries once
- **Rate limiting**: login_attempts table per IP

## External Services
| Service | Endpoint | Key Type |
|---------|----------|----------|
| Google Maps | maps.googleapis.com | API Key |
| Map SaaS | map-saas.intaleqapp.com | x-api-key |
| Here Maps | autosuggest.search.hereapi.com | API Key |
| OSRM | routec.intaleq.xyz / routesy.intaleq.xyz | None |
| PayMob | paymob.com | HMAC |
| Twilio | verify.twilio.com | Account SID + Token |
| Azure OCR | ocrhamza.cognitiveservices.azure.com | Subscription Key |
| OpenAI | api.openai.com | Bearer Token |
| Llama | Together API | Bearer Token |
| SMS Kazumi | sms.kazumi.me | API Key |

## File Map (Key Files)
```
siro_rider/
  lib/main.dart, app_bindings.dart, splash_screen_page.dart
  lib/controller/home/map/ride_lifecycle_controller.dart (4600 lines)
  lib/controller/home/map/ride_state.dart (8-state enum)
  lib/controller/home/map/map_socket_controller.dart
  lib/controller/home/map/map_engine_controller.dart
  lib/controller/functions/crud.dart (720 lines, unified HTTP client)
  lib/constant/links.dart (all API endpoints)
  lib/views/home/map_widget.dart/*.dart (20+ map UI widgets)

siro_driver/
  lib/main.dart (550 lines, accept/reject logic)
  lib/controller/functions/background_service.dart
  lib/controller/home/captin/home_captain_controller.dart
  lib/views/home/Captin/driver_map_page.dart
  lib/views/home/Captin/orderCaptin/order_request_page.dart

backend/
  schema_primary.sql (1826 lines, 60+ tables)
  schema_ride.sql (1787 lines)
  auth/*.php, ride/*.php, Admin/*.php

socket_intaleq/
  driver_socket.php, passenger_socket.php

siro_admin/ (Flutter Web admin panel)
  20+ controllers, 30+ views

siro_service/ (Driver registration agent app)
```

## Key Business Rules
- **Ride timeout**: `_totalSearchTimeoutSeconds` → increase fee dialog
- **Wait time**: 5-minute passenger wait after driver arrival
- **Deviation**: 50m threshold before re-routing
- **Socket reliability**: 3 updates → stop polling
- **Cash payment**: Driver marks as received, confirmation dialog
- **Wallet payment**: Deduct from passengerWallet, verify balance
- **Multi-point trips**: Up to 5 waypoints (step0-step4 in ride args)
- **Car types**: Speed, Comfort, Family, Delivery, Blash (free), Late, Heavy, Nature, Electric, PinkBike, Van, FemalDriver
- **Regions**: Syria (routesy), Jordan (routesjo), Egypt (routec)