Design live location tracking for a delivery app like Blinkit or Zomato.

package com.androidinterview.tracking.geo;

// A point on the ground, plus the two bits of arithmetic the rest of this
// design needs. Distances are metres and times are milliseconds everywhere,
// stated once here so nothing downstream has to guess.
public record LatLng(double lat, double lng) {

    public static final double EARTH_RADIUS_METERS = 6_371_000.0;

    // Equirectangular, not haversine. Over the couple of kilometres between a
    // dark store and a customer the error is centimetres, and this runs on
    // every fix and every animation frame. Haversine is the right call the
    // moment anything here measures a trip rather than a leg.
    public double metersTo(LatLng other) {
        double dLat = Math.toRadians(other.lat - lat);
        double dLng = Math.toRadians(other.lng - lng) * Math.cos(Math.toRadians((lat + other.lat) / 2));
        return EARTH_RADIUS_METERS * Math.sqrt(dLat * dLat + dLng * dLng);
    }

    // Straight line fraction of the way to another point. A t below zero or
    // above one extrapolates on purpose, which is what the dead reckoning in
    // the interpolator is built on.
    public LatLng towards(LatLng other, double t) {
        return new LatLng(lat + (other.lat - lat) * t, lng + (other.lng - lng) * t);
    }

    @Override
    public String toString() {
        return String.format("%.5f,%.5f", lat, lng);
    }
}

package com.androidinterview.tracking.marker;

import com.androidinterview.tracking.geo.LatLng;

// The customer app gets a point every few seconds and draws sixty frames a
// second, so this is the piece that turns one into the other. It glides the
// pin along the last leg, keeps gliding for a short window when the next point
// is late, and then stops and admits it does not know.
public final class MarkerInterpolator {

    // One animation frame's worth of truth for the customer's map.
    public record Frame(
            LatLng position,
            // Nothing has arrived for longer than it should have. The screen
            // greys the pin and shows the timestamp rather than letting a
            // frozen marker read as a rider who has stopped moving.
            boolean stale,
            long ageMillis,
            // Server time on the newest fix, which is what the "updated 2
            // minutes ago" line renders from. Never the phone's clock.
            long lastServerMillis) {}

    private final long staleAfterMillis;
    // How far past the newest fix we are willing to guess, as a fraction of the
    // leg just travelled. Half a leg smooths over one dropped packet. A whole
    // leg starts driving the pin through buildings, and a customer who walks
    // out to meet a rider who was never there is worse than a pin that paused.
    private final double deadReckonFraction;

    private LatLng from;
    private LatLng to;
    private long legStartedAt;
    private long legMillis = 1L;
    private long lastFixAt;
    private long lastServerMillis;

    public MarkerInterpolator() {
        this(15_000, 0.5);
    }

    public MarkerInterpolator(long staleAfterMillis, double deadReckonFraction) {
        this.staleAfterMillis = staleAfterMillis;
        this.deadReckonFraction = deadReckonFraction;
    }

    // The first call is the retained message the broker hands over the moment
    // the screen subscribes, so the pin is on the map before any live point
    // arrives. It places the marker rather than animating to it.
    public void onFix(LatLng position, long atMillis, long serverMillis) {
        LatLng current = from == null ? position : frameAt(atMillis).position();
        from = current;
        to = position;
        legMillis = lastFixAt == 0L ? 1L : Math.max(1L, atMillis - lastFixAt);
        legStartedAt = atMillis;
        lastFixAt = atMillis;
        lastServerMillis = serverMillis;
    }

    // Called once per frame with the phone's monotonic clock. The device clock
    // is used here and nowhere else, and only to answer "how long since we
    // heard anything".
    public Frame frameAt(long atMillis) {
        if (to == null) throw new IllegalStateException("no fix yet, subscribe before drawing");
        long age = atMillis - lastFixAt;
        boolean stale = age > staleAfterMillis;
        double raw = (double) (atMillis - legStartedAt) / legMillis;
        // Clamped at one once stale, so the pin settles on the last point we
        // actually received and stops inventing a route.
        double limit = stale ? 1.0 : 1.0 + deadReckonFraction;
        double t = Math.max(0.0, Math.min(limit, raw));
        return new Frame(from.towards(to, t), stale, age, lastServerMillis);
    }

    public boolean hasFix() {
        return to != null;
    }
}

package com.androidinterview.tracking.outbox;

import com.androidinterview.tracking.geo.LatLng;
import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.Deque;
import java.util.List;

// The rider app's answer to a basement car park. Fixes go in whether or not
// there is a connection, they leave in sequence order, and nothing is thrown
// away because a socket dropped.
public final class LocationOutbox {

    // One published point. The sequence number is per rider and strictly
    // increasing, and it is the whole reason a delivery survives a tunnel. The
    // broker delivers at least once, so the server will see duplicates, and
    // (riderId, seq) is the key it deduplicates on.
    public record Fix(
            String riderId,
            long seq,
            LatLng position,
            // Taken on the phone when the fix was taken, so a batch that
            // arrives ten minutes late still draws in the right order. The
            // server stamps its own receive time beside it, because a rider
            // whose clock is an hour out would otherwise rewrite history.
            long deviceMillis) {}

    private final String riderId;
    private final int capacity;
    private final Deque<Fix> pending = new ArrayDeque<>();
    private final Deque<Fix> inFlight = new ArrayDeque<>();
    private long nextSeq = 1L;
    private long dropped;

    public LocationOutbox(String riderId) {
        // Roughly eight hours of moving fixes. A delivery is twenty minutes,
        // so in practice this is never reached, and it is here because an
        // unbounded queue on a phone is a crash waiting for a long enough
        // outage.
        this(riderId, 6_000);
    }

    public LocationOutbox(String riderId, int capacity) {
        this.riderId = riderId;
        this.capacity = capacity;
    }

    public Fix enqueue(LatLng position, long deviceMillis) {
        Fix fix = new Fix(riderId, nextSeq++, position, deviceMillis);
        if (pending.size() + inFlight.size() >= capacity) {
            pending.pollFirst();
            dropped++;
        }
        pending.addLast(fix);
        return fix;
    }

    // Handed to the publisher. They stay in flight rather than leaving, so a
    // drop before the broker acknowledges them replays them instead of losing
    // them.
    public List<Fix> drain(int max) {
        int take = Math.min(max, pending.size());
        List<Fix> batch = new ArrayList<>(take);
        for (int i = 0; i < take; i++) {
            Fix fix = pending.removeFirst();
            inFlight.addLast(fix);
            batch.add(fix);
        }
        return batch;
    }

    // QoS 1 acknowledgement from the broker, and the only thing that deletes a
    // fix. Acknowledgements are cumulative because the sequence is.
    public void acknowledge(long seq) {
        while (!inFlight.isEmpty() && inFlight.peekFirst().seq() <= seq) inFlight.removeFirst();
    }

    // The connection died. Everything unacknowledged goes back to the front of
    // the queue, still in sequence order, and the next connect replays it.
    public void onDisconnected() {
        while (!inFlight.isEmpty()) pending.addFirst(inFlight.removeLast());
    }

    public int size() {
        return pending.size() + inFlight.size();
    }

    public long dropped() {
        return dropped;
    }

    public List<Fix> snapshot() {
        List<Fix> all = new ArrayList<>(pending);
        all.addAll(inFlight);
        return all;
    }
}

package com.androidinterview.tracking.policy;

import com.androidinterview.tracking.state.TrackingState;

// The whole battery budget of this feature is these numbers. A rider works an
// eight hour shift on one charge, so the honest framing is that a fix every
// second for the entire shift is not available to us at any price, and every
// line here is about spending the fixes where somebody is looking.
public final class LocationPolicy {

    // Maps onto the fused provider's priorities. Kept as our own enum so this
    // file stays pure JVM and testable, and so the rest of the app never has
    // to know which location library is underneath.
    public enum Accuracy { HIGH_ACCURACY, BALANCED_POWER, LOW_POWER }

    // One request's worth of settings. intervalMillis and minIntervalMillis go
    // straight into LocationRequest.Builder. The displacement filter and the
    // heartbeat are ours, because what the phone samples and what the phone
    // publishes are two different rates, and conflating them is the battery bug.
    public record Cadence(
            Accuracy accuracy,
            long intervalMillis,
            long minIntervalMillis,
            double minDisplacementMeters,
            long heartbeatMillis) {}

    // Below this the rider is parked, waiting at the store, or standing in a
    // lift. GPS jitter alone reads as roughly half a metre a second.
    private static final double STOPPED_METERS_PER_SECOND = 1.0;

    private LocationPolicy() {}

    // Null means take no fixes at all. Not a slow cadence, none.
    public static Cadence cadenceFor(TrackingState state, double speedMetersPerSecond) {
        if (state instanceof TrackingState.Arriving) {
            // The customer is watching a pin close in on their door, so this
            // is where the expensive settings are worth it.
            return new Cadence(Accuracy.HIGH_ACCURACY, 2_000, 1_000, 10.0, 20_000);
        }
        if (state instanceof TrackingState.Tracking) {
            if (speedMetersPerSecond < STOPPED_METERS_PER_SECOND) {
                // Queueing at the pickup counter. Nothing is moving, so a GPS
                // lock costs battery to redraw the same pin.
                return new Cadence(Accuracy.BALANCED_POWER, 15_000, 5_000, 30.0, 90_000);
            }
            return new Cadence(Accuracy.HIGH_ACCURACY, 5_000, 2_000, 25.0, 60_000);
        }
        return null;
    }
}

package com.androidinterview.tracking.policy;

import com.androidinterview.tracking.geo.LatLng;

// The gate between the fixes the phone takes and the points that leave it.
// Sampling at five seconds and publishing everything sampled is how a rider
// stuck at a traffic light sends four hundred identical points an hour.
public final class PublishGate {

    // A fix whose accuracy circle is wider than this is a cell tower guess.
    // Publishing it teleports the pin across two neighbourhoods and back.
    private static final double WORST_USABLE_ACCURACY_METERS = 100.0;

    private LatLng lastPublished;
    private long lastPublishedAt;

    public boolean accept(LocationPolicy.Cadence cadence, LatLng position, double accuracyMeters, long atMillis) {
        if (accuracyMeters > WORST_USABLE_ACCURACY_METERS) return false;
        if (lastPublished == null) return publish(position, atMillis);
        double moved = lastPublished.metersTo(position);
        long silentFor = atMillis - lastPublishedAt;
        // Distance filter first, heartbeat second. The heartbeat exists only so
        // the customer's screen can tell a parked rider apart from a dead one.
        if (moved < cadence.minDisplacementMeters() && silentFor < cadence.heartbeatMillis()) return false;
        return publish(position, atMillis);
    }

    private boolean publish(LatLng position, long atMillis) {
        lastPublished = position;
        lastPublishedAt = atMillis;
        return true;
    }

    public void reset() {
        lastPublished = null;
        lastPublishedAt = 0L;
    }
}

package com.androidinterview.tracking.state;

// What the rider app is doing right now, which is the single input that
// decides how often the phone asks for a fix, whether anything is published at
// all, and what the customer is allowed to subscribe to. Tracking that does
// not end is the privacy bug in this whole design, so DELIVERED is a real
// state and not a flag on TRACKING.
public sealed interface TrackingState {

    // Inside the geofence around the drop the customer sees "arriving", and
    // the phone spends its remaining battery budget there, because that is the
    // one minute of the delivery anybody actually watches.
    int ARRIVING_RADIUS_METERS = 150;

    record Idle() implements TrackingState {}

    record Tracking(String orderId) implements TrackingState {}

    record Arriving(String orderId, double distanceToDropMeters) implements TrackingState {}

    record Delivered(String orderId, long atMillis) implements TrackingState {}

    default String activeOrderId() {
        if (this instanceof Tracking t) return t.orderId();
        if (this instanceof Arriving a) return a.orderId();
        if (this instanceof Delivered d) return d.orderId();
        return null;
    }

    // The only question the location layer asks this machine.
    default boolean publishing() {
        return this instanceof Tracking || this instanceof Arriving;
    }

    // One transition table, so nothing anywhere else in the app decides it has
    // worked out that a delivery is over. Anything not listed leaves the state
    // alone, which is how a duplicate server event or a late fix arriving
    // after the drop stays harmless.
    default TrackingState on(TrackingEvent event) {
        if (event instanceof TrackingEvent.Assigned a && this instanceof Idle) {
            return new Tracking(a.orderId());
        }
        if (event instanceof TrackingEvent.DistanceToDrop d && this instanceof Tracking t) {
            return d.meters() <= ARRIVING_RADIUS_METERS ? new Arriving(t.orderId(), d.meters()) : this;
        }
        // Leaving the geofence again is normal, a rider parks, walks off to the
        // wrong gate and comes back, so this edge runs both ways.
        if (event instanceof TrackingEvent.DistanceToDrop d && this instanceof Arriving a) {
            return d.meters() > ARRIVING_RADIUS_METERS
                    ? new Tracking(a.orderId())
                    : new Arriving(a.orderId(), d.meters());
        }
        if (event instanceof TrackingEvent.DeliveryConfirmed c && publishing()) {
            return new Delivered(activeOrderId(), c.atMillis());
        }
        if (event instanceof TrackingEvent.Released) {
            return new Idle();
        }
        return this;
    }

    sealed interface TrackingEvent {
        record Assigned(String orderId) implements TrackingEvent {}

        // Recomputed from every accepted fix, which is cheap, and confirmed by
        // the server geofence, which is authoritative.
        record DistanceToDrop(double meters) implements TrackingEvent {}

        // Server confirmed, never inferred on the phone. A rider standing in
        // the right doorway has not delivered anything.
        record DeliveryConfirmed(long atMillis) implements TrackingEvent {}

        record Released() implements TrackingEvent {}
    }
}

package com.androidinterview.tracking.geo

import kotlin.math.cos
import kotlin.math.roundToInt
import kotlin.math.sqrt

// The two units this design keeps confusing itself about if they stay raw
// numbers. A distance filter in metres and an interval in milliseconds are
// both "a number that got bigger", and swapping them compiles happily.
@JvmInline
value class Meters(val value: Double) : Comparable<Meters> {
    override fun compareTo(other: Meters): Int = value.compareTo(other.value)
    operator fun minus(other: Meters): Meters = Meters(value - other.value)
    override fun toString(): String = "${value.roundToInt()}m"
}

@JvmInline
value class Millis(val value: Long) : Comparable<Millis> {
    override fun compareTo(other: Millis): Int = value.compareTo(other.value)
    override fun toString(): String = "${value}ms"
}

// A point on the ground. Deliberately not a value class, because an inline
// value class carries one field and a coordinate is two, and packing a pair of
// doubles into a Long to win the allocation would cost far more in readability
// than it saves on a phone that allocates a handful of these a second.
data class LatLng(val lat: Double, val lng: Double) {

    // Equirectangular, not haversine. Over the couple of kilometres between a
    // dark store and a customer the error is centimetres, and this runs on
    // every fix and every animation frame. Haversine is the right call the
    // moment anything here measures a trip rather than a leg.
    fun metersTo(other: LatLng): Meters {
        val dLat = Math.toRadians(other.lat - lat)
        val dLng = Math.toRadians(other.lng - lng) * cos(Math.toRadians((lat + other.lat) / 2))
        return Meters(EARTH_RADIUS_METERS * sqrt(dLat * dLat + dLng * dLng))
    }

    // Straight line fraction of the way to another point. t below zero or
    // above one extrapolates on purpose, which is what the dead reckoning in
    // the interpolator is built on.
    fun towards(other: LatLng, t: Double): LatLng =
        LatLng(lat + (other.lat - lat) * t, lng + (other.lng - lng) * t)

    override fun toString(): String = "%.5f,%.5f".format(lat, lng)

    companion object {
        const val EARTH_RADIUS_METERS = 6_371_000.0
    }
}

package com.androidinterview.tracking.marker

import com.androidinterview.tracking.geo.LatLng

// One animation frame's worth of truth for the customer's map.
data class Frame(
    val position: LatLng,
    // Nothing has arrived for longer than it should have. The screen greys the
    // pin and shows the timestamp rather than letting a frozen marker read as
    // a rider who has stopped moving.
    val stale: Boolean,
    val ageMillis: Long,
    // Server time on the newest fix, which is what the "updated 2 minutes ago"
    // line renders from. Never the phone's clock.
    val lastServerMillis: Long,
)

// The customer app gets a point every few seconds and draws sixty frames a
// second, so this is the piece that turns one into the other. It glides the
// pin along the last leg, keeps gliding for a short window when the next point
// is late, and then stops and admits it does not know.
class MarkerInterpolator(
    private val staleAfterMillis: Long = 15_000,
    // How far past the newest fix we are willing to guess, as a fraction of
    // the leg just travelled. Half a leg smooths over one dropped packet. A
    // whole leg starts driving the pin through buildings, and a customer who
    // walks out to meet a rider who was never there is worse than a pin that
    // paused.
    private val deadReckonFraction: Double = 0.5,
) {

    private var from: LatLng? = null
    private var to: LatLng? = null
    private var legStartedAt = 0L
    private var legMillis = 1L
    private var lastFixAt = 0L
    private var lastServerMillis = 0L

    // The first call is the retained message the broker hands over the moment
    // the screen subscribes, so the pin is on the map before any live point
    // arrives. It places the marker rather than animating to it.
    fun onFix(position: LatLng, atMillis: Long, serverMillis: Long) {
        val current = if (from == null) position else frameAt(atMillis).position
        from = current
        to = position
        legMillis = if (lastFixAt == 0L) 1L else maxOf(1L, atMillis - lastFixAt)
        legStartedAt = atMillis
        lastFixAt = atMillis
        lastServerMillis = serverMillis
    }

    // Called once per frame with the phone's monotonic clock. The device clock
    // is used here and nowhere else, and only to answer "how long since we
    // heard anything".
    fun frameAt(atMillis: Long): Frame {
        val start = from
        val end = to
        require(start != null && end != null) { "no fix yet, subscribe before drawing" }
        val age = atMillis - lastFixAt
        val stale = age > staleAfterMillis
        val raw = (atMillis - legStartedAt).toDouble() / legMillis
        // Clamped at one once stale, so the pin settles on the last point we
        // actually received and stops inventing a route.
        val limit = if (stale) 1.0 else 1.0 + deadReckonFraction
        val t = raw.coerceIn(0.0, limit)
        return Frame(start.towards(end, t), stale, age, lastServerMillis)
    }

    val hasFix: Boolean get() = to != null
}

package com.androidinterview.tracking.outbox

import com.androidinterview.tracking.geo.LatLng

// One published point. The sequence number is per rider and strictly
// increasing, and it is the whole reason a delivery survives a tunnel. The
// broker delivers at least once, so the server will see duplicates, and
// (riderId, seq) is the key it deduplicates on.
data class Fix(
    val riderId: String,
    val seq: Long,
    val position: LatLng,
    // Taken on the phone when the fix was taken, so a batch that arrives ten
    // minutes late still draws in the right order. The server stamps its own
    // receive time beside it, because a rider whose clock is an hour out would
    // otherwise rewrite history.
    val deviceMillis: Long,
)

// The rider app's answer to a basement car park. Fixes go in whether or not
// there is a connection, they leave in sequence order, and nothing is thrown
// away because a socket dropped.
class LocationOutbox(
    private val riderId: String,
    // Roughly eight hours of moving fixes. A delivery is twenty minutes, so in
    // practice this is never reached, and it is here because an unbounded
    // queue on a phone is a crash waiting for a long enough outage.
    private val capacity: Int = 6_000,
) {

    private val pending = ArrayDeque<Fix>()
    private val inFlight = ArrayDeque<Fix>()
    private var nextSeq = 1L

    var dropped = 0L
        private set

    fun enqueue(position: LatLng, deviceMillis: Long): Fix {
        val fix = Fix(riderId, nextSeq++, position, deviceMillis)
        if (pending.size + inFlight.size >= capacity) {
            pending.removeFirstOrNull()
            dropped++
        }
        pending.addLast(fix)
        return fix
    }

    // Handed to the publisher. They stay in flight rather than leaving, so a
    // drop before the broker acknowledges them replays them instead of losing
    // them.
    fun drain(max: Int): List<Fix> {
        val batch = ArrayList<Fix>(minOf(max, pending.size))
        repeat(minOf(max, pending.size)) {
            val fix = pending.removeFirst()
            inFlight.addLast(fix)
            batch.add(fix)
        }
        return batch
    }

    // QoS 1 acknowledgement from the broker, and the only thing that deletes a
    // fix. Acknowledgements are cumulative because the sequence is.
    fun acknowledge(seq: Long) {
        while (inFlight.isNotEmpty() && inFlight.first().seq <= seq) inFlight.removeFirst()
    }

    // The connection died. Everything unacknowledged goes back to the front of
    // the queue, still in sequence order, and the next connect replays it.
    fun onDisconnected() {
        while (inFlight.isNotEmpty()) pending.addFirst(inFlight.removeLast())
    }

    val size: Int get() = pending.size + inFlight.size

    fun snapshot(): List<Fix> = pending.toList() + inFlight.toList()
}

package com.androidinterview.tracking.policy

import com.androidinterview.tracking.geo.LatLng
import com.androidinterview.tracking.geo.Meters
import com.androidinterview.tracking.geo.Millis
import com.androidinterview.tracking.state.TrackingState

// Maps onto the fused provider's priorities. Kept as our own enum so this file
// stays pure JVM and testable, and so the rest of the app never has to know
// which location library is underneath.
enum class Accuracy { HighAccuracy, BalancedPower, LowPower }

// One request's worth of settings. interval and minInterval go straight into
// LocationRequest.Builder, minDisplacement and heartbeat are ours, because
// what the phone samples and what the phone publishes are two different rates
// and conflating them is the battery bug.
data class Cadence(
    val accuracy: Accuracy,
    val interval: Millis,
    val minInterval: Millis,
    val minDisplacement: Meters,
    val heartbeat: Millis,
)

// The whole battery budget of this feature is these numbers. A rider works an
// eight hour shift on one charge, so the honest framing is that a second by
// second GPS fix for the entire shift is not available to us at any price, and
// every line here is about spending the fixes where somebody is looking.
object LocationPolicy {

    // Below this the rider is parked, waiting at the store, or standing in a
    // lift. GPS jitter alone reads as roughly half a metre a second.
    private const val STOPPED_METERS_PER_SECOND = 1.0

    // Null means take no fixes at all. Not a slow cadence, none.
    fun cadenceFor(state: TrackingState, speedMetersPerSecond: Double): Cadence? = when (state) {
        is TrackingState.Idle, is TrackingState.Delivered -> null

        // The customer is watching a pin close in on their door, so this is
        // where the expensive settings are worth it.
        is TrackingState.Arriving -> cadence(Accuracy.HighAccuracy, 2_000, 1_000, 10.0, 20_000)

        // Under the threshold the rider is queueing at the pickup counter, and
        // a GPS lock is battery spent to redraw the same pin.
        is TrackingState.Tracking ->
            if (speedMetersPerSecond < STOPPED_METERS_PER_SECOND) {
                cadence(Accuracy.BalancedPower, 15_000, 5_000, 30.0, 90_000)
            } else {
                cadence(Accuracy.HighAccuracy, 5_000, 2_000, 25.0, 60_000)
            }
    }

    private fun cadence(accuracy: Accuracy, interval: Long, minInterval: Long, displacement: Double, heartbeat: Long) =
        Cadence(accuracy, Millis(interval), Millis(minInterval), Meters(displacement), Millis(heartbeat))
}

// The gate between the fixes the phone takes and the points that leave it.
// Sampling at five seconds and publishing everything sampled is how a rider
// stuck at a traffic light sends four hundred identical points an hour.
class PublishGate {

    private var lastPublished: LatLng? = null
    private var lastPublishedAt = 0L

    // A fix whose accuracy circle is wider than this is a cell tower guess.
    // Publishing it teleports the pin across two neighbourhoods and back.
    private val worstUsableAccuracy = Meters(100.0)

    fun accept(cadence: Cadence, position: LatLng, accuracy: Meters, atMillis: Long): Boolean {
        if (accuracy > worstUsableAccuracy) return false
        val previous = lastPublished ?: return publish(position, atMillis)
        val moved = previous.metersTo(position)
        val silentFor = atMillis - lastPublishedAt
        // Distance filter first, heartbeat second. The heartbeat exists only so
        // the customer's screen can tell a parked rider apart from a dead one.
        if (moved < cadence.minDisplacement && silentFor < cadence.heartbeat.value) return false
        return publish(position, atMillis)
    }

    private fun publish(position: LatLng, atMillis: Long): Boolean {
        lastPublished = position
        lastPublishedAt = atMillis
        return true
    }

    fun reset() {
        lastPublished = null
        lastPublishedAt = 0L
    }
}

package com.androidinterview.tracking.state

import com.androidinterview.tracking.geo.Meters

// What the rider app is doing right now, which is the single input that
// decides how often the phone asks for a fix, whether anything is published at
// all, and what the customer is allowed to subscribe to. Tracking that does
// not end is the privacy bug in this whole design, so Delivered is a real
// state and not a flag on Tracking.
sealed interface TrackingState {

    data object Idle : TrackingState

    data class Tracking(val orderId: String) : TrackingState

    // Inside the geofence around the drop. The customer sees "arriving" and
    // the phone spends its remaining battery budget here, because this is the
    // one minute of the delivery anybody actually watches.
    data class Arriving(val orderId: String, val distanceToDrop: Meters) : TrackingState

    data class Delivered(val orderId: String, val atMillis: Long) : TrackingState

    val activeOrderId: String?
        get() = when (this) {
            is Idle -> null
            is Tracking -> orderId
            is Arriving -> orderId
            is Delivered -> orderId
        }

    // The only question the location layer asks this machine.
    val publishing: Boolean get() = this is Tracking || this is Arriving
}

sealed interface TrackingEvent {
    data class Assigned(val orderId: String) : TrackingEvent

    // Recomputed from every accepted fix, which is cheap, and confirmed by the
    // server geofence, which is authoritative.
    data class DistanceToDrop(val distance: Meters) : TrackingEvent

    // Server confirmed, never inferred on the phone. A rider standing in the
    // right doorway has not delivered anything.
    data class DeliveryConfirmed(val atMillis: Long) : TrackingEvent

    data object Released : TrackingEvent
}

const val ARRIVING_RADIUS_METERS = 150.0

// One transition table, so nothing anywhere else in the app decides it has
// worked out that a delivery is over. Anything not listed leaves the state
// alone, which is how a duplicate server event or a late fix arriving after
// the drop stays harmless.
fun TrackingState.on(event: TrackingEvent): TrackingState = when {
    event is TrackingEvent.Assigned && this is TrackingState.Idle ->
        TrackingState.Tracking(event.orderId)

    event is TrackingEvent.DistanceToDrop && this is TrackingState.Tracking ->
        if (event.distance.value <= ARRIVING_RADIUS_METERS) {
            TrackingState.Arriving(orderId, event.distance)
        } else {
            this
        }

    // Leaving the geofence again is normal, a rider parks, walks off to the
    // wrong gate and comes back, so this edge runs both ways.
    event is TrackingEvent.DistanceToDrop && this is TrackingState.Arriving ->
        if (event.distance.value > ARRIVING_RADIUS_METERS) {
            TrackingState.Tracking(orderId)
        } else {
            TrackingState.Arriving(orderId, event.distance)
        }

    event is TrackingEvent.DeliveryConfirmed && publishing ->
        TrackingState.Delivered(activeOrderId!!, event.atMillis)

    event is TrackingEvent.Released -> TrackingState.Idle

    else -> this
}