Apps

• Rider app — Flutter, apps/rider_app. Google-first auth + phone OTP, simulate mode, EN/MS/中文, dark mode.
• Driver app — Flutter, apps/driver_app. Sign-up, onboarding funnel (incomplete → pending → approved), go online, earnings.
• Landing site — React + Vite, apps/landing. Public marketing page: rider/driver offering, 🇲🇾/🇸🇬 requirements, driver registration form, live-editable name & logo.
• Admin dashboard — this page, served by the backend at /admin. Local-dev only, no auth guard yet.

Backend & integrations

• NestJS + PostgreSQL (TypeORM, schema sync on start; DB auto-created by ensure-database.ts).
• Realtime — Socket.IO gateways /rider & /driver: live location, offers, ride status.
• Payments — Stripe charges + Connect payouts. SMS — Twilio OTP. Google — Sign-In, Maps/Places.
• Driver leads — public POST /driver-applications from the landing form → driver_applications table (kept separate from the driver-app onboarding funnel shown in the Applications tab).

Design language

Own style, not a clone: indigo accent #4F46E5, wavy headers, pill navigation. Grab/TADA used only as structural references. The landing site follows the same language.

Docs

• ARCHITECTURE.md — living design doc (stack, data model, build status).
• README.md — repo guide & conventions.
• apps/landing/README.md — landing setup, brand & copy editing.
• backend/api/README.md — backend setup & credentials.

1 · Install & run the server (backend/api)

Prerequisites: Node 20+, npm, Docker (for local Postgres — or use AWS RDS).

cd backend/api
cp .env.example .env     # then edit — see card 2
docker compose up -d     # Postgres 16 (user/pass/db: ridehailing)
npm install
npm run start:dev        # auto-creates the DB, API on :3000

This dashboard: http://localhost:3000/admin. Production: npm run build then npm run start:prod. Useful extras: npm run typecheck, npm run db:ensure.

2 · Configure the server (.env)

• DATABASE_URL — local docker: postgres://ridehailing:ridehailing@localhost:5432/ridehailing; for RDS also set DATABASE_SSL=true (+ optional DATABASE_SSL_CA_PATH).
• JWT_ACCESS_SECRET / JWT_REFRESH_SECRET — generate with openssl rand -base64 48.
• SMS_PROVIDER — console (OTP printed to server logs, zero setup) or twilio + the three TWILIO_* vars.
• GOOGLE_CLIENT_ID_WEB/ANDROID/IOS — OAuth client IDs for Google Sign-In.
• STRIPE_SECRET_KEY / STRIPE_WEBHOOK_SECRET — optional; payments run with mock data if unset.
• ADMIN_PASSWORD — protects this dashboard: every /admin/* API call needs the x-admin-token header (the login overlay handles it).
• CORS_ORIGINS — comma-separated production allowlist; unset = dev-open. Native apps are unaffected (no Origin header).
• HITCH_MAX_TRIPS_PER_DAY (default 2), PUBLIC_BASE_URL, PORT. Platform commission/flat fee/processor fee/competitor benchmark moved off env vars onto the Platform fees tab (DB-backed, admin-editable).

3 · Landing site (apps/landing)

cd apps/landing
npm install
npm run dev              # :5173, proxies /api → :3000

Production build: VITE_API_BASE_URL=https://api.example.com npm run build → static dist/ folder, host anywhere. VITE_SIMULATE_BACKEND (default true) makes the driver form fall back to a clearly-labelled simulated success when the API is unreachable — set it to false in production. The on-page booking simulator is pure client-side, always available.

4 · Flutter apps (rider & driver)

cd apps/rider_app      # or apps/driver_app
cp env.example.json env.json   # edit API_BASE_URL etc.
flutter pub get
flutter run

Config is loaded from env.json at startup (bundled asset — no --dart-define flags). Set "SIMULATE_BACKEND": "true" there to run the whole app on mock data with no backend. Google Maps keys also go in AndroidManifest / AppDelegate — see each app's README.

1 · Booking & ride lifecycle

The rider is charged when the ride is requested and refunded on cancel. Status chain: requested → matched → enRoute → arrived → inProgress → completed (or cancelled at any point before completion).

2 · Driver matching

Nearest-eligible ranking (haversine). Eligibility honors vehicle tier, Hitch daily-trip cap, destination mode, auto-accept and back-to-back queueing — all gated by feature flags. Alongside that one-at-a-time push, the Jobs tab (driver.availableJobs flag) lets any eligible driver browse and directly claim a still-unmatched ride instead of waiting for an offer.

3 · Driver onboarding & landing-site leads

Two entry points: the landing site produces leads (driver_applications), while a real Driver account is created by the driver app and walks the approval funnel reviewed in the Applications tab.

4 · Authentication (Google-first, then phone)

Google OAuth native credentials and real-device verification are still required; see docs/GOOGLE-SIGN-IN.md. Rider/driver access and refresh tokens are separated; account linking requires an existing authenticated session. Same dual path for riders and drivers: verified email immediately via Google, phone OTP optionally attached to the same account (Bearer token prevents duplicates).

5 · Payments & driver payouts

Stripe throughout: rider charge on request, refund on cancel; per-trip earnings ledger (gross / commission / net) and payouts via Stripe Connect Express.

6 · Realtime channels

Socket.IO namespaces with an in-memory presence map (Redis deferred). REST fallback for location pushes; persisted last-known position for this dashboard and cold-start matching.

7 · Content management (promos, news, home, pricing)

Everything the rider app shows that isn't a ride is edited here and served from the same API — images upload to local /uploads.

8 · Support & feedback

Support requests are a resolve-only queue; feedback is real two-way messaging with one thread per (rider, topic) — general, payment dispute, or account deletion.

Zones