[ { "id": "01-system-context", "title": "Programmable Messaging Platform — System Context", "layout": "context", "canvas": { "width": 1700 }, "colWidth": 265, "system": { "label": "Programmable Messaging Platform", "sub": "Submit to terminal state" }, "groups": [ { "side": "left", "title": "People", "nodes": [ { "id": "dev", "label": "App developer", "kind": "actor", "sub": "40,000 tenants", "rel": "POST /v1/messages", "dir": "in" }, { "id": "recipient", "label": "Message recipient", "kind": "actor", "sub": "the handset", "rel": "replies STOP", "dir": "in" }, { "id": "compliance", "label": "Compliance officer", "kind": "actor", "rel": "queries by number", "dir": "in" }, { "id": "sre", "label": "Platform SRE", "kind": "actor", "rel": "route health", "dir": "in" } ] }, { "side": "right", "title": "Carriers and channels (not ours)", "nodes": [ { "id": "mno", "label": "Mobile network operator", "kind": "external", "sub": "SMPP bind", "rel": "submit + receipt", "kind2": "bidirectional" }, { "id": "agg", "label": "SMS aggregator", "kind": "external", "sub": "HTTP", "rel": "submit + receipt", "kind2": "bidirectional", "icon": "fa5_broadcast_tower" }, { "id": "wa", "label": "WhatsApp Business Platform", "kind": "external", "rel": "template send", "kind2": "bidirectional", "icon": "fa5_whatsapp" }, { "id": "rcs", "label": "RCS hub", "kind": "external", "rel": "rich send", "kind2": "bidirectional" } ] }, { "side": "top", "title": "Tenant systems", "nodes": [ { "id": "tapp", "label": "Tenant application", "kind": "external", "sub": "OTP and transactional", "rel": "send + status", "kind2": "bidirectional" }, { "id": "campaign", "label": "Campaign tool", "kind": "external", "sub": "bulk", "rel": "batch submit", "dir": "in" }, { "id": "tidp", "label": "Tenant identity provider", "kind": "security", "rel": "console SSO", "dir": "in" } ] }, { "side": "bottom", "title": "Adjacent platforms (out of scope)", "nodes": [ { "id": "metering", "label": "Metering and billing", "kind": "external", "sub": "rated usage events", "kind2": "async" }, { "id": "numbers", "label": "Number inventory", "kind": "external", "sub": "read only", "dir": "in" }, { "id": "regulator", "label": "Regulator / ombudsman", "kind": "external", "sub": "evidence on request", "kind2": "batch" } ] } ], "note": "Everything on the right belongs to somebody else: their window, their price, their receipt, their silence.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture", "date": "2026-10" } }, { "id": "02-high-level-architecture", "title": "Programmable Messaging Platform — High-Level Architecture", "layout": "flow", "canvas": { "width": 1780 }, "chain": true, "align": "middle", "nodeWidth": 190, "stages": [ { "title": "Submit", "nodes": [ { "id": "tenant", "label": "Tenant application", "kind": "external" }, { "id": "api", "label": "Send API", "kind": "integration", "sub": "Cloud Run" } ] }, { "title": "Admit", "nodes": [ { "id": "validate", "label": "Validation", "kind": "app", "sub": "destination, sender, body" }, { "id": "consent", "label": "Consent and compliance", "kind": "security", "sub": "fails closed" } ] }, { "title": "Own", "nodes": [ { "id": "ledger", "label": "Message ledger", "kind": "store", "sub": "Cloud Spanner" }, { "id": "bodies", "label": "Body store", "kind": "store", "sub": "Cloud Storage, CMEK" } ] }, { "title": "Schedule and route", "nodes": [ { "id": "lanes", "label": "Class lanes", "kind": "queue", "sub": "Pub/Sub" }, { "id": "pacer", "label": "Route pacing", "kind": "queue", "sub": "Cloud Tasks" }, { "id": "selector", "label": "Route selector", "kind": "app", "sub": "cost, quality, pinned" } ] }, { "title": "Attempt", "nodes": [ { "id": "adapter", "label": "Channel adapters", "kind": "app", "sub": "one contract" }, { "id": "session", "label": "Session plane", "kind": "platform", "sub": "GKE StatefulSet" } ] }, { "title": "Carrier", "nodes": [ { "id": "carrier", "label": "Carrier or aggregator", "kind": "external", "sub": "220 routes" } ] }, { "title": "Outcome", "nodes": [ { "id": "receipts", "label": "Receipt ingest", "kind": "integration", "sub": "25k/s" }, { "id": "projection", "label": "State projection", "kind": "store", "sub": "Bigtable" }, { "id": "callback", "label": "Tenant callback", "kind": "integration", "sub": "signed, DLQ" } ] } ], "edges": [ { "from": "carrier", "to": "receipts", "label": "late, partial, absent", "kind": "async", "route": "gutter" }, { "from": "receipts", "to": "ledger", "label": "append", "kind": "async", "route": "gutter" } ], "note": "State is a fold over the ledger, never a field the submit path writes.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture" } }, { "id": "03-actors", "title": "Who the Platform Is For, and What They Get To Do", "layout": "actors", "canvas": { "width": 1740 }, "cardWidth": 268, "groups": [ { "title": "The person holding the handset", "kind": "boundary", "actors": [ { "id": "recipient", "label": "Message recipient", "sub": "never signed up with us", "goal": "Get the code while the login page is still open, and have STOP actually stop it.", "journeys": [ { "id": "j-otp", "label": "Receive a login code", "sub": "the six-digit moment" }, { "id": "j-stop", "label": "Text STOP and be left alone" } ] } ] }, { "title": "Tenant builders and operators", "kind": "cloud", "actors": [ { "id": "dev", "label": "App developer", "sub": "40,000 tenants", "goal": "Send my first message in ten minutes, and find out why one did not arrive without opening a ticket.", "journeys": [ { "id": "j-integrate", "label": "Send the first message" }, { "label": "Diagnose a non-delivery" } ] }, { "id": "campaigner", "label": "Campaign operator", "sub": "bulk traffic", "goal": "Get four million messages out inside my window, and know whether they are paced or stuck.", "journeys": [ { "label": "Run a paced campaign" }, { "label": "Read queue age by route" } ] }, { "id": "officer", "label": "Compliance officer", "sub": "190 jurisdictions", "goal": "Prove what we sent to this number, when, and on whose recorded consent.", "journeys": [ { "label": "Answer a regulator" }, { "label": "Freeze a sender identity" } ] } ] }, { "title": "Carriers and the people who watch them", "kind": "plain", "actors": [ { "id": "carrier", "label": "Carrier or aggregator", "kind": "external", "sub": "220 routes", "goal": "Receive traffic inside the window we contracted, from a sender identity we registered.", "journeys": [ { "label": "Accept paced submissions" }, { "label": "Return delivery receipts" } ] }, { "id": "sre", "label": "Platform SRE", "sub": "on call", "goal": "Know within minutes that a route is accepting everything and delivering nothing.", "journeys": [ { "label": "Catch a silent route" }, { "label": "Drain a dead bind" } ] } ] } ], "note": "The paying customer is the developer; the person the product happens to is the recipient.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture" } }, { "id": "04-journey-otp", "title": "Journey — The Login Code That Has To Arrive Now", "layout": "journey", "canvas": { "width": 1700 }, "actor": { "label": "Message recipient", "sub": "mid-login, on a bank app", "goal": "Finish signing in without starting again", "trigger": "Tapped \"send me a code\" on a login screen", "success": "One code, once, inside the time the page allows" }, "phases": [ { "title": "Tap send code", "sub": "page starts a timer" }, { "title": "Wait" }, { "title": "Tap it again", "moment": true }, { "title": "Code arrives", "moment": true }, { "title": "Type it in" } ], "lanes": [ { "title": "What they do", "kind": "step", "cells": [ [ { "label": "Asks for a code" } ], [ { "label": "Watches the lock screen" } ], [ { "label": "Presses resend" } ], [ { "label": "Reads six digits" } ], [ { "label": "Submits and is in" } ] ] }, { "title": "What the platform does", "kind": "system", "cells": [ [ { "label": "Accepts, interactive class" }, { "label": "Ledger write, then ack" } ], [ { "label": "Paced to the route" }, { "label": "Carrier accepts" } ], [ { "label": "Same client reference" }, { "label": "Dedup returns message 1" } ], [ { "label": "Receipt correlated" }, { "label": "Status becomes delivered" } ], [ { "label": "Usage event emitted" } ] ] }, { "title": "How it feels", "kind": "emotion", "levels": [ "Fine", "Anxious", "Giving up" ], "points": [ 0, 1, 2, 0, 0 ] }, { "title": "Where it hurts", "kind": "pain", "cells": [ [], [ { "label": "No receipt yet, so no answer" } ], [ { "label": "Resend without dedup = two codes" } ], [ { "label": "A carrier receipt can be a lie" } ], [] ] }, { "title": "What the architecture owes it", "kind": "gain", "cells": [ [ { "label": "Ack means durably owned" } ], [ { "label": "p95 to carrier under 2 s" } ], [ { "label": "Client reference is the key" } ], [ { "label": "Unknown stays unknown" } ], [ { "label": "Attempt-level cost record" } ] ] } ], "chain": true, "note": "The trough is the resend, and the resend is where duplicates are made.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture" } }, { "id": "05-journey-integrate", "title": "Journey — Developer Sends One Message, Then Has To Explain One", "layout": "journey", "canvas": { "width": 1740 }, "actor": { "label": "App developer", "sub": "first integration, no telecom background", "goal": "Send a message, then account for one that did not arrive", "trigger": "A product requirement to send order confirmations", "success": "Shipped, and able to answer support without a ticket to us" }, "phases": [ { "title": "Read the docs" }, { "title": "First send" }, { "title": "It says accepted" }, { "title": "Customer says nothing came", "moment": true }, { "title": "Find out why", "moment": true }, { "title": "Ship" } ], "lanes": [ { "title": "What they do", "kind": "step", "cells": [ [ { "label": "Picks a sender identity" } ], [ { "label": "POSTs one message" } ], [ { "label": "Logs the message id" } ], [ { "label": "Searches by their own id" } ], [ { "label": "Reads the attempt trail" } ], [ { "label": "Adds the callback" } ] ] }, { "title": "What the platform does", "kind": "system", "cells": [ [ { "label": "Dry-run shows route and price" } ], [ { "label": "Rejects unroutable at submit" } ], [ { "label": "Accepted is a promise, not a delivery" } ], [ { "label": "Lookup by client reference" } ], [ { "label": "Route, attempts, receipts, reason" } ], [ { "label": "Signed callback with DLQ" } ] ] }, { "title": "How it feels", "kind": "emotion", "levels": [ "Confident", "Uneasy", "Blaming us" ], "points": [ 0, 0, 1, 2, 1, 0 ] }, { "title": "Where it hurts", "kind": "pain", "cells": [ [ { "label": "Sender rules differ by country" } ], [], [ { "label": "Accepted reads as delivered" } ], [ { "label": "No answer sounds like no system" } ], [ { "label": "Carrier reason codes are jargon" } ], [] ] }, { "title": "What the architecture owes it", "kind": "gain", "cells": [ [ { "label": "Rules are data, not support lore" } ], [ { "label": "Fast, specific rejections" } ], [ { "label": "Status vocabulary says accepted" } ], [ { "label": "Unknown is a named answer" } ], [ { "label": "Reason mapped to plain words" } ], [ { "label": "Pull reconstructs what push missed" } ] ] } ], "chain": true, "note": "The trough is a customer complaint the developer cannot answer; everything in act 5 exists to move it.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture" } }, { "id": "06-journey-stop", "title": "Journey — Texting STOP and Being Left Alone", "layout": "journey", "canvas": { "width": 1600 }, "actor": { "label": "Message recipient", "sub": "on a shared short code", "goal": "Make it stop, once, without a web form", "trigger": "A marketing message they did not ask for", "success": "One confirmation, then silence from every tenant on that number" }, "phases": [ { "title": "Unwanted message" }, { "title": "Replies STOP", "moment": true }, { "title": "Confirmation" }, { "title": "The next campaign", "moment": true } ], "lanes": [ { "title": "What they do", "kind": "step", "cells": [ [ { "label": "Reads it, annoyed" } ], [ { "label": "Texts STOP" } ], [ { "label": "Gets one reply" } ], [ { "label": "Waits to see" } ] ] }, { "title": "What the platform does", "kind": "system", "cells": [ [ { "label": "Inbound endpoint verified" } ], [ { "label": "Keyword intercepted first" }, { "label": "Consent written, append-only" } ], [ { "label": "Mandated reply sent" }, { "label": "Tenant told, already actioned" } ], [ { "label": "Submit refused, attributably" } ] ] }, { "title": "How it feels", "kind": "emotion", "levels": [ "Left alone", "Annoyed", "Reporting you" ], "points": [ 1, 1, 0, 0 ] }, { "title": "Where it hurts", "kind": "pain", "cells": [ [ { "label": "Shared number hides the sender" } ], [ { "label": "Duplicate inbound = two opt-outs" } ], [], [ { "label": "Messages already in flight" } ] ] }, { "title": "What the architecture owes it", "kind": "gain", "cells": [ [ { "label": "Ownership by allocation rule" } ], [ { "label": "Dedup by provider reference" } ], [ { "label": "Platform owns the keyword" } ], [ { "label": "30 s propagation, stated" } ] ] } ], "chain": true, "note": "The only journey where the right answer is that nothing else happens.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture" } }, { "id": "07-layered", "title": "Layered Architecture — Submit Downwards, Receipts Upwards", "layout": "bands", "canvas": { "width": 1700 }, "layerHeaderWidth": 160, "bands": [ { "name": "Tenant edge", "nodes": [ { "id": "sendapi", "label": "Send API", "kind": "integration", "sub": "Cloud Run" }, { "id": "batchapi", "label": "Batch and dry-run", "kind": "integration" }, { "id": "statusapi", "label": "Status query", "kind": "integration" }, { "id": "cbout", "label": "Callback dispatch", "kind": "integration", "sub": "signed" }, { "id": "console", "label": "Console and reporting", "kind": "app" } ] }, { "name": "Admission", "nodes": [ { "id": "norm", "label": "Destination normalise", "kind": "app" }, { "id": "senderchk", "label": "Sender and jurisdiction", "kind": "app" }, { "id": "dedup", "label": "Client-reference dedup", "kind": "app" }, { "id": "consentev", "label": "Consent and compliance", "kind": "security", "sub": "fails closed" }, { "id": "credit", "label": "Quota and credit", "kind": "app" } ] }, { "name": "Ownership", "nodes": [ { "id": "ledgerw", "label": "Message ledger", "kind": "store", "sub": "Cloud Spanner" }, { "id": "bodyw", "label": "Body and media store", "kind": "store", "sub": "Cloud Storage" }, { "id": "proj", "label": "State projection", "kind": "store", "sub": "Bigtable" } ] }, { "name": "Scheduling", "nodes": [ { "id": "classlane", "label": "Class lanes", "kind": "queue", "sub": "Pub/Sub" }, { "id": "fair", "label": "Cross-tenant fairness", "kind": "app" }, { "id": "lease", "label": "Route leases", "kind": "store", "sub": "Memorystore" }, { "id": "pace", "label": "Pacing and parking", "kind": "queue", "sub": "Cloud Tasks" }, { "id": "ttl", "label": "TTL expiry sweeper", "kind": "app" } ] }, { "name": "Routing and adapters", "nodes": [ { "id": "sel", "label": "Route selector", "kind": "app" }, { "id": "breaker", "label": "Per-route breaker", "kind": "app" }, { "id": "smsad", "label": "SMS and MMS adapter", "kind": "app" }, { "id": "waad", "label": "WhatsApp adapter", "kind": "app", "icon": "fa5_whatsapp" }, { "id": "rcsad", "label": "RCS adapter", "kind": "app" } ] }, { "name": "Session plane", "nodes": [ { "id": "bind", "label": "Carrier binds", "kind": "platform", "sub": "GKE StatefulSet" }, { "id": "natout", "label": "Allowlisted egress", "kind": "platform", "sub": "Cloud NAT", "icon": "net_nat" }, { "id": "custody", "label": "Credential custody", "kind": "security", "sub": "Secret Manager" } ] }, { "name": "Ingest (upwards)", "nodes": [ { "id": "rcptin", "label": "Receipt ingest", "kind": "integration", "sub": "verify and dedup" }, { "id": "inbin", "label": "Inbound ingest", "kind": "integration" }, { "id": "corr", "label": "Correlate and apply", "kind": "app", "sub": "monotonic" }, { "id": "quar", "label": "Quarantine", "kind": "risk", "sub": "uncorrelatable" }, { "id": "kw", "label": "Keyword interception", "kind": "security" } ] }, { "name": "Control plane", "nodes": [ { "id": "routereg", "label": "Route and price table", "kind": "store", "sub": "Spanner" }, { "id": "senderreg", "label": "Sender-identity registry", "kind": "store" }, { "id": "rules", "label": "Compliance rule set", "kind": "store", "sub": "versioned" }, { "id": "consentst", "label": "Consent store", "kind": "store", "sub": "append-only" }, { "id": "audit", "label": "Audit log", "kind": "store", "sub": "7 years" } ] } ], "edges": [ { "from": "sendapi", "to": "consentev", "label": "every submit", "kind": "sync" }, { "from": "consentev", "to": "ledgerw", "label": "then ack", "kind": "sync" }, { "from": "classlane", "to": "sel", "label": "by class", "kind": "async" }, { "from": "smsad", "to": "bind", "label": "attempt", "kind": "sync" }, { "from": "rcptin", "to": "corr", "label": "provider ref", "kind": "async" }, { "from": "consentst", "to": "consentev", "label": "hot path", "kind": "sync", "route": "gutter" } ], "note": "The only layer that writes durably on submit is Ownership; everything below it is retryable.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture" } }, { "id": "08-platform-components", "title": "Container View — Services, Stores and the Boundaries Between Them", "layout": "nested", "canvas": { "width": 1760 }, "boxes": [ { "title": "Google Cloud — messaging project", "kind": "cloud", "dir": "col", "children": [ { "title": "Tenant-facing plane", "kind": "boundary", "nodes": [ { "id": "lb", "label": "Global load balancer", "kind": "integration", "sub": "Cloud Armor" }, { "id": "submit", "label": "Submit service", "kind": "app", "sub": "Cloud Run" }, { "id": "status", "label": "Status service", "kind": "app", "sub": "Cloud Run" }, { "id": "cb", "label": "Callback dispatcher", "kind": "app", "sub": "Cloud Run" } ] }, { "title": "Admission and ownership", "kind": "boundary", "nodes": [ { "id": "admit", "label": "Admission service", "kind": "app" }, { "id": "compl", "label": "Compliance evaluator", "kind": "security" }, { "id": "spanner", "label": "Message ledger", "kind": "store", "sub": "Cloud Spanner" }, { "id": "gcs", "label": "Body store", "kind": "store", "sub": "Cloud Storage" }, { "id": "bt", "label": "State projection", "kind": "store", "sub": "Bigtable" } ] }, { "title": "Delivery plane", "kind": "boundary", "nodes": [ { "id": "sched", "label": "Scheduler", "kind": "app", "sub": "class lanes" }, { "id": "psub", "label": "Lane topics", "kind": "queue", "sub": "Pub/Sub" }, { "id": "tasks", "label": "Route pacing queues", "kind": "queue", "sub": "Cloud Tasks" }, { "id": "attempt", "label": "Attempt executor", "kind": "app", "sub": "Cloud Run" }, { "id": "redis", "label": "Lease and quality store", "kind": "store", "sub": "Memorystore" } ] }, { "title": "Session plane (stateful, pinned)", "kind": "trust", "nodes": [ { "id": "smpp", "label": "SMPP session pods", "kind": "platform", "sub": "GKE StatefulSet" }, { "id": "nat", "label": "Static egress", "kind": "platform", "sub": "Cloud NAT", "icon": "net_nat" }, { "id": "sm", "label": "Carrier credential custody", "kind": "security", "sub": "Secret Manager + KMS" } ] }, { "title": "Ingest plane", "kind": "boundary", "nodes": [ { "id": "rcpt", "label": "Receipt endpoint", "kind": "integration" }, { "id": "inb", "label": "Inbound endpoint", "kind": "integration" }, { "id": "rpsub", "label": "Receipt and inbound streams", "kind": "queue", "sub": "Pub/Sub" }, { "id": "apply", "label": "Correlate and apply", "kind": "app" }, { "id": "qbucket", "label": "Quarantine", "kind": "risk" } ] }, { "title": "Control plane and evidence", "kind": "boundary", "nodes": [ { "id": "reg", "label": "Registry service", "kind": "app", "sub": "routes, senders, rules" }, { "id": "consentdb", "label": "Consent store", "kind": "store", "sub": "Spanner" }, { "id": "bq", "label": "Analytics and evidence", "kind": "store", "sub": "BigQuery" }, { "id": "logs", "label": "Audit archive", "kind": "store", "sub": "Bucket Lock" } ] } ] } ], "outside": [ { "id": "carriers", "label": "Carriers and aggregators", "kind": "external", "sub": "220 routes" }, { "id": "chapi", "label": "Channel business APIs", "kind": "external", "sub": "WhatsApp, RCS" }, { "id": "meter", "label": "Metering and billing", "kind": "external" } ], "edges": [ { "from": "lb", "to": "submit", "label": "HTTPS", "kind": "sync" }, { "from": "submit", "to": "admit", "kind": "sync" }, { "from": "admit", "to": "compl", "label": "fails closed", "kind": "sync" }, { "from": "admit", "to": "spanner", "label": "append then ack", "kind": "sync" }, { "from": "sched", "to": "psub", "kind": "async" }, { "from": "psub", "to": "attempt", "kind": "async" }, { "from": "attempt", "to": "tasks", "label": "pace", "kind": "async" }, { "from": "attempt", "to": "smpp", "label": "submit", "kind": "sync" }, { "from": "smpp", "to": "carriers", "label": "bind", "kind": "bidirectional" }, { "from": "attempt", "to": "chapi", "label": "HTTPS", "kind": "sync" }, { "from": "carriers", "to": "rcpt", "label": "receipts", "kind": "async" }, { "from": "rcpt", "to": "rpsub", "kind": "async" }, { "from": "rpsub", "to": "apply", "kind": "async" }, { "from": "apply", "to": "bt", "kind": "async" }, { "from": "apply", "to": "qbucket", "label": "no match", "kind": "error" }, { "from": "apply", "to": "meter", "kind": "async" } ], "note": "Omitted: console, IaC and the per-service sidecars. The session plane is the only stateful workload.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture" } }, { "id": "09-integration", "title": "Interface Catalogue — What Comes In, What Goes Out", "layout": "hub", "canvas": { "width": 1700 }, "left": { "title": "Inbound to the platform", "nodes": [ { "id": "send", "label": "Send API", "kind": "integration", "sub": "REST, message or batch", "rel": "submit" }, { "id": "statusq", "label": "Status API", "kind": "integration", "sub": "id or client reference", "rel": "pull" }, { "id": "rcpthook", "label": "Carrier receipt endpoint", "kind": "integration", "sub": "signed or allowlisted", "rel": "receipts" }, { "id": "inbhook", "label": "Carrier inbound endpoint", "kind": "integration", "sub": "ack under 250 ms", "rel": "inbound" } ] }, "centre": { "title": "Programmable Messaging Platform", "nodes": [ { "id": "core", "label": "Message spine", "kind": "app", "sub": "admit, own, schedule, attempt" }, { "id": "adapters", "label": "Channel adapters", "kind": "app", "sub": "one internal contract" } ] }, "right": { "title": "Outbound from the platform", "nodes": [ { "id": "smppout", "label": "SMPP binds", "kind": "external", "sub": "MNOs, static egress", "rel": "submit_sm", "dir": "out" }, { "id": "httpout", "label": "Aggregator HTTP", "kind": "external", "sub": "REST per provider", "rel": "submit", "dir": "out" }, { "id": "richout", "label": "Rich channel APIs", "kind": "external", "sub": "WhatsApp, RCS", "rel": "send", "dir": "out" }, { "id": "cbhook", "label": "Tenant callback", "kind": "integration", "sub": "signed, retried, DLQ", "rel": "status", "dir": "out" } ] }, "note": "Four inbound contracts, four outbound. Omitted for legibility: the registry API (view 18) and the rated-usage stream (views 10 and 14).", "meta": { "v": "1.0", "owner": "Integration Platform Architecture" } }, { "id": "10-data-flow", "title": "Data Flow — One Message, From Submission To Evidence", "layout": "flow", "canvas": { "width": 1780 }, "chain": true, "align": "top", "nodeWidth": 196, "stages": [ { "title": "Sources", "nodes": [ { "id": "tenantapp", "label": "Tenant submission", "kind": "external", "sub": "body + destination" }, { "id": "carrierev", "label": "Carrier events", "kind": "external", "sub": "receipts, inbound" } ] }, { "title": "Landing", "nodes": [ { "id": "ledg", "label": "Message ledger", "kind": "store", "sub": "submission + attempts" }, { "id": "body", "label": "Body store", "kind": "store", "sub": "30 days default" }, { "id": "rstream", "label": "Receipt stream", "kind": "queue", "sub": "13 months" }, { "id": "istream", "label": "Inbound stream", "kind": "queue", "sub": "90 days" } ] }, { "title": "Processing", "nodes": [ { "id": "correlate", "label": "Correlate to attempt", "kind": "app", "sub": "provider reference" }, { "id": "fold", "label": "Monotonic state fold", "kind": "app", "sub": "no backwards moves" }, { "id": "rate", "label": "Rate the attempt", "kind": "app", "sub": "segments x price" }, { "id": "quality", "label": "Route quality rollup", "kind": "app", "sub": "Dataflow" } ] }, { "title": "Serving", "nodes": [ { "id": "pstore", "label": "State projection", "kind": "store", "sub": "Bigtable" }, { "id": "qstore", "label": "Route quality store", "kind": "store", "sub": "Memorystore" }, { "id": "warehouse", "label": "Analytics and evidence", "kind": "store", "sub": "BigQuery" } ] }, { "title": "Consumers", "nodes": [ { "id": "statusc", "label": "Status API and callbacks", "kind": "integration" }, { "id": "selc", "label": "Route selector", "kind": "app", "sub": "reads quality" }, { "id": "meterc", "label": "Metering and billing", "kind": "external" }, { "id": "auditc", "label": "Regulator and dispute", "kind": "external", "sub": "7 years" } ] } ], "edges": [ { "from": "rstream", "to": "correlate", "label": "late, duplicated", "kind": "async" }, { "from": "correlate", "to": "fold", "kind": "sync" }, { "from": "fold", "to": "pstore", "label": "rebuildable", "kind": "async" }, { "from": "rate", "to": "meterc", "label": "one per attempt", "kind": "async", "route": "gutter" }, { "from": "quality", "to": "qstore", "kind": "async" }, { "from": "ledg", "to": "fold", "kind": "sync" } ], "note": "The projection is a cache of the ledger; the receipt stream outlives the bodies it describes.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture" } }, { "id": "11-data-architecture", "title": "Data Architecture — Ownership, Rebuildability and Retention", "layout": "nested", "canvas": { "width": 1760 }, "boxes": [ { "title": "Authoritative — cannot be rebuilt from anything else", "kind": "trust", "dir": "row", "children": [ { "title": "What we did", "kind": "boundary", "nodes": [ { "id": "a_ledger", "label": "Message ledger", "kind": "store", "sub": "Spanner, RPO 0, 90 d hot" }, { "id": "a_receipt", "label": "Receipt stream", "kind": "store", "sub": "13 months, evidence" }, { "id": "a_inbound", "label": "Inbound messages", "kind": "store", "sub": "90 days" } ] }, { "title": "What we were allowed to do", "kind": "boundary", "nodes": [ { "id": "a_consent", "label": "Consent history", "kind": "store", "sub": "append-only, 7 years" }, { "id": "a_audit", "label": "Audit log", "kind": "store", "sub": "Bucket Lock, 7 years" } ] } ] }, { "title": "Configuration — small, strongly consistent, versioned", "kind": "boundary", "dir": "row", "children": [ { "title": "Control plane", "kind": "plain", "nodes": [ { "id": "c_route", "label": "Route and price table", "kind": "store", "sub": "220 routes" }, { "id": "c_sender", "label": "Sender-identity registry", "kind": "store" }, { "id": "c_rules", "label": "Jurisdictional rule set", "kind": "store", "sub": "no deploy to change" }, { "id": "c_tenant", "label": "Tenancy and entitlement", "kind": "store" } ] } ] }, { "title": "Derived — rebuildable from the authoritative stores", "kind": "boundary", "dir": "row", "children": [ { "title": "Serving projections", "kind": "plain", "nodes": [ { "id": "d_state", "label": "State projection", "kind": "store", "sub": "RTO 2 h to rebuild" }, { "id": "d_index", "label": "Client-reference index", "kind": "store" }, { "id": "d_bq", "label": "Analytics marts", "kind": "store", "sub": "BigQuery" } ] }, { "title": "Volatile operational state", "kind": "plain", "nodes": [ { "id": "d_lease", "label": "Route leases", "kind": "store", "sub": "RPO 60 s, not authority" }, { "id": "d_quality", "label": "Route quality counters", "kind": "store", "sub": "RPO 60 s" } ] } ] }, { "title": "Content — shorter life than the record of it", "kind": "trust", "dir": "row", "children": [ { "title": "Tenant content", "kind": "plain", "nodes": [ { "id": "b_body", "label": "Message bodies", "kind": "store", "sub": "0 to 90 d, per-tenant keys" }, { "id": "b_media", "label": "MMS and rich media", "kind": "store", "sub": "CMEK" }, { "id": "b_quar", "label": "Quarantined payloads", "kind": "risk", "sub": "30 days" } ] } ] } ], "edges": [ { "from": "a_ledger", "to": "d_state", "label": "fold", "kind": "async" }, { "from": "a_receipt", "to": "d_state", "label": "fold", "kind": "async" }, { "from": "c_route", "to": "d_lease", "label": "windows", "kind": "sync" } ], "note": "Store-no-body mode removes the bottom band entirely and changes nothing above it.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture" } }, { "id": "12-data-model", "title": "Data Model — Message, Attempt, Receipt, Consent", "layout": "er", "canvas": { "width": 1700, "cols": 4 }, "rowGap": 260, "entities": [ { "id": "tenant", "name": "tenant", "kind": "store", "row": 0, "col": 0, "attrs": [ "tenant_id PK", "plan", "entitlement_mps", "residency_region", "credit_balance" ] }, { "id": "sender", "name": "sender_identity", "kind": "store", "row": 0, "col": 1, "attrs": [ "sender_id PK", "tenant_id FK -> tenant", "type long|short|alpha|toll", "registrations jsonb", "throughput_ceiling" ] }, { "id": "route", "name": "route", "kind": "store", "row": 0, "col": 2, "attrs": [ "route_id PK", "channel", "jurisdiction", "provider", "price_per_segment", "window_mps" ] }, { "id": "consent", "name": "consent_event", "kind": "store", "row": 1, "col": 0, "attrs": [ "consent_event_id PK", "tenant_id FK -> tenant", "destination_hash", "sender_id FK -> sender", "state granted|withdrawn", "evidence", "recorded_at" ] }, { "id": "message", "name": "message", "kind": "store", "row": 1, "col": 1, "attrs": [ "message_id PK", "tenant_id FK -> tenant", "client_reference UQ per tenant", "destination_hash", "sender_id FK -> sender", "channel_requested", "traffic_class", "ttl_expires_at", "segments_quoted", "accepted_at" ] }, { "id": "attempt", "name": "attempt", "kind": "store", "row": 1, "col": 2, "attrs": [ "attempt_id PK", "message_id FK -> message", "seq", "route_id FK -> route", "provider_reference", "submit_outcome", "segments_charged", "submitted_at" ] }, { "id": "body", "name": "message_body", "kind": "store", "row": 2, "col": 0, "attrs": [ "body_id PK", "message_id FK -> message", "object_uri", "kms_key", "purge_after" ] }, { "id": "receipt", "name": "receipt", "kind": "store", "row": 2, "col": 2, "attrs": [ "receipt_id PK", "attempt_id FK -> attempt NULLable", "provider_reference", "carrier_status", "carrier_reason", "carrier_timestamp", "received_at" ] }, { "id": "state", "name": "message_state", "kind": "store", "row": 2, "col": 1, "attrs": [ "message_id PK FK -> message", "state accepted..unknown", "terminal_at", "derived_from_attempt", "// projection, not authority" ] }, { "id": "inbound", "name": "inbound_message", "kind": "store", "row": 1, "col": 3, "attrs": [ "inbound_id PK", "route_id FK -> route", "provider_reference UQ per route", "sender_id FK -> sender", "keyword_actioned", "received_at" ] }, { "id": "usage", "name": "rated_usage_event", "kind": "store", "row": 2, "col": 3, "attrs": [ "usage_event_id PK", "attempt_id FK -> attempt", "tenant_id FK -> tenant", "route_id FK -> route", "segments", "amount" ] } ], "relations": [ { "from": "tenant", "to": "consent", "label": "1 : N", "from_side": "s", "to_side": "n" }, { "from": "consent", "to": "message", "label": "at submit", "from_side": "e", "to_side": "w", "kind": "optional" }, { "from": "sender", "to": "message", "label": "1 : N", "from_side": "s", "to_side": "n" }, { "from": "message", "to": "attempt", "label": "1 : N", "from_side": "e", "to_side": "w" }, { "from": "route", "to": "attempt", "label": "1 : N", "from_side": "s", "to_side": "n" }, { "from": "route", "to": "inbound", "label": "1 : N", "from_side": "s3", "to_side": "n" }, { "from": "message", "to": "state", "label": "1 : 1", "from_side": "s", "to_side": "n" }, { "from": "message", "to": "body", "label": "1 : 0..1", "from_side": "s1", "to_side": "n", "kind": "optional" }, { "from": "attempt", "to": "receipt", "label": "1 : N", "from_side": "s", "to_side": "n", "kind": "optional" }, { "from": "attempt", "to": "usage", "label": "1 : 1", "from_side": "s3", "to_side": "n" } ], "note": "receipt.attempt_id is nullable on purpose: an uncorrelatable receipt is kept, not dropped.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture" } }, { "id": "13-send-sequence", "title": "Critical Flow — Submit To Carrier Acceptance For An Interactive Message", "layout": "sequence", "canvas": { "width": 1740 }, "lifelines": [ { "id": "app", "label": "Tenant app", "kind": "actor" }, { "id": "api", "label": "Send API", "kind": "integration" }, { "id": "comp", "label": "Compliance", "kind": "security" }, { "id": "led", "label": "Message ledger", "kind": "store" }, { "id": "sch", "label": "Scheduler", "kind": "queue" }, { "id": "exe", "label": "Attempt executor", "kind": "app" }, { "id": "ses", "label": "Session plane", "kind": "platform" }, { "id": "car", "label": "Carrier", "kind": "external", "icon": "fa5_broadcast_tower" } ], "messages": [ { "from": "app", "to": "api", "label": "POST message, client reference", "kind": "call" }, { "from": "api", "to": "api", "label": "normalise, sender and jurisdiction check", "kind": "self" }, { "from": "api", "to": "led", "label": "dedup on client reference", "kind": "call" }, { "from": "led", "to": "api", "label": "no prior message", "kind": "return" }, { "from": "api", "to": "comp", "label": "consent, quiet hours, content", "kind": "call" }, { "from": "comp", "to": "api", "label": "allow, rule set v412", "kind": "return" }, { "from": "api", "to": "led", "label": "append submission", "kind": "call" }, { "from": "led", "to": "api", "label": "committed, RPO 0", "kind": "return" }, { "from": "api", "to": "app", "label": "202 accepted, id, segments", "kind": "return" }, { "from": "api", "to": "sch", "label": "enqueue, interactive lane", "kind": "async" }, { "from": "sch", "to": "exe", "label": "lease, fairness checked", "kind": "async" }, { "from": "exe", "to": "exe", "label": "select route, take throughput lease", "kind": "self" }, { "from": "exe", "to": "led", "label": "append attempt intent", "kind": "call" }, { "from": "exe", "to": "ses", "label": "submit on bind", "kind": "call" }, { "from": "ses", "to": "car", "label": "submit_sm", "kind": "call" }, { "from": "car", "to": "ses", "label": "accepted, provider reference", "kind": "return" }, { "from": "ses", "to": "led", "label": "append attempt outcome", "kind": "call" }, { "from": "car", "to": "exe", "label": "throttled: park with release time", "kind": "error" } ], "note": "The acknowledgement at step 9 promises ownership, not delivery. Nothing after it blocks the tenant.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture" } }, { "id": "14-receipt-and-state", "title": "Receipt Ingest — Verify, Correlate, Fold, Notify", "layout": "flow", "canvas": { "width": 1780 }, "chain": true, "align": "top", "nodeWidth": 198, "stages": [ { "title": "Arrival", "nodes": [ { "id": "cin", "label": "Carrier receipt", "kind": "external", "sub": "25k/s, 100k/s burst" }, { "id": "verify", "label": "Verify origin", "kind": "security", "sub": "signature or allowlist" } ] }, { "title": "Admit", "nodes": [ { "id": "rdedup", "label": "Dedup", "kind": "app", "sub": "route + provider ref" }, { "id": "durable", "label": "Receipt stream", "kind": "queue", "sub": "durable before ack" }, { "id": "ack", "label": "Ack carrier", "kind": "integration", "sub": "p99 under 250 ms" } ] }, { "title": "Correlate", "nodes": [ { "id": "match", "label": "Match to attempt", "kind": "app", "sub": "by provider reference" }, { "id": "noMatch", "label": "Quarantine", "kind": "risk", "sub": "never discarded" } ] }, { "title": "Fold", "nodes": [ { "id": "mono", "label": "Monotonic apply", "kind": "app", "sub": "terminal is terminal" }, { "id": "ttlx", "label": "TTL sweeper", "kind": "app", "sub": "no receipt = unknown" }, { "id": "ledg2", "label": "Message ledger", "kind": "store", "sub": "append the fact" } ] }, { "title": "Serve", "nodes": [ { "id": "proj2", "label": "State projection", "kind": "store", "sub": "Bigtable" }, { "id": "qual2", "label": "Route quality signal", "kind": "store", "sub": "feeds routing" } ] }, { "title": "Notify", "nodes": [ { "id": "cbq", "label": "Callback dispatch", "kind": "integration", "sub": "signed, retried" }, { "id": "dlq", "label": "Callback DLQ", "kind": "risk", "sub": "pull still works" }, { "id": "pull", "label": "Status API", "kind": "integration", "sub": "the fallback of record" } ] } ], "edges": [ { "from": "match", "to": "noMatch", "label": "unknown reference", "kind": "error" }, { "from": "ttlx", "to": "mono", "label": "expiry is a fact", "kind": "sync" }, { "from": "mono", "to": "qual2", "label": "delivery rate", "kind": "async" }, { "from": "cbq", "to": "dlq", "label": "exhausted", "kind": "error" } ], "note": "A receipt is acknowledged once it is durable, long before it is understood.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture" } }, { "id": "15-channel-pipelines", "title": "Per-Channel Pipelines Behind One Internal Contract", "layout": "swimlane", "canvas": { "width": 1780 }, "laneHeaderWidth": 190, "stages": [ "Resolve", "Adapt", "Pace", "Submit", "Receipt", "Settle" ], "lanes": [ { "title": "SMS via SMPP", "cells": [ [ { "label": "Number type and MCC", "kind": "app" } ], [ { "label": "GSM-7 or UCS-2 split", "kind": "app" } ], [ { "label": "Bind window lease", "kind": "queue" } ], [ { "label": "submit_sm per segment", "kind": "platform" } ], [ { "label": "deliver_sm DLR", "kind": "integration" } ], [ { "label": "Rate per segment", "kind": "app" } ] ] }, { "title": "SMS via aggregator", "cells": [ [ { "label": "Same resolution", "kind": "app" } ], [ { "label": "Provider JSON shape", "kind": "app" } ], [ { "label": "HTTP route lease", "kind": "queue" } ], [ { "label": "POST, provider id", "kind": "integration" } ], [ { "label": "Webhook receipt", "kind": "integration" } ], [ { "label": "Rate per segment", "kind": "app" } ] ] }, { "title": "WhatsApp", "cells": [ [ { "label": "Business identity check", "kind": "security" } ], [ { "label": "Approved template only", "kind": "decision" } ], [ { "label": "Per-number tier limit", "kind": "queue" } ], [ { "label": "Graph send", "kind": "integration" } ], [ { "label": "Read and delivered", "kind": "integration" } ], [ { "label": "Conversation pricing", "kind": "app" } ] ] }, { "title": "RCS", "cells": [ [ { "label": "Capability probe", "kind": "decision" } ], [ { "label": "Rich card or fall back", "kind": "app" } ], [ { "label": "Hub window lease", "kind": "queue" } ], [ { "label": "Agent message", "kind": "integration" } ], [ { "label": "Event, often absent", "kind": "risk" } ], [ { "label": "Fallback hop rated too", "kind": "app" } ] ] }, { "title": "Inbound (reverse)", "cells": [ [ { "label": "Verify and dedup", "kind": "security" } ], [ { "label": "Normalise to one shape", "kind": "app" } ], [ { "label": "Per-route rate limit", "kind": "queue" } ], [ { "label": "Keyword interception", "kind": "security" } ], [ { "label": "Consent written first", "kind": "store" } ], [ { "label": "Tenant webhook, actioned", "kind": "integration" } ] ] } ], "note": "Adding a channel adds a lane. Nothing in the ledger or the state model changes.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture" } }, { "id": "16-ambiguous-submit", "title": "The Ambiguous Submit — When Nobody Knows Whether It Was Sent", "layout": "sequence", "canvas": { "width": 1700 }, "lifelines": [ { "id": "exe2", "label": "Attempt executor", "kind": "app" }, { "id": "led3", "label": "Message ledger", "kind": "store" }, { "id": "ses2", "label": "Session plane", "kind": "platform" }, { "id": "car2", "label": "Carrier", "kind": "external", "icon": "fa5_broadcast_tower" }, { "id": "pol", "label": "Route policy", "kind": "decision" }, { "id": "sw", "label": "TTL sweeper", "kind": "app" }, { "id": "ten", "label": "Tenant", "kind": "actor" } ], "messages": [ { "from": "exe2", "to": "led3", "label": "append intent, attempt 1", "kind": "call" }, { "from": "exe2", "to": "ses2", "label": "submit", "kind": "call" }, { "from": "ses2", "to": "car2", "label": "submit_sm, sequence 8841", "kind": "call" }, { "from": "car2", "to": "ses2", "label": "no response, window timeout", "kind": "error" }, { "from": "ses2", "to": "led3", "label": "append outcome: ambiguous", "kind": "call" }, { "from": "exe2", "to": "pol", "label": "does this route support query?", "kind": "call" }, { "from": "pol", "to": "exe2", "label": "no query, do not re-attempt", "kind": "return" }, { "from": "exe2", "to": "led3", "label": "record the policy applied", "kind": "call" }, { "from": "car2", "to": "led3", "label": "late receipt, delivered", "kind": "async" }, { "from": "sw", "to": "led3", "label": "if TTL elapses first: unknown", "kind": "self" }, { "from": "led3", "to": "ten", "label": "status = delivered or unknown, with the attempt trail", "kind": "return" } ], "note": "Two legitimate endings for one attempt. The platform says which happened, and never guesses.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture" } }, { "id": "17-deployment", "title": "Deployment — Two Regions, One Stateful Plane", "layout": "nested", "canvas": { "width": 1760 }, "boxes": [ { "title": "Google Cloud — europe-west1 (primary)", "kind": "cloud", "dir": "row", "children": [ { "title": "zone b — stateless", "kind": "boundary", "nodes": [ { "id": "r1z1a", "label": "Submit and status", "kind": "app", "sub": "Cloud Run" }, { "id": "r1z1b", "label": "Attempt executors", "kind": "app", "sub": "autoscaled" }, { "id": "r1z1c", "label": "Ingest workers", "kind": "app" } ] }, { "title": "zone c — stateless", "kind": "boundary", "nodes": [ { "id": "r1z2a", "label": "Submit and status", "kind": "app" }, { "id": "r1z2b", "label": "Attempt executors", "kind": "app" }, { "id": "r1z2c", "label": "Ingest workers", "kind": "app" } ] }, { "title": "zone d — session plane", "kind": "trust", "nodes": [ { "id": "r1s1", "label": "SMPP session pods", "kind": "platform", "sub": "GKE StatefulSet" }, { "id": "r1s2", "label": "Static egress", "kind": "platform", "sub": "Cloud NAT, allowlisted", "icon": "net_nat" } ] }, { "title": "regional data", "kind": "boundary", "nodes": [ { "id": "r1d1", "label": "Message ledger", "kind": "store", "sub": "Spanner, multi-region" }, { "id": "r1d2", "label": "State projection", "kind": "store", "sub": "Bigtable" }, { "id": "r1d3", "label": "Leases and quality", "kind": "store", "sub": "Memorystore HA" }, { "id": "r1d4", "label": "Bodies", "kind": "store", "sub": "Cloud Storage, CMEK" } ] } ] }, { "title": "Google Cloud — europe-west4 (second region)", "kind": "cloud", "dir": "row", "children": [ { "title": "stateless, warm", "kind": "boundary", "nodes": [ { "id": "r2a", "label": "Submit and status", "kind": "app", "sub": "RTO 20 min" }, { "id": "r2b", "label": "Attempt executors", "kind": "app" }, { "id": "r2c", "label": "Ingest workers", "kind": "app" } ] }, { "title": "session plane", "kind": "trust", "nodes": [ { "id": "r2s", "label": "Standby binds", "kind": "platform", "sub": "second allowlisted range" } ] }, { "title": "regional data", "kind": "boundary", "nodes": [ { "id": "r2d1", "label": "Ledger replica", "kind": "store", "sub": "same Spanner instance" }, { "id": "r2d2", "label": "Projection replica", "kind": "store" }, { "id": "r2d3", "label": "Leases", "kind": "store", "sub": "regional, not shared" } ] } ] }, { "title": "Global", "kind": "boundary", "dir": "row", "children": [ { "title": "Edge and control", "kind": "plain", "nodes": [ { "id": "glb", "label": "Global load balancer", "kind": "integration", "sub": "Cloud Armor, anycast" }, { "id": "greg", "label": "Registry and rules", "kind": "store", "sub": "Spanner" }, { "id": "gkms", "label": "KMS and Secret Manager", "kind": "security" }, { "id": "gobs", "label": "Monitoring and logging", "kind": "platform" } ] } ] } ], "outside": [ { "id": "carr2", "label": "Carriers", "kind": "external", "sub": "egress allowlists per region" }, { "id": "resident", "label": "Residency-pinned tenants", "kind": "risk", "sub": "no cross-region failover" } ], "edges": [ { "from": "glb", "to": "r1z1a", "label": "primary", "kind": "sync" }, { "from": "glb", "to": "r2a", "label": "failover", "kind": "error" }, { "from": "r1s1", "to": "carr2", "label": "binds", "kind": "bidirectional" }, { "from": "r2s", "to": "carr2", "label": "standby binds", "kind": "error" }, { "from": "r1d1", "to": "r2d1", "label": "synchronous", "kind": "sync" } ], "note": "Leases are regional on purpose: a shared lease store would put a carrier window behind a cross-region hop.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture" } }, { "id": "18-cicd", "title": "Delivery Pipeline — Code, Routes And Rules Ship Differently", "layout": "flow", "canvas": { "width": 1780 }, "chain": true, "align": "top", "nodeWidth": 196, "stages": [ { "title": "Source", "nodes": [ { "id": "repo", "label": "Service repository", "kind": "app", "sub": "trunk based" }, { "id": "iac", "label": "Terraform", "kind": "platform", "sub": "infrastructure", "icon": "terraform" }, { "id": "rulesrc", "label": "Rule and route data", "kind": "store", "sub": "not code" } ] }, { "title": "Build", "nodes": [ { "id": "cb", "label": "Cloud Build", "kind": "platform" }, { "id": "ar", "label": "Artifact Registry", "kind": "store", "sub": "signed images" } ] }, { "title": "Gates", "nodes": [ { "id": "unit", "label": "Unit and contract tests", "kind": "decision", "sub": "adapter contract" }, { "id": "sim", "label": "Carrier simulator suite", "kind": "decision", "sub": "late, dup, silent receipts" }, { "id": "binauthz", "label": "Binary Authorization", "kind": "security" }, { "id": "policy", "label": "Policy and residency check", "kind": "security" } ] }, { "title": "Environments", "nodes": [ { "id": "dev", "label": "Development", "kind": "app", "sub": "simulated carriers only", "icon": "server" }, { "id": "stg", "label": "Staging", "kind": "app", "sub": "one real test route", "icon": "server" }, { "id": "prod", "label": "Production", "kind": "app", "sub": "canary by route", "icon": "server" } ] }, { "title": "Runtime change", "nodes": [ { "id": "rulepub", "label": "Rule set publish", "kind": "integration", "sub": "versioned, 30 s" }, { "id": "routepub", "label": "Route table publish", "kind": "integration", "sub": "no deploy" }, { "id": "rollback", "label": "Rollback", "kind": "decision", "sub": "pointer move" } ] } ], "edges": [ { "from": "sim", "to": "stg", "label": "must pass", "kind": "sync" }, { "from": "rulesrc", "to": "rulepub", "label": "data path, reviewed", "kind": "batch", "route": "gutter" }, { "from": "prod", "to": "rollback", "label": "on regression", "kind": "error" }, { "from": "routepub", "to": "prod", "label": "effective in 30 s", "kind": "async" } ], "note": "A jurisdictional rule change must not need a deployment; that is a requirement, so it gets its own path.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture" } }, { "id": "19-observability", "title": "Observability — Signal By Stage, And The Ones Nobody Else Watches", "layout": "grid", "canvas": { "width": 1780 }, "laneHeaderWidth": 180, "columns": [ "Submit", "Admission", "Ledger", "Scheduling", "Attempt and session", "Ingest and state" ], "rows": [ { "title": "Rate and saturation", "cells": [ [ { "label": "Accepted per second", "kind": "platform" } ], [ { "label": "Rejections by reason", "kind": "platform" } ], [ { "label": "Write latency p99", "kind": "platform" } ], [ { "label": "Queue age by class", "kind": "platform" } ], [ { "label": "Lease waits per route", "kind": "platform" } ], [ { "label": "Receipts per second", "kind": "platform" } ] ] }, { "title": "Correctness", "cells": [ [ { "label": "Dedup hit rate", "kind": "app" } ], [ { "label": "Consent refusals", "kind": "security" } ], [ { "label": "Append failures", "kind": "risk" } ], [ { "label": "TTL expiries", "kind": "app" } ], [ { "label": "Ambiguous submit rate", "kind": "risk" } ], [ { "label": "Uncorrelatable receipts", "kind": "risk" } ] ] }, { "title": "The ones nobody else watches", "cells": [ [ { "label": "Accepted but never attempted", "kind": "risk" } ], [ { "label": "Rule set version in use", "kind": "app" } ], [ { "label": "Projection lag", "kind": "risk" } ], [ { "label": "Bulk starving interactive", "kind": "risk" } ], [ { "label": "Delivery rate collapse", "kind": "risk" } ], [ { "label": "Unknown-state share", "kind": "risk" } ] ] }, { "title": "SLO and alert", "cells": [ [ { "label": "Submit availability 99.99", "kind": "decision" } ], [ { "label": "Consent eval 99.99", "kind": "decision" } ], [ { "label": "RPO 0 verified", "kind": "decision" } ], [ { "label": "Interactive age p99 3 s", "kind": "decision" } ], [ { "label": "Route breaker trips", "kind": "decision" } ], [ { "label": "Receipt visible p95 2 s", "kind": "decision" } ] ] }, { "title": "Evidence and cost", "cells": [ [ { "label": "Per-tenant submit trail", "kind": "store" } ], [ { "label": "Rule version per refusal", "kind": "store" } ], [ { "label": "Ledger write cost share", "kind": "store" } ], [ { "label": "Fairness share per route", "kind": "store" } ], [ { "label": "Cost per segment by route", "kind": "store" } ], [ { "label": "Margin and quality together", "kind": "store" } ] ] } ], "note": "Row three is the point of the view: silent collapse and unknown share are the failures with no error.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture" } }, { "id": "20-route-lifecycle", "title": "Route Lifecycle — How A Route Earns And Loses Traffic", "layout": "cycle", "canvas": { "width": 1500 }, "centre": { "label": "Route quality loop" }, "nodes": [ { "label": "Contract and register", "kind": "app", "sub": "window, price, sender type", "id": "c1" }, { "label": "Bind and probe", "kind": "platform", "sub": "staging traffic only", "id": "c2" }, { "label": "Admit to the table", "kind": "decision", "sub": "two routes per jurisdiction", "id": "c3" }, { "label": "Carry paced traffic", "kind": "queue", "sub": "lease enforced", "id": "c4" }, { "label": "Measure the outcome", "kind": "store", "sub": "delivery rate, receipt lag", "id": "c5" }, { "label": "Weight or trip", "kind": "app", "sub": "policy or breaker", "id": "c6" }, { "label": "Requalify or retire", "kind": "risk", "sub": "never silently kept", "id": "c7" } ], "ringLabels": [ "registered", "probe passes", "eligible", "real traffic", "signals", "re-weighted", "back to contract" ], "rx": 440, "ry": 215, "note": "A route with no measured outcome cannot stay eligible; absence of receipts is itself a signal.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture" } }, { "id": "21-security-zones", "title": "Trust Zones — Nothing Trusted Comes From A Carrier", "layout": "zones", "canvas": { "width": 1740 }, "zones": [ { "title": "Internet — tenants and carriers", "kind": "trust", "nodes": [ { "id": "z_tenant", "label": "Tenant application", "kind": "external" }, { "id": "z_carrier", "label": "Carrier POST", "kind": "external", "sub": "unverified until proven" }, { "id": "z_hostile", "label": "Forged receipt attempt", "kind": "risk" } ] }, { "title": "Perimeter", "kind": "trust", "nodes": [ { "id": "z_armor", "label": "Cloud Armor and WAF", "kind": "security" }, { "id": "z_lb", "label": "Global load balancer", "kind": "integration", "sub": "mTLS optional" }, { "id": "z_auth", "label": "Credential check", "kind": "security", "sub": "scoped, revocable" }, { "id": "z_sigv", "label": "Carrier signature verify", "kind": "security", "sub": "or allowlist + secret" } ] }, { "title": "Application — stateless, workload identity only", "kind": "trust", "nodes": [ { "id": "z_submit", "label": "Submit and admission", "kind": "app" }, { "id": "z_exec", "label": "Attempt executors", "kind": "app", "sub": "no long-lived secrets" }, { "id": "z_ingest", "label": "Ingest workers", "kind": "app", "sub": "schema-bounded input" } ] }, { "title": "Custody and session — the only place credentials live", "kind": "trust", "nodes": [ { "id": "z_custody", "label": "Credential custody", "kind": "security", "sub": "per-route scope" }, { "id": "z_kms", "label": "Cloud KMS", "kind": "security", "sub": "tenant-managed keys", "icon": "fa5_key" }, { "id": "z_sess", "label": "Session pods", "kind": "platform", "sub": "pinned egress" } ] }, { "title": "Data — encrypted, classified, residency-pinned", "kind": "trust", "nodes": [ { "id": "z_ledger", "label": "Message ledger", "kind": "store" }, { "id": "z_body", "label": "Bodies", "kind": "store", "sub": "store-no-body supported" }, { "id": "z_consent", "label": "Consent and audit", "kind": "store", "sub": "append-only" }, { "id": "z_break", "label": "Break-glass body access", "kind": "risk", "sub": "time-bound, audited" } ] } ], "edges": [ { "from": "z_tenant", "to": "z_armor", "label": "TLS, scoped credential", "kind": "sync" }, { "from": "z_carrier", "to": "z_sigv", "label": "verify before it is data", "kind": "sync" }, { "from": "z_auth", "to": "z_submit", "label": "tenant identity", "kind": "sync" }, { "from": "z_exec", "to": "z_custody", "label": "short-lived token", "kind": "sync" }, { "from": "z_custody", "to": "z_sess", "label": "bind material", "kind": "sync" }, { "from": "z_submit", "to": "z_ledger", "label": "append", "kind": "sync" } ], "note": "An unverifiable carrier delivery is treated as hostile, not as data. That is the zone boundary that matters.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture" } }, { "id": "22-identity-flow", "title": "Identity And Authorisation — Four Different Things Prove Themselves", "layout": "sequence", "canvas": { "width": 1740 }, "lifelines": [ { "id": "i_tenant", "label": "Tenant app", "kind": "actor" }, { "id": "i_edge", "label": "Edge", "kind": "integration" }, { "id": "i_cred", "label": "Credential service", "kind": "security" }, { "id": "i_reg", "label": "Sender registry", "kind": "store" }, { "id": "i_consent", "label": "Consent store", "kind": "store" }, { "id": "i_exec", "label": "Attempt executor", "kind": "app" }, { "id": "i_cust", "label": "Custody", "kind": "security" }, { "id": "i_car", "label": "Carrier", "kind": "external", "icon": "fa5_broadcast_tower" } ], "messages": [ { "from": "i_tenant", "to": "i_edge", "label": "scoped API credential", "kind": "call" }, { "from": "i_edge", "to": "i_cred", "label": "introspect, check limits", "kind": "call" }, { "from": "i_cred", "to": "i_edge", "label": "tenant, scopes, sender allowlist", "kind": "return" }, { "from": "i_edge", "to": "i_reg", "label": "may this tenant use this sender here?", "kind": "call" }, { "from": "i_reg", "to": "i_edge", "label": "registered in this jurisdiction", "kind": "return" }, { "from": "i_edge", "to": "i_consent", "label": "is this destination still consenting?", "kind": "call" }, { "from": "i_consent", "to": "i_edge", "label": "granted, evidence v9", "kind": "return" }, { "from": "i_exec", "to": "i_cust", "label": "workload identity, no static secret", "kind": "call" }, { "from": "i_cust", "to": "i_exec", "label": "short-lived, single-route token", "kind": "return" }, { "from": "i_exec", "to": "i_car", "label": "bind with route credential", "kind": "call" }, { "from": "i_car", "to": "i_exec", "label": "bound, sequence window open", "kind": "return" }, { "from": "i_cred", "to": "i_edge", "label": "revocation effective within 15 s", "kind": "async" } ], "note": "The tenant, the sender identity, the destination's consent and the carrier credential are four separate proofs.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture" } } ]