[ { "id": "01-system-context", "title": "Link Platform — System Context", "layout": "context", "canvas": { "width": 1720 }, "colWidth": 265, "system": { "label": "Link Management Platform", "sub": "short code in, redirect out" }, "groups": [ { "side": "left", "title": "People who click", "nodes": [ { "id": "clicker", "label": "Link clicker", "kind": "actor", "sub": "150k redirects/s", "rel": "GET /{code}", "dir": "in" }, { "id": "unfurl", "label": "Chat unfurler", "kind": "external", "sub": "preview bots", "rel": "prefetch", "dir": "in" }, { "id": "scanner", "label": "Mail and security scanner", "kind": "external", "sub": "not a human click", "rel": "scan", "dir": "in" } ] }, { "side": "top", "title": "People who own links", "nodes": [ { "id": "marketer", "label": "Campaign owner", "kind": "actor", "sub": "40k tenants", "rel": "creates links", "dir": "in" }, { "id": "dev", "label": "Customer developer", "kind": "actor", "sub": "bulk API", "rel": "bulk API", "dir": "in" }, { "id": "safety", "label": "Trust and safety analyst", "kind": "actor", "rel": "blocks links", "dir": "in" } ] }, { "side": "right", "title": "Systems it depends on", "nodes": [ { "id": "entra", "label": "Microsoft Entra ID", "kind": "security", "sub": "tenant admin sign-in", "rel": "OIDC", "dir": "in" }, { "id": "feeds", "label": "URL reputation feeds", "kind": "external", "sub": "malware, phishing", "rel": "verdicts", "dir": "in" }, { "id": "dns", "label": "Azure DNS and managed TLS", "kind": "platform", "sub": "12k branded domains", "rel": "certificates" }, { "id": "destination", "label": "Customer destination site", "kind": "external", "sub": "never fetched, only named" } ] }, { "side": "bottom", "title": "Downstream consumers", "nodes": [ { "id": "bi", "label": "Customer BI and CRM", "kind": "external", "sub": "click export", "kind2": "batch" }, { "id": "billing", "label": "Billing", "kind": "external", "sub": "metered redirects", "kind2": "async" } ] } ], "note": "Out of scope: campaign management, email sending, and anything about the destination page itself — the platform names a location and steps out of the way.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-09" } }, { "id": "02-high-level-architecture", "title": "Link Platform — High-Level Architecture", "layout": "flow", "canvas": { "width": 1780 }, "chain": true, "align": "middle", "stages": [ { "title": "1 · Create", "nodes": [ { "id": "mgmt", "label": "Management API", "kind": "app", "sub": "Container Apps" }, { "id": "reserve", "label": "Alias reservation", "kind": "store", "sub": "conditional create" } ] }, { "title": "2 · Own", "nodes": [ { "id": "linktable", "label": "Link table", "kind": "store", "sub": "Cosmos DB · 12B links" } ] }, { "title": "3 · Propagate", "nodes": [ { "id": "revoke", "label": "Revocation publisher", "kind": "queue", "sub": "own channel · 60 s" }, { "id": "proj", "label": "Projection publisher", "kind": "app", "sub": "change feed · 5 min" } ] }, { "title": "4 · Resolve", "nodes": [ { "id": "afd", "label": "Front Door edge", "kind": "integration", "sub": "anycast · 30 s cache" }, { "id": "resolver", "label": "Regional resolver", "kind": "app", "sub": "read-only" }, { "id": "hot", "label": "Hot set cache", "kind": "store", "sub": "Azure Cache for Redis" } ] }, { "title": "5 · Redirect", "nodes": [ { "id": "client", "label": "Clicker's browser", "kind": "external", "sub": "302 + no-store" } ] }, { "title": "6 · Count", "nodes": [ { "id": "logs", "label": "Edge access log", "kind": "queue", "sub": "Event Hubs" }, { "id": "adx", "label": "Click store", "kind": "store", "sub": "Azure Data Explorer" } ] }, { "title": "7 · Police", "nodes": [ { "id": "screen", "label": "Destination screening", "kind": "security", "sub": "at create, then periodic" }, { "id": "queueui", "label": "Review and appeal", "kind": "app", "sub": "human in the loop" } ] } ], "edges": [ { "from": "mgmt", "to": "reserve", "label": "claim" }, { "from": "afd", "to": "resolver", "label": "3% miss" }, { "from": "resolver", "to": "hot", "label": "point read" }, { "from": "revoke", "to": "resolver", "label": "deny-set", "kind": "async" }, { "from": "proj", "to": "hot", "label": "warm", "kind": "async" }, { "from": "afd", "to": "logs", "label": "every click, cached or not", "kind": "async" }, { "from": "screen", "to": "revoke", "label": "block", "kind": "error" } ], "note": "Stage 4 reads only stages 3's output. No arrow runs from the redirect path back into the link table.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-09" } }, { "id": "03-actors-and-journeys", "title": "Who the Platform Is For, and What They Get to Do", "layout": "actors", "canvas": { "width": 1760 }, "cardWidth": 265, "groups": [ { "title": "The people who click", "kind": "trust", "actors": [ { "id": "clicker", "label": "Link clicker", "sub": "never signed up for this", "goal": "I clicked a link somebody sent me. I want the page, now, and I want to know if it is a trap.", "journeys": [ { "id": "j-click", "label": "Click a short link", "sub": "the only journey at 150k/s" }, { "label": "Preview before clicking" } ] } ] }, { "title": "The people who own links", "kind": "boundary", "actors": [ { "id": "marketer", "label": "Campaign owner", "sub": "40k tenants", "goal": "The code goes on 10,000 printed cards on Friday. I need to be able to change where it points afterwards.", "journeys": [ { "id": "j-launch", "label": "Launch a campaign link", "sub": "alias + branded domain" }, { "id": "j-kill", "label": "Kill a live link" }, { "label": "Read the click report" } ] }, { "id": "dev", "label": "Customer developer", "sub": "bulk and API users", "goal": "Shorten 40,000 links in one import and get back a result per row, not a 429.", "journeys": [ { "label": "Bulk import a campaign" }, { "label": "Subscribe to the click stream" } ] }, { "id": "admin", "label": "Tenant administrator", "sub": "enterprise tier", "goal": "Prove our branded domain is ours, and know before its certificate expires, not after.", "journeys": [ { "label": "Verify a branded domain" }, { "label": "Scope and revoke API keys" } ] } ] }, { "title": "The people who defend it", "kind": "lane", "actors": [ { "id": "safety", "label": "Trust and safety analyst", "sub": "24/7 rota", "goal": "Stop a phishing link within a minute of hearing about it, and be able to show why I did.", "journeys": [ { "label": "Block and appeal", "sub": "60 s globally" }, { "label": "Work the review queue" } ] }, { "id": "sre", "label": "Platform SRE", "sub": "on call", "goal": "Keep the redirect path up while everything behind it is broken, and know which one it is.", "journeys": [ { "label": "Absorb a viral link" }, { "label": "Fail a region out" }, { "label": "Rebuild the projection" } ] } ] }, { "title": "Machines in the cast", "kind": "cloud", "actors": [ { "id": "unfurl", "label": "Chat unfurler", "kind": "external", "sub": "~18% of traffic", "goal": "Fetch the link so my user sees a preview. I am not a click and must not be counted as one.", "journeys": [ { "label": "Prefetch a destination" } ] }, { "id": "feed", "label": "Reputation feed", "kind": "external", "sub": "3 feeds", "goal": "Tell the platform a destination turned malicious after it was approved.", "journeys": [ { "label": "Deliver a verdict change" } ] } ] } ], "note": "The clicker never signs up, never logs in and is the only actor at full traffic scale — which is why the redirect path owes them a working link, not a branded one.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-09" } }, { "id": "04-journey-click-a-short-link", "title": "Journey — A Clicker Follows a Short Link", "layout": "journey", "canvas": { "width": 1760 }, "actor": { "label": "Link clicker", "sub": "anonymous, mobile, impatient", "goal": "Get to the page the sender meant, in one tap", "trigger": "A code in an email, a QR on a poster, a link in a group chat", "success": "The destination loads and nothing about the hop was noticeable" }, "phases": [ { "title": "Encounter", "sub": "outside the platform" }, { "title": "Tap" }, { "title": "Resolve", "moment": true }, { "title": "Arrive", "moment": true }, { "title": "Doubt", "sub": "only sometimes" } ], "lanes": [ { "title": "What they do", "kind": "step", "cells": [ [ { "label": "Scans a QR code" }, { "label": "Reads a shortened link" } ], [ { "label": "Taps it" } ], [ { "label": "Waits" } ], [ { "label": "Lands on the page" } ], [ { "label": "Wonders where it went" } ] ] }, { "title": "What the platform does", "kind": "system", "cells": [ [], [ { "label": "TLS at nearest PoP" } ], [ { "label": "Cache or resolver hit" }, { "label": "Deny-set check" } ], [ { "label": "302, no-store" }, { "label": "Click logged after" } ], [ { "label": "Preview endpoint" } ] ] }, { "title": "How it feels", "kind": "emotion", "levels": [ "Trusting", "Neutral", "Suspicious" ], "points": [ 1, 1, 2, 0, 2 ] }, { "title": "Where it hurts", "kind": "pain", "cells": [ [ { "label": "Destination is invisible" } ], [], [ { "label": "Cold code: slow first tap" } ], [ { "label": "410 with no explanation" } ], [ { "label": "No way to check safety" } ] ] }, { "title": "What answers it", "kind": "gain", "cells": [ [ { "label": "Public preview suffix" } ], [], [ { "label": "Hot set + 30 s edge cache" } ], [ { "label": "Four distinct terminal states" } ], [ { "label": "Interstitial that names the reason" } ] ] } ], "chain": true, "note": "The trough is at Resolve for a cold code and at Arrive for a dead one — both are answered by views 14 and 16, not by a better page.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-09" } }, { "id": "05-journey-launch-a-campaign-link", "title": "Journey — A Campaign Owner Launches a Printed Link", "layout": "journey", "canvas": { "width": 1760 }, "actor": { "label": "Campaign owner", "sub": "marketing, not engineering", "goal": "One memorable link on our own domain, on 10,000 printed cards", "trigger": "Print deadline on Friday; the landing page is not finished", "success": "The code works on Monday and still works when the page moves in March" }, "phases": [ { "title": "Claim", "sub": "pick the alias" }, { "title": "Brand", "sub": "own domain" }, { "title": "Commit", "moment": true, "sub": "sent to print" }, { "title": "Launch" }, { "title": "Change", "moment": true } ], "lanes": [ { "title": "What they do", "kind": "step", "cells": [ [ { "label": "Asks for /spring" } ], [ { "label": "Uses go.acme.com" } ], [ { "label": "Sends artwork to print" } ], [ { "label": "Watches the clicks" } ], [ { "label": "Repoints the link" } ] ] }, { "title": "What the platform does", "kind": "system", "cells": [ [ { "label": "Conditional claim" }, { "label": "Screens destination" } ], [ { "label": "Verified domain + TLS" } ], [ { "label": "Code retired forever" } ], [ { "label": "Counts, bots split out" } ], [ { "label": "Edit propagates ≤ 5 min" } ] ] }, { "title": "How it feels", "kind": "emotion", "levels": [ "Confident", "Neutral", "Anxious" ], "points": [ 1, 1, 2, 1, 0 ] }, { "title": "Where it hurts", "kind": "pain", "cells": [ [ { "label": "Alias already taken" } ], [ { "label": "Certificate lapses later" } ], [ { "label": "No undo after print" } ], [ { "label": "Unfurlers inflate day one" } ], [ { "label": "How long until it changes?" } ] ] }, { "title": "What answers it", "kind": "gain", "cells": [ [ { "label": "Named conflict, never a swap" } ], [ { "label": "Renewal alert before expiry" } ], [ { "label": "Code is identity, not target" } ], [ { "label": "Bot class on every report" } ], [ { "label": "Published 5 min bound" } ] ] } ], "chain": true, "note": "Commit is the irreversible phase: once the code is on paper, every later requirement in the set follows from the fact that it can never be reissued or reassigned.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-09" } }, { "id": "06-journey-kill-a-live-link", "title": "Journey — Killing a Link That Is Already Out There", "layout": "journey", "canvas": { "width": 1760 }, "actor": { "label": "Trust and safety analyst", "sub": "with the customer watching", "goal": "Make a live, distributed link stop redirecting, everywhere, now", "trigger": "An abuse report, or a feed flipping an approved destination to malicious", "success": "Clicks stop within the minute, and the decision is defensible afterwards" }, "phases": [ { "title": "Hear", "sub": "report or feed" }, { "title": "Judge", "moment": true }, { "title": "Kill", "moment": true }, { "title": "Prove" }, { "title": "Appeal" } ], "lanes": [ { "title": "What they do", "kind": "step", "cells": [ [ { "label": "Takes the report" } ], [ { "label": "Reviews the destination" } ], [ { "label": "Presses block" } ], [ { "label": "Writes the finding" } ], [ { "label": "Handles the owner's appeal" } ] ] }, { "title": "What the platform does", "kind": "system", "cells": [ [ { "label": "Report intake + triage" } ], [ { "label": "Feed scores and history" } ], [ { "label": "Deny-set push ≤ 60 s" } ], [ { "label": "Feed, score, actor stored" } ], [ { "label": "Reinstate on the same path" } ] ] }, { "title": "How it feels", "kind": "emotion", "levels": [ "In control", "Neutral", "Exposed" ], "points": [ 2, 1, 0, 0, 1 ] }, { "title": "Where it hurts", "kind": "pain", "cells": [ [ { "label": "No idea of the blast radius" } ], [ { "label": "False positive costs a customer" } ], [ { "label": "Edge caches may still serve" } ], [], [ { "label": "Owner cannot see why" } ] ] }, { "title": "What answers it", "kind": "gain", "cells": [ [ { "label": "Live click rate per code" } ], [ { "label": "Interstitial, not deletion" } ], [ { "label": "30 s cache TTL bounds it" } ], [ { "label": "Immutable audit record" } ], [ { "label": "Reason shown to the owner" } ] ] } ], "chain": true, "note": "This journey is the reason revocation has its own propagation channel: the analyst's 60 seconds cannot wait behind a five-minute projection.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-09" } }, { "id": "07-layered-architecture", "title": "Layered Architecture — Where the Plane Boundary Falls", "layout": "bands", "canvas": { "width": 1760 }, "layerHeaderWidth": 160, "bands": [ { "name": "Clients", "nodes": [ { "id": "browser", "label": "Browser and QR scanner", "kind": "external" }, { "id": "bots", "label": "Unfurlers and scanners", "kind": "external" }, { "id": "console", "label": "Tenant console", "kind": "external" }, { "id": "api-client", "label": "Customer API client", "kind": "external" } ] }, { "name": "Edge", "nodes": [ { "id": "afd", "label": "Front Door", "kind": "integration", "sub": "anycast + TLS" }, { "id": "waf", "label": "WAF and bot rules", "kind": "security" }, { "id": "edgecache", "label": "Response cache", "kind": "store", "sub": "30 s TTL" }, { "id": "accesslog", "label": "Access log stream", "kind": "queue", "sub": "every request" } ] }, { "name": "Redirect plane", "nodes": [ { "id": "denyset", "label": "Deny-set check", "kind": "security", "sub": "in process" }, { "id": "resolver", "label": "Resolver", "kind": "app", "sub": "read-only" }, { "id": "rules", "label": "Routing rules", "kind": "app", "sub": "device, geo" }, { "id": "hotset", "label": "Hot set cache", "kind": "store", "sub": "Redis" } ] }, { "name": "Management plane", "nodes": [ { "id": "mgmt", "label": "Link API", "kind": "app" }, { "id": "bulk", "label": "Bulk import", "kind": "app", "sub": "10k per request" }, { "id": "domains", "label": "Domain and TLS service", "kind": "platform" }, { "id": "safety", "label": "Trust and safety", "kind": "security" } ] }, { "name": "State", "nodes": [ { "id": "linktable", "label": "Link table", "kind": "store", "sub": "Cosmos DB" }, { "id": "reserve", "label": "Reservation index", "kind": "store", "sub": "strong" }, { "id": "audit", "label": "Audit log", "kind": "store", "sub": "immutable blob" }, { "id": "clicks", "label": "Click store", "kind": "store", "sub": "Data Explorer" } ] }, { "name": "Propagation", "nodes": [ { "id": "revpub", "label": "Revocation publisher", "kind": "queue", "sub": "fast channel" }, { "id": "proj", "label": "Projection publisher", "kind": "app", "sub": "change feed" } ] }, { "name": "Platform", "nodes": [ { "id": "entra", "label": "Entra ID and workload identity", "kind": "security" }, { "id": "kv", "label": "Key Vault", "kind": "security" }, { "id": "monitor", "label": "Azure Monitor and ADX", "kind": "platform" }, { "id": "iac", "label": "Bicep and GitHub Actions", "kind": "platform" } ] } ], "edges": [ { "from": "browser", "to": "afd", "label": "GET /{code}" }, { "from": "afd", "to": "resolver", "label": "miss" }, { "from": "resolver", "to": "hotset" }, { "from": "linktable", "to": "proj", "kind": "async" }, { "from": "proj", "to": "hotset", "label": "warm", "kind": "async" }, { "from": "revpub", "to": "denyset", "label": "≤ 60 s", "kind": "async" } ], "note": "The only arrows from the management plane into the redirect plane pass through Propagation, and nothing in the redirect plane writes to State. The console, the click export, the alias claim and the link write are drawn in views 08, 10 and 15.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-09" } }, { "id": "08-container-view", "title": "Container View — Two Planes, One Link Table", "layout": "nested", "canvas": { "width": 1780 }, "boxes": [ { "title": "Azure Front Door Premium — global edge", "kind": "cloud", "dir": "row", "children": [ { "title": "Request handling", "kind": "boundary", "nodes": [ { "id": "tls", "label": "TLS and anycast", "kind": "integration", "sub": "shared + branded" }, { "id": "waf", "label": "WAF and bot manager", "kind": "security" }, { "id": "cache", "label": "Redirect cache", "kind": "store", "sub": "30 s TTL" } ] }, { "title": "Telemetry out", "kind": "boundary", "nodes": [ { "id": "logs", "label": "Access log to Event Hubs", "kind": "queue", "sub": "one row per click" } ] } ] }, { "title": "Redirect plane — read-only, 12 regions", "kind": "boundary", "dir": "row", "children": [ { "title": "Resolution", "kind": "plain", "nodes": [ { "id": "resolver", "label": "Resolver service", "kind": "app", "sub": "Container Apps" }, { "id": "deny", "label": "Deny-set matcher", "kind": "security", "sub": "in-process, 5 s refresh" }, { "id": "rules", "label": "Routing rule engine", "kind": "app", "sub": "device, geo, locale" } ] }, { "title": "Regional read cache", "kind": "plain", "nodes": [ { "id": "hot", "label": "Hot set", "kind": "store", "sub": "Redis · 97% hit" }, { "id": "neg", "label": "Negative cache", "kind": "store", "sub": "unknown codes" } ] } ] }, { "title": "Management plane — 2 regions, one write region", "kind": "boundary", "dir": "row", "children": [ { "title": "Link lifecycle", "kind": "plain", "nodes": [ { "id": "api", "label": "Link API", "kind": "app", "sub": "create, edit, kill" }, { "id": "alloc", "label": "Code allocator", "kind": "app", "sub": "random base62-7" }, { "id": "bulk", "label": "Bulk importer", "kind": "app", "sub": "10k per request" } ] }, { "title": "Tenancy and trust", "kind": "plain", "nodes": [ { "id": "domain", "label": "Domain and TLS service", "kind": "platform" }, { "id": "screen", "label": "Screening worker", "kind": "security", "sub": "Functions" }, { "id": "review", "label": "Review and appeal", "kind": "app" } ] }, { "title": "Propagation", "kind": "plain", "nodes": [ { "id": "proj", "label": "Projection publisher", "kind": "app", "sub": "change feed" }, { "id": "revpub", "label": "Revocation publisher", "kind": "queue", "sub": "Event Grid" } ] } ] }, { "title": "State", "kind": "trust", "dir": "row", "children": [ { "title": "Authoritative", "kind": "plain", "nodes": [ { "id": "link", "label": "Link table", "kind": "store", "sub": "Cosmos DB · TTL" }, { "id": "res", "label": "Reservation index", "kind": "store", "sub": "strong, single writer" } ] }, { "title": "Derived and evidential", "kind": "plain", "nodes": [ { "id": "clickstore", "label": "Click store", "kind": "store", "sub": "Data Explorer" }, { "id": "auditlog", "label": "Audit log", "kind": "store", "sub": "immutable" } ] } ] } ], "outside": [ { "id": "feeds", "label": "Reputation feeds", "kind": "external", "sub": "3 providers" }, { "id": "entra", "label": "Microsoft Entra ID", "kind": "security" } ], "edges": [ { "from": "tls", "to": "resolver", "label": "miss" }, { "from": "resolver", "to": "hot" }, { "from": "api", "to": "link", "label": "write" }, { "from": "link", "to": "proj", "kind": "async" }, { "from": "proj", "to": "hot", "kind": "async" }, { "from": "revpub", "to": "deny", "kind": "async" }, { "from": "screen", "to": "revpub", "kind": "error", "route": "gutter" }, { "from": "feeds", "to": "screen", "label": "verdicts", "kind": "async" }, { "from": "logs", "to": "clickstore", "label": "clicks", "kind": "async" } ], "note": "Omitted for clarity: the console, the click export API, the alias claim (view 15) and the cold read from the link table (view 09). Dashed amber is propagation, dashed red is a block; the redirect plane never writes to State.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-09" } }, { "id": "09-resolution-components", "title": "Inside a Resolution: The Read Path, Component by Component", "layout": "nested", "canvas": { "width": 1740 }, "boxes": [ { "title": "Front Door PoP — nearest of 190+", "kind": "cloud", "dir": "col", "children": [ { "title": "Before any lookup", "kind": "plain", "nodes": [ { "id": "sni", "label": "SNI and certificate", "kind": "security", "sub": "branded or shared" }, { "id": "wafr", "label": "WAF ruleset", "kind": "security" }, { "id": "botc", "label": "Bot classification", "kind": "app", "sub": "tag, never block" }, { "id": "cachel", "label": "Cache lookup", "kind": "store", "sub": "key = host + code" } ] } ] }, { "title": "Regional resolver pod — read-only", "kind": "boundary", "dir": "col", "children": [ { "title": "Guards, in order", "kind": "plain", "nodes": [ { "id": "parse", "label": "Bounded parse", "kind": "app", "sub": "code shape only" }, { "id": "denym", "label": "Deny-set match", "kind": "security", "sub": "revoked, blocked" }, { "id": "coalesce", "label": "Request coalescer", "kind": "app", "sub": "one fetch per code" } ] }, { "title": "Lookup ladder", "kind": "plain", "nodes": [ { "id": "l1", "label": "L1 in-process LRU", "kind": "store", "sub": "hot keys, 10 s" }, { "id": "l2", "label": "L2 regional Redis", "kind": "store", "sub": "hot set" }, { "id": "l3", "label": "L3 Cosmos DB read replica", "kind": "store", "sub": "in-region" } ] }, { "title": "Response construction", "kind": "plain", "nodes": [ { "id": "ruleeval", "label": "Routing rule eval", "kind": "app", "sub": "device, geo, locale" }, { "id": "params", "label": "Parameter merge", "kind": "app", "sub": "deterministic order" }, { "id": "state", "label": "Terminal state picker", "kind": "decision", "sub": "404 · 410 · block" } ] } ] }, { "title": "After the response has left", "kind": "lane", "dir": "row", "children": [ { "title": "Never on the critical path", "kind": "plain", "nodes": [ { "id": "emit", "label": "Click event emit", "kind": "queue", "sub": "fire and forget" }, { "id": "buf", "label": "Local durable buffer", "kind": "store", "sub": "30 s RPO" }, { "id": "counters", "label": "Hot-code counters", "kind": "app", "sub": "promotion signal" } ] } ] } ], "edges": [ { "from": "cachel", "to": "parse", "label": "miss only" }, { "from": "parse", "to": "denym" }, { "from": "denym", "to": "coalesce", "label": "not revoked" }, { "from": "coalesce", "to": "l1" }, { "from": "l1", "to": "l2", "label": "miss" }, { "from": "l2", "to": "l3", "label": "miss" }, { "from": "l3", "to": "ruleeval" }, { "from": "ruleeval", "to": "params" }, { "from": "params", "to": "state" }, { "from": "state", "to": "emit", "label": "after send", "kind": "async" }, { "from": "emit", "to": "buf", "kind": "async" } ], "note": "The deny-set is matched before the lookup ladder, not after: a revoked code must not be answerable from any cache layer. Hot-code counters promote a code into L1 and are read by no one on the request path.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-09" } }, { "id": "10-integration-surface", "title": "Integration Surface — Every Interface the Platform Owns", "layout": "hub", "canvas": { "width": 1720 }, "left": { "title": "Inbound", "nodes": [ { "id": "redirect", "label": "Redirect endpoint", "kind": "external", "sub": "GET /{code}", "rel": "150k/s" }, { "id": "preview", "label": "Preview endpoint", "kind": "external", "sub": "inspect, do not visit", "rel": "" }, { "id": "linkapi", "label": "Link API", "kind": "external", "sub": "REST + idempotency key", "rel": "" }, { "id": "bulkapi", "label": "Bulk import API", "kind": "external", "sub": "10k rows", "rel": "" }, { "id": "consoleui", "label": "Tenant console", "kind": "external", "sub": "Entra ID", "rel": "" }, { "id": "abuse", "label": "Abuse report intake", "kind": "external", "sub": "public form + API", "rel": "" } ] }, "centre": { "title": "Platform", "nodes": [ { "id": "core", "label": "Link Management Platform", "kind": "app", "sub": "redirect plane + management plane" } ] }, "right": { "title": "Outbound and dependencies", "nodes": [ { "id": "clickexport", "label": "Click stream export", "kind": "external", "sub": "Event Hubs", "rel": "", "dir": "out", "kind2": "async" }, { "id": "reportapi", "label": "Analytics query API", "kind": "external", "sub": "rollups", "rel": "", "dir": "out" }, { "id": "meter", "label": "Billing meter feed", "kind": "external", "sub": "redirects, bots split", "rel": "hourly", "dir": "out", "kind2": "batch" }, { "id": "repfeeds", "label": "Reputation feeds", "kind": "external", "sub": "3 providers", "rel": "verdicts", "kind2": "async" }, { "id": "dnstls", "label": "Azure DNS and managed TLS", "kind": "platform", "sub": "branded domains", "rel": "", "dir": "out" }, { "id": "idp", "label": "Entra ID", "kind": "security", "sub": "admin identity", "rel": "tokens" } ] }, "note": "Two interfaces are effectively frozen once published: the redirect URL shape and the click event schema. Both are versioned as public contracts.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-09" } }, { "id": "11-storage-zones", "title": "Storage Zones — Ownership, Consistency and Rebuildability", "layout": "nested", "canvas": { "width": 1760 }, "boxes": [ { "title": "Authoritative — lost data is lost business", "kind": "trust", "dir": "row", "children": [ { "title": "Link table · Cosmos DB", "kind": "plain", "nodes": [ { "id": "links", "label": "Link records", "kind": "store", "sub": "12B · RPO 0" }, { "id": "ttl", "label": "Native TTL", "kind": "platform", "sub": "expiry, eventual" } ] }, { "title": "Reservation index · strong", "kind": "plain", "nodes": [ { "id": "resv", "label": "(domain, code) claims", "kind": "store", "sub": "conditional create" } ] }, { "title": "Tenancy", "kind": "plain", "nodes": [ { "id": "tenants", "label": "Tenants and domains", "kind": "store", "sub": "verification state" }, { "id": "keys", "label": "API keys and secrets", "kind": "security", "sub": "Key Vault" } ] } ] }, { "title": "Derived — disposable, rebuildable in 30 minutes", "kind": "boundary", "dir": "row", "children": [ { "title": "Read path", "kind": "plain", "nodes": [ { "id": "hotset", "label": "Hot set", "kind": "store", "sub": "Redis, 12 regions" }, { "id": "negcache", "label": "Negative cache", "kind": "store", "sub": "unknown codes" }, { "id": "edgec", "label": "Edge response cache", "kind": "store", "sub": "30 s" } ] }, { "title": "Revocation", "kind": "plain", "nodes": [ { "id": "denyset", "label": "Deny-set", "kind": "security", "sub": "compact, fast channel" } ] }, { "title": "Tenant indexes", "kind": "plain", "nodes": [ { "id": "bytenant", "label": "Links by tenant", "kind": "store", "sub": "listing and search" } ] } ] }, { "title": "Evidential — append only, never updated", "kind": "boundary", "dir": "row", "children": [ { "title": "Click data · Azure Data Explorer", "kind": "plain", "nodes": [ { "id": "raw", "label": "Raw click events", "kind": "store", "sub": "90 days" }, { "id": "daily", "label": "Daily rollups", "kind": "store", "sub": "25 months" }, { "id": "monthly", "label": "Monthly rollups", "kind": "store", "sub": "5 years" } ] }, { "title": "Decisions", "kind": "plain", "nodes": [ { "id": "audit", "label": "Audit log", "kind": "store", "sub": "400 days, immutable" }, { "id": "abusev", "label": "Abuse evidence", "kind": "store", "sub": "2 years" } ] } ] } ], "outside": [ { "id": "buffer", "label": "Edge click buffer", "kind": "queue", "sub": "Event Hubs · 30 s RPO" } ], "edges": [ { "from": "links", "to": "hotset", "label": "projection", "kind": "async" }, { "from": "resv", "to": "links", "label": "claim then write" }, { "from": "denyset", "to": "edgec", "label": "bounded by TTL", "kind": "async" }, { "from": "buffer", "to": "raw", "label": "ingest", "kind": "async" }, { "from": "raw", "to": "daily", "label": "materialise", "kind": "batch" }, { "from": "daily", "to": "monthly", "kind": "batch" } ], "note": "Zone tells you the recovery plan: authoritative is replicated and backed up, derived is thrown away and rebuilt, evidential is written once and never corrected. The by-tenant index is built from the same change feed as the hot set.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-09" } }, { "id": "12-data-model", "title": "Data Model — Code, Destination, Click", "layout": "er", "canvas": { "width": 1700, "cols": 4 }, "rowGap": 235, "entities": [ { "id": "tenant", "name": "tenant", "kind": "store", "row": 1, "col": 0, "attrs": [ "tenant_id PK", "plan", "link_quota", "redirect_quota", "created_at" ] }, { "id": "domain", "name": "domain", "kind": "store", "row": 1, "col": 1, "attrs": [ "domain PK", "tenant_id FK -> tenant", "verified_at", "cert_state", "cert_expires_at" ] }, { "id": "link", "name": "link", "kind": "store", "row": 1, "col": 2, "attrs": [ "domain PK", "code PK", "tenant_id FK -> tenant", "destination_url", "state", "is_alias", "expires_at (TTL)", "created_by", "created_at" ] }, { "id": "reservation", "name": "code_reservation", "kind": "store", "row": 0, "col": 2, "attrs": [ "domain PK", "code PK", "claimed_at", "claimed_by", "retired bool" ] }, { "id": "rule", "name": "routing_rule", "kind": "store", "row": 2, "col": 1, "attrs": [ "rule_id PK", "domain FK -> link", "code FK -> link", "match_kind", "match_value", "destination_url", "priority" ] }, { "id": "revocation", "name": "revocation_entry", "kind": "security", "row": 2, "col": 2, "attrs": [ "domain PK", "code PK", "reason", "source", "effective_at", "expires_from_set_at" ] }, { "id": "clickevent", "name": "click_event", "kind": "store", "row": 2, "col": 3, "attrs": [ "event_id PK", "domain FK -> link", "code FK -> link", "occurred_at", "country", "device_class", "referrer_host", "traffic_class", "edge_pop" ] }, { "id": "audit", "name": "audit_entry", "kind": "store", "row": 2, "col": 0, "attrs": [ "audit_id PK", "tenant_id FK -> tenant", "subject_code", "action", "actor", "before", "after", "at" ] }, { "id": "abuse", "name": "abuse_decision", "kind": "security", "row": 1, "col": 3, "attrs": [ "decision_id PK", "domain FK -> link", "code FK -> link", "feed", "score", "verdict", "reviewer", "decided_at" ] }, { "id": "rollup", "name": "click_rollup_daily", "kind": "store", "row": 3, "col": 3, "attrs": [ "domain PK", "code PK", "day PK", "human_clicks", "bot_clicks", "unique_estimate", "top_country" ] }, { "id": "apikey", "name": "api_key", "kind": "security", "row": 0, "col": 0, "attrs": [ "key_id PK", "tenant_id FK -> tenant", "scopes", "created_at", "revoked_at" ] } ], "relations": [ { "from": "tenant", "to": "apikey", "label": "1 : N", "from_side": "n", "to_side": "s" }, { "from": "tenant", "to": "domain", "label": "1 : N", "from_side": "e", "to_side": "w" }, { "from": "tenant", "to": "audit", "label": "1 : N", "from_side": "s", "to_side": "n" }, { "from": "domain", "to": "link", "label": "1 : N", "from_side": "e", "to_side": "w" }, { "from": "link", "to": "reservation", "label": "1 : 1", "from_side": "n", "to_side": "s" }, { "from": "link", "to": "abuse", "label": "1 : N", "from_side": "e", "to_side": "w", "kind": "optional" }, { "from": "link", "to": "rule", "label": "1 : N", "from_side": "s1", "to_side": "n" }, { "from": "link", "to": "revocation", "label": "0 : 1", "from_side": "s", "to_side": "n" }, { "from": "link", "to": "clickevent", "label": "1 : N", "from_side": "s3", "to_side": "n" }, { "from": "clickevent", "to": "rollup", "label": "N : 1", "from_side": "s", "to_side": "n" } ], "note": "code_reservation exists separately from link so that a retired code can never be claimed again — the record outlives the link it once identified.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-09" } }, { "id": "13-propagation-paths", "title": "Two Propagation Paths, Two Different Promises", "layout": "flow", "canvas": { "width": 1780 }, "align": "top", "stages": [ { "title": "Write", "nodes": [ { "id": "write", "label": "Link write", "kind": "app", "sub": "create, edit, kill" }, { "id": "table", "label": "Link table", "kind": "store", "sub": "authoritative" } ] }, { "title": "Fork", "nodes": [ { "id": "classify", "label": "Change classifier", "kind": "decision", "sub": "urgent or routine?" } ] }, { "title": "Fast channel · ≤ 60 s", "nodes": [ { "id": "revq", "label": "Revocation topic", "kind": "queue", "sub": "Event Grid" }, { "id": "denybuild", "label": "Deny-set builder", "kind": "app", "sub": "compact delta" } ] }, { "title": "Slow channel · ≤ 5 min", "nodes": [ { "id": "feed", "label": "Cosmos change feed", "kind": "queue", "sub": "ordered per partition" }, { "id": "projw", "label": "Projection worker", "kind": "app", "sub": "12 regions" } ] }, { "title": "Regional state", "nodes": [ { "id": "hotreg", "label": "Hot set", "kind": "store", "sub": "Redis" }, { "id": "denyreg", "label": "Deny-set replica", "kind": "security", "sub": "5 s pull" } ] }, { "title": "Edge effect", "nodes": [ { "id": "cachettl", "label": "Response cache", "kind": "store", "sub": "30 s TTL bounds staleness" }, { "id": "served", "label": "What the clicker gets", "kind": "external" } ] } ], "edges": [ { "from": "write", "to": "table", "label": "durable" }, { "from": "table", "to": "classify", "label": "committed" }, { "from": "classify", "to": "revq", "label": "kill or block", "kind": "error" }, { "from": "classify", "to": "feed", "kind": "async", "route": "gutter" }, { "from": "revq", "to": "denybuild", "kind": "async" }, { "from": "denybuild", "to": "denyreg", "label": "delta push", "kind": "async" }, { "from": "feed", "to": "projw", "kind": "async" }, { "from": "projw", "to": "hotreg", "label": "upsert", "kind": "async" }, { "from": "denyreg", "to": "served", "label": "410 or interstitial", "kind": "error" }, { "from": "hotreg", "to": "cachettl", "label": "on miss" }, { "from": "cachettl", "to": "served", "label": "302" } ], "note": "One write, two paths, two published bounds. The fast channel carries only stop instructions, which is why it can be small enough to be fast.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-09" } }, { "id": "14-redirect-hot-path", "title": "Critical Flow — One Click, Resolved", "layout": "sequence", "canvas": { "width": 1740 }, "lifelines": [ { "id": "clicker", "label": "Clicker", "kind": "actor" }, { "id": "pop", "label": "Front Door PoP", "kind": "integration" }, { "id": "resolver", "label": "Regional resolver", "kind": "app" }, { "id": "deny", "label": "Deny-set", "kind": "security" }, { "id": "hot", "label": "Hot set (Redis)", "kind": "store" }, { "id": "cosmos", "label": "Link table", "kind": "store" }, { "id": "hub", "label": "Click stream", "kind": "queue" } ], "messages": [ { "from": "clicker", "to": "pop", "label": "GET go.acme.com/spring", "kind": "call" }, { "from": "pop", "to": "pop", "label": "TLS for branded host, WAF, bot tag", "kind": "self" }, { "from": "pop", "to": "pop", "label": "cache lookup: host + code", "kind": "self" }, { "from": "pop", "to": "clicker", "label": "cached 302 (97% of clicks end here)", "kind": "return" }, { "from": "pop", "to": "resolver", "label": "miss: forward to nearest region", "kind": "call" }, { "from": "resolver", "to": "resolver", "label": "bounded parse of the code shape", "kind": "self" }, { "from": "resolver", "to": "deny", "label": "is this code revoked or blocked?", "kind": "call" }, { "from": "deny", "to": "resolver", "label": "not present", "kind": "return" }, { "from": "resolver", "to": "resolver", "label": "coalesce concurrent misses on this code", "kind": "self" }, { "from": "resolver", "to": "hot", "label": "GET link:go.acme.com:spring", "kind": "call" }, { "from": "hot", "to": "resolver", "label": "miss (3% of misses)", "kind": "return" }, { "from": "resolver", "to": "cosmos", "label": "point read, in-region replica", "kind": "call" }, { "from": "cosmos", "to": "resolver", "label": "destination, state, rules", "kind": "return" }, { "from": "resolver", "to": "hot", "label": "populate, TTL 24h", "kind": "async" }, { "from": "resolver", "to": "resolver", "label": "evaluate rules, merge parameters", "kind": "self" }, { "from": "resolver", "to": "pop", "label": "302 + Cache-Control: max-age=30", "kind": "return" }, { "from": "pop", "to": "clicker", "label": "302 to destination", "kind": "return" }, { "from": "pop", "to": "hub", "label": "access log row — after the response left", "kind": "async" } ], "note": "Nothing in this flow writes to the link table, and the click event is emitted by the edge log rather than by the resolver — which is why a cached redirect is still a counted click.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-09" } }, { "id": "15-creation-and-alias-reservation", "title": "Critical Flow — Claiming a Code Nobody Else Can Have", "layout": "sequence", "canvas": { "width": 1740 }, "lifelines": [ { "id": "owner", "label": "Campaign owner", "kind": "actor" }, { "id": "api", "label": "Link API", "kind": "app" }, { "id": "screen", "label": "Screening", "kind": "security" }, { "id": "res", "label": "Reservation index", "kind": "store" }, { "id": "link", "label": "Link table", "kind": "store" }, { "id": "proj", "label": "Projection publisher", "kind": "app" }, { "id": "hot", "label": "Hot set", "kind": "store" } ], "messages": [ { "from": "owner", "to": "api", "label": "POST /links alias=spring, domain=go.acme.com", "kind": "call" }, { "from": "api", "to": "api", "label": "idempotency key seen in last 24h?", "kind": "self" }, { "from": "api", "to": "api", "label": "validate scheme, length, host; check reserved list", "kind": "self" }, { "from": "api", "to": "screen", "label": "destination reputation", "kind": "call" }, { "from": "screen", "to": "api", "label": "clean (blocked verdicts refuse creation)", "kind": "return" }, { "from": "api", "to": "res", "label": "conditional create (domain, code) — If-None-Match", "kind": "call" }, { "from": "res", "to": "api", "label": "409 if claimed or retired", "kind": "error" }, { "from": "res", "to": "api", "label": "201 claimed — exactly one writer wins", "kind": "return" }, { "from": "api", "to": "link", "label": "write link record, RPO 0", "kind": "call" }, { "from": "link", "to": "api", "label": "committed in the write region", "kind": "return" }, { "from": "api", "to": "owner", "label": "201 with the short link (p99 ≤ 250 ms)", "kind": "return" }, { "from": "link", "to": "proj", "label": "change feed", "kind": "async" }, { "from": "proj", "to": "hot", "label": "pre-warm in the creating region ≤ 1 s", "kind": "async" }, { "from": "proj", "to": "hot", "label": "pre-warm elsewhere ≤ 10 s p99", "kind": "async" } ], "note": "The conflict is returned, never worked around: the platform will not substitute a generated code for an alias a customer asked for. Reservation is the only strongly consistent step in the whole architecture.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-09" } }, { "id": "16-revocation-and-abuse-block", "title": "Critical Flow — Stopping a Link in Under a Minute", "layout": "sequence", "canvas": { "width": 1740 }, "lifelines": [ { "id": "feed", "label": "Reputation feed", "kind": "external" }, { "id": "safety", "label": "Analyst", "kind": "actor" }, { "id": "rev", "label": "Review service", "kind": "app" }, { "id": "link", "label": "Link table", "kind": "store" }, { "id": "revpub", "label": "Revocation publisher", "kind": "queue" }, { "id": "deny", "label": "Regional deny-set", "kind": "security" }, { "id": "pop", "label": "Front Door PoP", "kind": "integration" } ], "messages": [ { "from": "feed", "to": "rev", "label": "approved destination now flagged", "kind": "async" }, { "from": "rev", "to": "safety", "label": "queue item with score and live click rate", "kind": "call" }, { "from": "safety", "to": "rev", "label": "block, with reason", "kind": "call" }, { "from": "rev", "to": "link", "label": "state = blocked, evidence stored", "kind": "call" }, { "from": "rev", "to": "revpub", "label": "publish revocation delta", "kind": "call" }, { "from": "revpub", "to": "deny", "label": "delta to 12 regions (pull every 5 s)", "kind": "async" }, { "from": "deny", "to": "deny", "label": "in-process set updated before next request", "kind": "self" }, { "from": "pop", "to": "pop", "label": "cached 302 may still serve for up to 30 s", "kind": "self" }, { "from": "pop", "to": "deny", "label": "on expiry, next miss hits the deny-set", "kind": "call" }, { "from": "deny", "to": "pop", "label": "blocked — interstitial, no-store", "kind": "error" }, { "from": "rev", "to": "safety", "label": "effective globally, ≤ 60 s p99", "kind": "return" }, { "from": "safety", "to": "rev", "label": "reinstate on appeal, same path", "kind": "call" } ], "note": "The 30-second edge cache TTL is what bounds the worst case, which is why it is a design parameter rather than a tuning knob: raising it for hit rate directly weakens this promise.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-09" } }, { "id": "17-click-analytics-pipeline", "title": "Click Analytics — From Access Log to a Number Someone Bills On", "layout": "flow", "canvas": { "width": 1780 }, "chain": true, "align": "middle", "stages": [ { "title": "Emit", "nodes": [ { "id": "edge", "label": "Edge access log", "kind": "queue", "sub": "cached or not" }, { "id": "resl", "label": "Resolver log", "kind": "queue", "sub": "misses only" } ] }, { "title": "Buffer", "nodes": [ { "id": "eh", "label": "Event Hubs", "kind": "queue", "sub": "30 s RPO · 7 day retain" } ] }, { "title": "Classify", "nodes": [ { "id": "botc", "label": "Traffic classifier", "kind": "app", "sub": "human · unfurler · scanner" }, { "id": "enrich", "label": "Enricher", "kind": "app", "sub": "country, device, referrer" }, { "id": "privacy", "label": "Identifier drop", "kind": "security", "sub": "no raw IP retained" } ] }, { "title": "Land", "nodes": [ { "id": "raw", "label": "Raw click events", "kind": "store", "sub": "ADX · 90 days" } ] }, { "title": "Roll up", "nodes": [ { "id": "mv", "label": "Materialised views", "kind": "app", "sub": "per code, per day" }, { "id": "uniq", "label": "Unique estimator", "kind": "app", "sub": "±2%, labelled" } ] }, { "title": "Serve", "nodes": [ { "id": "dash", "label": "Tenant dashboard", "kind": "external", "sub": "≤ 60 s p95" }, { "id": "export", "label": "Click stream export", "kind": "external", "sub": "at least once" }, { "id": "bill", "label": "Billing meter", "kind": "external", "sub": "humans and bots split" } ] }, { "title": "Reconcile", "nodes": [ { "id": "recon", "label": "Daily reconciliation", "kind": "app", "sub": "±0.5% vs edge counters" }, { "id": "alarm", "label": "Loss alarm", "kind": "risk", "sub": "budget 0.05%" } ] } ], "edges": [ { "from": "resl", "to": "eh", "kind": "async" }, { "from": "privacy", "to": "raw", "label": "append only", "kind": "async" }, { "from": "raw", "to": "mv", "kind": "batch" }, { "from": "mv", "to": "dash" }, { "from": "raw", "to": "export", "label": "replayable", "kind": "async", "route": "gutter" }, { "from": "recon", "to": "alarm", "kind": "error" } ], "note": "Counting from the edge access log rather than from application code is what lets the redirect be cached for 30 seconds without losing a click.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-09" } }, { "id": "18-deployment-architecture", "title": "Deployment — Global Read Path, Two Write Regions", "layout": "nested", "canvas": { "width": 1780 }, "boxes": [ { "title": "Azure Front Door Premium — 190+ PoPs, one anycast address set", "kind": "cloud", "dir": "row", "children": [ { "title": "Every PoP", "kind": "plain", "nodes": [ { "id": "anycast", "label": "Anycast TLS", "kind": "integration", "sub": "shared + 12k branded" }, { "id": "wafp", "label": "WAF and bot rules", "kind": "security" }, { "id": "cachep", "label": "Response cache", "kind": "store", "sub": "30 s" } ] } ] }, { "title": "Read regions — 12, identical, stateless", "kind": "boundary", "dir": "row", "children": [ { "title": "West Europe (example read region)", "kind": "plain", "nodes": [ { "id": "ca1", "label": "Resolver · Container Apps", "kind": "app", "sub": "3 zones, KEDA on RPS" }, { "id": "redis1", "label": "Azure Cache for Redis", "kind": "store", "sub": "zone-redundant" }, { "id": "cos1", "label": "Cosmos DB read replica", "kind": "store", "sub": "in-region" } ] }, { "title": "11 further read regions", "kind": "plain", "nodes": [ { "id": "caN", "label": "Same three components", "kind": "app", "sub": "no regional state of its own" } ] } ] }, { "title": "Write regions — North Europe (primary) and East US 2 (standby)", "kind": "boundary", "dir": "row", "children": [ { "title": "Primary", "kind": "plain", "nodes": [ { "id": "mgmt1", "label": "Management plane", "kind": "app", "sub": "Container Apps" }, { "id": "coswrite", "label": "Cosmos DB write region", "kind": "store", "sub": "single writer" }, { "id": "func1", "label": "Screening and publishers", "kind": "app", "sub": "Functions" } ] }, { "title": "Standby", "kind": "plain", "nodes": [ { "id": "mgmt2", "label": "Management plane", "kind": "app", "sub": "warm, scaled to 1" }, { "id": "coss", "label": "Cosmos failover target", "kind": "store", "sub": "RTO ≤ 5 min for writes" } ] } ] }, { "title": "Shared platform services", "kind": "trust", "dir": "row", "children": [ { "title": "Identity and secrets", "kind": "plain", "nodes": [ { "id": "entra", "label": "Entra ID", "kind": "security", "sub": "workload identity" }, { "id": "kvp", "label": "Key Vault", "kind": "security", "sub": "per-region replica" } ] }, { "title": "Telemetry and analytics", "kind": "plain", "nodes": [ { "id": "ehp", "label": "Event Hubs", "kind": "queue", "sub": "geo-paired" }, { "id": "adxp", "label": "Azure Data Explorer", "kind": "store", "sub": "2 clusters" }, { "id": "mon", "label": "Azure Monitor", "kind": "platform" } ] } ] } ], "outside": [ { "id": "ops", "label": "SRE and deployment", "kind": "actor", "sub": "GitHub Actions" } ], "edges": [ { "from": "anycast", "to": "ca1", "label": "origin group, latency based" }, { "from": "ca1", "to": "redis1" }, { "from": "redis1", "to": "cos1" }, { "from": "coswrite", "to": "cos1", "label": "replication ≤ 5 s", "kind": "async" }, { "from": "cachep", "to": "ehp", "label": "access log", "kind": "async" }, { "from": "func1", "to": "redis1", "label": "warm and deny-set", "kind": "async", "route": "gutter" }, { "from": "coswrite", "to": "coss", "label": "failover pair", "kind": "bidirectional" } ], "note": "Losing the primary write region stops link creation and editing; it does not stop a single redirect. That asymmetry is the deployment expressing the plane split.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-09" } }, { "id": "19-release-pipeline", "title": "Release Pipeline — Shipping to a Path That Cannot Stop", "layout": "flow", "canvas": { "width": 1780 }, "chain": true, "align": "middle", "stages": [ { "title": "Source", "nodes": [ { "id": "repo", "label": "Mono-repo", "kind": "app", "sub": "services + Bicep" }, { "id": "pr", "label": "Pull request", "kind": "app", "sub": "2 reviewers" } ] }, { "title": "Build", "nodes": [ { "id": "ci", "label": "GitHub Actions", "kind": "platform", "sub": "OIDC to Azure" }, { "id": "img", "label": "Signed image", "kind": "store", "sub": "ACR + attestation" } ] }, { "title": "Gates", "nodes": [ { "id": "contract", "label": "Redirect contract test", "kind": "security", "sub": "status codes frozen" }, { "id": "alias", "label": "Uniqueness race test", "kind": "security", "sub": "concurrent claims" }, { "id": "perf", "label": "Resolver latency gate", "kind": "security", "sub": "p99 ≤ 40 ms" } ] }, { "title": "Staging", "nodes": [ { "id": "stg", "label": "Staging region", "kind": "app", "sub": "shadow traffic replay" } ] }, { "title": "Canary", "nodes": [ { "id": "canary", "label": "One read region", "kind": "app", "sub": "5% of PoP origins" }, { "id": "slo", "label": "SLO watchdog", "kind": "platform", "sub": "auto rollback" } ] }, { "title": "Fleet", "nodes": [ { "id": "rollout", "label": "12 read regions", "kind": "app", "sub": "one at a time" }, { "id": "mgmtdep", "label": "Management plane", "kind": "app", "sub": "deployed last" } ] }, { "title": "Schema and data", "nodes": [ { "id": "migrate", "label": "Additive-only migrations", "kind": "store", "sub": "no destructive step" }, { "id": "rebuild", "label": "Projection rebuild drill", "kind": "platform", "sub": "monthly, timed" } ] } ], "edges": [ { "from": "pr", "to": "contract", "label": "required check", "route": "gutter" }, { "from": "canary", "to": "slo" }, { "from": "slo", "to": "canary", "label": "rollback", "kind": "error" }, { "from": "rollout", "to": "mgmtdep", "label": "readers first" }, { "from": "migrate", "to": "rebuild", "kind": "batch" } ], "note": "Read regions ship before the management plane, because a resolver that cannot read a new field is a worse failure than a management plane that cannot yet write one.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-09" } }, { "id": "20-observability", "title": "Observability — Signals by Pipeline Stage", "layout": "grid", "canvas": { "width": 1780 }, "laneHeaderWidth": 160, "stages": [ "Edge", "Resolution", "Propagation", "Management", "Analytics" ], "lanes": [ { "title": "Golden metrics", "cells": [ [ { "label": "Redirects/s per PoP", "kind": "platform" }, { "label": "Cache hit rate", "kind": "platform", "sub": "≥ 97%" } ], [ { "label": "Resolve p99", "kind": "platform", "sub": "≤ 40 ms" }, { "label": "L1/L2/L3 hit mix", "kind": "platform" } ], [ { "label": "Deny-set age", "kind": "platform", "sub": "≤ 5 s" }, { "label": "Projection lag", "kind": "platform", "sub": "≤ 5 min" } ], [ { "label": "Create p99", "kind": "platform" }, { "label": "Claim conflict rate", "kind": "platform" } ], [ { "label": "Click freshness", "kind": "platform", "sub": "≤ 60 s p95" } ] ] }, { "title": "Correctness checks", "cells": [ [ { "label": "Terminal-state mix", "kind": "app", "sub": "404 · 410 · block" } ], [ { "label": "Wrong-destination probe", "kind": "security", "sub": "synthetic, zero tolerance" } ], [ { "label": "Revocation end-to-end probe", "kind": "security", "sub": "every 60 s" } ], [ { "label": "Reserved-alias audit", "kind": "security" } ], [ { "label": "Count reconciliation", "kind": "app", "sub": "±0.5% daily" } ] ] }, { "title": "Saturation", "cells": [ [ { "label": "PoP egress", "kind": "platform" } ], [ { "label": "Redis CPU and evictions", "kind": "risk" }, { "label": "Coalescer queue depth", "kind": "platform" } ], [ { "label": "Change feed backlog", "kind": "risk" } ], [ { "label": "Cosmos RU headroom", "kind": "risk", "sub": "write region" } ], [ { "label": "Event Hubs lag", "kind": "risk" } ] ] }, { "title": "Cost signals", "cells": [ [ { "label": "Cost per million redirects", "kind": "platform", "sub": "≤ $0.05" } ], [ { "label": "Miss cost share", "kind": "platform" } ], [], [ { "label": "RU spend per tenant", "kind": "platform" } ], [ { "label": "Raw retention spend", "kind": "platform" }, { "label": "Bot traffic share", "kind": "platform" } ] ] }, { "title": "Alarms that page", "cells": [ [ { "label": "Redirect error rate", "kind": "risk", "sub": "any region" } ], [ { "label": "p99 breach 5 min", "kind": "risk" } ], [ { "label": "Revocation probe fails", "kind": "risk", "sub": "the 60 s promise" } ], [ { "label": "Uniqueness conflict spike", "kind": "risk" } ], [ { "label": "Click loss > 0.05%", "kind": "risk" } ] ] } ], "note": "One row is different in kind: the wrong-destination and revocation probes test claims the platform sells, not resources it consumes.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-09" } }, { "id": "21-link-lifecycle", "title": "Link Lifecycle — The Loop a Code Never Leaves", "layout": "cycle", "canvas": { "width": 1520 }, "centre": { "label": "Code identity", "sub": "issued once" }, "nodes": [ { "id": "claimed", "label": "Claimed", "kind": "app", "sub": "reservation written" }, { "id": "screened", "label": "Screened", "kind": "security", "sub": "destination checked" }, { "id": "live", "label": "Live", "kind": "app", "sub": "resolving at the edge" }, { "id": "edited", "label": "Edited", "kind": "app", "sub": "same code, new target" }, { "id": "suspended", "label": "Suspended", "kind": "risk", "sub": "expired, killed, blocked" }, { "id": "retired", "label": "Retired", "kind": "security", "sub": "never re-issued" } ], "ringLabels": [ "verdict", "warmed", "repointed", "revoked", "deleted", "stands" ], "rx": 430, "ry": 210, "note": "Suspended returns to Live on appeal or reactivation, and clicks are kept throughout. Retired returns nowhere: it is the one irreversible transition in the platform.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-09" } }, { "id": "22-security-trust-zones", "title": "Security — Trust Zones and What Crosses Them", "layout": "zones", "canvas": { "width": 1760 }, "zones": [ { "title": "Hostile — the open internet", "kind": "trust", "nodes": [ { "id": "anon", "label": "Anonymous clicker", "kind": "external", "sub": "no identity, ever" }, { "id": "botz", "label": "Bots and scanners", "kind": "external" }, { "id": "attacker", "label": "Enumeration attempt", "kind": "risk", "sub": "guessing codes" }, { "id": "phisher", "label": "Abusive creator", "kind": "risk", "sub": "bulk sign-up" } ] }, { "title": "Perimeter — Front Door", "kind": "trust", "nodes": [ { "id": "tlsz", "label": "TLS termination", "kind": "security", "sub": "managed certificates" }, { "id": "privlink", "label": "Private Link to origins", "kind": "security", "sub": "no public origin" }, { "id": "wafz", "label": "WAF and rate rules", "kind": "security" }, { "id": "botrule", "label": "Bot classification", "kind": "app", "sub": "tag, not block" } ] }, { "title": "Redirect zone — read-only, no secrets", "kind": "trust", "nodes": [ { "id": "resz", "label": "Resolver", "kind": "app", "sub": "no write credential" }, { "id": "hotz", "label": "Hot set", "kind": "store", "sub": "read replica of a projection" }, { "id": "denyz", "label": "Deny-set", "kind": "security" } ] }, { "title": "Management zone — the only writer", "kind": "trust", "nodes": [ { "id": "apiz", "label": "Link API", "kind": "app", "sub": "tenant-scoped keys" }, { "id": "screenz", "label": "Screening", "kind": "security" }, { "id": "reviewz", "label": "Review console", "kind": "app", "sub": "Entra ID + MFA" }, { "id": "kvz", "label": "Key Vault", "kind": "security", "sub": "workload identity only" } ] }, { "title": "Data zone — no inbound internet path", "kind": "trust", "nodes": [ { "id": "linkz", "label": "Link table", "kind": "store" }, { "id": "resvz", "label": "Reservation index", "kind": "store" }, { "id": "adxz", "label": "Click store", "kind": "store", "sub": "no identifiers" }, { "id": "auditz", "label": "Audit log", "kind": "store", "sub": "immutable, WORM" } ] } ], "edges": [ { "from": "anon", "to": "tlsz", "label": "HTTPS only" }, { "from": "attacker", "to": "wafz", "label": "rate limited", "kind": "error" }, { "from": "phisher", "to": "botrule", "label": "challenged", "kind": "error" }, { "from": "tlsz", "to": "privlink", "label": "origin auth" }, { "from": "privlink", "to": "resz", "label": "private only" }, { "from": "resz", "to": "hotz" }, { "from": "apiz", "to": "linkz", "label": "writes" }, { "from": "apiz", "to": "resvz" }, { "from": "reviewz", "to": "auditz", "label": "append only" } ], "note": "The redirect zone holds no writable credential: compromising a resolver yields link destinations already public to anyone holding the code. Its only read of the data zone is the cold read in view 09, over Private Link; management traffic enters through the same perimeter and is drawn in view 23.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-09" } }, { "id": "23-identity-and-access", "title": "Identity — Who Proves What, and Where Nobody Has To", "layout": "sequence", "canvas": { "width": 1740 }, "lifelines": [ { "id": "clicker", "label": "Clicker", "kind": "actor" }, { "id": "devu", "label": "Customer developer", "kind": "actor" }, { "id": "edge", "label": "Front Door", "kind": "integration" }, { "id": "apis", "label": "Link API", "kind": "app" }, { "id": "idp", "label": "Entra ID", "kind": "security" }, { "id": "kv", "label": "Key Vault", "kind": "security" }, { "id": "data", "label": "Link table", "kind": "store" } ], "messages": [ { "from": "clicker", "to": "edge", "label": "GET /{code} — no credential, by design", "kind": "call" }, { "from": "edge", "to": "clicker", "label": "302; every field treated as hostile", "kind": "return" }, { "from": "devu", "to": "idp", "label": "console sign-in, MFA", "kind": "call" }, { "from": "idp", "to": "devu", "label": "token with one tenant claim", "kind": "return" }, { "from": "devu", "to": "apis", "label": "POST /links with tenant-scoped API key", "kind": "call" }, { "from": "apis", "to": "kv", "label": "resolve key hash and scopes", "kind": "call" }, { "from": "kv", "to": "apis", "label": "scopes: links:write on 2 domains", "kind": "return" }, { "from": "apis", "to": "apis", "label": "reject if key spans more than one tenant", "kind": "self" }, { "from": "apis", "to": "idp", "label": "workload identity for data access", "kind": "call" }, { "from": "idp", "to": "apis", "label": "managed identity token", "kind": "return" }, { "from": "apis", "to": "data", "label": "write, partitioned by code hash", "kind": "call" }, { "from": "data", "to": "apis", "label": "committed, audit entry appended", "kind": "return" }, { "from": "apis", "to": "devu", "label": "201 — actor recorded on the link", "kind": "return" } ], "note": "The clicker has no identity and must never need one. Every other actor is scoped to exactly one tenant, and the resolver appears nowhere in this diagram because it holds no credential at all.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-09" } } ]