MODULE 03 · REAL-TIME MESSAGING & E2EE MEDIA

WhatsApp — Chat & Encrypted Media

Library-agnostic architecture for sub-16ms optimistic messaging, monotonic sequence gap recovery, half-open socket detection, and resumable E2EE blob transfers.

Act I · Scope, Constraints & Device Budgets

Messaging Guarantees & Mobile Resource Envelope

Step 1 of 5
Functional Scope
Core UX
  • 1:1 & Group Messaging: Persistent bi-directional delivery across multi-device sessions with ordered conversation timelines.
  • <16ms Optimistic Local Echo: Messages write to Local SSOT immediately on Send tap and render inside a single display frame.
  • 3-Stage Delivery Receipts: Deterministic state machine transitions from PENDING → SENT → DELIVERED → READ.
  • E2EE Media Attachments & Offline Catch-Up: Client-encrypted chunked uploads plus automatic delta replay upon reconnect.
Non-Functional Constraints
Reliability & Security
  • Zero Duplicate Sends (UUIDv7): Every outgoing message carries a client-generated client_msg_id enforced idempotently by both relay and Local SSOT.
  • Clock-Skew-Resilient Ordering: Conversation order relies strictly on server-assigned monotonic server_seq, never local device clocks.
  • Battery-Conscious Persistent Socket: Adaptive PING/PONG heartbeat detects half-open zombie connections without keeping cellular radios permanently awake.
  • Zero-Knowledge E2EE Media Relay: Blob CDN stores only opaque AES-256-GCM ciphertext; decryption keys travel exclusively inside the E2EE chat channel.
Optimistic UI Render
< 16 ms

Single 60Hz frame budget from Composer tap to SQLite WAL local echo.

Adaptive Heartbeat
25–45 s

NAT-safe keep-alive interval tuned to detect zombie TCP sockets quickly.

E2EE Media Chunk
256 KB

Resumable encrypted chunk size minimizing wasted bytes on Wi-Fi/5G drops.

Radio & Battery Cap
< 2% / hr

Background socket + push wake budget under active chat workloads.

Act II · API, Wire Protocol & Local Storage Contract

WebSocket Frames, Resumable Media & SQLite WAL Schema

Step 2 of 5
WebSocket Wire Frames & Resumable Media HTTP
JSON / HTTP PATCH
Local SSOT Storage Schema (SQLite WAL)
Atomic Persistence
Act III · Interactive 5-Node Topology, Telemetry HUD & Chaos Switchboard

Real-Time Messaging, Gap Recovery & E2EE Media Simulator

SOCKET CONNECTED
Step 1 / 6
5-Node Topology · Optimistic Send & 3-Stage ACK
COMPOSER TAP
chat Chat UI & Composer <16ms Optimistic UI READY · 120Hz database Local SSOT & Outbox SQLite WAL · HWM HWM #402 · 0 QUEUED cable Socket & Heartbeat Persistent WS · 30s CONNECTED · PONG lock E2EE & Media Chunker AES-256-GCM · 256KB KEYS READY cloud Chat Relay & Blob CDN Zero-Knowledge Edge ONLINE · 28ms RTT
COMPOSER TAP

Loading simulator...

Invariant active
Live Event Console
Live Telemetry HUD
Real-Time
Socket State
CONNECTED
Heartbeat 30s OK
Outbox Queue
0 pending
Idempotent UUIDv7
Server Seq (HWM)
#402
Contiguous timeline
Media Transfer
IDLE
256 KB AES-GCM chunks
Chaos Engineering Switchboard
0 Active
Act IV · Zero-Dependency Kotlin Contracts & Platform Mapping

Library-Agnostic Core & Android / iOS Equivalents

Auto-Synced to Simulator
Platform Mapping Strip (Android & iOS Equivalents) 6 Agnostic Primitives
Agnostic Primitive Android Equivalent iOS Equivalent
Local SSOT Database Room / SQLDelight Core Data / SwiftData / SQLite
Persistent Socket Engine OkHttp WebSocket / Ktor URLSessionWebSocketTask / NWConnection
E2EE Keystore & Crypto Android Keystore + LibSignal / Tink Keychain + CryptoKit / LibSignal
Resumable Media Transfer WorkManager + Foreground Service URLSession Background Upload + BGTaskScheduler
Background Wake / Push FCM High-Priority Data Message APNs Notification Service Extension / PushKit
Connectivity & Handover ConnectivityManager.NetworkCallback NWPathMonitor
Act V · Production Tradeoffs & Observability SLOs

Engineering Tradeoffs & Production Targets

Step 5 of 5
Tradeoff 01 Low Latency + Battery

Persistent WebSocket + Push Wake vs. HTTP Long Polling

Chosen: WS + Push Wake

Single multiplexed TCP socket while foregrounded; OS push wakes the app cleanly when suspended.

Rejected: Long Polling

Repeated HTTP/TLS handshakes and header overhead drain cellular battery and inflate tail latency.

Why It Wins: Cuts wire overhead by >85% during active conversations while keeping background radio wakeups within the < 2% / hr battery envelope.

Tradeoff 02 Deterministic Order

Server Monotonic Sequence (server_seq) vs. Client Wall-Clock

Chosen: server_seq

Per-conversation monotonic integers make gaps immediately detectable (seq > hwm + 1) and ordering total.

Rejected: Client Clocks

Manual time-zone changes, NTP drift, and offline sends cause scrambled threads and silent message loss.

Why It Wins: Local optimistic messages render at the tail until ACKed, then snap cleanly to their canonical server_seq without missing packets.

Tradeoff 03 Zero HoL Blocking

Upload-Then-Send Encrypted Pointer vs. Inline Media Over WS

Chosen: Blob + Pointer

256 KB encrypted chunks upload over HTTP PATCH; only a ~250B media_ptr rides the chat WebSocket.

Rejected: Inline WS Blob

A 4.2 MB video blocks text messages and heartbeat PINGs behind head-of-line TCP congestion.

Why It Wins: Keeps text chats snappy (<350ms p99), enables byte-range resume across Wi-Fi/5G switches, and offloads heavy egress to Edge Blob CDNs.

Tradeoff 04 Zero-Knowledge

Client-Side E2EE vs. Server-Side Full-Text Search

Chosen: Client E2EE + FTS

Messages stay end-to-end encrypted in transit and on relay; local SQLite FTS5 indexes decrypted history on device.

Rejected: Server Indexing

Requires plaintext access on relay servers, breaking end-to-end privacy guarantees and expanding breach blast radius.

Why It Wins: Preserves strict zero-knowledge privacy while delivering instant offline search over years of local conversation history.

Production Observability SLOs
Live Reliability Targets
p99 Send-to-ACK < 350 ms
Duplicate Delivery Rate 0.00%
Zombie Socket Detection < 30 s
Media Resume Success > 99.4%