Design a Ride-Hailing Rider App

+----------------+     +--------------------+     +----------------------+
|  MapScreen     |<--->|  TripViewModel     |<--->|  TripStateMachine    |
|  MKMapView +   |     |  @Observable       |     |  pure Swift, tested  |
|  bottom sheet  |     +----+----------+----+     +----------------------+
+-------+--------+          |          |
        ^                   |          v
        |                   |     +----------------------+
+-------+--------+          |     |  TripAPI (REST)      |  estimate, request,
| DriverMarker   |          |     |                      |  cancel, active trip
| Animator       |          |     +----------------------+
+-------+--------+          v
        ^           +--------------------+
        +-----------|  LiveTripChannel   |  WebSocket: trip updates +
                    |                    |  driver locations
                    +--------------------+
+--------------------+                       +----------------------+
|  LocationService   |  pickup location      |  APNs + Live Activity|
|  CLLocationUpdate  |---------------------->|  (app in background) |
+--------------------+                       +----------------------+

struct Coordinate: Codable, Sendable, Equatable {
    let lat: Double
    let lng: Double
}

struct DriverLocation: Codable, Sendable {
    let coordinate: Coordinate
    let heading: Double           // degrees, 0 = north
    let timestamp: Date
    let seq: Int64                // grows with each update: drop old ones
}

struct Driver: Codable, Sendable {
    let id, name, carModel, plate: String
    let rating: Double
    let photoURL: URL
}

struct Money: Codable, Sendable {
    let amountMinor: Int          // cents; never use Double for money
    let currency: String          // "USD"
}

enum TripState: String, Codable, Sendable {
    case searching, driverAssigned, driverArrived, onTrip
    case completed, cancelled, noDriversFound
}

struct Trip: Codable, Sendable, Identifiable {
    let id: String
    var state: TripState
    let pickup: Coordinate
    let dropoff: Coordinate
    var driver: Driver?
    var etaSeconds: Int?
    var fare: Money?
    var version: Int              // the server adds 1 on every change
}

struct TripRequest: Codable, Sendable {
    let pickup: Coordinate
    let dropoff: Coordinate
    let productID: String         // "economy", "xl", ...
}

POST /v1/estimates          { pickup, dropoff }      -> [{ productID, fare, etaSeconds }]
GET  /v1/drivers/nearby?lat=..&lng=..                -> [Coordinate]  (before a trip)
POST /v1/trips              Idempotency-Key: <uuid>  -> Trip
GET  /v1/trips/active                                -> Trip or 204
POST /v1/trips/{id}/cancel                           -> Trip
wss://rt.example.com/v1/trips/{id}                   -> events: tripUpdated, driverMoved

enum TripEvent: Sendable {
    case tripUpdated(Trip)
    case driverMoved(DriverLocation)
}

protocol TripAPI: Sendable {
    func estimate(pickup: Coordinate, dropoff: Coordinate) async throws -> [Estimate]
    func requestTrip(_ request: TripRequest, idempotencyKey: UUID) async throws -> Trip
    func activeTrip() async throws -> Trip?
    func cancel(tripID: String) async throws -> Trip
}

protocol LiveTripChannel: Sendable {
    func events(tripID: String) -> AsyncThrowingStream<TripEvent, Error>
}

protocol LocationProviding: Sendable {
    func currentLocation(accuracy: CLLocationAccuracy) async throws -> Coordinate
}

            +------------+   no car    +-----------------+
 request -->| searching  |------------>| noDriversFound  |
            +-----+------+             +-----------------+
                  | driver accepts
                  v
            +----------------+  driver cancels (search again)
            | driverAssigned |---------------------------> searching
            +-----+----------+
                  | driver at pickup
                  v
            +----------------+
            | driverArrived  |
            +-----+----------+
                  | trip starts
                  v
            +----------------+    trip ends    +-------------+
            |    onTrip      |---------------->|  completed  |
            +----------------+                 +-------------+

  searching / driverAssigned / driverArrived --(rider or driver cancels)--> cancelled

import os

struct TripStateMachine {
    private(set) var trip: Trip?
    private let logger = Logger(subsystem: "app.rides", category: "trip")

    static let allowed: [TripState: Set<TripState>] = [
        .searching:      [.driverAssigned, .noDriversFound, .cancelled],
        .driverAssigned: [.driverArrived, .searching, .cancelled],
        .driverArrived:  [.onTrip, .cancelled],
        .onTrip:         [.completed],
        .completed: [], .cancelled: [], .noDriversFound: []
    ]

    mutating func apply(_ update: Trip) {
        if let current = trip {
            guard update.version > current.version else { return }   // old or duplicate
            let ok = update.state == current.state
                  || Self.allowed[current.state, default: []].contains(update.state)
            if !ok {
                // We missed events, for example while offline. The server is the truth,
                // so we accept the update. But we log it: it can also point to a bug.
                logger.warning("Jump \(current.state.rawValue) -> \(update.state.rawValue)")
            }
        }
        trip = update
    }
}

import MapKit

@MainActor
final class DriverMarkerAnimator {
    let annotation = MKPointAnnotation()
    weak var annotationView: MKAnnotationView?
    private var lastSeq: Int64 = -1
    private var lastUpdate = Date.distantPast

    func handle(_ location: DriverLocation) {
        guard location.seq > lastSeq else { return }          // old update: ignore
        lastSeq = location.seq

        let target = CLLocationCoordinate2D(latitude: location.coordinate.lat,
                                            longitude: location.coordinate.lng)
        let rotation = CGAffineTransform(rotationAngle: location.heading * .pi / 180)
        let gap = Date().timeIntervalSince(lastUpdate)
        lastUpdate = Date()

        if gap > 10 {
            // We were in the background or offline. Do not animate across the city.
            annotation.coordinate = target
            annotationView?.transform = rotation
            return
        }
        UIView.animate(withDuration: 2.5, delay: 0,
                       options: [.curveLinear, .beginFromCurrentState]) {
            self.annotation.coordinate = target
            self.annotationView?.transform = rotation
        }
    }
}

import CoreLocation

enum LocationError: Error { case unavailable }

struct LocationService: LocationProviding {
    func currentLocation(accuracy: CLLocationAccuracy) async throws -> Coordinate {
        for try await update in CLLocationUpdate.liveUpdates() {
            if let location = update.location, location.horizontalAccuracy <= accuracy {
                return Coordinate(lat: location.coordinate.latitude,
                                  lng: location.coordinate.longitude)
            }
        }
        throw LocationError.unavailable
    }
}

extension TripViewModel {
    func requestRide(_ request: TripRequest) async {
        let key = UUID()                       // one key for this tap, reused on retries
        for attempt in 1...3 {
            do {
                let trip = try await api.requestTrip(request, idempotencyKey: key)
                machine.apply(trip)
                connectLive(tripID: trip.id)
                return
            } catch {
                if attempt == 3 {
                    showError("Could not request a ride. Try again.")
                    return
                }
                try? await Task.sleep(for: .seconds(Double(attempt)))   // 1 s, then 2 s
            }
        }
    }
}

func liveLoop(tripID: String) async {
    var attempt = 0
    while !Task.isCancelled, machine.trip?.state.isActive == true {
        do {
            if let fresh = try await api.activeTrip() { machine.apply(fresh) }   // resync first
            for try await event in channel.events(tripID: tripID) {
                attempt = 0
                switch event {
                case .tripUpdated(let trip): machine.apply(trip)
                case .driverMoved(let location): marker.handle(location)
                }
            }
        } catch {
            attempt += 1
            try? await Task.sleep(for: .seconds(min(30, pow(2, Double(attempt)))))
        }
    }
}