# Tarivo Product Charter Document status: Active product specification Version: 2.0 Owner: Energiedin Team Market: Morocco Primary language: French Supported languages: French, Arabic, English Currency: MAD Timezone: Africa/Casablanca ## 1. Product Positioning Tarivo is a premium smart mobility SaaS platform for Morocco. It connects passengers, drivers, support agents and administrators through a secure, API-first operating system for ride booking, realtime communication, live tracking, payments, document validation and offline-capable driver workflows. The product is inspired by the operational quality of Uber, inDrive, Careem, Glovo and Uber Eats, but it is not a clone and not a demo. Tarivo must be adapted to Moroccan usage patterns: cash payments, city-based transport rules, French-first product language, Arabic RTL support and local vehicle categories. ## 2. Product Principles - API-first: future mobile apps must consume the same backend. - Backend-owned business rules: the frontend displays state, it does not decide ride, payment, authorization or sync outcomes. - Realtime by design: ride operations, notifications, chat, calls and tracking are event-driven. - Offline tolerance: selected driver actions must survive unstable connectivity. - Operational traceability: important actions are auditable. - Human review remains possible for sensitive AI-assisted decisions. - SaaS quality: every feature must support maintainability, observability and production operation. ## 3. MVP Scope The first production release must include the capabilities below. Implementation status belongs in `TASKS.md`; this document defines target behavior and acceptance criteria. ### 3.0 Mandatory SaaS Capabilities Tarivo MVP is not acceptable unless these production capabilities are included: - Realtime chat with delivery/read states, persistent notifications, sound, ringing, audio calls and video calls. - Glovo/Uber Eats-style persistent notifications that survive refresh, reconnect and missed websocket events. - Realtime driver geolocation on a map with last-known location and delayed stream states. - Secure file upload with queued AI processing for OCR, image analysis and document validation. - Offline mode with synchronization. The first required scenario is driver start or finish trip while internet connection is lost. - Payment or transaction flow with automatic backend confirmation callback, idempotency and invoice generation after confirmed payment. - External API integrations through backend services, including maps, payments, AI, email and SMS. ### 3.1 Authentication and Roles Users can register, log in, verify phone/email and manage profile information. Roles are Guest, Passenger, Driver, Support Agent, Admin and Super Admin. Acceptance criteria: - Protected routes require authentication. - Role permissions are enforced by backend policies. - Auth endpoints are rate limited. - Sensitive auth actions are logged. - Suspended or deleted users cannot access protected features. ### 3.2 Driver Onboarding Drivers can submit identity, driving license, insurance, vehicle registration and vehicle photo documents. Documents are uploaded securely and processed asynchronously by AI while admin review remains authoritative. Acceptance criteria: - File type, MIME type and size are validated. - Original filenames are never trusted for storage paths. - Private files are not directly public. - AI result is stored separately from file metadata. - Admin can approve or reject with a reason. - Driver receives persistent notification when status changes. ### 3.3 Operational Dashboard Authenticated users need a role-scoped dashboard for the current operational state. The dashboard must show real backend state and must not invent driver, ride, notification, payment or sync values in the frontend. Acceptance criteria: - Support, admin and super admin users receive operations scope. - Passengers receive only their own rides, trips, payments and notifications. - Drivers receive only their own driver profile, eligible ride work and assigned trips. - Loading, empty, permission denied, error and offline states are visible. - Pending modules are displayed as unavailable or pending, never as fake data. ### 3.4 Ride Request and Trip Lifecycle Passengers can request rides by pickup, destination, vehicle type and payment method. Drivers can accept, arrive, start, pause, resume, complete or cancel trips according to valid backend state transitions. Acceptance criteria: - Invalid state transitions return HTTP `409`. - Ride creation, acceptance, cancellation and completion are audited. - Driver availability updates when a trip starts or ends. - Passenger and driver see the same canonical trip state from the API. - Route, duration and price calculations are backend-owned. ### 3.5 Persistent Notifications Critical alerts remain visible until the user acts or the event resolves. Examples: incoming ride request, incoming call, driver arrived, payment failed, document rejected and support reply. Acceptance criteria: - Notifications are persisted in the database. - Critical notifications support read and acted states. - Blocking alerts are available for incoming ride, call and payment failure. - Sound behavior respects user preference where allowed. - Backend does not rely only on browser push or frontend memory. ### 3.6 Chat, Ringing, Audio Call and Video Call Passengers, drivers and support agents can communicate through ride or support conversations. Calls use persisted call sessions and authorized signaling. Acceptance criteria: - Messages support sent, delivered, read and failed states. - Messages persist before broadcast. - Typing indicators are ephemeral and authorized. - Calls support ringing, accepted, declined, missed, ended and failed states. - WebRTC signaling is authorized through backend-controlled channels. - Call sessions are stored for audit and support context. ### 3.7 Realtime Map Tracking Active trips show pickup, destination, route, ETA and driver position. Acceptance criteria: - Driver location updates are authenticated and rate limited. - Only authorized trip participants can receive location events. - Last known location and timestamp are visible if the stream is delayed. - Google Maps integration is isolated behind backend services where business state, secrets or billing-sensitive logic are involved. - Passenger and driver UIs expose delayed/offline tracking states. ### 3.8 Offline Mode and Synchronization Drivers can continue selected trip actions during a connection loss. The first required scenario is start or finish trip while offline. Acceptance criteria: - Frontend stores eligible actions with an idempotency key. - UI shows offline, pending sync, synced and conflict states. - Backend revalidates trip state when syncing. - Duplicate sync requests do not duplicate business effects. - Conflicts return HTTP `409` with a clear reason. ### 3.9 Payments and Transactions Tarivo supports cash, wallet and Stripe. Online payments are completed through verified callbacks. Wallet changes are atomic. Acceptance criteria: - Frontend payment state is never trusted. - Stripe webhooks are signature-verified. - Webhook event IDs are stored and processed idempotently. - Wallet debit and credit operations use database transactions. - Invoice is generated only after confirmed payment or completed cash flow. - Payment failures create persistent notifications. ### 3.10 External API Integrations Initial integrations are Google Maps, Stripe, OpenAI, email and SMS. Acceptance criteria: - External providers are isolated behind backend services. - Provider failures return friendly platform errors. - Operational metadata is logged without storing secrets. - API keys are read only from environment variables. - Provider-facing jobs are retryable where safe. ## 4. Non-Goals for MVP - Native iOS or Android apps - Food delivery - Corporate accounts - Driver incentive engine - Dynamic pricing automation - Public partner API - Multi-country rollout The architecture must not block these later modules. ## 5. Moroccan Product Requirements Supported cities for the first release: - Casablanca - Rabat - Marrakech - Agadir - Tangier - Fes - Meknes - Oujda - Nador - Laayoune - Dakhla Supported vehicle categories: - Petit Taxi - Grand Taxi - Premium - Moto - Delivery Cash payment is mandatory. MAD is the default currency. Arabic screens must support RTL layout. ## 6. Required User-Facing States Every major user workflow must handle: - Loading - Empty - Error - Success - Permission denied - Offline - Pending sync - Synced - Conflict ## 7. Success Metrics - Ride request creation is fast and reliable. - Drivers do not miss critical ride or call alerts. - Realtime tracking remains understandable during weak connectivity. - Payment state updates automatically after callbacks. - Offline driver actions sync without duplicate effects. - AI reduces manual document review time without removing human control. - Admins can trace ride, payment, role and document decisions.