GET /driver/auth/check-phone?phoneNumber=9876543210 — no authentication.

Called from the mobile-number screen before any OTP is sent, so the app knows where the driver will land once verification succeeds. The backend decides this, not Flutter. Do not infer "returning driver" from local storage or from the number looking familiar.

POST /driver/auth/send-otp

POST /driver/auth/verify-otp

FCM token is stored immediately on success so ride requests / admin notifications can reach the device before any further screens load.

OTP value itself is never sent via push — SMS only.

• Validate mobile locally before calling send-otp.
• Disable Verify button while request in flight.
• Store tokens in encrypted local storage.
• Resend FCM token to backend whenever Firebase refreshes it, not just at login.

This replaces a direct multipart-to-backend upload. Required for production; acceptable to defer only if you are knowingly trading it for MVP speed, with a firm plan to cut over before real users register (see migration note in §1 — cutting over after drivers already have data under the old scheme is more painful than building this first).

Backend still enforces file type/size via the presign policy itself (content-type + max-size conditions on the presigned URL), and should trigger an async virus scan after upload lands in storage — this is mandatory, not optional, since these are ID and financial documents. Until scan completes:

POST /driver/auth/register — JSON (no file bytes; see §4.1) Header: Idempotency-Key: <uuid> — required (see §4.4)

• Registration token valid, mobile verified, driver doesn't already exist.
• Age ≥ 18, vehicle number format valid.
• Duplicate checks — mandatory, not conditional: Aadhaar, PAN, Driving Licence, active vehicle number. (Original draft marked Aadhaar/PAN duplicate checks as optional "if business rules require" — for a driver-facing app this must be mandatory; one identity document tied to multiple accounts is a fraud vector.)
• File type/size re-verified server-side even though presign policy already constrains it.
• UPI/bank format re-validated server-side.
• Check against banned identifiers table (§6.3) — separate from the active-duplicate check.

Applies to Aadhaar, PAN, Driving Licence, Bank Account Number, IFSC (optional), UPI ID (optional, policy-dependent).

Why not just UNIQUE on an encrypted column: AES-GCM uses a random IV per encryption, so the same real Aadhaar number produces different ciphertext every time. A UNIQUE constraint on the encrypted column will never catch a duplicate — two rows with the same real-world Aadhaar look like different values. This is the actual mechanism, not a style choice, so it can't be skipped.

Duplicate checks at registration query aadhaar_hash, never aadhaar_encrypted. Same pattern for PAN and Driving Licence (DL was flagged as "must be unique" in the source draft but not flagged for encryption — it should get both, it's as sensitive as PAN).

Never log encrypted or plaintext values, or the hash inputs, in application logs.

Store in Redis (not Postgres — this is a short-lived dedup record, not permanent data):

On repeat key within TTL: return the stored response verbatim, do not re-run registration logic. Applies to POST /driver/auth/register and PATCH /driver/profile/resubmit, and should be the default for any future state-creating endpoint (ride accept, payout request, etc.).

GET /driver/profile/review-status

Action required — every outstanding issue returned together, not one at a time:

Overall status = APPROVED only if every item is APPROVED; ACTION_REQUIRED if any item is REJECTED and none is under a permanent ban; PERMANENTLY_REJECTED overrides all if set (fraud path).

PATCH /driver/profile/resubmit Header: Idempotency-Key: <uuid> (§4.4)

Open question, not yet resolved in this doc: the flow for getting new files in place before this call. Expected: driver calls POST /drivers/documents/presign again for just the flagged fields, uploads to storage, then calls resubmit with the new keys — but this needs to be written explicitly as its own sub-flow before implementation, not assumed.

Versioning requirement: resubmitted documents must not overwrite the original object key. Use a versioned key per attempt (e.g. drivingLicenseFront_v2), keeping prior versions retrievable. Silently overwriting the original loses the audit trail of what was actually reviewed and rejected — needed for any future dispute or fraud investigation.

Driver re-uploads only flagged fields, not the full document set.

Audit log — required, not optional, for KYC-adjacent onboarding. Permanent, no deletion. Every approve/reject action must be recorded, not just reflected in a current-state reason field:

IP/device are captured on a best-effort basis (whatever the admin panel's session already has) — not a new tracking system to build, just don't drop those fields if they're already available in the request context. A single overwritable reason string (as in the original draft) loses history the moment a second review happens on the same document. Rows are never deleted, only appended — this is the mechanism that makes the audit trail actually trustworthy under dispute. Given driver payouts (§11) touch payment-aggregator-adjacent flows, treat this as a compliance requirement, not a nice-to-have.

Rationale: "is this Aadhaar already an active driver" (§4.2 unique constraint) and "is this Aadhaar permanently banned" are different business rules. A permanently-rejected driver's identifier hash sitting in the active-driver unique index doesn't stop them re-registering with a *different* Aadhaar while their original vehicle/DL stays flagged — check both tables independently at registration time.

Ship this now — no heartbeat, no Redis progress tracking, no watch-percentage validation:

One check stays server-side even at MVP (§7-MVP note): complete for module N must reject if module N−1 isn't already marked complete in the driver's record — this is a single lookup, not a build project, and it's the difference between a training requirement and a training suggestion. Everything else in §7.2/§7.3 below (heartbeat cadence validation, resume-from-timestamp, plausibility checks on watch %) is 🔵 Phase 2 — noted for the target architecture, not built now.

Quiz, MVP version: admin toggles quizRequired: true/false per module. If true: fixed 5 MCQs (not randomized — §7.4 question-bank randomization is 🔵 Phase 2), pass threshold 80%. Fail → retry quiz or re-watch, admin-configured which.

GET /driver/training/modules

language is set by admin per driver (or defaulted), never chosen client-side. Falls back to English if the assigned language's content doesn't exist for a module. locked reflects sequential-unlock state (§7.2) — Flutter uses it to render, but the backend independently enforces it (see below), it is not a UI-only rule.

Not built at MVP (§7.0) beyond the sequential-unlock check. Documented here as the target architecture for when video-completion fraud becomes an actual observed problem, not a hypothetical one:

Decided: Server-side completion validation and sequential-unlock enforcement are the target architecture; heartbeat/anti-cheat portion is 🔵 Phase 2 per §7.0 — the sequential-unlock check alone ships at MVP since it's a single lookup, not a build project.

Resume: if the app closes mid-video, Redis progress key lets playback resume from last recorded timestamp rather than restarting.

Sequential unlock — enforced server-side. POST /driver/training/complete for module N must reject (not silently ignore) if module N−1 isn't already complete in the driver's record. Flutter's disabled/locked UI state is a convenience, not the control.

POST /driver/training/complete Header: Idempotency-Key: <uuid> (per §4.4 — a duplicate submit must not double-process)

watchPercentage in the request is advisory only — backend computes the authoritative value from stored heartbeat data (§7.2) and does not trust this field for the pass/fail decision.

All modules complete → training status flips to COMPLETED, canGoOnline becomes true (reflected in Dashboard §8.1 and Profile Status §5).

Per-module or end-of-training, admin-configured (quizRequired: true/false). Pass threshold recommended 80%.

Decided: 🔵 Phase 2 — randomized question bank deferred; MVP uses a fixed 5-MCQ set per §7.0. Revisit once quiz-sharing among drivers is an observed problem, not before.

GET /driver/dashboard

driver.canGoOnline reflects training completion (§7) and approval status (§6) combined — Flutter gates the online toggle on this field, not on inferring it from multiple other calls.

Explicit online/offline toggle (driver-intentional action only — not the presence recovery mechanism, see §9.1): PATCH /driver/status

GET /driver/scheduled-rides — full list, fetched on-demand when the driver taps the summary card, not on every dashboard load.

Assignment model: customer creates a recurring schedule template (not a 30-day driver lock). A scheduled job runs 30–60 min before each occurrence, tries the preferred driver first (if online/available), falls back to nearest eligible driver if no response within a configured timeout. See §9.3 for the locking requirement on this job — concurrent job runs must not double-assign the same occurrence.

This rule applies to the dashboard and to any future screen with the same shape (summary + live fields):

Example: scheduledRideCancelled arrives → Flutter decrements scheduledRides.count locally from 4 to 3. It does not call GET /driver/dashboard again to get the new count. Refetching on every event defeats the purpose of having sockets and reintroduces the staleness window it's meant to close.

PATCH /driver/status (§8.1) is for explicit, intentional toggles only. It is never the recovery mechanism for crashes, force-kills, OS suspension, or signal loss — those cannot reliably call a REST endpoint on the way out, so presence must be transport-layer managed.

[DECIDED — see Final Decisions table] Redis is now load-bearing for online status, GEO location, and locking simultaneously — a Redis restart/failover with no persistence (AOF) or reconciliation step silently drops every driver to invisible at once. AOF persistence is enabled now (cheap to turn on, no reason to defer it); the reconciliation job (reconnecting sockets re-push GEO + online key automatically rather than requiring a manual toggle) remains a pre-production item, not urgent during the current Cloudflare/testing phase. Redis is a cache/presence layer only — PostgreSQL remains the source of truth for anything that must survive a Redis flush (driver records, ride history, wallet balances); nothing that matters long-term is ever Redis-only.

Postgres stores only last-known location + ride history — never the live location stream. Nearby-driver search uses GEORADIUS/GEOSEARCH against Redis.

Cost control on ETA ranking — calling the routing API on every eligible driver in radius doesn't scale: pre-filter to a wider pool by Redis GEO distance alone (e.g. top 30–40 nearest), then call Mappls only on that trimmed set for ETA ranking. Cache Mappls responses briefly (few seconds, keyed by rounded driver-location + pickup grid cell) since nearby drivers often share overlapping route segments. Unbounded per-candidate routing calls scale linearly with ride volume and put dispatch latency on the critical path of a third-party API.

Offer locking (prevents double-offer, not just double-accept): when a driver is selected for a broadcast round, atomically mark them offered — SET NX in Redis, TTL matching the 15s window — *before* sending the popup, not just before processing the accept. Without this, two concurrent dispatch rounds (different rides) can both select and notify the same driver simultaneously.

Per-driver offer timeout: no response within 15s → release that driver from the current offer, do not wait indefinitely on one unresponsive socket.

Each round re-runs the eligible-driver query excluding everyone already offered in a prior round (offeredDriverIds set, ride-scoped, Redis, TTL = ride's max dispatch window) — expansion must not re-notify a driver who already rejected or timed out on the same ride. No drivers found at max radius → customer sees "No drivers are currently available nearby. Please try again in a few minutes."

Mid-search cancellation: if the customer cancels while status is still SEARCHING (before any accept), all outstanding popups must close and dispatch state (offer locks, offered-driver set) must be torn down — not left to expire on their own TTLs.

Multi-server requirement: ride:takenByAnother and other cross-driver broadcasts require a shared Socket.IO adapter (e.g. socket.io-redis) once there's more than one Socket.IO server instance behind the load balancer — otherwise a broadcast only reaches drivers whose socket happens to be held by the same server instance that processed the accept, silently breaking the "close all other popups" guarantee.

Scheduled-ride assignment (§8.2) uses the identical ride_assign_lock:<rideId> pattern before the scheduler job assigns a driver to a recurring-schedule occurrence — prevents overlapping job runs from double-assigning the same occurrence.

• Heartbeat every 15–20s (also drives §9.1 TTL refresh).
• Automatic reconnect with exponential backoff.
• JWT verified at socket handshake.
• [DECIDED — see Final Decisions table] Socket re-authenticates via a refresh event 2–5 minutes before the access token actually expires — not at expiry. Refreshing ahead of the deadline is what avoids an actual disconnect gap; refreshing exactly at expiry risks a race where the old token is rejected before the new one is confirmed accepted.

Canonical states (used everywhere in this module — the transition-guard implementation must validate against this exact list, not a shortened one):

CANCELLED and NO_SHOW are reachable from multiple earlier states (see §10.12–10.13) — they are not purely terminal-from-COMPLETED, they branch off mid-flow.

Backend must reject invalid transitions (e.g. COMPLETE before START, START before OTP_VERIFIED, ARRIVED after COMPLETED) using the full state list above, not a subset — this matters most under retries on poor network conditions, where a duplicate/out-of-order request is the actual attack surface, not a hypothetical.

POST /rides/{rideId}/accept Header: Idempotency-Key: <uuid>

• Verify driver JWT.
• Acquire Redis lock (ride_assign_lock:<rideId>, per §9.3) — only the lock-winner's accept commits.
• Ride status → ASSIGNED. Driver status → BUSY. Remove driver from matching pool (§9.3).
• Fetch route (driver → pickup) via Mappls.
• All other candidate drivers receive ride:takenByAnother (per §9.3) so their popups close.

Called once after accept, not repeatedly — mid-trip guidance uses the Navigation SDK client-side (per §"one improvement" already established), backend only receives GPS pings via socket for live tracking (§9.2).

PATCH /rides/{rideId}/arrived Header: Idempotency-Key: <uuid>

Backend validates, does not trust the client's claim of arrival:

Pass → status ARRIVED, waiting timer starts (§10.4). Fail →

Starts only after geofence validation succeeds — never on the raw "I've Arrived" tap.

At maximum, driver gets a Customer No Show → Cancel Ride action.

PATCH /rides/{rideId}/no-show Header: Idempotency-Key: <uuid>

• Status → NO_SHOW.
• No-show fee applied per business policy — charging mechanism must be explicit: deduct from customer's stored payment method or wallet balance. If neither exists (COD-only customer), post the fee as a blocking negative balance on the account rather than attempting a charge with no valid target.
• Driver released → status ONLINE, re-added to Redis GEO matching pool immediately.

Generated only on transition to ARRIVED (not at booking) — Redis-stored, TTL 10 min, pushed via FCM to customer app. No SMS needed (customer already has the app open).

POST /rides/{rideId}/verify-otp Header: Idempotency-Key: <uuid>

Success → status OTP_VERIFIED, OTP deleted from Redis immediately (not left to expire).

PATCH /rides/{rideId}/start Header: Idempotency-Key: <uuid> — required here specifically because a retried start call must not overwrite start_time/start_lat/start_lng a second time with a later value.

Stores once: start_time, start_lat, start_lng. Fetches route (pickup → destination) once via Mappls; Navigation SDK + client-side rerouting handles the rest.

Same transport as §9.2 — no separate mechanism.

PATCH /rides/{rideId}/complete Header: Idempotency-Key: <uuid>

Stores: end_time, end_lat, end_lng, actual_distance, actual_duration. Driver released → ONLINE, re-added to Redis GEO. Triggers fare finalization (§10.14).

Every state-mutating endpoint above (accept, arrived, no-show, verify-otp, start, complete, cancel) requires Idempotency-Key per the policy already defined in §4.4. A repeated request with the same key returns the stored original response — it never re-executes or partially overwrites state.

POST /rides/{rideId}/cancel (actor: customer) Header: Idempotency-Key: <uuid>

Driver released back to matching pool, status → CANCELLED. Penalty per business rules (e.g. free before driver accepts, fee after driver is en route).

POST /rides/{rideId}/cancel (actor: driver) Header: Idempotency-Key: <uuid>

Request field: reason — enum, not free text (customer_unreachable, wrong_pickup_location, vehicle_issue, personal_emergency, other). Ride re-enters dispatch (§9.3) for a new driver. Cancellation rate is tracked per driver with reason breakdown, not as a single undifferentiated rate — a driver correctly cancelling because of a bad pickup pin should not count the same as a driver cancelling to avoid a low fare.

• Cancellation rate (trailing 20 rides) tracked continuously per driver.
• Admin dashboard shows a color band: 🟢 0–20% · 🟡 20–30% · 🔴 above 30% — reduces manual monitoring load without needing full automation.
• Automatic in-app warning notification fires the moment a driver crosses 20% — the driver is told, not just tracked silently.
• No automatic suspension: admin makes the suspension call manually, informed by the color band and reason breakdown, not by an automatic rule.

🔵 Phase 2: automatic suspension at the 30% threshold (e.g. 48h dispatch hold pending review), once real cancellation-rate baseline data exists to calibrate the threshold with confidence — thresholds set from zero production data risk over- or under-penalizing drivers.

Estimated fare (shown at booking): distance matrix + ETA + pricing rules. Final fare (computed at complete): actual GPS distance + actual duration + waiting charges + tolls (if applicable) + surge.

Decided: Surge pricing is locked at booking — the customer-trust-friendly option over the revenue-protective alternative (surge floating to actual trip time). Chosen as the simpler, more supportable default for launch.

Customer always sees an itemized breakdown (base + distance + time + waiting + toll + surge), not just a total.

Customer ↔ driver calls proxy through a telephony provider (e.g. Exotel) using a virtual number pair — neither party's real number is exposed to the other's device dialer or call log. Both directions required: customer-initiates-call-to-driver (as originally specified) and driver-initiates-call-to-customer (common in practice — driver asking "which gate/entrance" — and not covered in the source flow, needs the same virtual-number mechanism, not a plain tel: fallback for this direction only).

Only Available Balance is withdrawable. Balance is never updated directly — every change is a ledger transaction (§11.10); the displayed balance is derived from the ledger, not a mutable field.

GET /driver/wallet

POST /driver/wallet/withdraw Header: Idempotency-Key: <uuid> (per §4.4/§10.10 convention)

Backend, in a single transaction:

The amount is reserved at request time, not at settlement — this is what prevents two concurrent withdraw taps (or a withdraw racing a cash-ride debit) from both passing a stale balance check.

Admin-configured settlement time (e.g. daily 5PM). Worker:

Immediately before calling Razorpay, re-check (state may have changed since the original request):

If the wallet has gone negative since the request (e.g. a cash ride collected in the interim):

Reserved money stays reserved (not returned to available, not paid out) while held. On-hold requests must not sit indefinitely — auto-cancel after a configured max hold period (e.g. 7–14 days) and return the reserved amount to available_balance net of whatever outstanding amount remains, with driver notification, rather than freezing the driver's money with no resolution path.

MVP: minimum withdrawal ₹500, maximum withdrawal ₹10,000, settlement processed at three admin-configured daily windows (e.g. 11AM / 3PM / 7PM) rather than a single daily run. No admin approval gate at MVP — since the max withdrawal (₹10,000) equals the threshold that would trigger review, every withdrawal in practice settles automatically. This is a deliberate MVP simplification, not an oversight: raising the max-withdrawal cap later is the trigger to re-enable the threshold gate below, at which point it starts actually filtering requests rather than sitting dormant.

🔵 Phase 2 target architecture (kept in the doc, inactive at current caps): withdrawals above a configurable threshold require explicit admin approval before the settlement worker will process them; withdrawals at or below the threshold flow straight through §11.4 with no manual step.

Build these endpoints now even though the gate is inactive at MVP caps — they're also the admin's manual dispute/reversal tool regardless of the threshold question, and cost nothing extra to have ready. The settlement worker query in §11.4 must explicitly exclude anything still pending the admin gate once it's active — a request rejected at 4:59PM must not be picked up by a 7:00PM run that doesn't check the gate.

Every payout call carries its own idempotency key to Razorpay (separate from the internal request header), keyed to the internal withdrawal ID:

This protects against the settlement worker itself retrying a timed-out call to Razorpay — without it, a retry after a network timeout can create a second real payout for one withdrawal request. Razorpay returns the original payout instead of creating a duplicate when the key repeats.

Never trust the Flutter success callback or the synchronous API response — only the webhook confirms money actually moved.

Webhook redelivery (normal Razorpay behavior, not an edge case) must not double-process — the event-ID check above is what makes that safe, not "we only trust webhooks" alone.

Payout failure: status → FAILED, reserved amount returned pending_withdrawal → available_balance, driver notified with reason, no ledger debit recorded (money never actually left).

POST /driver/wallet/pay-outstanding — Razorpay Checkout.

Hard rule: the Flutter checkout success callback never unblocks the driver or clears outstandingBalance — only the server-side payment.captured webhook does, verified with the same event-ID dedup pattern as §11.8. A client-side callback is spoofable; only clear the block, update the wallet, and resume dispatch eligibility after backend-side webhook confirmation.

POST/PATCH /driver/bank-account must not mark bankVerified: true on save alone.

MVP: account status is PENDING_VERIFICATION immediately on save and stays there until admin manual review (submitted details shown alongside the driver's registered KYC name for visual cross-check) flips it to VERIFIED or REJECTED. Only VERIFIED accounts pass the §11.5 revalidation gate before payout. This is weaker than penny-drop but non-zero, and matches the current testing-phase reality of low withdrawal volume where manual review is actually feasible.

Phase 2: swap manual review for penny-drop verification (Razorpay/Cashfree — a ₹1 test transfer confirms the account-holder name matches the driver's registered name programmatically), gated behind a feature flag so the switch is a config change, not a re-architecture — the PENDING_VERIFICATION → VERIFIED/REJECTED state model stays identical, only what triggers the transition changes. This becomes a hard requirement once payout volume grows past what admin can manually eyeball — a bank account belonging to someone other than the registered driver is a real fraud vector that manual review only slows down, not eliminates.

Every action creates a transaction record — the wallet balance is a derived sum, never written directly:

Table structure — deliberately includes balance_before/balance_after on every row even without double-entry accounting, so a proper ledger can be introduced later without redesigning the table:

This alone gives dispute resolution, withdrawal history, and an audit trail without needing full double-entry bookkeeping — and balance_before/balance_after on every row means a future migration to double-entry has a verifiable trail to reconcile against, rather than starting from a single running total with no history of how it got there.

Double-entry bookkeeping — out of scope for v1. It was proposed with an incorrect example (both legs shown as debits to different accounts, which doesn't balance to zero and would never reconcile against Razorpay/bank statements). The single-entry ledger above is correct and sufficient on its own for MVP. If double-entry is wanted later — genuinely useful once transaction volume and internal accounts multiply — it needs a proper chart of accounts (Driver Wallet as a liability account, Speedoo Bank/Cash as an asset account, Platform Revenue as its own account, with real matching debit/credit pairs) built with an accountant or someone who owns the books, not derived from this doc.

All business-rule values configurable from admin — no deploy required to change pricing.

Two independent fields per benefit, as established: Category (icon/grouping/analytics — Vehicle Service, Restaurant, Education, Welcome Kit, Medical, Fuel, Coupon; Medical/Fuel/Coupon reserved for Phase 2 benefits, kept in the enum now so adding those benefits later needs no schema change) and Fulfillment Type (drives the UI action and workflow).

🟢 MVP fulfillment enum — matches Phase 1 benefits exactly (§12 intro):

Fulfillment Type stays the authoritative enum regardless of phase — no new value ships without a defined workflow or an explicit stateless designation, per the pattern above.

POST /admin/benefits

Eligibility rule kind matters for state behavior: count/hours/referral-based rules (TOTAL_RIDES, ONLINE_HOURS, REFERRAL_COUNT) are monotonic — once reached, eligibility is permanent. Rate-based rules (RATING_ABOVE, ACCEPTANCE_RATE_ABOVE, CANCELLATION_RATE_BELOW) can cross back below threshold. Decided: Rate-based eligibility is locked in at the moment first reached and does not get revoked if the rate later drops — silently pulling back an already-shown "eligible" badge is worse for driver trust than the alternative.

GET /driver/benefits

progress, eligible, and expiryDate are required fields, not optional — the driver rewards screen's progress bars and eligibility badges depend on them; a stripped-down list response loses that UI. Filtered server-side by the requesting driver's vehicleType and city against the benefit's configured vehicleTypes/cities — a driver never sees a benefit they're categorically excluded from, not shown-then-rejected on claim.

GET /driver/benefits/{id} — full details (terms, partner, documents required, expiry) per benefit.

POST /driver/benefits/{id}/action Header: Idempotency-Key: <uuid> — required; a duplicate tap on Book/Apply/Claim must not create two bookings/applications/claims.

Backend re-validates eligibility, claim limits, expiry, and driver-active status on every call regardless of type — this is not a one-time check performed only when the badge first turned "eligible."

Request body shape is determined by the benefit's fulfillmentType (backend dispatches internally; each shape is a stable contract Flutter can rely on):

Response varies correspondingly (QR image + token + 5-min expiry / booking confirmation / application ID + status / claim ID + tracking status).

Immutable, same pattern as the wallet ledger (§11.11) — never update a points total directly:

Balance is always derived from the ledger.

Progress is computed on the relevant event (ride completed, rating received, referral confirmed), not recalculated on every app open:

POST /partner/offers/redeem — requires partner-level authentication (API key or partner JWT), not just a valid QR token. A valid-looking token alone doesn't establish that the caller is the authorized partner; without caller auth, a token interception or replay against any endpoint can redeem a driver's benefit ahead of the legitimate partner. This applies even though the partner-facing portal UI itself is future scope (§15 of the source material) — the auth model for this endpoint isn't deferrable just because the UI is.

Backend checks: token not already used, not expired (5 min from generation), driver still eligible/active → mark REDEEMED.

Ticket states: OPEN → IN_PROGRESS → RESOLVED → CLOSED (or REOPENED from RESOLVED if the driver replies again within a configurable window, e.g. 7 days — after which a reply creates a new ticket rather than reopening an old one).

Emergency SOS (already referenced in the ride-lifecycle bottom card, §10) gets its own path, separate from the general ticket system — it needs to reach a human faster than a support queue:

Triggers immediate admin/ops alert (not a queued ticket) with driver location and active-ride context attached. Define the actual escalation path (ops dashboard alert, SMS to a duty number, or integration with local emergency services) before this ships — an SOS button that just creates a normal-priority ticket defeats its purpose.

app-config should be checked at every cold launch (same pattern as §5 profile status) — this is how you handle a critical bug fix or policy change without waiting on app-store review lag, by gating access at the config level rather than the code level.

Invalidates the current device's refresh token server-side (not just a client-side token wipe — per §3, AUTH_LOGOUT_REMOTE push exists specifically because sessions can be revoked from the backend, so logout must actually reach the backend, not just clear local storage) and unregisters the FCM token for this device.

Distinct from logout — this is a driver requesting account closure. Given the KYC/financial data on file (§4, §11), this should route to admin review rather than execute instantly (outstanding wallet balance, active rides, pending withdrawals all need resolution first).

Consolidates error codes introduced across modules — new codes should be added here as they're introduced, not left scattered.

*(Extend this table as each remaining module — Ride cancellation edge cases, Settings, etc. — introduces new codes.)*

(Duplicated from §2 for quick reference — keep both in sync if this ever changes.)