11 · Tracking the order to the door

• Repository — the one owner of one kind of data. It turns the server's format into the app's model.
• Composite — a repository that only reads: it asks two repositories and combines their answers. Not needed here.
• Store — in-memory state that several screens show at once. Here: the tracking screen and the Home banner.
• Use case — one user intent with a product rule. None here: the user only watches.
• View model — the screen's brain. It owns the screen's state and hands the screen one view state.
• State machine — a fixed set of statuses and the moves allowed between them.
• Version — a number the server bumps on every change. Higher is newer.
• Fix — one reported rider position, with the time it was taken.
• Stale — older than we're willing to present as current.
• Live Activity — a small live card on the lock screen and Dynamic Island, updated by push.
• Polling — asking the server again on a timer.

"What does the screen show?" → The steps (placed, picking, on the way, arriving, delivered), an ETA, and the rider on a map once she leaves the hub.

"How often does the server learn where the rider is?" → Her app reports every 5 seconds, when it has signal.

"What real-time tools do we have?" → REST, and APNs from question 10. Another team runs a socket service; nobody here has used it.

"Where else does the status show?" → A banner on Home while an order is active, and a Live Activity on the lock screen.

"How long does an order last?" → Ten minutes typically. A problem order can run an hour.

"What can go wrong?" → Cancelled by the hub, items missing, rider delayed. The server says which.

"Offline?" → Riders cross dead zones; customers sit in trains.

"Minimum OS, stack?" → iOS 17, SwiftUI, Swift 6.

Out of scope, said first: placing the order (question 6), push handling in general (question 10), chatting with or calling the rider, cancelling from the app, the rider's own app.

Required for the prompt

1. Show the status as steps. An old reply never moves it back.
2. Show the rider on a map, moving smoothly, honest when the fix is old.
3. Show an ETA that never lies: a range, and "running late" when late.
4. Keep the lock screen current with a Live Activity; open the screen from a push.

What must feel good: never an older status over a newer one · never "live" when it isn't · light on battery · right after a relaunch.

Production considerations (say, don't draw): timeouts, backoff, the Live Activity push budget, metrics. See section 12.

Optional follow-ups (add only when asked):

Sub-second rider movement     → a server-sent event stream
Offline relaunch shows the last state → persist the last snapshot
Order placed on the web       → push-to-start the Live Activity
Chat with the rider           → a socket, because it's two-way

"I'll start simple and add each of these when the requirement appears."

"The server owns the order's state and bumps a version on every change. A tracking repository calls GET /orders/active at launch and on foreground, GET /orders/{id}/tracking when polled, and PUT /orders/{id}/live-activity-token for the lock screen. A polling engine asks every 5 seconds while the app is open and an order is on the way, slower while picking, never in the background, with backoff on errors. A shared store keeps the newest snapshot per order, using a state-machine policy: newer version wins, a finished order stays finished. The view model asks a freshness policy how to word an old fix and a late ETA. When the app isn't open, the server updates the Live Activity by push."

Nine cards, one chip. OrderTracking isn't a card; it's at the top of section 6.

Not drawn: AppLifecycle over scenePhase and NetworkStatus over NWPathMonitor (card 7's triggers), the HTTPClient, and the clock the view model reads. Not on the list yet: everything under "optional follow-ups".

flowchart TB
  Tap["`**1 · Push tap**
reused from Q10`"]
  subgraph P["PRESENTATION"]
    View["`**2 · Tracking screen**
OrderTrackingView`"] -- "actions → view state" --> VM["`**3 · Tracking view model**
OrderTrackingViewModel`"]
  end
  subgraph D["DOMAIN"]
    Store["`**4 · Tracking store**
OrderTrackingStore
shared with the Home banner`"]
    Fresh["`**5 · Freshness policy**
TrackingFreshnessPolicy`"]
    Status["`**6 · Status policy**
OrderStatusPolicy`"]
    Chip["`«protocol»
OrderTrackingRepository`"]
  end
  subgraph DA["DATA"]
    Poll["`**7 · Polling engine**
TrackingPollingEngine`"]
    Live["`**8 · Live Activity engine**
OrderLiveActivityEngine`"]
    Repo["`**9 · Tracking repository**
RemoteOrderTrackingRepository
GET /orders/active
GET /orders/{id}/tracking
PUT /orders/{id}/live-activity-token`"]
  end
  Tap -- "route → screen" --> View
  VM -- "watch → snapshot" --> Store
  VM -- "age → wording" --> Fresh
  Store -- "apply → keep?" --> Status
  Store -- "watch → snapshots" --> Chip
  Fresh ~~~ Chip
  Chip ~~~ Poll
  Chip ~~~ Live
  Poll -- "poll → snapshot" --> Repo
  Live -- "token → saved" --> Repo
  Repo -. "implements" .-> Chip
  class View,VM pres
  class Store,Fresh,Status,Chip dom
  class Poll,Live,Repo data
  class Tap reuse

How to read it. Solid arrows: request → reply, asker to answerer. Dashed: implements. Grey: reused from question 10. The engines only make card 9 fetch or send; every snapshot reaches the screen through card 4.

Dependency inversion, in one line. The domain writes the one promise (the chip); card 9 keeps it, so the dashed arrow points up and the store never sees HTTP, timers or ActivityKit.

A shared store is on this sketch because the clarified prompt puts the status on two screens: this one and the Home banner. They must never disagree.

On Miro: three frames, nine cards, one chip. Point at card 6: "correctness lives in this pure function."

The model everyone shares. Mapped by card 9; the screen never sees a DTO.

enum OrderStatus: Equatable, Sendable {
    case placed, picking, onTheWay, arriving
    /// terminal
    case delivered, cancelled(reason: String)
    /// "Rider delayed": not terminal, the server moves it on
    case problem(message: String)
}

struct OrderTracking: Equatable, Sendable {
    let orderID: OrderID
    /// bumped by the server on every change
    let version: Int
    let status: OrderStatus
    /// absolute times, so an old snapshot is still right. nil = unknown
    let eta: ClosedRange<Date>?
    /// coordinate + recordedAt. nil before she leaves the hub
    let rider: RiderFix?
    let destination: Coordinate
    /// when the server built this snapshot
    let generatedAt: Date
}

1 · Push tap (reused from question 10)

Job: a tapped order push becomes .order(id), and the root opens this screen. Sign-in and account checks already happened there.

2 · Tracking screen (OrderTrackingView)

Job: draws the map, the steps and the ETA, and reports appear, disappear and map gestures.

Interface: reads viewModel.viewState; calls onAppear(), onDisappear(), userMovedMap().

Choices:

• MapKit for SwiftUI: Map(position:) with an Annotation for the rider and one for home. The camera starts at .automatic, framing both, until the user pans.
• Smoothing: each fix animates the pin with withAnimation(.linear) over the poll interval. No guessing ahead: a pin that drives past a turn is worse than one that waits.

3 · Tracking view model (OrderTrackingViewModel)

Job: turns the store's snapshot and the current time into one view state.

struct OrderTrackingViewState: Equatable {
    /// placed … delivered, with the current one marked
    let steps: [StepRow]
    /// "Arriving 18:42–18:46" · "Running a little late" · "ETA updating"
    let eta: String
    /// live, stale(label: "Updated 40 s ago"), or hidden
    let riderPin: RiderPin
    /// a cancelled or problem message, if any
    let banner: String?
}

@MainActor @Observable
final class OrderTrackingViewModel {
    init(order: OrderID, store: OrderTrackingStore, freshness: TrackingFreshnessPolicy, clock: DateProvider)

    var viewState: OrderTrackingViewState { get }

    func onAppear() async
    func onDisappear()
    func userMovedMap()
}

Choices:

• A 5-second tick re-asks the freshness policy, so "Updated 40 s ago" grows without new data.
• Steps, not a progress bar. A problem shows a banner over its step.

4 · Tracking store (OrderTrackingStore)

Job: holds the newest snapshot per active order, for this screen and the Home banner.

@MainActor @Observable
final class OrderTrackingStore {
    init(tracking: OrderTrackingRepository, status: OrderStatusPolicy)

    /// loading, loaded(OrderTracking), or unavailable (never fetched)
    func state(of order: OrderID) -> TrackingState
    /// Applies card 9's stream for the app's lifetime.
    func start() async
}

Choices:

• The stale-result guard is the version. A poll reply and a foreground fetch can land in either order; the policy keeps the newer.
• Rider fixes have their own guard, recordedAt: position updates more often than status, and a status bump must not bring an older fix with it.
• No protocol. It's in-memory state; tests use it with a fake repository.

5 · Freshness policy (TrackingFreshnessPolicy)

Job: a pure rule for what the user may be told about old data and lateness.

struct TrackingFreshnessPolicy: Sendable {
    /// < 20 s live · < 2 min stale with its age · older hidden
    func pin(for fix: RiderFix?, now: Date) -> RiderPin
    /// a range · running late after the latest · updating when old
    func eta(_ eta: ClosedRange<Date>?, generatedAt: Date, now: Date) -> ETAWording
}

Choice: ETA honesty is a product rule. Never a single minute, never "0 min", never negative: past the latest time it says "running a little late", and a snapshot older than 2 minutes says "ETA updating".

6 · Status policy (OrderStatusPolicy)

Job: the state machine. Should this snapshot replace the one we have?

struct OrderStatusPolicy: Sendable {
    /// false if not newer by version, or if current is terminal.
    /// A newer version may move a stage back (a new rider): the server's truth.
    func shouldReplace(_ current: OrderTracking?, with incoming: OrderTracking) -> Bool
}

Choices:

• Version decides order, the machine decides finality. delivered and cancelled never reopen; everything else follows the server's newest version.
• Rejected: "stage only moves forward". A reassigned rider is a real move back to picking. Comparing stages would hide it.

7 · Polling engine (TrackingPollingEngine)

Job: while the app is open and an order is active, makes card 9 fetch on a timer.

@MainActor
final class TrackingPollingEngine {
    init(tracking: TrackingRefresher, lifecycle: AppLifecycle, network: NetworkStatus)
    /// At launch. Triggers: foreground, background, network back, order finished.
    func start()
    func stop()
}

Choices:

• Cadence by stage: 15 s while picking, 5 s on the way and arriving, none once terminal.
• Background = stop. iOS suspends the app anyway; the Live Activity and alert pushes cover it. Foreground or network back = fetch at once.
• Errors back off, 5 → 10 → 20 → 30 s, reset on success.

8 · Live Activity engine (OrderLiveActivityEngine)

Job: starts the lock-screen card when an order begins, sends its push token, updates it while the app is open, and ends it.

@MainActor
final class OrderLiveActivityEngine {
    init(tracking: LiveActivityTokens, snapshots: TrackingStream)
    /// At launch: re-attaches to running activities, then follows snapshots.
    func start()
}

Choice: the server is the writer when the app is closed. Both writers stamp generatedAt as the update's timestamp, so the system ignores whichever is older (section 10).

9 · Tracking repository (RemoteOrderTrackingRepository)

Job: calls the three endpoints, maps TrackingDTO to OrderTracking, and publishes every snapshot it gets.

/// Domain: the store's promise
protocol OrderTrackingRepository: Sendable {
    /// Every snapshot fetched, for every order, in arrival order (not version order).
    /// Replays the latest per order on subscribe. One stream per caller.
    /// Finishes when the caller's task is cancelled.
    func snapshots() -> AsyncStream<OrderTracking>
}

/// Data-internal: card 7's promise
protocol TrackingRefresher: Sendable {
    /// Throws on failure; cancelling cancels the request.
    func refreshActive() async throws
    func refresh(_ order: OrderID) async throws
}

/// Data-internal: card 8's promise
protocol LiveActivityTokens: Sendable {
    /// Retried until it lands or the order ends.
    func send(_ token: Data, for order: OrderID) async throws
}

actor RemoteOrderTrackingRepository: OrderTrackingRepository, TrackingRefresher, LiveActivityTokens, TrackingStream {
    init(http: HTTPClient)
}

Choice: one actor, small promises per caller. It publishes in arrival order and doesn't judge; judging is card 6's job, in the store.

Why these parts, and no more. Each card changes for one reason:

No use case: the user only watches, and loading has no rule. Not added: a composite (one source), a socket, persistence, a DI container.

Flow 1 — opening the screen, then a late reply.

sequenceDiagram
  participant P as Polling engine
  participant R as Tracking repo
  participant S as Store
  participant VM as View model
  P->>R: refresh(8F3K)
  R->>R: GET /orders/8F3K/tracking
  Note over R: slow reply, version 6
  P->>R: refresh(8F3K) on foreground
  R-->>S: version 7, on the way
  Note over S: newer, keep
  S-->>VM: on the way, fix 3 s old
  R-->>S: version 6, picking
  alt older version
    Note over S: drop it
  else current is delivered
    Note over S: terminal, drop anything
  end

Flow 2 — the app goes to the background, then the order arrives.

sequenceDiagram
  participant P as Polling engine
  participant L as Live Activity engine
  participant A as APNs and ActivityKit
  participant R as Tracking repo
  L->>R: send(token, 8F3K)
  Note over P: background, stop
  A->>A: liveactivity push, arriving, stale in 3 min
  A->>A: liveactivity end, delivered
  Note over P: foreground, fetch now
  P->>R: refresh(8F3K)
  alt loaded
    R-->>L: delivered, version 9
    Note over L: already ended, nothing to do
  else failed
    R-->>P: error
    Note over P: back off, try in 5 s
  end

GET /v1/orders/active
    → { "orders": [ <tracking> ] }

GET /v1/orders/{id}/tracking
    → { "orderId": "8F3K", "version": 7, "status": "onTheWay",
        "problem": null,
        "eta": { "earliest": "2026-10-20T18:42:00Z", "latest": "2026-10-20T18:46:00Z" },
        "rider": { "firstName": "Ana", "lat": 52.52, "lng": 13.40,
                   "recordedAt": "2026-10-20T18:37:55Z" },
        "destination": { "lat": 52.53, "lng": 13.41 },
        "generatedAt": "2026-10-20T18:38:00Z" }

PUT /v1/orders/{id}/live-activity-token   { "token": "…hex…" }   → 204

ActivityKit push the server sends (apns-push-type: liveactivity):
{ "aps": { "timestamp": 1792521480, "event": "update",
           "content-state": { "status": "arriving", "etaLatest": 1792521960 },
           "stale-date": 1792521660 } }

• A version on every change, so the client can order replies it receives out of order.
• Times, not durations. "18:46" stays true in an old snapshot; "8 min" doesn't.
• Personal, never cached on a shared CDN. Map tiles are Apple's, not ours.

The decision: poll while the app is open; let the server push (alerts and Live Activity updates) when it isn't.

1. Open, order on the way: poll every 5 s. The rider only reports every 5 s, so a stream can't be fresher than that.
2. Backgrounded: stop. Only push works there anyway, and polling can't run in a suspended app.
3. Returning: fetch at once; the version guard sorts whatever lands.
4. Errors: back off to 30 s, and say "Updating…" instead of pretending.

Switch condition: sub-second movement, or poll volume that hurts the server. Then server-sent events first, read with URLSession.bytes(for:): one-way, plain HTTP, the same snapshot shape. A URLSessionWebSocketTask only when the client must talk back, like chatting with the rider.

Rejected: a WebSocket now. Two-way plumbing for a one-way feed, on a new service.

The decision: a Live Activity started when the order is placed, updated by ActivityKit pushes, ended by whoever sees the end first.

1. Start in the foreground. At the order-placed moment the app is open: check areActivitiesEnabled, then Activity.request(attributes:content:pushType: .token). Static attributes: order ID, hub. Content: status, ETA, rider's first name. Under 4 KB, so no map.
2. Send the token, every time it changes. Watch pushTokenUpdates and PUT /orders/{id}/live-activity-token each new one; the server addresses updates to it.
3. Updates carry a stale date. Each one sets staleDate (and stale-date in the push) about 3 minutes ahead. If pushes stop, the card shows it's outdated instead of lying. Stage changes go at priority 10; ETA drift at priority 5, to stay inside the push budget.
4. End with final content. On delivered or cancelled, end(_:dismissalPolicy:) with the final state; .default keeps it on the lock screen for up to four hours.

The 8-hour limit. A Live Activity can be active for up to eight hours; then the system ends it, and it stays on the lock screen up to four more. A 10-minute order never gets near it; a problem order stuck for hours does, so the app and alert pushes remain the source of truth.

Two writers, one rule. In the foreground the app can update the card too, via update(_:alertConfiguration:timestamp:) (iOS 17.2+). Both pass generatedAt; the system ignores anything older than what it already shows. That's the version guard again, enforced by the OS.

Order placed on the web? The app normally starts one only in the foreground. From iOS 17.2, pushToStartTokenUpdates gives a token the server can use to start one. A later rung.

The decision: nothing on the phone runs while killed, so the server keeps the lock screen current; on return, show nothing old as if it were new.

1. Killed: no polling, no store. The Live Activity and alert pushes keep arriving, server-driven. If they stop, the stale date greys the card.
2. Relaunched from a push: the tap routes to .order(8F3K) (question 10). The store is empty, so the screen says "Getting your order…" while GET /orders/active runs. No guessed status.
3. Offline in a tunnel: keep the last snapshot. The freshness policy does the talking: the pin dims with "Updated 50 s ago", then hides; the ETA reads "ETA updating". A small "Offline" line, never an error screen.
4. Back online: the network trigger fetches at once. Whatever arrives passes the version guard, so a delayed old reply can't move the steps back.

Delivered meanwhile? The first fetch says so; the Live Activity engine ends anything still running.

Rejected: a saved snapshot shown as current at relaunch. It could say "picking" for an order that arrived. If persisted, show it dimmed with its time.

Failures

Production notes (short, not on the board)

• Networking: a 5 s timeout per poll; one poll in flight per order; honour Retry-After on 429.
• Battery: no customer location, no background work, the map only while visible.
• Metrics: snapshot age when shown, out-of-order drops, ETA error, Live Activity stale rate.

Scale, back of the envelope, with the interviewer's numbers:

orders a day × minutes watched × polls a minute = tracking GETs
orders a day × updates per order                = Live Activity pushes

200,000 × 3 × 12 is about 7 million small GETs a day, around 80 a second. Ten updates per order is 2 million pushes. Neither changes the client.

Grow only when asked

Smoother rider        → server-sent events, same snapshot shape
Relaunch offline      → persist the last snapshot, shown dimmed
Order from the web    → push-to-start token (iOS 17.2+)
Two orders at once    → the store already keys by order; relevance score on each Live Activity
Chat with the rider   → a socket, two-way at last

Answer out loud first, then open.

Scope and architecture

The state machine

Map and ETA

Transport and background

Live Activities

Production and change

14+ is a pass.A zero names the thing to read about next.:::