# PROJECT_OVERVIEW — Siro (Siro) Ride-Hailing Platform

## Business Purpose

Siro (Siro) is a multi-region ride-hailing platform connecting passengers with drivers (captains). It operates across Syria, Jordan, and Egypt. The platform supports multiple car types (Speed, Comfort, Family, Delivery, Electric, Van, Bike) with dynamic pricing via a "Kazan" percentage-based commission system.

### Core Ride-Hailing Workflow
1. Passenger requests ride → System searches nearby drivers → Driver accepts → Navigate to pickup → Ride begins → Ride completes → Payment processed → Rating submitted

### User Types
- **Passenger** (Rider) — Requests rides via siro_rider app
- **Driver** (Captain) — Accepts rides via siro_driver app
- **Admin** — Manages system via siro_admin app (Flutter Web/PWA)
- **Service Agent** — Manages driver registration via siro_service app
- **Employee** — Staff managing drivers, passengers, complaints

### Driver Types
| Type | Code | Description |
|------|------|-------------|
| Speed | Speed | Standard rides |
| Comfort | Comfort | Premium rides |
| Family | Family | Larger vehicle |
| Delivery | Delivery | Package delivery |
| Free/Blash | Blash | Economy |
| Late | Late | Off-peak |
| Heavy | Heavy | Cargo |
| Nature | Nature | Scenic routes |
| Electric | Electric | EV |
| Pink Bike | PinkBike | Motorcycle |
| Van | Van | Minibus |
| Female Driver | FemalDriver | Women-only |

### Payment Methods
- Cash
- Visa/Credit Card (PayMob)
- Wallet (internal balance)
- MTN Mobile Money
- Syriatel Mobile Money
- E-Cash
- Stripe

### External Integrations
| Service | Purpose |
|---------|---------|
| Google Maps | Map rendering, geocoding, routing |
| Here Maps | Place autocomplete |
| Map SaaS (intaleqapp.com) | Custom routing, reverse geocoding, places |
| OpenStreetMap (routec/routesy) | OSRM routing |
| Firebase | Push notifications, analytics, crashlytics |
| PayMob | Payment gateway |
| Twilio | SMS verification |
| WhatsApp Cloud API | OTP delivery |
| Azure OCR | Document scanning |
| OpenAI GPT | Document data extraction |
| Llama AI | Document data extraction |
| Agora | Voice/video calls |
| WebRTC | Signaling service |
| SMS Kazumi | SMS provider (Egypt) |

---

## System Modules

| Module | Purpose | Dependencies | Main Files |
|--------|---------|--------------|------------|
| **Authentication** | Login, signup, OTP, JWT management, Google/Apple auth | Firebase, Twilio, WhatsApp | `siro_rider/lib/controller/auth/*.dart`, `backend/auth/*.php` |
| **Dispatching** | Ride request → driver matching → offer → accept | WebSocket, MySQL GIS | `socket_intaleq/*.php`, `backend/ride/*.php` |
| **Matching** | Nearby driver search via spatial queries | MySQL SPATIAL indexes | `backend/ride/location/*.php` |
| **Maps & GIS** | Map rendering, routing, geocoding, driver tracking | Google Maps, Map SaaS, OSRM | `siro_rider/lib/controller/home/map/*.dart` |
| **Payments** | Ride payment, wallet, PayMob, MTN, Syriatel, E-Cash | PayMob, Stripe | `siro_rider/lib/controller/payment/*.dart`, `backend/ride/payment/*.php` |
| **Wallet** | Passenger & driver balance management | Payment server (walletintaleq.xyz) | `siro_rider/lib/controller/payment/passenger_wallet_history_controller.dart` |
| **Notifications** | Push (FCM), local, in-app notifications | Firebase | `siro_rider/lib/controller/firebase/*.dart` |
| **Chat** | In-app messaging between driver & passenger | PHP API | `backend/ride/chat/send_message.php` |
| **Rating** | Post-ride driver & passenger ratings | MySQL | `siro_rider/lib/controller/rate/*.dart`, `backend/ride/rate/*.php` |
| **Promotions** | Promo codes, referral rewards | MySQL | `siro_rider/lib/controller/home/profile/promos_controller.dart` |
| **AI Services** | OCR document scanning, data extraction | Azure OCR, OpenAI, Llama | `siro_rider/lib/controller/functions/crud.dart` (getLlama, getChatGPT, arabicTextExtractByVisionAndAI) |
| **Admin Functions** | Dashboard, driver/passenger management, analytics | All backend APIs | `siro_admin/lib/controller/admin/*.dart` |
| **Realtime Tracking** | WebSocket driver location streaming, passenger tracking | Socket.IO (PHP) | `socket_intaleq/*.php`, `siro_rider/lib/controller/home/map/map_socket_controller.dart` |
| **Referral System** | Unified referral codes for drivers & passengers | MySQL | `backend/migration_referral_system.sql`, `backend/ride/invitor/*.php` |
| **Complaints** | Post-ride issue resolution | MySQL | `siro_rider/lib/controller/home/profile/complaint_controller.dart`, `backend/Admin/AdminRide/` |
| **Emergency** | SOS signals, safety features | Agora, WebRTC | `siro_rider/lib/services/emergency_signal_service.dart` |

## Architecture Overview

```
┌─────────────────────────────────────────────────────┐
│                   Mobile Apps (Flutter)              │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────┐ │
│  │ siro_rider  │  │ siro_driver  │  │ siro_admin │ │
│  │ (Passenger) │  │  (Captain)   │  │  (Admin)   │ │
│  └──────┬──────┘  └──────┬───────┘  └─────┬──────┘ │
└─────────┼─────────────────┼─────────────────┼────────┘
          │                 │                 │
          ▼                 ▼                 ▼
┌─────────────────────────────────────────────────────┐
│              API Gateway (api.intaleq.xyz)           │
│  ┌───────────┐ ┌──────────┐ ┌───────────────────┐   │
│  │ Auth API  │ │ Ride API │ │ Payment API       │   │
│  └───────────┘ └──────────┘ └───────────────────┘   │
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────┴──────────────────────────────┐
│              Backend Servers (PHP)                   │
│  ┌──────────┐ ┌──────────┐ ┌───────────────────┐   │
│  │ Main API │ │ Ride API │ │ Payment Server    │   │
│  │ siro_v3│ │ rides.   │ │ walletintaleq.xyz│   │
│  └──────────┘ └──────────┘ └───────────────────┘   │
│  ┌──────────┐ ┌──────────┐ ┌───────────────────┐   │
│  │ Location │ │ Socket   │ │ Map SaaS          │   │
│  │ location.│ │ rides.   │ │ map-saas.         │   │
│  └──────────┘ └──────────┘ └───────────────────┘   │
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────┴──────────────────────────────┐
│              MySQL Databases                         │
│  ┌────────────────┐  ┌─────────────────────┐        │
│  │ intaleqDB1     │  │ intaleq-ridesDB     │        │
│  │ (Primary Main) │  │ (Ride-specific)     │        │
│  └────────────────┘  └─────────────────────┘        │
└─────────────────────────────────────────────────────┘
```

## Tech Stack

| Layer | Technology |
|-------|-----------|
| Mobile | Flutter (Dart) with GetX state management |
| Backend | PHP (native, no framework) |
| Database | MySQL 8.0 with GIS (SPATIAL indexes, POINT columns) |
| Realtime | PHP WebSockets (Socket.IO compatible) |
| Maps | Google Maps (primary), Siro Maps (custom), OSRM routing |
| Payments | PayMob, custom wallet server |
| Auth | JWT, Firebase Auth, Google Sign-In, Apple Sign-In |
| Storage | GetStorage (local), FlutterSecureStorage |
| Push | Firebase Cloud Messaging (FCM) |