Siro/knowledge/PROJECT_OVERVIEW.md

PROJECT_OVERVIEW — Siro (Intaleq) Ride-Hailing Platform

Business Purpose

Siro (Intaleq) 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    │   │
│  │ intaleq_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), Intaleq 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)