[ { "id": "01-system-context", "title": "Consumer Messaging Platform — System Context", "layout": "context", "canvas": { "width": 1720 }, "colWidth": 250, "system": { "label": "Consumer Messaging Platform", "sub": "Chat, calls, status" }, "groups": [ { "side": "left", "title": "People", "nodes": [ { "id": "user", "label": "Individual User", "sub": "Phone-number identity", "kind": "actor", "rel": "chats, calls, status", "dir": "in" }, { "id": "admin", "label": "Group & Community Admin", "kind": "actor", "rel": "membership, policy", "dir": "in" }, { "id": "tns", "label": "Trust & Safety Analyst", "kind": "actor", "rel": "reports, appeals", "dir": "in" } ] }, { "side": "top", "title": "Identity & device platforms", "nodes": [ { "id": "otp", "label": "SMS & Voice OTP", "sub": "Phone verification", "kind": "external", "rel": "send code", "kind2": "sync" }, { "id": "apns", "label": "Apple APNs", "kind": "external", "rel": "wake device", "kind2": "async" }, { "id": "fcm", "label": "Google FCM", "kind": "external", "rel": "wake device", "kind2": "async" }, { "id": "attest", "label": "Device Attestation", "sub": "Play Integrity / DeviceCheck", "kind": "external", "rel": "verify device", "kind2": "sync" } ] }, { "side": "right", "title": "Network & storage services", "nodes": [ { "id": "cdn", "label": "Global CDN", "sub": "Media edge", "kind": "external", "rel": "encrypted blobs", "kind2": "sync" }, { "id": "turn", "label": "STUN / TURN Relay", "sub": "NAT traversal", "kind": "external", "rel": "call media path", "kind2": "sync" }, { "id": "backup", "label": "Cloud Backup Providers", "sub": "iCloud / Google Drive", "kind": "external", "rel": "encrypted backup", "kind2": "batch" } ] }, { "side": "bottom", "title": "Partners & governance", "nodes": [ { "id": "addr", "label": "Device Address Book", "sub": "On-device contacts", "kind": "external", "rel": "hashed discovery", "dir": "in" }, { "id": "biz", "label": "Business Platform Partners", "sub": "Template messaging", "kind": "external", "rel": "REST + webhook", "dir": "in" }, { "id": "reg", "label": "Regulators & Law Enforcement", "kind": "external", "rel": "metadata under process", "kind2": "batch" } ] } ], "note": "Message content is never available to the platform; only metadata and ciphertext cross this boundary.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-08" } }, { "id": "02-high-level-architecture", "title": "High-Level Architecture", "layout": "flow", "chain": true, "canvas": { "width": 1660 }, "stages": [ { "title": "Clients", "nodes": [ { "id": "mob", "label": "Mobile App", "sub": "iOS / Android", "kind": "app" }, { "id": "comp", "label": "Companion Clients", "sub": "Desktop / Web", "kind": "app" } ] }, { "title": "Edge", "nodes": [ { "id": "lb", "label": "Anycast Edge", "sub": "TLS 1.3 + Noise", "kind": "integration" }, { "id": "gw", "label": "Connection Gateway", "sub": "Persistent sockets", "kind": "app" }, { "id": "guard", "label": "Rate & Abuse Guard", "kind": "security" } ] }, { "title": "Core services", "nodes": [ { "id": "chat", "label": "Chat Service", "sub": "Accept & order", "kind": "app" }, { "id": "fan", "label": "Fanout Service", "sub": "Per recipient device", "kind": "app" }, { "id": "kds", "label": "Key Distribution", "sub": "Public prekeys", "kind": "security" }, { "id": "pres", "label": "Presence & Receipts", "kind": "app" } ] }, { "title": "Async backbone", "nodes": [ { "id": "dq", "label": "Delivery Queue", "sub": "Per-device inbox", "kind": "queue" }, { "id": "bus", "label": "Event Bus", "sub": "Kafka", "kind": "queue" }, { "id": "push", "label": "Push Dispatcher", "sub": "APNs / FCM", "kind": "app" } ] }, { "title": "Data", "nodes": [ { "id": "ms", "label": "Message Store", "sub": "Ciphertext, TTL 30 d", "kind": "store" }, { "id": "adb", "label": "Account & Group DB", "sub": "Sharded SQL", "kind": "store" }, { "id": "blob", "label": "Media Blob Store", "sub": "Object + CDN", "kind": "store" }, { "id": "pc", "label": "Presence Cache", "sub": "Redis, TTL 60 s", "kind": "store" } ] }, { "title": "Delivery", "nodes": [ { "id": "pn", "label": "Push Notification", "sub": "Offline wake", "kind": "external" }, { "id": "rdev", "label": "Recipient Devices", "sub": "Open socket", "kind": "app" } ] } ], "edges": [ { "from": "rdev", "to": "pres", "label": "delivered / read", "kind": "async", "route": "gutter" }, { "from": "push", "to": "pn", "label": "silent wake", "kind": "async" } ], "note": "Six stages only. Calls, status, search and backup have their own views.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-08" } }, { "id": "03-layered-architecture", "title": "Layered Architecture", "layout": "bands", "canvas": { "width": 1660 }, "layerHeaderWidth": 170, "bands": [ { "name": "Client", "nodes": [ { "id": "ui", "label": "Chat, Calls & Status UI", "kind": "app" }, { "label": "Local Message DB", "sub": "SQLCipher", "kind": "store" }, { "label": "Signal Protocol Store", "kind": "security" }, { "label": "Media Cache", "kind": "store" }, { "label": "On-device Search Index", "kind": "store" } ] }, { "name": "Transport", "nodes": [ { "id": "noise", "label": "Noise Session", "sub": "XX handshake", "kind": "security" }, { "label": "Binary Framing", "sub": "Multiplexed streams", "kind": "app" }, { "label": "Reconnect & Backoff", "kind": "app" }, { "label": "Offline Outbox", "kind": "queue" } ] }, { "name": "Edge", "nodes": [ { "id": "egw", "label": "Connection Gateway", "kind": "app" }, { "label": "Session Registry", "sub": "Device to node", "kind": "store" }, { "label": "Anycast Load Balancer", "kind": "integration" }, { "label": "Rate & Abuse Guard", "kind": "security" } ] }, { "name": "Application services", "nodes": [ { "id": "svc", "label": "Chat Service", "kind": "app" }, { "label": "Fanout Service", "kind": "app" }, { "label": "Group & Community", "kind": "app" }, { "label": "Presence & Receipts", "kind": "app" }, { "label": "Media Service", "kind": "app" }, { "label": "Calls & Status", "kind": "app" } ] }, { "name": "Integration & async", "nodes": [ { "id": "int", "label": "Event Bus", "kind": "queue" }, { "label": "Delivery Queue", "kind": "queue" }, { "label": "Push Dispatcher", "kind": "app" }, { "label": "Business API Gateway", "kind": "integration" } ] }, { "name": "Data", "nodes": [ { "id": "dat", "label": "Message Store", "kind": "store" }, { "label": "Account & Group DB", "kind": "store" }, { "label": "Media Blobs", "kind": "store" }, { "label": "Presence Cache", "kind": "store" }, { "label": "Prekey Store", "kind": "store" } ] }, { "name": "Platform", "nodes": [ { "id": "plat", "label": "Kubernetes & Service Mesh", "kind": "platform" }, { "label": "HSM-backed KMS", "kind": "security" }, { "label": "Observability", "sub": "OpenTelemetry", "kind": "platform" }, { "label": "CI/CD & Release Control", "kind": "platform" } ] } ], "edges": [ { "from": "ui", "to": "noise", "label": "encrypted frames", "kind": "sync" }, { "from": "noise", "to": "egw", "label": "TCP 443 / WSS", "kind": "sync" }, { "from": "egw", "to": "svc", "label": "gRPC, device claim", "kind": "sync" }, { "from": "svc", "to": "int", "label": "publish", "kind": "async" }, { "from": "int", "to": "dat", "label": "persist", "kind": "sync" } ], "note": "Dependencies point downward only. Delivery back to a device re-enters through the Edge layer.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-08" } }, { "id": "04-container-architecture", "title": "Container Architecture", "layout": "nested", "canvas": { "width": 1660 }, "boxes": [ { "title": "Client devices", "kind": "onprem", "dir": "row", "children": [ { "title": "Primary device", "kind": "boundary", "nodes": [ { "id": "capp", "label": "Chat Application", "sub": "Swift / Kotlin", "kind": "app" }, { "id": "cdb", "label": "Encrypted Local DB", "sub": "SQLCipher", "kind": "store" }, { "id": "cks", "label": "Key Store", "sub": "Secure Enclave / Keystore", "kind": "security" } ] }, { "title": "Companion devices", "kind": "boundary", "nodes": [ { "id": "wapp", "label": "Desktop & Web Client", "sub": "Electron / WASM", "kind": "app" }, { "id": "wdb", "label": "Companion Session Store", "kind": "store" } ] } ] }, { "title": "Edge tier", "kind": "cloud", "dir": "row", "children": [ { "title": "Point of presence", "kind": "boundary", "nodes": [ { "id": "alb", "label": "Anycast Terminator", "sub": "TLS 1.3", "kind": "integration" }, { "id": "cgw", "label": "Connection Gateway", "sub": "Erlang/OTP, 1M sockets/pool", "kind": "app" } ] }, { "title": "Edge control", "kind": "boundary", "nodes": [ { "id": "sreg", "label": "Session Registry", "sub": "Redis Cluster", "kind": "store" }, { "id": "rgd", "label": "Auth & Rate Guard", "sub": "Device-scoped tokens", "kind": "security" } ] } ] }, { "title": "Core services — Kubernetes", "kind": "cloud", "dir": "row", "children": [ { "title": "Messaging", "kind": "boundary", "nodes": [ { "id": "chatsvc", "label": "Chat Service", "sub": "Go, idempotent accept", "kind": "app" }, { "id": "fansvc", "label": "Fanout Service", "sub": "Go, sharded workers", "kind": "app" }, { "id": "rcpt", "label": "Receipt Service", "kind": "app" } ] }, { "title": "Identity & social", "kind": "boundary", "nodes": [ { "id": "acct", "label": "Account Service", "sub": "Registration, profile", "kind": "app" }, { "id": "grp", "label": "Group & Community Service", "kind": "app" }, { "id": "kdssvc", "label": "Key Distribution Service", "sub": "Public prekeys only", "kind": "security" } ] }, { "title": "Rich features", "kind": "boundary", "nodes": [ { "id": "media", "label": "Media Service", "sub": "Resumable upload", "kind": "app" }, { "id": "call", "label": "Call Signalling Service", "sub": "WebRTC SDP relay", "kind": "app" }, { "id": "stat", "label": "Status Service", "sub": "24 h TTL", "kind": "app" } ] } ] }, { "title": "Data tier", "kind": "cloud", "dir": "row", "children": [ { "title": "Operational stores", "kind": "boundary", "nodes": [ { "id": "mstore", "label": "Message Store", "sub": "ScyllaDB, RF 3", "kind": "store" }, { "id": "agdb", "label": "Account & Group DB", "sub": "Sharded MySQL", "kind": "store" } ] }, { "title": "Cache & async", "kind": "boundary", "nodes": [ { "id": "prescache", "label": "Presence Cache", "sub": "Redis", "kind": "store" }, { "id": "dqueue", "label": "Delivery Queue", "sub": "Per-device inbox", "kind": "queue" }, { "id": "ebus", "label": "Event Bus", "sub": "Kafka", "kind": "queue" } ] }, { "title": "Blob & keys", "kind": "boundary", "nodes": [ { "id": "obj", "label": "Media Object Store", "sub": "Immutable, TTL 30 d", "kind": "store" }, { "id": "hsm", "label": "Backup Key Vault", "sub": "HSM-backed", "kind": "security" } ] } ] } ], "outside": [ { "id": "oapns", "label": "APNs / FCM", "kind": "external" }, { "id": "ocdn", "label": "Global CDN", "kind": "external" }, { "id": "oturn", "label": "STUN / TURN", "kind": "external" }, { "id": "ootp", "label": "SMS OTP Provider", "kind": "external" } ], "edges": [ { "from": "capp", "to": "cgw", "label": "Noise over TCP 443", "kind": "sync" }, { "from": "wapp", "to": "cgw", "label": "Noise over WSS", "kind": "sync" }, { "from": "cgw", "to": "chatsvc", "label": "gRPC", "kind": "sync" }, { "from": "chatsvc", "to": "mstore", "label": "ciphertext write", "kind": "sync" }, { "from": "chatsvc", "to": "fansvc", "label": "", "kind": "async" }, { "from": "fansvc", "to": "dqueue", "label": "per-device enqueue", "kind": "async" }, { "from": "dqueue", "to": "cgw", "label": "deliver on socket", "kind": "async" }, { "from": "media", "to": "obj", "label": "encrypted blob", "kind": "sync" }, { "from": "obj", "to": "ocdn", "label": "origin pull", "kind": "sync" }, { "from": "acct", "to": "ootp", "label": "verification code", "kind": "sync" }, { "from": "call", "to": "oturn", "label": "relay allocation", "kind": "sync" } ], "note": "Push dispatch, business API gateway and observability agents omitted for legibility.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-08" } }, { "id": "05-identity-registration", "title": "Registration & Device Onboarding", "layout": "sequence", "canvas": { "width": 1560 }, "lifelines": [ { "id": "u", "label": "User", "kind": "actor" }, { "id": "cl", "label": "Client App", "kind": "app" }, { "id": "gw", "label": "Edge Gateway", "kind": "app" }, { "id": "ac", "label": "Account Service", "kind": "app" }, { "id": "ot", "label": "OTP Provider", "kind": "external" }, { "id": "kd", "label": "Key Distribution", "kind": "security" }, { "id": "cd", "label": "Contact Discovery", "kind": "app" } ], "messages": [ { "from": "u", "to": "cl", "label": "enter phone number", "kind": "call" }, { "from": "cl", "to": "gw", "label": "register(E.164, device pubkey)", "kind": "call" }, { "from": "gw", "to": "ac", "label": "create pending account", "kind": "call" }, { "from": "ac", "to": "ac", "label": "rate limit by number, IP, device", "kind": "self" }, { "from": "ac", "to": "ot", "label": "send 6-digit code", "kind": "async" }, { "from": "ot", "to": "u", "label": "SMS or voice call", "kind": "async" }, { "from": "u", "to": "cl", "label": "enter code", "kind": "call" }, { "from": "cl", "to": "ac", "label": "verify(code, attestation)", "kind": "call" }, { "from": "ac", "to": "ac", "label": "check SIM-swap signals", "kind": "self" }, { "from": "ac", "to": "cl", "label": "account id + device token", "kind": "return" }, { "from": "cl", "to": "cl", "label": "generate identity key pair", "kind": "self" }, { "from": "cl", "to": "kd", "label": "publish identity, signed prekey, 100 one-time prekeys", "kind": "call" }, { "from": "kd", "to": "cl", "label": "registration complete", "kind": "return" }, { "from": "cl", "to": "cd", "label": "upload hashed address book", "kind": "call" }, { "from": "cd", "to": "cl", "label": "registered contacts, privacy filtered", "kind": "return" }, { "from": "ac", "to": "cl", "label": "re-registration lockout if number reused", "kind": "error" } ], "note": "Private keys never leave the device. Only public key material reaches Key Distribution.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-08" } }, { "id": "06-message-send-delivery", "title": "Message Send and Delivery Path", "layout": "flow", "chain": true, "canvas": { "width": 1660 }, "stages": [ { "title": "Compose", "nodes": [ { "id": "ratchet", "label": "Double Ratchet", "sub": "One key per message", "kind": "security" }, { "id": "sdev", "label": "Sender Device", "sub": "Assigns client_msg_id", "kind": "app" } ] }, { "title": "Ingress", "nodes": [ { "id": "gwin", "label": "Connection Gateway", "sub": "Authenticated socket", "kind": "app" }, { "id": "idem", "label": "Duplicate?", "sub": "client_msg_id seen", "kind": "decision" } ] }, { "title": "Accept & order", "nodes": [ { "id": "chat", "label": "Chat Service", "sub": "Server id + timestamp", "kind": "app" }, { "id": "mstore", "label": "Message Store", "sub": "Ciphertext, TTL 30 d", "kind": "store" } ] }, { "title": "Fan out", "nodes": [ { "id": "resolve", "label": "Recipient Resolver", "sub": "Account to device list", "kind": "app" }, { "id": "fanout", "label": "Fanout Workers", "sub": "Sharded by device", "kind": "app" }, { "id": "inbox", "label": "Per-device Inbox", "sub": "Durable queue", "kind": "queue" } ] }, { "title": "Deliver", "nodes": [ { "id": "online", "label": "Online Path", "sub": "Push down open socket", "kind": "app" }, { "id": "offline", "label": "Offline Path", "sub": "Silent APNs / FCM wake", "kind": "app" } ] }, { "title": "Confirm", "nodes": [ { "id": "rdev", "label": "Recipient Device", "sub": "Decrypt, store, ack", "kind": "app" }, { "id": "rcpt", "label": "Receipt Service", "sub": "Delivered, read, played", "kind": "app" } ] } ], "edges": [ { "from": "idem", "to": "chat", "label": "no, accept", "kind": "sync" }, { "from": "idem", "to": "sdev", "label": "yes, replay server id", "kind": "error", "route": "gutter" }, { "from": "rcpt", "to": "sdev", "label": "receipt fanout to sender devices", "kind": "async", "route": "gutter" } ], "note": "Server ack sets the single tick; the recipient device sets every state after it.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-08" } }, { "id": "07-delivery-receipt-states", "title": "Delivery and Receipt State Matrix", "layout": "grid", "canvas": { "width": 1700 }, "laneHeaderWidth": 170, "columns": [ "Trigger", "Emitted by", "Server action", "Sender sees", "Server retention" ], "rows": [ { "title": "Pending", "cells": [ [ { "label": "No server ack yet", "kind": "app" } ], [ { "label": "Sender client", "kind": "app" } ], [ { "label": "None, not yet received", "kind": "external" } ], [ { "label": "Clock icon", "kind": "app" } ], [ { "label": "Local outbox only", "kind": "store" } ] ] }, { "title": "Sent", "cells": [ [ { "label": "Chat Service accepts", "kind": "app" } ], [ { "label": "Chat Service", "kind": "app" } ], [ { "label": "Server id assigned, ciphertext stored", "kind": "app" } ], [ { "label": "One tick", "kind": "app" } ], [ { "label": "Until delivered, max 30 d", "kind": "store" } ] ] }, { "title": "Delivered", "cells": [ [ { "label": "Ciphertext reaches a device", "kind": "app" } ], [ { "label": "Recipient device", "kind": "app" } ], [ { "label": "Route receipt, purge ciphertext", "kind": "app" } ], [ { "label": "Two ticks", "kind": "app" } ], [ { "label": "Purged on last device ack", "kind": "store" } ] ] }, { "title": "Read", "cells": [ [ { "label": "Chat opened by recipient", "kind": "app" } ], [ { "label": "Recipient device", "kind": "app" } ], [ { "label": "Route if receipts enabled", "kind": "decision" } ], [ { "label": "Blue ticks", "kind": "app" } ], [ { "label": "Receipt event only", "kind": "store" } ] ] }, { "title": "Played", "cells": [ [ { "label": "Voice note or view-once opened", "kind": "app" } ], [ { "label": "Recipient device", "kind": "app" } ], [ { "label": "Route, then expire view-once blob", "kind": "app" } ], [ { "label": "Blue microphone", "kind": "app" } ], [ { "label": "Blob deleted immediately", "kind": "store" } ] ] }, { "title": "Undeliverable", "cells": [ [ { "label": "30 days with no device ack", "kind": "risk" } ], [ { "label": "TTL reaper", "kind": "app" } ], [ { "label": "Drop ciphertext, no notification", "kind": "risk" } ], [ { "label": "Stays at one tick", "kind": "risk" } ], [ { "label": "Nothing retained", "kind": "store" } ] ] } ], "note": "Read and played states are advisory; a recipient who disables receipts stops them at delivered.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-08" } }, { "id": "08-group-fanout", "title": "Fanout by Conversation Class", "layout": "swimlane", "canvas": { "width": 1700 }, "laneHeaderWidth": 190, "stages": [ "Publish", "Resolve recipients", "Encrypt", "Fan out", "Deliver" ], "lanes": [ { "title": "1:1 chat", "cells": [ [ { "label": "Sender device", "kind": "app" } ], [ { "label": "Peer devices, 1 to 5", "kind": "app" } ], [ { "label": "Pairwise Signal session", "sub": "One ciphertext per device", "kind": "security" } ], [ { "label": "Direct enqueue", "kind": "queue" } ], [ { "label": "Socket or push", "kind": "app" } ] ] }, { "title": "Group, up to 1024", "cells": [ [ { "label": "Member device", "kind": "app" } ], [ { "label": "Group Service", "sub": "Members to devices", "kind": "app" } ], [ { "label": "Sender Key", "sub": "One ciphertext, N key copies", "kind": "security" } ], [ { "label": "Sharded fanout workers", "sub": "Hash by device id", "kind": "app" } ], [ { "label": "Per-device inbox", "kind": "queue" } ] ] }, { "title": "Community announcement", "cells": [ [ { "label": "Admin device", "kind": "app" } ], [ { "label": "Announcement roster", "sub": "Read-only members", "kind": "store" } ], [ { "label": "Sender Key, rekey on leave", "kind": "security" } ], [ { "label": "Batched fanout with backpressure", "kind": "app" } ], [ { "label": "Rate-shaped delivery", "kind": "queue" } ] ] }, { "title": "Broadcast list", "cells": [ [ { "label": "Sender device", "kind": "app" } ], [ { "label": "Private recipient list", "sub": "No shared identity", "kind": "store" } ], [ { "label": "Pairwise sessions", "kind": "security" } ], [ { "label": "N independent sends", "kind": "app" } ], [ { "label": "Arrives as a 1:1 chat", "kind": "app" } ] ] } ], "note": "Sender Keys keep group cost linear in devices for transport and constant for encryption.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-08" } }, { "id": "09-offline-sync-retry", "title": "Offline Queuing and Retry Loop", "layout": "cycle", "canvas": { "width": 1500 }, "centre": { "label": "At-least-once delivery", "sub": "Idempotent at the client" }, "nodes": [ { "label": "Undelivered ciphertext", "sub": "Per-device inbox", "kind": "store", "id": "undel" }, { "label": "Push wake", "sub": "APNs / FCM, no content", "kind": "integration", "id": "wake" }, { "label": "Client reconnects", "sub": "Noise session resume", "kind": "app", "id": "recon" }, { "label": "Inbox drain", "sub": "Ordered by server id", "kind": "app", "id": "drain" }, { "label": "Per-message ack", "sub": "Deduplicated by id", "kind": "app", "id": "ack" }, { "label": "Purge from server", "sub": "Or TTL at 30 days", "kind": "app", "id": "purge" } ], "ringLabels": [ "silent push", "socket opens", "batched pull", "ack each id", "delete ciphertext", "re-queue if no ack" ], "rx": 430, "ry": 205, "note": "Retry uses exponential backoff with jitter; the client discards duplicates by message id.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-08" } }, { "id": "10-media-pipeline", "title": "Media Upload and Download Pipeline", "layout": "flow", "chain": true, "canvas": { "width": 1660 }, "stages": [ { "title": "Capture", "nodes": [ { "id": "cap", "label": "Camera, gallery, file", "kind": "app" }, { "id": "comp", "label": "Client Compression", "sub": "H.264 / WebP / Opus", "kind": "app" }, { "id": "thumb", "label": "Thumbnail Generation", "sub": "On device", "kind": "app" } ] }, { "title": "Protect", "nodes": [ { "id": "mk", "label": "Random Media Key", "sub": "AES-256-CBC", "kind": "security" }, { "id": "hmac", "label": "HMAC-SHA256 Tag", "sub": "Integrity", "kind": "security" } ] }, { "title": "Upload", "nodes": [ { "id": "msvc", "label": "Media Service", "sub": "Resumable, chunked", "kind": "app" }, { "id": "obj", "label": "Object Store", "sub": "Immutable, TTL 30 d", "kind": "store" }, { "id": "dedupe", "label": "Blob already stored?", "sub": "SHA-256 of ciphertext", "kind": "decision" } ] }, { "title": "Reference", "nodes": [ { "id": "chat", "label": "Chat Service", "sub": "Normal send path", "kind": "app" }, { "id": "pay", "label": "Message Payload", "sub": "URL + key + hash", "kind": "app" } ] }, { "title": "Distribute", "nodes": [ { "id": "cdn", "label": "CDN Edge", "sub": "Signed URL, origin pull", "kind": "integration" }, { "id": "inline", "label": "Inline Thumbnail", "sub": "Encrypted in payload", "kind": "app" } ] }, { "title": "Consume", "nodes": [ { "id": "rdev", "label": "Recipient Device", "sub": "Verify HMAC, decrypt", "kind": "app" }, { "id": "gal", "label": "Media Gallery", "sub": "On-device, per chat", "kind": "store" } ] } ], "edges": [ { "from": "dedupe", "to": "pay", "label": "yes, reuse handle", "kind": "sync", "route": "gutter" }, { "from": "dedupe", "to": "obj", "label": "no, store blob", "kind": "sync" } ], "note": "The platform stores opaque bytes; the media key travels only inside the encrypted message.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-08" } }, { "id": "11-presence-typing-push", "title": "Presence, Typing and Push Signals", "layout": "swimlane", "canvas": { "width": 1700 }, "laneHeaderWidth": 190, "stages": [ "Emit", "Route", "State held", "Fan out", "Client effect" ], "lanes": [ { "title": "Presence", "cells": [ [ { "label": "Socket connect and disconnect", "kind": "app" } ], [ { "label": "Gateway heartbeat", "sub": "Every 30 s", "kind": "app" } ], [ { "label": "Presence Cache", "sub": "Redis, TTL 60 s", "kind": "store" } ], [ { "label": "Subscribed open chats only", "kind": "app" } ], [ { "label": "Online or last seen", "kind": "app" } ] ] }, { "title": "Typing indicator", "cells": [ [ { "label": "Keystroke, debounced 2 s", "kind": "app" } ], [ { "label": "Gateway, never persisted", "kind": "app" } ], [ { "label": "In-memory, TTL 10 s", "kind": "store" } ], [ { "label": "Open chat participants", "kind": "app" } ], [ { "label": "Typing banner", "kind": "app" } ] ] }, { "title": "Privacy gate", "cells": [ [ { "label": "User privacy setting", "kind": "decision" } ], [ { "label": "Evaluated at fan-out time", "kind": "app" } ], [ { "label": "Account & Group DB", "kind": "store" } ], [ { "label": "Reciprocity rule", "sub": "Hide yours, lose theirs", "kind": "decision" } ], [ { "label": "Signal suppressed", "kind": "risk" } ] ] }, { "title": "Push notification", "cells": [ [ { "label": "Undelivered message or call", "kind": "app" } ], [ { "label": "Push Dispatcher", "kind": "app" } ], [ { "label": "Device token registry", "kind": "store" } ], [ { "label": "APNs, FCM, Web Push", "kind": "external" } ], [ { "label": "Silent wake, then fetch and decrypt", "kind": "app" } ] ] } ], "note": "Push payloads carry no message content; the woken client fetches and decrypts locally.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-08" } }, { "id": "12-e2e-encryption", "title": "End-to-End Encryption Architecture", "layout": "flow", "chain": true, "canvas": { "width": 1700 }, "stages": [ { "title": "Device key material", "nodes": [ { "id": "ik", "label": "Identity Key Pair", "sub": "Curve25519, long lived", "kind": "security" }, { "id": "spk", "label": "Signed Prekey", "sub": "Rotated weekly", "kind": "security" }, { "id": "opk", "label": "One-time Prekeys", "sub": "100 per device", "kind": "security" } ] }, { "title": "Key distribution", "nodes": [ { "id": "kds", "label": "Key Distribution Service", "sub": "Public keys only", "kind": "app" }, { "id": "pks", "label": "Prekey Store", "sub": "Consumed once", "kind": "store" }, { "id": "sn", "label": "Safety Number", "sub": "Out-of-band verify", "kind": "security" } ] }, { "title": "Session setup", "nodes": [ { "id": "x3dh", "label": "X3DH Handshake", "sub": "Works while offline", "kind": "security" }, { "id": "root", "label": "Root & Chain Keys", "kind": "security" } ] }, { "title": "Message encryption", "nodes": [ { "id": "dr", "label": "Double Ratchet", "sub": "New key per message", "kind": "security" }, { "id": "sk", "label": "Sender Key", "sub": "Group messages", "kind": "security" }, { "id": "mk", "label": "Media Key", "sub": "Per blob, AES-256", "kind": "security" } ] }, { "title": "Transport", "nodes": [ { "id": "ct", "label": "Ciphertext + Header", "sub": "Ratchet counters", "kind": "app" }, { "id": "srv", "label": "Platform", "sub": "Cannot decrypt", "kind": "external" } ] }, { "title": "Recipient", "nodes": [ { "id": "plain", "label": "Plaintext in Secure Store", "sub": "SQLCipher on device", "kind": "store" }, { "id": "step", "label": "Ratchet Step", "sub": "Out-of-order tolerant", "kind": "security" } ] } ], "edges": [ { "from": "sn", "to": "step", "label": "key change warning", "kind": "error", "route": "gutter" } ], "note": "The platform holds no private key and no plaintext at any point on this path.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-08" } }, { "id": "13-multi-device-sync", "title": "Multi-Device Linking and Synchronisation", "layout": "sequence", "canvas": { "width": 1600 }, "lifelines": [ { "id": "pri", "label": "Primary Device", "kind": "app" }, { "id": "cmp", "label": "Companion Device", "kind": "app" }, { "id": "gw", "label": "Edge Gateway", "kind": "app" }, { "id": "dev", "label": "Device Service", "kind": "app" }, { "id": "kd", "label": "Key Distribution", "kind": "security" }, { "id": "ch", "label": "Chat Service", "kind": "app" }, { "id": "peer", "label": "Peer Device", "kind": "external" } ], "messages": [ { "from": "cmp", "to": "cmp", "label": "generate its own identity key pair", "kind": "self" }, { "from": "cmp", "to": "gw", "label": "request linking nonce", "kind": "call" }, { "from": "gw", "to": "dev", "label": "issue challenge, 60 s TTL", "kind": "call" }, { "from": "dev", "to": "cmp", "label": "QR payload", "kind": "return" }, { "from": "pri", "to": "pri", "label": "scan QR, verify nonce and fingerprint", "kind": "self" }, { "from": "pri", "to": "dev", "label": "authorise device, signed by account identity", "kind": "call" }, { "from": "dev", "to": "kd", "label": "register companion identity and prekeys", "kind": "call" }, { "from": "pri", "to": "cmp", "label": "encrypted history bundle", "kind": "async" }, { "from": "ch", "to": "cmp", "label": "backlog from its own device inbox", "kind": "async" }, { "from": "peer", "to": "ch", "label": "new message, one ciphertext per device", "kind": "async" }, { "from": "ch", "to": "pri", "label": "deliver device copy", "kind": "async" }, { "from": "ch", "to": "cmp", "label": "deliver device copy", "kind": "async" }, { "from": "cmp", "to": "ch", "label": "read receipt", "kind": "call" }, { "from": "ch", "to": "pri", "label": "sync read state across devices", "kind": "async" }, { "from": "pri", "to": "dev", "label": "revoke device, rotate sender keys", "kind": "error" } ], "note": "Each device is an independent Signal session; the primary device is not a relay.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-08" } }, { "id": "14-calls-architecture", "title": "Voice and Video Call Architecture", "layout": "flow", "chain": true, "canvas": { "width": 1700 }, "stages": [ { "title": "Initiate", "nodes": [ { "id": "caller", "label": "Caller Device", "kind": "app" }, { "id": "sig", "label": "Call Signalling Service", "sub": "Over the chat socket", "kind": "app" }, { "id": "wake", "label": "Callee Wake", "sub": "VoIP push, high priority", "kind": "integration" } ] }, { "title": "Negotiate", "nodes": [ { "id": "sdp", "label": "SDP Offer and Answer", "sub": "Sent as ciphertext", "kind": "app" }, { "id": "ice", "label": "ICE Candidates", "sub": "Trickled", "kind": "app" } ] }, { "title": "Key agreement", "nodes": [ { "id": "srtp", "label": "SRTP Master Key", "sub": "From the Signal session", "kind": "security" }, { "id": "dtls", "label": "DTLS-SRTP Binding", "kind": "security" } ] }, { "title": "Path selection", "nodes": [ { "id": "stun", "label": "STUN Reflexive", "kind": "integration" }, { "id": "p2p", "label": "Direct Peer to Peer", "sub": "When reachable", "kind": "app" }, { "id": "turn", "label": "TURN Relay", "sub": "Symmetric NAT fallback", "kind": "integration" } ] }, { "title": "Group media", "nodes": [ { "id": "sfu", "label": "Selective Forwarding Unit", "sub": "Forwards encrypted frames", "kind": "app" }, { "id": "simul", "label": "Simulcast Layers", "sub": "Bandwidth adaptive", "kind": "app" }, { "id": "jit", "label": "Jitter & FEC", "sub": "Loss concealment", "kind": "app" } ] }, { "title": "Terminate", "nodes": [ { "id": "miss", "label": "Missed Call Push", "kind": "integration" }, { "id": "rec", "label": "Call Record", "sub": "Metadata only", "kind": "store" } ] } ], "edges": [ { "from": "p2p", "to": "turn", "label": "fallback on ICE failure", "kind": "error" } ], "note": "The SFU forwards encrypted frames and never holds the media key. No call content is recorded.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-08" } }, { "id": "15-status-stories", "title": "Status and Stories Pipeline", "layout": "flow", "chain": true, "canvas": { "width": 1660 }, "stages": [ { "title": "Create", "nodes": [ { "id": "compose", "label": "Text, Photo or Video Composer", "kind": "app" }, { "id": "aud", "label": "Audience rule", "sub": "Contacts except, only share", "kind": "decision" } ] }, { "title": "Protect", "nodes": [ { "id": "skey", "label": "Random Status Key", "sub": "AES-256 per post", "kind": "security" }, { "id": "eblob", "label": "Encrypted Status Blob", "kind": "app" } ] }, { "title": "Publish", "nodes": [ { "id": "ssvc", "label": "Status Service", "kind": "app" }, { "id": "sblob", "label": "Status Blob Store", "sub": "Hard TTL 24 h", "kind": "store" }, { "id": "roster", "label": "Audience Roster", "sub": "Resolved at publish", "kind": "store" } ] }, { "title": "Distribute", "nodes": [ { "id": "sfan", "label": "Fanout to Allowed Viewers", "sub": "Key copy per device", "kind": "app" }, { "id": "scdn", "label": "CDN Edge", "sub": "Pre-warmed on publish", "kind": "integration" } ] }, { "title": "Consume", "nodes": [ { "id": "viewer", "label": "Viewer Device", "sub": "Decrypt and render", "kind": "app" }, { "id": "vr", "label": "View Receipt", "sub": "If read receipts on", "kind": "app" } ] }, { "title": "Expire", "nodes": [ { "id": "reap", "label": "TTL Reaper", "sub": "Hard delete at 24 h", "kind": "app" }, { "id": "vlist", "label": "Viewer List", "sub": "Purged with the post", "kind": "store" } ] } ], "edges": [ { "from": "aud", "to": "roster", "label": "audience snapshot", "kind": "sync", "route": "gutter" } ], "note": "Expiry is enforced server side and on device; a viewer who never opened it loses access at 24 h.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-08" } }, { "id": "16-search-history-backup", "title": "Search, History, Backup and Restore", "layout": "swimlane", "canvas": { "width": 1700 }, "laneHeaderWidth": 190, "stages": [ "Trigger", "On device", "Protection", "Off device", "Recovery" ], "lanes": [ { "title": "Message search", "cells": [ [ { "label": "Search box, filters", "kind": "app" } ], [ { "label": "Full-text index over local DB", "kind": "store" } ], [ { "label": "Index lives inside the encrypted DB", "kind": "security" } ], [], [] ] }, { "title": "User & group search", "cells": [ [ { "label": "Name or number lookup", "kind": "app" } ], [ { "label": "Local contact and group cache", "kind": "store" } ], [ { "label": "Hashed identifiers only", "kind": "security" } ], [ { "label": "Discovery Service", "sub": "Rate limited, no enumeration", "kind": "app" } ], [] ] }, { "title": "Chat history", "cells": [ [ { "label": "Every accepted message", "kind": "app" } ], [ { "label": "Local chat DB is the record", "kind": "store" } ], [ { "label": "Device encryption at rest", "kind": "security" } ], [ { "label": "Undelivered ciphertext only", "sub": "TTL 30 d", "kind": "store" } ], [ { "label": "History transfer on device change", "kind": "app" } ] ] }, { "title": "Backup & restore", "cells": [ [ { "label": "Scheduled or manual backup", "kind": "app" } ], [ { "label": "Snapshot plus media manifest", "kind": "app" } ], [ { "label": "AES-256 with 64-digit key or password", "kind": "security" } ], [ { "label": "iCloud, Google Drive or provider store", "kind": "external" } ], [ { "label": "Key from HSM vault, 10 attempts", "kind": "security" } ] ] }, { "title": "Storage management", "cells": [ [ { "label": "Storage usage screen", "kind": "app" } ], [ { "label": "Usage by chat and by media type", "kind": "app" } ], [], [ { "label": "Blob retained 30 d for re-download", "kind": "store" } ], [ { "label": "Selective delete and re-fetch", "kind": "app" } ] ] } ], "note": "Blank cells are deliberate. On-device search never reaches the platform, by design.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-08" } }, { "id": "17-data-architecture", "title": "Data Architecture and Ownership Zones", "layout": "nested", "canvas": { "width": 1660 }, "boxes": [ { "title": "On device — system of record for plaintext", "kind": "trust", "dir": "row", "children": [ { "title": "Conversation data", "kind": "boundary", "nodes": [ { "id": "lchat", "label": "Chat Database", "sub": "SQLCipher, full history", "kind": "store" }, { "id": "lmedia", "label": "Media Cache", "sub": "Decrypted blobs", "kind": "store" }, { "id": "lidx", "label": "Search Index", "sub": "Local only", "kind": "store" } ] }, { "title": "Cryptographic material", "kind": "boundary", "nodes": [ { "id": "lsess", "label": "Session & Ratchet State", "kind": "security" }, { "id": "lid", "label": "Identity Private Key", "sub": "Hardware backed", "kind": "security" } ] } ] }, { "title": "Server — transient, rebuildable", "kind": "cloud", "dir": "row", "children": [ { "title": "In flight", "kind": "boundary", "nodes": [ { "id": "sund", "label": "Undelivered Ciphertext", "sub": "TTL 30 d", "kind": "store" }, { "id": "sq", "label": "Delivery Queue", "sub": "Per device", "kind": "queue" }, { "id": "sblob", "label": "Media Blob", "sub": "TTL 30 d", "kind": "store" } ] }, { "title": "Ephemeral state", "kind": "boundary", "nodes": [ { "id": "spres", "label": "Presence", "sub": "TTL 60 s", "kind": "store" }, { "id": "styp", "label": "Typing State", "sub": "TTL 10 s", "kind": "store" }, { "id": "ssess", "label": "Socket Registry", "sub": "Rebuilt on reconnect", "kind": "store" } ] } ] }, { "title": "Server — durable metadata, never content", "kind": "cloud", "dir": "row", "children": [ { "title": "Account and social graph", "kind": "boundary", "nodes": [ { "id": "dacc", "label": "Account & Device Registry", "kind": "store" }, { "id": "dgrp", "label": "Group & Community Metadata", "kind": "store" }, { "id": "dblk", "label": "Block & Privacy Settings", "kind": "store" } ] }, { "title": "Keys and safety", "kind": "boundary", "nodes": [ { "id": "dpk", "label": "Public Prekey Bundles", "kind": "store" }, { "id": "dvault", "label": "Backup Key Vault", "sub": "HSM, rate limited", "kind": "security" }, { "id": "dabuse", "label": "Abuse & Report Records", "sub": "Retention 90 d", "kind": "store" } ] } ] } ], "outside": [ { "id": "ocloud", "label": "Cloud Backup Providers", "kind": "external" }, { "id": "ocdn2", "label": "CDN Edge Cache", "kind": "external" } ], "edges": [ { "from": "lchat", "to": "ocloud", "label": "encrypted backup", "kind": "batch" }, { "from": "sblob", "to": "ocdn2", "label": "origin pull", "kind": "sync" }, { "from": "sund", "to": "lchat", "label": "drained on delivery", "kind": "async" }, { "from": "dvault", "to": "ocloud", "label": "key escrow, user held", "kind": "sync" } ], "note": "Everything above the durable band is rebuildable or expendable. Losing it costs delivery latency, not history.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-08" } }, { "id": "18-data-model", "title": "Core Data Model", "layout": "er", "canvas": { "width": 1700, "cols": 4 }, "rowGap": 260, "entities": [ { "id": "contact", "name": "contact_link", "kind": "store", "row": 0, "col": 0, "attrs": [ "account_id FK -> account", "contact_hash PK", "is_blocked", "discovered_at" ] }, { "id": "account", "name": "account", "kind": "store", "row": 0, "col": 1, "attrs": [ "account_id PK", "phone_e164 UNIQUE", "display_name", "about_status", "photo_blob_id", "created_at" ] }, { "id": "device", "name": "device", "kind": "store", "row": 0, "col": 2, "attrs": [ "device_id PK", "account_id FK -> account", "platform", "is_primary", "registration_id", "last_seen_at" ] }, { "id": "devkey", "name": "device_key", "kind": "store", "row": 0, "col": 3, "attrs": [ "key_id PK", "device_id FK -> device", "key_type identity | signed | onetime", "public_key", "consumed_at" ] }, { "id": "status", "name": "status_post", "kind": "store", "row": 1, "col": 0, "attrs": [ "status_id PK", "account_id FK -> account", "blob_id", "audience_rule", "expires_at" ] }, { "id": "member", "name": "membership", "kind": "store", "row": 1, "col": 1, "attrs": [ "conversation_id FK", "account_id FK -> account", "role member | admin | owner", "joined_at" ] }, { "id": "inbox", "name": "device_inbox", "kind": "store", "row": 1, "col": 2, "attrs": [ "device_id FK -> device", "message_id FK -> message_envelope", "ciphertext BLOB", "state", "expires_at" ] }, { "id": "receipt", "name": "receipt", "kind": "store", "row": 1, "col": 3, "attrs": [ "message_id FK", "device_id FK", "state delivered | read | played", "recorded_at" ] }, { "id": "call", "name": "call_record", "kind": "store", "row": 2, "col": 0, "attrs": [ "call_id PK", "conversation_id FK", "kind voice | video | group", "started_at", "duration_s" ] }, { "id": "conv", "name": "conversation", "kind": "store", "row": 2, "col": 1, "attrs": [ "conversation_id PK", "kind direct | group | broadcast", "created_by FK -> account", "created_at" ] }, { "id": "msg", "name": "message_envelope", "kind": "store", "row": 2, "col": 2, "attrs": [ "message_id PK server", "client_msg_id UNIQUE per sender", "conversation_id FK", "sender_device_id FK", "created_at", "expires_at" ] }, { "id": "blob", "name": "media_blob", "kind": "store", "row": 2, "col": 3, "attrs": [ "blob_id PK", "sha256_ciphertext", "size_bytes", "mime_type", "expires_at" ] }, { "id": "gmeta", "name": "group_metadata", "kind": "store", "row": 3, "col": 1, "attrs": [ "conversation_id PK FK", "subject", "description", "icon_blob_id", "only_admins_post" ] } ], "relations": [ { "from": "account", "to": "contact", "label": "1 : N", "from_side": "w", "to_side": "e" }, { "from": "account", "to": "device", "label": "1 : N", "from_side": "e", "to_side": "w" }, { "from": "device", "to": "devkey", "label": "1 : N", "from_side": "e", "to_side": "w" }, { "from": "account", "to": "status", "label": "1 : N", "from_side": "s1", "to_side": "n" }, { "from": "account", "to": "member", "label": "1 : N", "from_side": "s3", "to_side": "n" }, { "from": "conv", "to": "member", "label": "1 : N", "from_side": "n", "to_side": "s" }, { "from": "conv", "to": "msg", "label": "1 : N", "from_side": "e", "to_side": "w" }, { "from": "conv", "to": "call", "label": "1 : N", "from_side": "w", "to_side": "e" }, { "from": "conv", "to": "gmeta", "label": "1 : 1", "from_side": "s", "to_side": "n", "kind": "optional" }, { "from": "msg", "to": "inbox", "label": "1 : N", "from_side": "n", "to_side": "s" }, { "from": "device", "to": "inbox", "label": "1 : N", "from_side": "s", "to_side": "n" }, { "from": "inbox", "to": "receipt", "label": "1 : N", "from_side": "e", "to_side": "w" }, { "from": "msg", "to": "blob", "label": "0 : 1", "from_side": "e", "to_side": "w", "kind": "optional" } ], "note": "message_envelope has no body column. Content exists only as ciphertext in device_inbox, until acknowledged.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-08" } }, { "id": "19-integration-architecture", "title": "Integration and Interface Catalogue", "layout": "hub", "canvas": { "width": 1660 }, "left": { "title": "Inbound consumers", "nodes": [ { "id": "imob", "label": "Mobile Client", "sub": "iOS / Android", "kind": "app", "rel": "Noise / TCP 443" }, { "id": "iweb", "label": "Desktop & Web Client", "kind": "app", "rel": "Noise / WSS" }, { "id": "ibiz", "label": "Business Platform Partner", "kind": "external", "rel": "REST + webhook" }, { "id": "iadm", "label": "Trust & Safety Console", "kind": "app", "rel": "mTLS, internal" }, { "id": "iops", "label": "Operations Tooling", "kind": "app", "rel": "gRPC, audited" } ] }, "centre": { "title": "Platform", "nodes": [ { "id": "core", "label": "Consumer Messaging Platform", "sub": "23 services, 2 active regions", "kind": "app" } ] }, "right": { "title": "Outbound dependencies", "nodes": [ { "id": "oapns", "label": "Apple APNs", "kind": "external", "rel": "HTTP/2 push", "dir": "out", "kind2": "async" }, { "id": "ofcm", "label": "Google FCM", "kind": "external", "rel": "HTTP v1 push", "dir": "out", "kind2": "async" }, { "id": "ootp", "label": "SMS & Voice OTP", "kind": "external", "rel": "REST, per signup", "dir": "out" }, { "id": "ocdn", "label": "Global CDN", "kind": "external", "rel": "origin pull", "dir": "out" }, { "id": "oturn", "label": "STUN / TURN Fleet", "kind": "external", "rel": "UDP relay", "dir": "out" }, { "id": "obak", "label": "Cloud Backup Providers", "kind": "external", "rel": "OAuth upload", "dir": "out", "kind2": "batch" }, { "id": "oatt", "label": "Device Attestation", "kind": "external", "rel": "REST, per device", "dir": "out" }, { "id": "oint", "label": "Abuse Intelligence Feeds", "kind": "external", "rel": "hourly batch", "dir": "out", "kind2": "batch" } ] }, "note": "Every inbound interface terminates at the edge; no dependency reaches the data tier directly.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-08" } }, { "id": "20-security-trust-zones", "title": "Security Trust Zones", "layout": "zones", "canvas": { "width": 1700 }, "zones": [ { "title": "Untrusted — Internet", "kind": "trust", "nodes": [ { "id": "atk", "label": "Attacker", "sub": "Scraping, enumeration", "kind": "risk" }, { "id": "usr", "label": "Legitimate Client", "kind": "app" }, { "id": "unv", "label": "Unverified Client", "sub": "Modified or emulated", "kind": "risk" }, { "id": "sim", "label": "SIM Swap Attempt", "kind": "risk" } ] }, { "title": "Perimeter", "kind": "trust", "nodes": [ { "id": "ddos", "label": "Anycast & DDoS Scrubbing", "kind": "security" }, { "id": "tls", "label": "TLS 1.3 Termination", "kind": "security" }, { "id": "noise", "label": "Noise Handshake", "sub": "Device key pinning", "kind": "security" }, { "id": "guard", "label": "Rate & Abuse Guard", "sub": "Per number, IP, device", "kind": "security" } ] }, { "title": "Application zone", "kind": "trust", "nodes": [ { "id": "gw", "label": "Connection Gateway", "kind": "app" }, { "id": "authz", "label": "Authorization", "sub": "Device-scoped claims", "kind": "security" }, { "id": "svc", "label": "Core Services", "sub": "mTLS service mesh", "kind": "app" } ] }, { "title": "Data zone", "kind": "trust", "nodes": [ { "id": "ms", "label": "Message Store", "sub": "Ciphertext only", "kind": "store" }, { "id": "adb", "label": "Account & Group DB", "sub": "Encrypted at rest", "kind": "store" }, { "id": "blob", "label": "Media Blobs", "sub": "Opaque bytes", "kind": "store" } ] }, { "title": "Key & audit zone", "kind": "trust", "nodes": [ { "id": "kms", "label": "HSM-backed KMS", "kind": "security" }, { "id": "vault", "label": "Backup Key Vault", "sub": "10 attempts, then lock", "kind": "security" }, { "id": "audit", "label": "Audit Log", "sub": "Append only, WORM", "kind": "store" } ] } ], "edges": [ { "from": "atk", "to": "ddos", "label": "traffic dropped", "kind": "error" }, { "from": "sim", "to": "guard", "label": "lockout, 7 days", "kind": "error" }, { "from": "unv", "to": "noise", "label": "session refused", "kind": "error" }, { "from": "usr", "to": "tls", "label": "TLS 1.3, pinned", "kind": "sync" }, { "from": "noise", "to": "gw", "label": "authenticated session", "kind": "sync" }, { "from": "gw", "to": "authz", "label": "device claim check", "kind": "sync" }, { "from": "authz", "to": "svc", "label": "scoped token, 15 min", "kind": "sync" }, { "from": "svc", "to": "ms", "label": "ciphertext write", "kind": "sync" }, { "from": "svc", "to": "kms", "label": "envelope keys", "kind": "sync" }, { "from": "vault", "to": "audit", "label": "access logged", "kind": "async" } ], "note": "A perimeter breach yields ciphertext and metadata. Message content requires a device private key.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-08" } }, { "id": "21-deployment-architecture", "title": "Deployment and Multi-Region Topology", "layout": "nested", "canvas": { "width": 1700 }, "boxes": [ { "title": "Global edge — Anycast", "kind": "cloud", "dir": "row", "children": [ { "title": "Points of presence, 200+ sites", "kind": "boundary", "nodes": [ { "id": "pop", "label": "Edge Terminator", "sub": "TLS + Noise", "kind": "app" }, { "id": "scrub", "label": "DDoS Scrubbing", "kind": "security" }, { "id": "cdnpop", "label": "CDN Cache", "sub": "Media blobs", "kind": "store" } ] }, { "title": "Global routing", "kind": "boundary", "nodes": [ { "id": "bgp", "label": "BGP Anycast + GeoDNS", "kind": "integration" }, { "id": "steer", "label": "Health-based Steering", "sub": "Drains a bad region", "kind": "app" } ] } ] }, { "title": "Region A — primary for pinned accounts", "kind": "cloud", "dir": "row", "children": [ { "title": "AZ-1", "kind": "boundary", "nodes": [ { "id": "a1gw", "label": "Gateway Pool", "sub": "1M sockets", "kind": "app" }, { "id": "a1svc", "label": "Core Services", "sub": "Kubernetes", "kind": "app" } ] }, { "title": "AZ-2", "kind": "boundary", "nodes": [ { "id": "a2gw", "label": "Gateway Pool", "sub": "1M sockets", "kind": "app" }, { "id": "a2svc", "label": "Core Services", "sub": "Kubernetes", "kind": "app" } ] }, { "title": "AZ-3 — stateful", "kind": "boundary", "nodes": [ { "id": "a3ms", "label": "Message Store", "sub": "RF 3, quorum write", "kind": "store" }, { "id": "a3q", "label": "Delivery Queue", "kind": "queue" }, { "id": "a3db", "label": "Account & Group DB", "sub": "Sharded, semi-sync", "kind": "store" } ] } ] }, { "title": "Region B — active for its own pinned accounts", "kind": "cloud", "dir": "row", "children": [ { "title": "AZ-1", "kind": "boundary", "nodes": [ { "id": "b1gw", "label": "Gateway Pool", "kind": "app" }, { "id": "b1svc", "label": "Core Services", "kind": "app" } ] }, { "title": "AZ-2", "kind": "boundary", "nodes": [ { "id": "b2gw", "label": "Gateway Pool", "kind": "app" }, { "id": "b2svc", "label": "Core Services", "kind": "app" } ] }, { "title": "AZ-3 — stateful", "kind": "boundary", "nodes": [ { "id": "b3ms", "label": "Message Store", "sub": "RF 3, quorum write", "kind": "store" }, { "id": "b3q", "label": "Delivery Queue", "kind": "queue" }, { "id": "b3db", "label": "Account & Group DB", "kind": "store" } ] } ] } ], "outside": [ { "id": "obj", "label": "Multi-region Object Store", "kind": "store" }, { "id": "turnf", "label": "TURN Relay Fleet", "kind": "external" } ], "edges": [ { "from": "bgp", "to": "a1gw", "label": "nearest healthy PoP", "kind": "sync" }, { "from": "a3db", "to": "b3db", "label": "registry replication", "kind": "async" }, { "from": "a3ms", "to": "b3ms", "label": "cross-region route", "kind": "async" }, { "from": "steer", "to": "b1gw", "label": "failover drain, 15 min", "kind": "error" } ], "note": "Accounts are pinned to a home region. Both regions serve live traffic; neither is idle standby.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-08" } }, { "id": "22-cicd-environments", "title": "CI/CD and Environment Progression", "layout": "flow", "chain": true, "canvas": { "width": 1700 }, "stages": [ { "title": "Source", "nodes": [ { "id": "proto", "label": "Protocol Schemas", "sub": "Versioned, compat checked", "kind": "app" }, { "id": "repo", "label": "Monorepo", "sub": "Trunk based", "kind": "app" } ] }, { "title": "Build", "nodes": [ { "id": "ci", "label": "Hermetic Build", "sub": "Pinned toolchain", "kind": "app" }, { "id": "repro", "label": "Reproducible Client Build", "sub": "Publicly verifiable", "kind": "app" }, { "id": "scan", "label": "SAST & Dependency Scan", "kind": "decision" } ] }, { "title": "Gates", "nodes": [ { "id": "unit", "label": "Unit & Protocol Conformance", "kind": "decision" }, { "id": "crypto", "label": "Crypto Test Vectors", "sub": "Known-answer tests", "kind": "decision" }, { "id": "perf", "label": "Performance Budget", "sub": "p99 fanout", "kind": "decision" } ] }, { "title": "Pre-production", "nodes": [ { "id": "dev", "label": "Development", "kind": "app" }, { "id": "stg", "label": "Staging", "sub": "Synthetic load replay", "kind": "app" }, { "id": "can", "label": "Canary", "sub": "0.1% of devices", "kind": "app" } ] }, { "title": "Production", "nodes": [ { "id": "roll", "label": "Regional Rollout", "sub": "AZ by AZ", "kind": "app" }, { "id": "flag", "label": "Feature Flags", "sub": "Server-side kill switch", "kind": "app" } ] }, { "title": "Verify", "nodes": [ { "id": "rb", "label": "Rollback", "sub": "One command, 5 min", "kind": "app" }, { "id": "slo", "label": "SLO Watchdog", "sub": "Auto-halt on burn", "kind": "app" } ] } ], "edges": [ { "from": "slo", "to": "can", "label": "auto-rollback on error budget burn", "kind": "error", "route": "gutter" }, { "from": "scan", "to": "repo", "label": "block and reopen", "kind": "error", "route": "gutter" } ], "note": "Client releases are staged over days; a protocol change ships behind a flag ahead of the client.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-08" } }, { "id": "23-observability-slo", "title": "Observability and Service Levels", "layout": "grid", "canvas": { "width": 1700 }, "laneHeaderWidth": 180, "columns": [ "Emit", "Collect", "Store", "Evaluate", "Act" ], "rows": [ { "title": "Availability", "cells": [ [ { "label": "Gateway and service health", "kind": "app" } ], [ { "label": "OpenTelemetry agents", "kind": "integration" } ], [ { "label": "Metrics TSDB", "kind": "store" } ], [ { "label": "99.99% messaging path", "kind": "decision" } ], [ { "label": "Page on-call, shed load", "kind": "app" } ] ] }, { "title": "Latency", "cells": [ [ { "label": "Send to deliver spans", "kind": "app" } ], [ { "label": "Trace sampling 1 in 1000", "kind": "integration" } ], [ { "label": "Trace store", "kind": "store" } ], [ { "label": "p99 under 500 ms in region", "kind": "decision" } ], [ { "label": "Halt rollout, scale fanout", "kind": "app" } ] ] }, { "title": "Delivery integrity", "cells": [ [ { "label": "Ack and receipt counters", "kind": "app" } ], [ { "label": "Event bus", "kind": "queue" } ], [ { "label": "Delivery ledger", "kind": "store" } ], [ { "label": "Undelivered over 30 min", "kind": "decision" } ], [ { "label": "Replay from device inbox", "kind": "app" } ] ] }, { "title": "Abuse & safety", "cells": [ [ { "label": "Reports, spam and rate signals", "kind": "app" } ], [ { "label": "Safety pipeline", "kind": "integration" } ], [ { "label": "Abuse record store", "kind": "store" } ], [ { "label": "Ban score threshold", "kind": "decision" } ], [ { "label": "Throttle, then ban", "kind": "risk" } ] ] }, { "title": "Capacity & cost", "cells": [ [ { "label": "Socket, fanout and egress counts", "kind": "app" } ], [ { "label": "Metrics agents", "kind": "integration" } ], [ { "label": "Capacity warehouse", "kind": "store" } ], [ { "label": "Headroom under 30%", "kind": "decision" } ], [ { "label": "Scale gateway pools", "kind": "app" } ] ] }, { "title": "Client health", "cells": [ [ { "label": "Crash, ANR and battery reports", "kind": "app" } ], [ { "label": "Crash pipeline", "kind": "integration" } ], [ { "label": "Crash store", "kind": "store" } ], [ { "label": "Crash-free 99.9% of sessions", "kind": "decision" } ], [ { "label": "Staged client rollback", "kind": "app" } ] ] } ], "note": "Signals are never derived from message content; every row is metadata or client telemetry.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-08" } } ]