How The Engine Actually Works

// UNDER THE HOOD

The naive topology is a full mesh: N participants, N(N−1)/2 edges, and each edge carrying its own position stream. Whether those edges are peer connections or server fan-out, the message volume is O(N²) and the per-client inbound rate is O(N).

A shared broadcast channel collapses the publish side to O(N): each client emits once per tick regardless of crowd size. The inbound side is still O(N) per client — that is inherent to 'everyone sees everyone' and no topology removes it. What the remaining mechanisms do is attack the constant in front of that N, and the N itself at the render layer.

This is the load-bearing correction to the previous version of this document, which claimed a WebRTC peer-to-peer mesh. A full P2P mesh does not remove the quadratic term — it relocates it from the server to the phone, where each device would hold N−1 concurrent encrypted sessions while also running a 3D map and a GPS. That trade is examined in the last chapter.

// UNDER THE HOOD

The transport is Supabase Realtime, used in both of its modes at once on a single channel. Presence holds the roster: join/leave events plus a metadata payload per key, replayed to anyone who connects. Broadcast carries the position stream.

The heavy field is the avatar, stored as a data URL. It lives in the presence metadata only. A peer's photo is cached client-side in a `metaRef` map and re-merged into the drawable peer on every recompute, precisely so it never needs to ride a position message.

Presence doubles as a low-rate position fallback (refreshed no more often than once per 10 s), which covers the window between joining and receiving a peer's first broadcast — otherwise a rider who has not moved since you connected would be invisible rather than stationary.

Incoming broadcasts do not each trigger a re-render. They are coalesced into one recompute per 350 ms window: at N peers, a recompute per inbound message is O(N) work N times per tick, and the coalescing is what keeps that from becoming the bottleneck before the network does.

// UNDER THE HOOD

Emission is gated on two conditions simultaneously — elapsed time AND distance travelled since the last emitted fix. Both thresholds step with the observed fleet size, so the gate tightens exactly when the crowd it is protecting gets large.

The distance gate is the one that carries a stationary fleet. GPS on a parked phone jitters by several metres; a time-only throttle would happily broadcast that jitter forever. Requiring 5 m of real movement at the tightest step (40 m at the loosest) means a static meet costs the channel nothing, which is the state a car-scene app spends most of its evening in.

The ladder is deliberately coarse — four steps, not a continuous function of N. A smooth curve would make the emission rate a function of a number that itself flickers as riders join and leave, so the rate would flicker with it and become impossible to reason about from a packet capture.

// UNDER THE HOOD

Each tracked entity — self and every peer — carries a small dead-reckoning state: a velocity vector in degrees per second, an EMA-smoothed speed estimate, and the age of the last real fix. Successive measurements derive the velocity; the render loop advances the target by that velocity times the frame delta.

Three guards make it safe rather than merely smooth. Prediction is capped at 1.4 s of extrapolation, so a dropped connection degrades into a stopped marker instead of a car driving off the map. Below 4 km/h of DERIVED speed the entity is treated as stationary and the raw fix is used unmodified. And the velocity estimate is blended at 0.45 rather than replaced, so a single noisy fix cannot slew the marker.

The derived speed is used rather than the reported one on purpose: a phone can announce a speed it is not achieving, and at a standstill the announced value is the least trustworthy number in the payload.

The same routine drives the self marker and the peer markers. That symmetry is the point — it means your own car and everyone else's degrade identically under bad signal, so nobody sees a map where only other people stutter.

// UNDER THE HOOD

`MAX_DRAWN = 60`. Above that the peer list is sorted by squared planar distance to the local fix and truncated. Squared distance, with a cos(lat) correction on the longitude term, avoids a square root and a haversine per peer per recompute — at 60+ peers inside a 350 ms loop that arithmetic is worth removing.

The drawable set is the intersection of two sources: peers currently PRESENT (from presence) and peers for whom a position is known (from broadcast or the presence fallback). A peer missing from either side is not drawn — which is what prevents a stale marker from outliving the rider it belongs to.

The `online` count is computed from the presence set before truncation, so the cap is a rendering decision and never leaks into a displayed number. This matters more than it looks: a cap that silently shrinks the reported population turns a performance guard into a lie about how busy the map is.

Every one of these entities is an HTML Marker positioned over the GL canvas, not a symbol layer. That is a deliberate trade — the cost is that DOM element count becomes the render budget, which is exactly why the cap exists; the benefit is real CSS, real accessibility and real tap targets on objects that carry buttons.

// UNDER THE HOOD

One row per rider in `fleet_scores`, advanced only by its owner. There is no shared counter to contend over, so there is no write contention and nothing to resolve — the property the previous version of this document attributed to CRDTs is obtained here by not having a contended cell in the first place.

The total is `get_community_km()`, a SECURITY DEFINER RPC summing those rows. Definer rights let the aggregate read across all rows without granting any client that read, so the sum is privileged while the underlying table stays locked down.

The client-side rolling is cosmetic and monotone by construction: it extrapolates from the aggregate live rate between syncs and clamps to never decrease, so a slow network shows a slightly optimistic counter that converges rather than a counter that visibly rewinds.

HONEST LIMIT — this is where the current implementation is weaker than the design. A rider's own `km` is upserted directly from the client, and there is no server-side plausibility check on the delta. 'No client can submit the total' is true; 'no client can inflate the total' is not, because inflating your own row inflates the sum. Closing it is a database-side clamp — bound each write by elapsed time since the previous write times a maximum plausible speed — and it is the single highest-value hardening item on the engine.

// UNDER THE HOOD

Authority is a server-held `(track, started_at)` pair. A client computes `now − started_at`, seeks its audio element to that offset and plays. No election, no host state, no renegotiation on churn — a dropping listener affects nothing but itself.

The realtime channel carries only that state, never audio bytes. The media itself is a static asset served with a long cache lifetime, so scaling listeners is a CDN problem rather than an application problem, and the marginal listener costs the application nothing at all.

The accuracy claim is deliberately modest. Convergence is bounded by clock skew between devices and by the network delay on reading the state — neither is corrected for, and the previous version of this document called this NTP synchronisation to the millisecond, which it is not and was never built to be. What it is: good enough that a convoy hears one song, achieved without any of the machinery that a stricter claim would require.

// UNDER THE HOOD

MOBILITY IS THE DISQUALIFIER, before any of the arithmetic. A vehicle in motion hands off between cell towers continuously, and a handoff can change the device's apparent address — which invalidates the candidate pair a connection was established on and forces an ICE restart. The workload here is not 'peers on stable links'; it is 'every peer's link is expected to break repeatedly, by design, for the entire session'. Peer connections are the wrong primitive for that, independent of scale.

A full WebRTC mesh at N peers requires N(N−1)/2 peer connections, each with its own ICE agent, DTLS handshake and SCTP association. Per client that is N−1 concurrent encrypted sessions — the quadratic term relocated to the least capable node in the system, alongside a Mapbox GL render loop and continuous GPS. The current star topology is one connection per client regardless of crowd size, and the server does the fan-out.

Establishment is not free either. ICE gathering costs on the order of a second before a channel is usable, and the drawable peer set here churns continuously as riders enter and leave the nearest-sixty radius. A membership that turns over faster than connections establish spends its life renegotiating — and that is before the handoffs above add their own churn on top.

Mobile carriers deploy CGNAT widely, so a meaningful fraction of mobile-to-mobile pairs cannot hole-punch and fall back to TURN. TURN relays the media through infrastructure you operate — for those pairs the traffic costs MORE than the shared channel it replaced, plus the relay fleet, plus its operation.

Against that: the payload is on the order of tens of bytes at a rate already throttled to between 2/s and 0.25/s. The saving is close to noise; the added surface is a signalling service, a STUN/TURN deployment, per-peer connection lifecycle, and a second delivery path to keep correct.

VERDICT — not the first upgrade, and arguably not the fifth. The ranked list of what would actually harden this engine: (1) the odometer write clamp from chapter 06, since a claim about integrity is currently stronger than its enforcement; (2) moving Street Cred and Wiper Notes off localStorage onto the existing `fleet_notes` table, since a reputation that lives on one phone is not a reputation; (3) instrumented measurements — bytes per rider per minute, wire-to-screen latency, frame rate at N peers — to replace the design parameters on this site with numbers somebody took. WebRTC belongs on this list only when the payload becomes voice.