taxi-machine

Taxi Machine

Orchestrator skill for white-label transportation products. Defines the domain, flows, and how to compose the technical skills — it does not replace project-specific backend/payments.

Composed skills

Need	Skill
Screen navigation (Expo SDK 57)	`react-native-expo-navigation`
White-label UI / theme	`better-mobile-interface-react-native`
Native map	`google-maps-sdk`
Directions / Places / Geocoding HTTP	`google-maps-apis`
Route on the map	`react-native-routes`
One-off GPS	`geolocation`
Address from coordinate	`reverse-geocoding`
Live position (app open)	`react-native-realtime-location`
Driver tracking in background	`react-native-background-location`
Lock Screen / ongoing status	`react-native-live-activities`
General RN app	`react-native-development`

White-label

Per-tenant config (remote or build-time):

TenantConfig {
  brand: { name, logo, accent, colorScheme }
  legal: { privacyUrl, termsUrl, supportPhone }
  maps: { provider: google, regionBias }
  features: { scheduledRides, chat, tips, multiStop }
  payments: { provider, methods[] }
}

UI tokens derived from accent + neutrals (better-mobile-interface-react-native).
No hardcoding the client name in screens — use config.
Features via flags; do not compile dead flows if the tenant doesn't use them.

Roles

Role	Main responsibilities
Passenger	Origin/destination, estimate price, request, track, pay, rate
Driver	Online/offline, accept, navigate to pax/destination, trip status, earnings
Ops (if in scope)	Monitor trips, support, basic fraud

Separate apps or flavors/targets per role — preserve the monorepo pattern.

Trip state machine

idle → estimating → requested → matching → accepted
    → driver_arriving → waiting_pax → in_trip → completed
    → (canceled | expired | failed) a partir de requested..waiting_pax

Rules:

Transitions only in the backend (source of truth); optimistic client with reconciliation.
Stable IDs tripId; idempotency on create/cancel/pay.
Timeouts: matching without a driver → expired; waiting_pax → product no-show policy.
Canceled by whom and with a typed reason.

Mandatory flows

Passenger

Origin/destination autocomplete (google-maps-apis Places) + pin on the map.
Reverse geocode of the pin (reverse-geocoding).
Estimate (price/ETA) before the request.
Matching + Live Activity / push.
Live map of the driver (react-native-realtime-location on the driver side + socket).
Driver→pax and pax→destination route (react-native-routes).
Payment and receipt; rating.

Driver

Online toggle + location permissions (When-In-Use; Always if background).
Ride offer with timeout; accept/decline.
Navigation / route to pickup and dropoff.
Background tracking only during an active trip (react-native-background-location).
Status: arrived / started / finished.
Live Activity / ongoing notification mirroring the phase.

Map and location

SDK on the device (google-maps-sdk); routes and geocode via APIs with restricted key.
Keys: iOS/Android bundle restrictions; server key only in the backend.
Default tenant region (city bias) for Places.
Privacy: GPS trail retention aligned with policy; do not log routes in raw analytics.

Payments and compliance (high level)

Preauth/capture according to the project's provider.
Receipt and dispute: clear states in the client.
App store categories: mobility; declare background location with legitimate use.
Terms and privacy linked in onboarding.

Suggested app structure

apps/passenger/
apps/driver/
packages/domain-trip/     # tipos e transições
packages/ui-theme/        # tokens white-label
packages/maps/

Adjust to the existing monorepo.

Anti-patterns

GPS Always on with driver offline
Price only in the client without server validation
Map without loading/permission error states
Hardcoded branding preventing a second tenant
Skip estimate and go straight to charge

Completion criteria

Trip states covered in both apps (or roles)
White-label config applies branding without rebuilding logic
Maps + routes + location + live activity composed correctly
Permissions requested at the right time
Cancel/expire/payment with clear feedback
Passenger and driver happy path tested on device