Taxi Platform Extension: App and Operations

Freelancer Job Post: Fleet-Ops, Driver App & Business Platform
1. Project Overview
Mangalore Travels Corporation (MTC) is seeking a developer/team to build the operational and business half of our live taxi/travel platform. You will integrate a net-new Flutter driver app, fleet-ops backend, billing system, unified inbox, and vendor portal into our existing FastAPI (backend) + Next.js (admin) architecture.

Note: This is an extension of a live, working system, not a from-scratch rewrite.

2. Existing Infrastructure (Your Foundation)
Backend: FastAPI, PostgreSQL, SQLAlchemy (async), Alembic, Pydantic, JWT auth (httpOnly, refresh), RBA (SUPER_ADMIN/SUB_ADMIN), SSE real-time notifications, Cloudflare R2 storage.

Admin Dashboard: Next.js App Router. Currently manages booking inquiries (NEW → CONTACTED → CONFIRMED → COMPLETED/CANCELLED), a marketing-facing fleet catalog, simple fares, and sub-admins.

In Progress: Basic corporate-account and payment-allocation tracking (coordinate boundaries with us).

Missing (Your Scope): Everything ops-related—Driver/trip models, Flutter app, GPS/telemetry, rate-card versioning, GST invoices, vendor portal, unified inbox.

3. Required Tech Stack (Non-Negotiable)
Mobile App: Flutter (Android-first). Offline-first architecture is mandatory (actions queue locally and sync upon reconnection).

Backend: FastAPI (matching existing layer conventions).

Real-time Tracking: WebSocket (live GPS) + Redis (position pipeline). Postgres must not take per-ping writes.

Push Notifications: Firebase Cloud Messaging (FCM).

Storage: Cloudflare R2 via presigned URLs.

Messaging: WhatsApp Business API (Cloud API/BSP) & Gmail API (OAuth, shared mailbox).

Mapping: Traffic-aware provider (e.g., Google Maps Platform). Please flag your provider assumption; API costs are billed separately.

4. Detailed Scope of Work (Modules A–R)
Driver & Fleet Ops
A. Driver & Fleet Management: Phone+PIN auth. Admin CRUD for drivers (profile, pay type, compliance docs like license, Aadhaar, police verification with expiry). Vehicle ops tracking (odometer, fuel type, owner vs. vendor, document expiries). Hard assignment blocks and 7/30-day alerts for expired docs.

B. Dispatch & Pre-Trip: Availability-aware assignment (conflict checks). FCM push/in-app accept. Automated pre-trip scheduler: T-45m driver push, T-30m customer WhatsApp OTP + live tracking, T+30m admin alert for unstarted trips.

C. Trip Execution & Tracking: Server-enforced state machine (Assigned to Closed + Cancelled) and duty-slip statuses. Requires OTP + live odometer photo to start; signature + photo to end. Idempotent, offline-safe event sync. Live GPS fleet map (3-5s freshness), SOS button, overspeed alerts, GPS vs. Odometer cross-checks.

Q. Maintenance Work Orders: Odometer-based service alerts. Lightweight work-order tracking (marks vehicle unavailable until closed).

Finance, Billing & Approvals
D. Fuel, Expenses & GST Invoices: Fuel logging (auto km/l computation). Expense uploads with admin approval queue. Deterministic fare calculation. One-tap GST invoice generation (sequential numbering, duty slip attached) stored in R2.

E. Quotation & Rate Cards: Version-controlled fares (Draft → Published → Superseded). Price-anchor quoting screen showing variance %. Variance thresholds trigger auto-send vs. approval routing.

F. Approval Engine: Unified Super Admin queue for permissions (e.g., price variances, vendor activation). Real-time delivery with one-tap approve/reject. No self-approvals.

G. Ledger & Payments: Record cash/UPI/bank/corporate payments. Driver wallet/ledger (advances, cash collected, incentives). Automated WhatsApp dunning (7/15/30 days). Bank-statement CSV import with auto/manual invoice matching.

H. Accounting & Reports: P&L per trip/vehicle, route profitability, dead mileage, GST summaries, and settlement statements. CSV exportable. Owner's daily dashboard (revenue, active trips, expirations).

P. Commissions: Auto-accruing flat or % commissions for vendors upon duty-slip verification. Monthly payout register (actual transfers happen out-of-band).

Portals & Communications
I. Feedback & Scoring: Post-trip WhatsApp rating request. 1-3 stars triggers an admin complaint ticket. 4-5 stars feed a 90-day rolling driver score.

K. Driver App (Flutter): Offline-capable, feature-first architecture (e.g., Riverpod/drift). Live-capture camera only (anti-fraud), foreground GPS tracking, wallet screen, English/Kannada, dark mode.

L. Admin Extensions (Next.js): Dispatch board, live map, detailed trip timelines, expense queues, rate-card editors, dunning, reports, and compliance dashboards.

M. Unified Inbox (WA + Gmail): Centralized Next.js inbox. Webhook-verified WhatsApp and polled Gmail API. Filterable thread views. Auto-links to customer bookings via exact phone/email matches. Custom admin-managed labels synced globally across the platform. Outbound WA must support pre-approved Meta templates.

N. Corporate Portal: Client profiles with credit terms. CONSOLIDATED billing mode for monthly scheduled PDFs instead of per-trip invoices.

O. Vendor Portal (Web-only): OTP login. Partners can view blocked vehicles/drivers, self-serve document uploads, accept/decline timed trip offers, and view their own commission statements.

Advanced Fleet Intelligence (Line-Item Separately)
R. Intelligence: Traffic-aware ETAs (shown to admin and WhatsApp), route/dispatch optimization based on traffic, an advanced driver scorecard (ratings + on-time % + safety events + fuel efficiency), and detailed fuel management dashboards.

5. System Jobs
J. Compliance Sweep: Nightly batch job checking all document expiries and updating dashboard alerts.

6. Out of Scope (Do Not Quote)
iOS App

Online payment gateways

GST e-invoicing (IRN/GSP integration)

AIS-140 hardware integration

TDS computation / Tally desktop bridge

Multi-tenant SaaS architecture

Advanced anomaly detection (beyond basic odometer/fuel checks)

Workshop/Parts inventory management

Driver training platforms

Automated 3-way vendor bill matching

7. Deliverables
Flutter Driver App (Android) source code.

FastAPI backend modules (A–J, N–R) with Alembic migrations.

Next.js Admin Dashboard extensions (L, M) + Web Vendor Portal (O).

Automated tests for critical paths (auth, state-machine, double-booking prevention, offline replay).

Handover documentation.

8. Proposal Requirements
To be considered, your proposal must include:

Itemized Pricing: Cost broken down by module (A–R). Do not submit just a single headline number.

Timeline: Phased delivery schedule in weeks/months.

Portfolio/Experience: Proof of experience with Flutter (offline-first), FastAPI (async), WebSocket, and messaging integrations (WA/Gmail APIs).

Assumptions & Risks: Any technical assumptions made (e.g., routing API choice) or clarifications needed before starting.