A complete engineering breakdown of the platform: every screen and capability across the Customer App, Driver App, Admin & Ops consoles — plus the real-time dispatch engine, pricing engine, data model, APIs, security and scalability layers that power them. Architected to deploy in any country — SMS, payments, maps and locale are all pluggable.
This document is feature- and architecture-first. It maps the entire product surface — four applications, six backend engines, the data model, the API layer, and the reliability/scale foundations — so engineering, review and estimation all work from the same source of truth.
Each client app talks to a shared Laravel API over REST for actions and WebSocket for live state. The dispatch engine, pricing engine and tracking pipeline sit behind that API and coordinate every order from request to proof-of-delivery.
Book, quote, pay, live-track and rate deliveries. Flutter · iOS + Android.
Go online, receive & complete jobs, navigate, capture POD, manage earnings. Flutter · iOS + Android.
Users, KYC, pricing, zones, finance, disputes, reports, feature flags. Web.
Live map of every driver & order, manual override, SLA & exception alerts. Web.
Geospatial nearest-driver matching, offer broadcast, timeout & auto re-assign.
Distance/time/vehicle fare calc, multi-stop, surge, promos, zone overrides.
Throttled GPS ingestion, live location fan-out, ETA, route history.
Gateways, wallets, COD, driver settlement, business billing, reconciliation.
Push, SMS, email, in-app inbox, masked calling, event-driven templates.
DB-backed i18n — add languages & edit copy without a new release.
Every transition is an event: it updates the order state machine, pushes a live update to the customer, notifies the driver, and (where relevant) triggers wallet, settlement or notification jobs on the queue.
The booking surface: fast to quote, transparent on price, and live from pickup to drop. Built for one-tap re-orders and multi-stop logistics alike.
The earning surface. Fast job cards, one-tap navigation, strict proof-of-delivery, and a fully transparent earnings & wallet ledger.
Everything configurable, nothing hard-coded. Pricing, zones, commissions, promos, feature flags and localization are all editable at runtime — no redeploy to change how the business runs.
The heart of the marketplace. When an order is confirmed, the engine finds the right driver in milliseconds using a geospatial index, then runs a controlled offer cycle until one accepts — or escalates to Ops.
Candidate drivers are scored, not just distance-sorted.
A deterministic, tunable broadcast strategy.
Transitions are guarded — e.g. you cannot reach PICKED_UP without a valid pickup OTP, and DELIVERED requires POD. Each transition emits a domain event consumed by tracking, notifications and settlement.
The engine continuously computes a demand/supply ratio per zone. When open requests outpace available drivers, a surge multiplier engages (bounded by admin caps) and the driver heatmap lights up that zone to pull supply in — closing the loop automatically.
Every fare is a deterministic calculation from admin-defined rules. The customer sees an estimate up front; the final fare adjusts only for measurable events (extra waiting, route change, add-ons) and is always itemized.
| Component | How it's calculated | Configurable by admin |
|---|---|---|
| Base fare | Flat start fee per vehicle type | Yes — per vehicle, per zone |
| Distance | Per-km rate × routed distance (Distance Matrix) | Yes |
| Time | Per-minute rate × estimated duration | Yes |
| Minimum fare | Floor applied if calc is lower | Yes |
| Multi-stop | Additive per extra stop + inter-stop distance | Yes |
| Waiting charge | Free minutes then per-minute after grace | Yes |
| Add-ons | Helper, COD handling, insurance, purchase-on-behalf | Yes |
| Surge | Multiplier from zone demand/supply, capped | Yes — rules & caps |
| Promo / discount | Code, first-order, referral — with stacking rules | Yes |
| Zone override | Any component replaced for a specific polygon | Yes |
Estimate vs final: the customer confirms against an estimate range. The final fare is recomputed from actuals at completion and shown as an itemized breakdown for full transparency and dispute-proofing.
Collect from the customer, hold and account for it, deduct commission, and pay the driver — with COD, wallets, business credit and full reconciliation handled as first-class flows.
Three cross-cutting services power the "live" feel of the product and its reach across Malaysia's multilingual market.
Efficient location streaming without draining battery or servers.
One event, many channels — all templated and localized.
A real facility, not hard-coded strings.
Real-time transport: Laravel Reverb / Soketi (WebSocket) with Redis pub/sub as the backplane, so multiple app servers share one live state. Localization is key-based i18n (Laravel lang + Flutter intl) with translations stored in the database.
A modular Laravel core (reusing the existing VMS domain) exposes REST + WebSocket to four clients, backed by relational + spatial + in-memory stores and an async worker tier for everything that shouldn't block a request.
The Laravel core is organized by domain modules (Orders, Dispatch, Pricing, Payments…) so each engine is testable and independently evolvable. The existing VMS handles Users, Drivers, Vehicles and Documents — reused, not rebuilt.
Everything country-specific — SMS, payment, maps, currency, language, phone/address formats, timezone, tax — sits behind a provider interface or a config value. Launching in a new country means adding configuration (and, where a local vendor is involved, a small adapter) — the core code never changes.
The SMS layer is an interface, not a single vendor.
Every gateway implements one common contract.
Currency, language and formats are data, not code.
| Concern | How it's abstracted | To add a country |
|---|---|---|
| SMS / OTP | Provider interface | Add credentials (or new adapter) |
| Payment | Gateway interface | Add gateway adapter + keys |
| Maps / geo | Geo-provider interface (Google default) | Set API key / region |
| Currency | ISO currency config | Select currency & format |
| Language | DB translations | Add locale + copy |
| Phone / Address | Locale rule set | Set country format |
| Timezone | Per-region setting | Set timezone |
| Tax / Invoice / Legal | Configurable rules & templates | Configure tax & invoice |
| Service area | Polygon zones + per-zone pricing | Draw zones, set fares |
Each external dependency (SMS, payment, maps) lives behind a clean interface. The core order/dispatch/pricing logic calls the interface, never a specific vendor. So a new market is configuration + optional adapter — the same battle-tested core serves every country, and multiple countries can run on one deployment with per-country settings.
The relational backbone. Spatial fields are indexed for geo queries; financial tables are append-only ledgers; translations live in the database for the localization facility.
| Entity | Key fields | Notes |
|---|---|---|
| User | role, phone, locale, wallet_id | Customer / staff; RBAC via roles |
| Driver | status, rating, tier, current_location | Extends VMS driver; spatial index on location |
| Vehicle | type, capacity, plate, documents | Reused from VMS |
| Order | state, vehicle_type, fare_id, driver_id | Drives the state machine |
| OrderStop | seq, lat/lng, contact, POD, status | One row per pickup/drop |
| Fare | base, distance, time, surge, addons, total | Itemized estimate + final |
| Payment | method, gateway_ref, status, amount | Idempotent callbacks |
| WalletTxn | wallet_id, type, amount, balance | Append-only ledger |
| Settlement | driver_id, period, payout_ref | Batch payouts |
| PricingRule / Zone | polygon, rates, multipliers | Runtime-editable |
| Promotion | code, type, limits, stacking | Promo engine |
| Rating / Dispute | score, ticket, SLA, resolution | Support workflow |
| Document | type, file, expiry, verified | KYC + expiry alerts |
| Device | push_token, platform, locale | Notification targeting |
| Translation | locale, key, value | Localization facility |
Horizontally scaled behind a load balancer; shared state lives in Redis, not in the process.
Read replicas, careful indexing, spatial indexes for geo, partitioning for high-volume tables.
Redis for hot config (pricing, zones), map-result caching, and fare estimates.
Queue workers scale independently; heavy work (settlement, notifications, webhooks) never blocks requests.
Redis GEO for live driver lookup; throttled ingestion keeps write volume bounded as fleet grows.
POD images to object storage + CDN, resized on upload to keep bandwidth low.
Multi-city ready: zones, pricing and supply are all scoped, so launching a new city is configuration — not a rebuild. The same cluster serves multiple regions with per-zone rules.
| Layer | Technology | Why |
|---|---|---|
| Mobile | Flutter (Dart) | One codebase → iOS + Android; fast, native-feel |
| Web / Portal | Next.js | SEO landing + business portal + admin |
| Backend | Laravel (PHP 8.3), modular | Reuses existing VMS core; mature, secure |
| Real-time | Laravel Reverb / Soketi (WebSocket) | Live tracking, order & offer events |
| Geo | Redis GEO + PostGIS | Nearest-driver & zone polygon queries |
| Data | MySQL + Redis + Object Storage | Relational + cache/live + media |
| Queue | Redis + Laravel Horizon | Async jobs, retries, monitoring |
| Maps | Google Maps Platform (MY) | Directions, Distance Matrix, Places, ETA |
| Payments | iPay88 / Curlec | DuitNow, FPX, Touch'n Go, GrabPay, cards |
| Push / SMS | FCM + SMS gateway | Notifications & OTP |
| Ops | Docker, CI/CD, Sentry | Repeatable deploys & observability |
Every environment is reproducible from code. Feature flags let new capabilities ship dark and roll out gradually — safe for a live marketplace.
Iterative delivery in two-week sprints, each ending with a working demo on staging. You see progress continuously, review at every milestone, and never wait for a big-bang reveal at the end.
2-week cycles: plan → build → demo → feedback. Scope stays flexible, direction stays yours.
Each phase ends with a reviewable deliverable and a go/no-go checkpoint.
Every feature ships with tests and a QA pass — not left to the end.
Progress update, staging link, blockers, next-sprint plan — in writing.
| Phase | Weeks | Deliverable | Exit criteria |
|---|---|---|---|
| 0 · Discovery | 1 | Finalized scope, screen list, API contract, VMS audit | Signed-off spec & data model |
| 1 · Foundation | 1–3 | UI/UX designs, VMS core extended, DB, auth, base API | API live on staging, designs approved |
| 2 · Apps + Dispatch | 4–8 | Customer & Driver apps, matching engine, live tracking, Admin/Ops | End-to-end order on staging |
| 3 · Pricing + Payments + POD | 9–12 | Fare engine, DuitNow/FPX/TnG, wallet, settlement, POD, QA | Paid order + payout works |
| 4 · Hardening + Launch | 13–14 | Load test, bug-fix, store submission, training, handover | Live on both stores |
VMS reuse compresses Phase 1 — Users, Drivers, Vehicles and Documents already exist, so the foundation phase extends rather than rebuilds.
A disciplined workflow so the codebase stays clean, reviewable and safe to change on a live marketplace.
Map existing Users/Drivers/Vehicles/Documents to the new schema; extend, don't duplicate.
OTP/JWT, RBAC, order model and state machine — the contract every app builds against.
Directions/Distance Matrix/Places integrated; GPS ingestion and live fan-out proven early.
Matching engine wired to Customer & Driver apps; full order lifecycle on staging.
Fare engine, gateway callbacks (idempotent), wallet and driver payouts.
Load-test real-time paths, fix, security review, then store submission.
Pricing math, state transitions, matching scoring.
API + gateway + maps + payment callbacks.
Concurrent drivers, GPS ingestion, WebSocket fan-out.
You test real flows on staging before launch.
Reproducible environments, the third-party accounts you'll need, and a clean handover so you own everything at the end.
| Service | Purpose | Owner |
|---|---|---|
| Apple Developer + Google Play | Publish iOS & Android apps | Client account, we submit |
| Google Maps Platform | Directions, Distance Matrix, Places, ETA | Client billing, we integrate |
| iPay88 / Curlec | DuitNow, FPX, Touch'n Go, cards | Client merchant account, we integrate |
| SMS gateway | OTP & alerts (MY sender ID) | Client account, we integrate |
| Firebase | Push notifications | Client project, we configure |
| Server / cloud | Hosting, DB, Redis, storage | Client billing, we set up |
| Domain + SSL | Web & API endpoints | Client, we configure |
We set up and configure every service; the accounts stay in your name so ownership and billing are always yours. The gateway, SMS and maps vendors above are the Malaysia defaults — for another country, the same setup swaps in that country's providers (see §10 Global-Ready).
Launch is the start, not the finish. A warranty period covers stabilization, and ongoing support keeps the platform healthy as you grow.
| Tier | Covers | Response |
|---|---|---|
| Warranty | Bugs in delivered features | Included, post-launch window |
| Maintenance | Updates, monitoring, minor tweaks, server care | Monthly retainer · priority |
| Enhancement | New modules & major features | Scoped & quoted per request |
The architecture is built so these are additive — feature-flagged and modular, no rebuild required.
