// 06 // TECHNICAL BLUEPRINT //

Core Architecture

The underlying infrastructure of the StreetWizard platform: a highly available, decentralized geospatial engine.

LAYER 01

ARCHITECTURE: SPOTIFY-LIKE P2P SCALING

[01]The core engineering challenge of multiplayer GPS is the exponential server cost associated with real-time coordinate broadcasting. StreetWizard bypasses the traditional bottleneck by implementing a WebRTC Peer-to-Peer topology.

[02]Instead of routing all telemetry through a central database, our backend WebSocket signaling server groups users into dynamic Geohash sectors. When users enter a specific radius, the system exchanges ICE candidates and establishes direct WebRTC Data Channels between the devices.

[03]By offloading GPS telemetry (Latitude, Longitude, speed, heading, and pitch) directly to active edge nodes, server bandwidth remains perfectly flat regardless of swarm density. As user volume increases, the localized network becomes faster and significantly cheaper to operate.

LAYER 02

GLOBAL TELEMETRY & CRDT AGGREGATION

[01]Tracking the exact distance traveled by the entire global community simultaneously requires a flawless approach to distributed state management to avoid database race conditions.

[02]The StreetWizard client-side engine calculates distance deltas locally using the Haversine formula based on high-frequency GPS polling. Instead of locking database rows, these deltas are fired into a distributed event stream utilizing Conflict-Free Replicated Data Types (CRDTs).

[03]This ensures that the global community odometer aggregates the exact metrics in real-time across multiple edge nodes, pushing the synchronized total back to all active clients globally with zero lag.

Geospatial Signaling & P2P Mesh Network (WebRTC)

The core challenge of multiplayer GPS is real-time server bottlenecking. StreetWizard bypasses this using a WebRTC peer-to-peer topology.

[+] GEOHASH PROXIMITY MATCHINGThe WebSocket signaling server never broadcasts coordinates. It groups users into dynamic Geohash sectors.
[+] MESH CONNECTIVITYEntering a Geohash radius triggers ICE candidate exchange, establishing direct WebRTC data channels between vehicles.
[+] EDGE OFFLOADINGLat/Lng, speed and heading move peer-to-peer at sub-millisecond latency. Server bandwidth stays flat regardless of swarm density.

Distributed Global Odometer (CRDTs & Redis)

Tracking the exact distance traveled by the entire global community simultaneously requires avoiding database race conditions.

[+] BATCH PROCESSINGThe client engine computes distance deltas locally with the Haversine formula from GPS polling.
[+] CONFLICT-FREE REPLICATED DATA TYPESNo row locking. Deltas are fired into a distributed event stream (Kafka / Redis PubSub).
[+] REAL-TIME AGGREGATIONCRDT counters aggregate the global integer across edge nodes and push the synchronized total to every client via SSE or WebSockets.

"Live Radio" Audio Synchronization Engine

Streaming the exact same track to a convoy requires mitigating network latency variance between peers.

[+] NTP-STYLE TIMESTAMPINGThe host node ships track metadata alongside a precise execution timestamp (HostTime + latency offset).
[+] BUFFER DELAYClients compute their own clock drift, pre-load the chunk into the Web Audio API buffer and fire playback at the exact synchronized UTC millisecond — zero echo across the convoy.

Kinematic 3D Rendering (Mapbox GL JS)

The frontend relies on a heavily customized WebGL rendering pipeline.

[+] CAMERA INTERPOLATIONrequestAnimationFrame loops derive dynamic pitch (55°–65°), bearing and zoom from the vehicle speed vector.
[+] SPATIAL UI LAYERSAvatars, Wiper Notes and chat nodes render as WebGL custom layers instead of DOM elements, preventing reflow lag at speed.

Automated Telemetry & State Hydration

Zero-technical-debt debugging mechanism built directly into the client.

[+] REDUX TREE DUMPSA caught Error Boundary serializes the full state tree: session, current Geohash, active peers.
[+] ENCRYPTED PAYLOADSThe snapshot plus the last 60 seconds of raw GPS logs is encrypted and shipped, letting engineers rehydrate the exact crash state locally.
[+] ZERO-LATENCY ROUTINGEvery dump is instantly routable to Lead@seub.net, so a production crash reaches the engineering desk before the pilot even parks.

Edge CDN Audio Scaling & 24/7 Rotation

Broadcasting live audio to thousands of concurrent pilots would normally generate catastrophic egress costs. StreetWizard offloads it entirely.

[+] STATE-ONLY BROADCASTRealtime channels never carry audio. They broadcast the playback state payload only — the exact started_at timestamp.
[+] CLIENT-SIDE SYNCEach device computes (now - started_at) and pulls the static chunk from the Edge CDN with an aggressive cacheControl of 31536000, pushing bandwidth to localized nodes.
[+] GAPLESS PG_CRON ROTATIONA PostgreSQL pg_cron job triggers wizardops.radio_rotate() to keep the station alive, gapless and advancing even with zero active listeners.

Real-Time Database Optimization

Live social state at map scale dies on naive queries. The data layer is tuned for constant-cost reads and reflow-free pushes.

[+] TRIGGER-BASED COUNTERSHeavy COUNT() queries are eliminated via SQL triggers maintaining denormalized counters — Street Cred math resolves as (Likes / (Likes + Dislikes)) * 100 server-side.
[+] REPLICA IDENTITY FULLWebSocket change feeds ship complete row images so clients patch state surgically, pushing live updates without forcing DOM reflows.
[+] PROXIMITY GATINGWiper Notes delivery is enforced at the database layer: a message row is only readable when a verified physical path-crossing exists between the two pilots.