# Doormile — Customer App A Flutter app for the Doormile customer journey: **Book pickup → Track → Delivered** State is a `ChangeNotifier` behind an `InheritedNotifier`; navigation is `Navigator` with named booking steps. Real maps come from `flutter_map` over OpenStreetMap/CARTO tiles and real positions from `geolocator` — no API key and no billing account required. Everything else is the Flutter SDK. ``` lib/ main.dart app entry, theme, page transitions data/ models.dart Booking, Destination, DeliveryDetails, JourneyStage… doormile_api.dart the service surface — one implementation live_doormile_api.dart ← the ONLY place the app talks to a server location_service.dart ← the ONLY place device GPS is touched map_config.dart ← the ONLY place tile URLs, attribution + keys live state/ app_state.dart single source of truth + stage transitions app_scope.dart InheritedNotifier plumbing ui/ tokens.dart colours, radii, type scale, shadows (Inter) format.dart greeting / relative time / date labels widgets/ buttons, chrome, inputs, option tiles, milestones… map_tiles.dart config → flutter_map layer, + attribution map_panel.dart real pannable map, pin locked to the centre route_map.dart real route map: polyline, hubs, live Miler screens/ auth/ login · sign up · OTP (shared brand scaffold) shell_screen.dart Home · Orders · Account bottom navigation home_screen.dart orders_screen.dart account_screen.dart order_details_screen.dart receipt for a finished order tracking_screen.dart live tracking, driven by stage booking/ pickup → destination → time → review → confirmed sheets/ place search, delivery details, cancel booking store/ Play Console listing assets ``` ## The product model this encodes The customer creates a **pickup booking**, not a shipment. Booking is four steps: ``` Home ▸ Book a Pickup 1. Pickup point map pin, pre-filled from the device location 2. Destination state → district, then "How many packages?" (defaults to 1) "+ Send to another place" adds another destination 3. Pickup time windows the backend still has capacity for 4. Review one line per place, combined estimate, Book Pickup ``` **One pickup booking → one or more destinations → order(s) created after collection.** A single Miler visit can collect packages bound for several districts; each destination becomes its own tracked order only once the Miler completes the pickup. The customer never sees carrier vocabulary — no consignment, no waybill, no AWB. * **Required:** pickup location, and for each destination a serviceable **state** + **district**. Package count defaults to 1. * **Optional:** exact street, landmark, recipient name and phone, delivery instructions — per destination, in a sheet opened from the destination card or Review. Never blocking, and shown as *"Not added — the Miler can confirm this at pickup."* * **Weight is never asked.** The Miler verifies it at pickup, which is when the price settles. * **Caps** come from `BookingLimits` (backend-served, defaults 20 packages / 5 destinations per pickup). Nothing in the UI hardcodes them. * **Cancellation** is whole-pickup only, and only while `DoormileApi.isCancellable(stage)` allows it. A customer sending one package to one district sees exactly what they saw before: pick a place, tap Next. The multi-destination machinery appears only when they ask for it. Stages shown to the customer (`JourneyStage`; raw backend keys never reach a screen): ``` Pickup booked → Miler assigned → Miler on the way → Miler arrived → Package picked up → Order created → In transit → Out for delivery → Delivered ``` **Cancellation** is offered only while `DoormileApi.isCancellable(stage)` is true — through *Miler arrived*. Once the Miler has custody the footer becomes a support action instead. ## Maps and location Both maps are real. `flutter_map` renders OpenStreetMap data through CARTO's basemaps — no API key, no billing, no per-request cost to develop against. **No widget knows a tile URL.** `lib/data/map_config.dart` is the only place a template, a subdomain list, an attribution string or a map API key exists; `lib/ui/widgets/map_tiles.dart` turns that into a layer. Changing provider is a build flag, never a map-screen edit — and a test fails the build if a URL ever reappears under `lib/ui/`. * **Pickup** (`DmMapPanel`) — the pin is welded to the centre of the map and the map moves under it. When it settles, the coordinates under the pin are reverse-geocoded and the address appears in the box below, inside the same card. Drag, and the address follows. * **The customer's own position** is a blue dot with an accuracy halo drawn at true map scale, so it shrinks as they zoom in. It is a real coordinate, not a screen overlay: dragging moves the crimson pickup pin and leaves the dot where the customer actually is, which is how they judge how far they have moved the pin from themselves. No fix means no dot — a dot in the wrong place is worse than none. * **Route** (`DmRouteMap`) — pickup and destination hub as real markers joined by the transit arc, with the Miler's live position along it. Non-interactive on purpose: it summarises a booking and must never steal a scroll gesture. * **Position** (`LocationService`) — the only place `geolocator` is touched. Every platform call is bounded by a timeout and every failure comes back as a typed `LocationDenial`, so a refused permission or a wedged plugin can never freeze the booking flow. It falls back to the service-area centre and says why. ### Choosing a tile provider CARTO is the development default and is *not* assumed to be the production contract. Everything is set at build time: ```bash # CARTO with a proper API key — the likely production step flutter build appbundle --dart-define=DM_MAP_KEY=$CARTO_API_KEY # a different vendor flutter run --dart-define=DM_MAP_PROVIDER=maptiler --dart-define=DM_MAP_KEY=… flutter run --dart-define=DM_MAP_PROVIDER=stadia --dart-define=DM_MAP_KEY=… # self-hosted or anything else flutter run \ --dart-define=DM_MAP_PROVIDER=custom \ --dart-define=DM_MAP_URL=https://tiles.doormile.in/streets/{z}/{x}/{y}.png \ --dart-define=DM_MAP_URL_MUTED=https://tiles.doormile.in/light/{z}/{x}/{y}.png \ --dart-define=DM_MAP_ATTRIBUTION='© Doormile · © OpenStreetMap contributors' ``` | Define | Effect | | --- | --- | | `DM_MAP_PROVIDER` | `carto` (default) · `osm` · `maptiler` · `stadia` · `custom` | | `DM_MAP_KEY` | Appended as the provider's key parameter (`api_key`, `key`) | | `DM_MAP_URL` / `DM_MAP_URL_MUTED` | Templates for `custom` | | `DM_MAP_SUBDOMAINS` | Comma-separated `{s}` shards | | `DM_MAP_ATTRIBUTION` / `_URL` | Credit line and licence link | | `DM_MAP_MAX_ZOOM` | Deepest native zoom the provider serves | | `DM_APP_VERSION` | Goes into the `User-Agent` | A provider that needs a key but was given none falls back to CARTO with a `warning` on the config rather than rendering a blank map. Every tile request carries `User-Agent: Doormile/ (in.doormile.customer)`, so the provider can attribute and rate-limit our traffic properly. `keepBuffer`/`panBuffer` stay at flutter_map's defaults — the app fetches the tiles it is about to draw and nothing more. There is no bulk prefetch or offline tile scraping, by design. The credit line is rendered on **every** map, its text taken from whichever provider is configured, so it stays correct after a swap. `ACCESS_FINE_LOCATION` / `ACCESS_COARSE_LOCATION` are declared on Android and `NSLocationWhenInUseUsageDescription` on iOS; GPS hardware is marked optional so Play does not filter the app off devices without it. ## Running it ```bash flutter pub get flutter run # any connected device or simulator flutter test # 88 tests covering the whole flow ``` `flutter run` talks to `https://api.doormile.com/api/v1`. Point it somewhere else with a define: ```bash flutter run --dart-define=DM_API_BASE=https:///api/v1 ``` ### Which build am I in? Every debug launch prints it as its first line: ``` [BUILD] DEV DATA (offline) · staging · no network ← the fake, any code works [BUILD] staging · https://api.doormile.com/api/v1 ← the real server ``` Check that line before anything else. The two builds are identical on screen, and the whole reason the first offline mode was deleted was that nobody could tell which one a handset was running. The Account screen says the same thing under **BUILD**, but a build that cannot get past the login screen cannot show you the Account screen — which is exactly when you need to know. **`[API] 401 …/auth/otp/verify · invalid_otp` means you are on the real server** and it refused the code. `1234` is not a real code; only the offline build accepts anything. See below. ### Two contract bugs found against production, 2026-09-23 Both were the same mistake — the client spelling a field the way the written contract spells it, where the server reads something else — and both were verified one request apart against `api.doormile.com`, same pickup, same slot. **The pickup coordinates are `lat`/`lng`, not `latitude`/`longitude`.** | sent | `POST /bookings` | | --- | --- | | `latitude` / `longitude` | **422 `unserviceable`** — "We are not collecting from that area yet" | | `lat` / `lng` | **201**, booking `DM-252803` | The server could not read the pin, could not place it in a serviceable area, and blamed the customer's address for a field name. **The app could not create a booking at all**; every serviceable district's own hub coordinates were refused as a pickup. Fixed in `Place.toJson`. **The same bug in `POST /fare/estimate` returns a wrong price instead of an error**, which is worse: | sent | local (0.2 km) | Chennai (427 km) | | --- | --- | --- | | `latitude` / `longitude` | ₹280–520, `routeKm` 0 | ₹280–520, `routeKm` 0 | | `lat` / `lng` | ₹45–90 | ₹150–280 | With the long spelling the server measures no route and answers a flat fallback band for every journey — roughly six times the real price on a local run, and the same number quoted for a parcel crossing the state. Every fare this app has shown was that fallback. Fixed in `LiveDoormileApi.estimateFare`. This is the third of these (`POST /auth/otp/verify` takes `code` where the document says `otp`). **Follow the server, not the document**, and `test/live_api_wire_test.dart` is where each one gets pinned down. ### The app cannot sign in to production Separate from the above, and still open. The real backend has no SMS gateway, so the OTP never arrives. The server does have a PIN flow — ``` POST /customer/auth/login {"phone": "+91…"} → {registered, pin_set} POST /customer/auth/verify-pin {"phone", "pin"} → {accessToken, refreshToken, customer} ``` — but the app does not use it: `login_screen.dart` calls `sendOtp`. Until those two endpoints are wired into the entrance, a booking cannot be made **from the app** against production, whatever the payload says. The QA account `+919999900001` ("Doormile QA") is registered with a PIN for exactly this. ### Signing in for development A shipping build has **one** API implementation, `LiveDoormileApi`, and it talks to a server. Nothing invented can reach a customer. But the real backend has no SMS gateway yet, so the OTP never arrives and you cannot sign in against it. Two dev-only ways in, both `!kReleaseMode` — no define can put either in a release build, and the Account screen prints the mode it is in: **Offline dev data** — the whole app, no server, any 4-digit code signs in: ```bash flutter run --dart-define=DM_MOCK=true ``` It opens **straight on Home**, already signed in as Joe Oommen — there is no server to refuse anybody, so stopping at a login screen would ask for a phone number and a code that mean nothing. Sign out and you get the real entrance, where any 10-digit number and **any 4-digit code** get you back in. This swaps in `DevDoormileApi`: in-memory serviceability, slots, fare and bookings, so you can walk signup → book → track without a backend. **A booking made here stays on the device — it reaches no server and no admin console.** The Account screen reads `DEV DATA (offline)`. **Real token** — talk to the live server, skip only the OTP round trip. Not a bypass: the server authorises every request it signs, and a revoked token signs the build straight back out: ```bash flutter run --dart-define=DM_DEV_TOKEN=eyJ... \ --dart-define=DM_DEV_REFRESH_TOKEN=... ``` **Real sign-in, no login screen** — runs the actual OTP request and verify pair at launch, so what it ends up holding is a token the server issued and a booking it makes reaches `pickupbookings` and the admin console: ```bash flutter run --dart-define=DM_LOGIN_AS=9876543210 \ --dart-define=DM_LOGIN_CODE= ``` The code has to be one the server will take. Two ways to have one: set `CX_STAGING_OTP` on a non-production backend (a fixed code, refused outright when `ENV=production`), or read the code the backend logged — with no SMS gateway registered its `logSender` writes every code to the application log and reports the send as successful. ### Walking a booking through its stages Against dev data, the tracking screen's stepper walks the in-memory booking. Against a non-production backend it drives the server's own QA helper (`POST /customer/ops/bookings/{ref}/stage`) — each tap posts and re-reads, so what appears is the stage the **server** recorded: ```bash flutter run --dart-define=DM_API_BASE=https:///api/v1 \ --dart-define=DM_ALLOW_STAGE_OVERRIDE=true ``` The backend gates it too, with `CX_ALLOW_STAGE_OVERRIDE`. The app refuses to send it on production regardless. ### Walking a booking through its stages On a non-production backend, the tracking screen can offer a stepper that drives the server's own QA helper (`POST /customer/ops/bookings/{ref}/stage`). Each tap posts and then re-reads the booking, so what appears is the stage the **server** recorded: ```bash flutter run --dart-define=DM_API_BASE=https:///api/v1 \ --dart-define=DM_ALLOW_STAGE_OVERRIDE=true ``` The backend gates it too, with `CX_ALLOW_STAGE_OVERRIDE`. The app refuses to send it on production regardless. ## The backend Every screen's data comes from `lib/data/live_doormile_api.dart`, which is a thin translation between the app's models and the wire contract — the transport concerns (envelope, error codes, bearer auth and its silent refresh, idempotency, `ETag`, keyset paging, retries) all live in `api_client.dart`. `DmAsyncList` wraps every backend-driven list, so loading skeletons, empty states and retry-on-error come with any new endpoint for free. `District` carries `lat`/`lng` for its hub, which is what the route map draws to; without them it simply draws the pickup end. Still to wire: push notifications (`POST /customer/devices` is implemented but no SDK produces a token), deep links (`GET /customer/orders/{trackingId}` is implemented but no intent filter or URL type is registered), and a post-booking edit screen for `PATCH …/destinations/{i}`. The contract is in [`docs/API_READINESS.md`](docs/API_READINESS.md). ## Releasing to Google Play The app is configured for a Play upload: application ID `in.doormile.customer`, label **Doormile**, portrait only, `INTERNET` declared in the main manifest, adaptive + monochrome launcher icon, an Android 12+ splash screen, R8 shrinking on release, and backup/device-transfer disabled. 1. **Create the upload key** (once): ```bash keytool -genkey -v -keystore android/upload-keystore.jks \ -keyalg RSA -keysize 2048 -validity 10000 -alias upload ``` 2. **Point Gradle at it**: copy `android/key.properties.example` to `android/key.properties` and fill in the four values. Both the keystore and `key.properties` are git-ignored — never commit them. Without this file the release build falls back to debug signing so `flutter run --release` keeps working locally. 3. **Set the version** in `pubspec.yaml` (`version: 1.0.0+1` → `versionName` + `versionCode`); bump the build number for every upload. 4. **Build the bundle**: ```bash flutter build appbundle --release # build/app/outputs/bundle/release/app-release.aab ``` 5. **Upload** to Play Console. Listing assets are in `store/`: `play_store_icon_512.png` and `play_feature_graphic_1024x500.png`. You still need phone screenshots, a short/full description, a privacy policy URL, the data-safety form (this build collects nothing — no analytics, no third-party SDKs) and a content rating. A JDK 17 is required for Android builds (`flutter doctor` will confirm) — the one bundled with Android Studio works: `flutter config --jdk-dir "/Applications/Android Studio.app/Contents/jbr/Contents/Home"`. ## Tests The test suite is the only place a fake backend exists: `test/support/fake_doormile_api.dart`, injected through `DoormileApi.overrideInstance`. It owns its bookings and its stage machine exactly as the server does — no test reaches into `AppState` to plant one. `test/live_api_wire_test.dart` checks what the app actually puts on the wire, field by field, against the customer API document. `test/booking_flow_test.dart` drives the app end to end: signing in through the OTP screen; dragging the pickup map and watching the address re-resolve; a refused location falling back without blocking the booking; booking one package to one district with every optional field skipped; four packages to one place; three destinations with mixed counts and the review total; the package cap and destination cap; state→district serviceability filtering; packages staying together until collection and then splitting into their own orders; cancelling; a delivered order's receipt; and the empty/error/retry service-area states.