# Tarivo Delivery Roadmap Document status: Active execution plan Version: 2.0 ## 1. Delivery Strategy Tarivo must be built as a production SaaS mobility platform, not as a demo. Every module is delivered as a vertical slice with backend code, frontend code, database changes, validation, authorization, audit logging, predictable errors, tests and documentation updates. The current repository checkout now contains Phase 0 Laravel and Next.js source trees. No business module is considered complete until its source code exists in this repository and the required verification commands pass. Mandatory MVP modules: - Realtime chat, persistent notification, ringing, audio call and video call - Glovo/Uber Eats-style persistent notification center with sound and action states - Realtime geolocation on map - Secure uploads with queued AI processing - Offline action queue and synchronization, starting with driver start/finish trip during connection loss - Payment or transaction flow with automatic verified callback and idempotent processing - External API integrations isolated behind backend services Status legend: - `[ ]`: not started or not verified in the current repository - `[~]`: partially implemented but not production complete - `[x]`: implemented, tested and documented in the current repository ## 2. Phase 0: Production Engineering Foundation Outcome: the repository can support real Laravel and Next.js development. Tasks: - [x] Restore or create the real project source tree under `backend/` and `frontend/` - [x] Create Laravel API application under `backend/` - [x] Create Next.js web application under `frontend/` - [x] Configure strict TypeScript, ESLint, Prettier or equivalent formatting - [x] Configure Laravel Pint and PHPUnit - [x] Configure `.env.example` files without secrets - [~] Configure local Docker or documented service requirements for MySQL, Redis, queues, scheduler and Reverb - [x] Add CI-ready commands for backend and frontend - [~] Add deployment notes for the production domain and independent backend / frontend deployment - [x] Remove stale static build artifacts from the production source tree or move them to a deployment artifact strategy Acceptance criteria: - A fresh checkout can install dependencies. - Backend tests can run. - Frontend typecheck, lint, tests and build can run. - Secrets are not committed. - The repository state matches `README.md`. Verification: - `backend`: `composer ci` passes with Laravel Pint and PHPUnit. - `frontend`: `npm run ci` passes with TypeScript, ESLint, Vitest and Next.js production build. - Known follow-up: `npm audit` reports two moderate advisories in the frontend dependency tree. Do not run `npm audit fix --force` without reviewing major version changes. ## 3. Phase 1: Identity and Authorization Outcome: users can authenticate and backend permissions are enforceable. Tasks: - [x] Install and configure Laravel Sanctum - [~] Add roles and permissions - [x] Create user, role and permission seeders - [x] Implement register, login, logout and current-user endpoints - [x] Implement phone and email verification provider placeholders - [x] Add Form Requests for auth input - [~] Add policies and middleware for protected routes - [x] Add auth audit logs - [~] Add feature tests for auth and authorization - [~] Build production login, registration and account state UI Acceptance criteria: - Unauthorized users cannot access protected resources. - Role checks are enforced by backend code. - Auth validation errors use the standard API envelope. - Login, registration and verification endpoints are rate limited. Implemented in the current repository: - Laravel Sanctum token auth, `users` UUID/status fields, soft deletes and role assignment through Spatie Permission. - Public passenger/driver registration, login, logout, current-user endpoint, verification placeholders, auth rate limits and audit logging. - Next.js `/login` and `/register` screens wired to typed API clients. - Verification: `backend` `composer ci` passes with 10 tests / 50 assertions; `frontend` `npm run ci` passes with 10 Vitest tests and production build. Remaining Phase 1 work: - Define granular permissions and policies beyond the initial role foundation. - Add profile, password and account-management endpoints and UI. - Add role-specific account state screens after the dashboard API exists. ## 4. Phase 2: Reference Data and Driver Onboarding Outcome: admins can prepare cities and vehicle types; drivers can submit real onboarding data. Tasks: - [x] Create cities and vehicle types migrations and seeders - [x] Create drivers, vehicles, files and driver document migrations - [x] Implement driver profile and vehicle APIs - [x] Implement secure upload service with private storage - [x] Implement driver document APIs - [x] Queue AI processing records after document upload - [~] Add admin document review endpoint - [x] Create driver onboarding frontend screens - [ ] Add admin review queue UI - [x] Add feature and component tests Acceptance criteria: - Driver cannot become approved without required documents. - File uploads are validated by extension, MIME type and size. - Private storage paths are never exposed through APIs. - Document approval and rejection are audited. - Driver receives persistent notification after review. Implemented in the current repository: - Public reference APIs for active launch cities and vehicle types. - Driver profile creation/update/list/detail with role and ownership policies. - Vehicle create/update/list/detail/delete with active city and vehicle type validation, seat capacity validation and audit logs. - Driver document upload with private local storage, server-generated paths, file metadata, checksum, duplicate document conflict handling and queued AI processing records. - Admin document review endpoint with approval/rejection state changes, driver rejection, required-document approval logic and audit logs. - Next.js `/driver/onboarding` screen connected to the backend reference, driver, vehicle and document APIs. - Verification: `backend` `composer ci` passes with 18 tests / 94 assertions; `frontend` `npm run ci` passes with 15 Vitest tests and production build. Remaining Phase 2 work: - Persistent notification creation after document review depends on the notification module. - Admin review queue UI is still pending. ## 5. Phase 3: Ride Request and Trip Lifecycle Outcome: a passenger can request a ride and a driver can complete it. Tasks: - [x] Create ride request, trip, trip status event and driver response migrations - [x] Implement backend-owned ride estimate service - [x] Implement ride creation endpoint - [x] Implement driver accept and reject actions - [x] Implement trip arrived, start, pause, resume, finish and cancel actions - [x] Add `TripLifecycleService` with explicit transition rules - [x] Add passenger, driver and operations policies - [x] Add passenger ride request frontend - [x] Add driver active ride frontend - [x] Add backend and frontend tests Acceptance criteria: - Invalid transitions return HTTP `409`. - Driver availability changes with trip state. - Ride and trip actions are audited. - Passenger and driver read the same canonical trip state from the API. Implemented in the current repository: - Ride request, driver response, trip and trip status event tables. - Backend-owned ride estimator using launch vehicle pricing and server-side distance/duration calculation. - Passenger ride creation with validation, policy enforcement and audit logs. - Driver accept/reject with approved online driver and matching approved vehicle checks, duplicate response conflicts and active-trip conflicts. - Trip arrived, start, pause, resume, finish and cancel transitions with explicit `TripLifecycleService` rules, status events, audit logs and driver availability release on completion/cancellation. - Next.js `/rides/request` passenger surface and `/driver/rides` driver console connected to ride and trip APIs. - Verification: `backend` `composer ci` passes with 25 tests / 140 assertions; `frontend` `npm run ci` passes with 22 Vitest tests and production build. Remaining Phase 3 work: - Persisted notifications and Reverb broadcasts for ride/trip events depend on the notification and realtime phases. - Google Maps route/ETA integration is deferred to the tracking/maps phase. ## 6. Phase 4: Persistent Notifications and Realtime Outcome: critical ride, call, payment and document events reach users reliably. Tasks: - [ ] Install and configure Laravel Reverb - [ ] Create notifications migration and API resource - [ ] Define notification priority, persistence, sound and action states - [ ] Implement notification center APIs - [ ] Broadcast notification creation on authorized private user channels - [ ] Broadcast ride and trip status events - [ ] Build persistent alert surface and notification center UI - [ ] Add notification sound preference handling - [ ] Add channel authorization and broadcast tests Acceptance criteria: - Critical notifications persist until read, acted, expired or resolved. - Incoming ride request, incoming call and payment failure can be blocking alerts. - Realtime channels are authorized. - Broadcast payloads are sanitized and minimal. ## 7. Phase 5: Chat, Ringing and Calls Outcome: ride participants and support can communicate in realtime. Tasks: - [ ] Create conversations, participants, messages and call sessions tables - [ ] Implement conversation creation and participant authorization - [ ] Implement message send, read receipt and typing endpoints - [ ] Broadcast message, typing and read receipt events - [ ] Implement call start, accept, decline, missed, end and signal endpoints - [ ] Broadcast incoming call ringing and call state changes - [ ] Build active ride chat UI - [ ] Build chat UI with offline send state - [ ] Build ringing, audio call and video call UI flows - [ ] Add backend and frontend tests Acceptance criteria: - Messages persist before broadcast. - Messages support sent, delivered, read and failed states. - Call sessions are stored and audited. - Only conversation participants can access messages or signaling. ## 8. Phase 6: Realtime Map Tracking Outcome: active trips show live driver location and route context. Tasks: - [ ] Create trip locations migration - [ ] Implement driver location update endpoint - [ ] Rate limit location updates - [ ] Broadcast authorized trip location events - [ ] Integrate Google Maps route and ETA services behind backend services - [ ] Build passenger and driver active trip map UI - [ ] Show degraded state when live data is stale - [ ] Add backend and frontend tests Acceptance criteria: - Unauthorized users cannot read trip tracking. - Last known location is available after reconnect. - Map UI shows waiting, delayed and offline states. - Google Maps secrets are not exposed through business APIs. ## 9. Phase 7: Uploads and AI Processing Outcome: uploaded documents and support attachments can be processed by AI. Tasks: - [ ] Implement reusable upload endpoints for authorized file purposes - [ ] Implement AI processing jobs for OCR, image analysis and document validation - [ ] Store AI results as structured JSON separate from file metadata - [ ] Build admin AI review UI - [ ] Add provider failure handling and safe user errors - [ ] Add queue tests and service tests Acceptance criteria: - AI failures do not break upload flow. - Sensitive approvals remain reviewable by an admin. - Users receive status notifications. - Raw provider errors are not exposed to users. ## 10. Phase 8: Offline Synchronization Outcome: selected driver actions survive connection loss. Tasks: - [ ] Create sync actions migration - [ ] Implement idempotency handling for offline actions - [ ] Implement single and batch sync endpoints - [ ] Implement frontend offline action queue - [ ] Add offline, pending sync, synced and conflict UI states - [ ] Test offline start and finish trip scenario - [ ] Document future offline action expansion rules Acceptance criteria: - Duplicate sync actions do not duplicate effects. - Backend revalidates canonical state during replay. - Conflicts return HTTP `409` with a clear reason. - Conflict state is visible and actionable in the UI. ## 11. Phase 9: Payments, Wallet and Invoices Outcome: cash, wallet and Stripe payments update financial state safely. Tasks: - [ ] Create wallet, transaction, payment, webhook event and invoice migrations - [ ] Implement cash payment creation and confirmation - [ ] Implement wallet debit and credit flow - [ ] Implement Stripe payment creation - [ ] Implement Stripe webhook signature verification and idempotency - [ ] Generate invoices only after confirmed payment or completed cash flow - [ ] Notify users about payment failures - [ ] Add payment, wallet, webhook and invoice tests Acceptance criteria: - Frontend payment state is never trusted. - Wallet writes are atomic. - Stripe callbacks are signature verified. - Webhook replay does not duplicate transactions or invoices. ## 12. Phase 10: Admin, Support and Operations Outcome: operations staff can manage the platform safely. Tasks: - [ ] Create support tickets module - [ ] Add support conversation and call workflows - [ ] Add AI complaint summary action - [ ] Create authenticated dashboard summary API - [ ] Create admin dashboard APIs - [ ] Create audit log viewer - [ ] Create external API log viewer - [ ] Add health and integration status endpoints - [ ] Add reporting foundations Acceptance criteria: - Support can inspect ride, chat, payment and notification context. - Admin actions are audited. - External provider failures are visible without exposing secrets. - Dashboard queries are scoped by authenticated role. ## 13. Phase 11: Production Readiness Outcome: Tarivo is deployable and operable as a real SaaS platform. Tasks: - [ ] Define production environment variables and secret management - [ ] Configure queue workers, scheduler and Reverb process supervision - [ ] Add backup and restore documentation for database and private files - [ ] Add log retention and audit retention policy - [ ] Add rate limiting review for auth, tracking, chat, uploads and payments - [ ] Add security checklist and release checklist - [ ] Run full backend and frontend CI - [ ] Run manual acceptance tests on the production domain Acceptance criteria: - Deployment and rollback steps are documented. - Secrets are managed through environment variables. - Critical jobs are supervised and observable. - A senior production review would not classify the release as a prototype.