[ { "id": "01-system-context", "title": "Discord Bot Platform — System Context", "layout": "context", "canvas": { "width": 1700 }, "system": { "label": "Bot Platform", "sub": "Events out, actions in" }, "groups": [ { "side": "left", "title": "Chat service (trusted)", "nodes": [ { "id": "chat", "label": "Chat Service", "sub": "messages, members, voice", "kind": "app", "rel": "commit events", "dir": "in" }, { "id": "perm", "label": "Permission Model", "sub": "roles, overrides", "kind": "app", "rel": "effective permissions", "dir": "in" } ] }, { "side": "top", "title": "People", "nodes": [ { "id": "dev", "label": "Bot Developer", "kind": "actor", "rel": "registers, monitors", "dir": "in" }, { "id": "admin", "label": "Server Administrator", "kind": "actor", "rel": "installs, revokes", "dir": "in" }, { "id": "user", "label": "Server Member", "kind": "actor", "rel": "invokes commands", "dir": "in" } ] }, { "side": "right", "title": "Bot side (untrusted)", "nodes": [ { "id": "botws", "label": "Bot Process", "sub": "WebSocket client", "kind": "external", "rel": "events, heartbeats", "dir": "out" }, { "id": "bothttp", "label": "Bot HTTPS Endpoint", "sub": "serverless or hosted", "kind": "external", "rel": "signed interactions", "dir": "out" }, { "id": "botrest", "label": "Bot REST Client", "kind": "external", "rel": "actions", "dir": "in" } ] }, { "side": "bottom", "title": "Platform dependencies", "nodes": [ { "id": "idp", "label": "Account Identity", "sub": "OAuth2 login", "kind": "external", "rel": "consent sign-in", "dir": "in" }, { "id": "scan", "label": "Public Code Scanner", "sub": "leaked tokens", "kind": "external", "rel": "token matches", "dir": "in", "kind2": "async" }, { "id": "obs", "label": "Observability", "kind": "platform", "rel": "metrics, traces", "dir": "out", "kind2": "async" } ] } ], "note": "Out of scope: message storage, voice media, user clients, and any bot runtime or hosting.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture", "date": "2026-10" } }, { "id": "02-high-level-architecture", "title": "Discord Bot Platform — High-Level Architecture", "layout": "flow", "chain": true, "align": "middle", "canvas": { "width": 1700 }, "stages": [ { "title": "Chat service", "nodes": [ { "id": "evt", "label": "Commit Events", "sub": "per-server stream", "kind": "queue" } ] }, { "title": "Fan-out", "nodes": [ { "id": "filt", "label": "Entitlement Filter", "sub": "intents x permissions", "kind": "app" }, { "id": "part", "label": "Server Partitions", "sub": "Event Hubs", "kind": "queue" } ] }, { "title": "Sessions", "nodes": [ { "id": "gw", "label": "Gateway Shards", "sub": "AKS stateful pods", "kind": "app" }, { "id": "sess", "label": "Session & Resume", "sub": "Azure Cache for Redis", "kind": "store" } ] }, { "title": "Edge", "nodes": [ { "id": "ws", "label": "WebSocket Edge", "sub": "Front Door + L4", "kind": "integration" }, { "id": "api", "label": "API Edge", "sub": "auth, rate limit", "kind": "integration" } ] }, { "title": "Bots", "nodes": [ { "id": "bots", "label": "Bot Processes", "kind": "external" }, { "id": "hooks", "label": "Interaction Endpoints", "kind": "external" } ] } ], "edges": [ { "from": "part", "to": "gw", "kind": "async" }, { "from": "gw", "to": "sess", "label": "resume buffer", "kind": "sync" }, { "from": "api", "to": "evt", "label": "actions", "kind": "sync", "route": "gutter" } ], "note": "Control plane (registry, installs, commands, tokens) is drawn in view 06.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture", "date": "2026-10" } }, { "id": "03-actors-and-journeys", "title": "Discord Bot Platform — Actors and Their Core Journeys", "layout": "actors", "canvas": { "width": 1700 }, "groups": [ { "title": "Builders", "kind": "boundary", "actors": [ { "id": "a-dev", "label": "Hobbyist bot developer", "sub": "millions, 1–50 servers", "goal": "Get my bot answering a slash command in my friends' server tonight, and know why when it does not.", "journeys": [ { "id": "j-first", "label": "Build and install a first bot" }, { "label": "Fix a failing command" } ] }, { "id": "a-big", "label": "Popular-bot operator", "sub": "thousands, 100k+ servers", "goal": "Run the bot across hundreds of shards and stay under every limit without waking anyone at 3 a.m.", "journeys": [ { "label": "Scale from 1 to 64 shards" }, { "label": "Survive a reconnect storm" } ] } ] }, { "title": "Communities", "kind": "cloud", "actors": [ { "id": "a-admin", "label": "Server administrator", "sub": "tens of millions", "goal": "Add a bot knowing exactly what it can do, and remove it the moment I regret it.", "journeys": [ { "label": "Install with scoped permissions" }, { "label": "Revoke or narrow a bot" } ] }, { "id": "a-user", "label": "Server member", "sub": "150 M monthly", "goal": "Type a command and get a response that either works or clearly says it did not.", "journeys": [ { "id": "j-cmd", "label": "Run a slash command" }, { "label": "Press a button" } ] } ] }, { "title": "Operators", "kind": "trust", "actors": [ { "id": "a-trust", "label": "Trust and safety analyst", "sub": "platform staff", "goal": "Suspend an abusive application in a minute without touching anyone else's bots.", "journeys": [ { "label": "Suspend an application" }, { "label": "Reset a leaked token" } ] }, { "id": "a-sre", "label": "Platform SRE", "kind": "actor", "goal": "See which shards are unhealthy before developers tell me.", "journeys": [ { "label": "Drain a Gateway node" } ] } ] } ], "meta": { "v": "1.0", "owner": "Integration Platform Architecture", "date": "2026-10" } }, { "id": "04-journey-first-bot", "title": "Journey — Developer, First Bot", "layout": "journey", "canvas": { "width": 1620 }, "actor": { "label": "Bot developer", "sub": "first application", "goal": "Have my bot answer /ping in a real server tonight", "trigger": "A friend's server needs a custom command", "success": "The command works, and I can see why when it does not" }, "phases": [ { "title": "Register", "sub": "dev portal" }, { "title": "Install", "moment": true }, { "title": "Connect" }, { "title": "First command", "moment": true }, { "title": "Grow" } ], "lanes": [ { "title": "What they do", "kind": "step", "cells": [ [ { "label": "Creates application" }, { "label": "Copies token" } ], [ { "label": "Builds invite link" }, { "label": "Picks permissions" } ], [ { "label": "Opens a socket" }, { "label": "Identifies" } ], [ { "label": "Registers /ping" }, { "label": "Types /ping" } ], [ { "label": "Joins 100 servers" } ] ] }, { "title": "How it feels", "kind": "emotion", "levels": [ "Excited", "Fine", "Stuck" ], "points": [ 0, 2, 1, 2, 1 ] }, { "title": "Where it hurts", "kind": "pain", "cells": [ [], [ { "label": "Scopes are unclear" } ], [ { "label": "Intents silently empty" } ], [ { "label": "\"Application did not respond\"" } ], [ { "label": "Review gate for content" } ] ] }, { "title": "What the platform gives", "kind": "system", "cells": [ [ { "label": "Public key + token once" } ], [ { "label": "Consent screen lists scopes" } ], [ { "label": "Close code names the cause" } ], [ { "label": "Test interaction + logs" } ], [ { "label": "Limit warnings at 75%" } ] ] } ], "chain": true, "note": "The trough is the 3-second acknowledgement: the platform can only show the user a failure, so the developer needs the reason.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture", "date": "2026-10" } }, { "id": "05-journey-run-command", "title": "Journey — Member, Runs a Slash Command", "layout": "journey", "canvas": { "width": 1620 }, "actor": { "label": "Server member", "sub": "on mobile", "goal": "Run /poll and see the poll appear", "trigger": "A friend asks for a vote in the channel", "success": "The poll posts and updates as people vote" }, "phases": [ { "title": "Discover" }, { "title": "Invoke", "moment": true }, { "title": "Wait" }, { "title": "Respond", "moment": true }, { "title": "Follow up" } ], "lanes": [ { "title": "What they do", "kind": "step", "cells": [ [ { "label": "Types / and browses" } ], [ { "label": "Fills options" }, { "label": "Sends" } ], [ { "label": "Sees \"thinking…\"" } ], [ { "label": "Reads the reply" } ], [ { "label": "Presses a button" } ] ] }, { "title": "How it feels", "kind": "emotion", "levels": [ "Delighted", "Fine", "Frustrated" ], "points": [ 1, 1, 2, 0, 1 ] }, { "title": "Where it hurts", "kind": "pain", "cells": [ [], [], [ { "label": "Silence after 3 s" } ], [ { "label": "Failed with no reason" } ], [ { "label": "Button token expired" } ] ] }, { "title": "What the platform gives", "kind": "system", "cells": [ [ { "label": "Command list, ≤60 s fresh" } ], [ { "label": "Option validation" } ], [ { "label": "Deferred ack, 15 min" } ], [ { "label": "Ephemeral error to user" } ], [ { "label": "New interaction per press" } ] ] } ], "chain": true, "note": "If the bot is down the user is told within 3 seconds; they never wait on a silent system.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture", "date": "2026-10" } }, { "id": "06-layered-architecture", "title": "Discord Bot Platform — Layered Architecture", "layout": "bands", "canvas": { "width": 1700 }, "layerHeaderWidth": 150, "bands": [ { "name": "Bot side (untrusted)", "nodes": [ { "id": "l-bot", "label": "Bot Processes", "kind": "external" }, { "id": "l-hook", "label": "Interaction Endpoints", "kind": "external" }, { "id": "l-dash", "label": "Developer Portal", "kind": "app" } ] }, { "name": "Edge", "nodes": [ { "id": "l-ws", "label": "WebSocket Edge", "sub": "Front Door, L4", "kind": "integration" }, { "id": "l-api", "label": "API Edge", "sub": "auth, buckets", "kind": "integration" }, { "id": "l-egr", "label": "Interaction Egress", "sub": "isolated pool", "kind": "integration" }, { "id": "l-oauth", "label": "OAuth / Install", "kind": "integration" } ] }, { "name": "Control plane", "nodes": [ { "id": "l-reg", "label": "Application Registry", "sub": "Cosmos DB", "kind": "store" }, { "id": "l-inst", "label": "Installations & Grants", "kind": "store" }, { "id": "l-cmd", "label": "Command Registry", "kind": "store" }, { "id": "l-tok", "label": "Token Service", "sub": "Key Vault", "kind": "security" } ] }, { "name": "Session plane", "nodes": [ { "id": "l-gw", "label": "Gateway Shards", "sub": "AKS pods", "kind": "app" }, { "id": "l-sess", "label": "Session & Resume", "sub": "Redis", "kind": "store" }, { "id": "l-ctr", "label": "Rate-limit Counters", "sub": "Redis", "kind": "store" } ] }, { "name": "Fan-out plane", "nodes": [ { "id": "l-filt", "label": "Entitlement Filter", "kind": "app" }, { "id": "l-part", "label": "Server Partitions", "sub": "Event Hubs", "kind": "queue" } ] }, { "name": "Chat service", "nodes": [ { "id": "l-chat", "label": "Commit Events", "kind": "external" }, { "id": "l-perm", "label": "Permission Model", "kind": "external" } ] } ], "edges": [ { "from": "l-bot", "to": "l-ws", "label": "WSS", "kind": "sync" }, { "from": "l-ws", "to": "l-gw", "label": "frames", "kind": "sync" }, { "from": "l-gw", "to": "l-part", "label": "pull", "kind": "async" }, { "from": "l-part", "to": "l-chat", "label": "consume", "kind": "async" } ], "note": "Layers lower down never call upward; bots reach only the edge.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture", "date": "2026-10" } }, { "id": "07-gateway-components", "title": "Discord Bot Platform — Containers and Components", "layout": "nested", "canvas": { "width": 1700 }, "boxes": [ { "title": "Session plane — AKS gateway pool", "kind": "boundary", "dir": "row", "children": [ { "title": "Gateway pod (one per shard group)", "kind": "plain", "nodes": [ { "id": "c-conn", "label": "Connection Manager", "sub": "heartbeat, identify" }, { "id": "c-seq", "label": "Sequencer", "sub": "per-session seq" }, { "id": "c-buf", "label": "Resume Buffer", "sub": "bounded ring" }, { "id": "c-ser", "label": "Serializer", "sub": "JSON, ETF, zstd" } ] }, { "title": "Fan-out workers", "kind": "plain", "nodes": [ { "id": "c-ent", "label": "Entitlement Filter", "sub": "intents x perms" }, { "id": "c-route", "label": "Shard Router", "sub": "id >> 22 mod N" }, { "id": "c-lease", "label": "Entitlement Lease Cache", "sub": "10 s TTL", "kind": "store" } ] } ] }, { "title": "Control plane", "kind": "cloud", "dir": "row", "children": [ { "title": "Registry services", "kind": "plain", "nodes": [ { "id": "c-reg", "label": "Application Registry", "kind": "store", "sub": "Cosmos DB" }, { "id": "c-inst", "label": "Installation Service", "kind": "app" }, { "id": "c-rev", "label": "Revocation Broadcaster", "kind": "queue", "sub": "Event Grid" } ] } ] } ], "outside": [ { "id": "c-bot", "label": "Bot Process", "kind": "external" }, { "id": "c-part", "label": "Server Partitions", "kind": "queue", "sub": "Event Hubs" } ], "edges": [ { "from": "c-bot", "to": "c-conn", "label": "WSS", "kind": "sync" }, { "from": "c-part", "to": "c-ent", "label": "events", "kind": "async" }, { "from": "c-ent", "to": "c-route", "kind": "sync" }, { "from": "c-inst", "to": "c-rev", "kind": "async" }, { "from": "c-rev", "to": "c-lease", "label": "invalidate", "kind": "async" }, { "from": "c-conn", "to": "c-seq", "kind": "sync" }, { "from": "c-seq", "to": "c-buf", "kind": "sync" } ], "note": "Omitted: metrics sidecars and the node drain controller.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture", "date": "2026-10" } }, { "id": "08-integration-surface", "title": "Discord Bot Platform — Interface Catalogue", "layout": "hub", "canvas": { "width": 1700 }, "left": { "title": "Callers", "nodes": [ { "id": "h-bot", "label": "Bot Gateway Client", "kind": "external", "rel": "WSS" }, { "id": "h-rest", "label": "Bot REST Client", "kind": "external" }, { "id": "h-admin", "label": "Server Administrator", "kind": "actor", "rel": "OAuth" }, { "id": "h-chat", "label": "Chat Service", "kind": "external", "rel": "events", "dir": "in", "kind2": "async" } ] }, "centre": { "title": "Bot Platform", "nodes": [ { "id": "h-core", "label": "Bot Platform", "sub": "gateway, interactions, REST" } ] }, "right": { "title": "Dependencies", "nodes": [ { "id": "h-hook", "label": "Bot Interaction Endpoint", "kind": "external", "rel": "signed POST", "dir": "out" }, { "id": "h-perm", "label": "Permission Model", "kind": "external", "rel": "permissions", "dir": "out" } ] }, "note": "Omitted: developer portal and leaked-token scanner, both low-volume.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture", "date": "2026-10" } }, { "id": "09-storage-zones", "title": "Discord Bot Platform — Data Architecture and Storage Zones", "layout": "nested", "canvas": { "width": 1700 }, "boxes": [ { "title": "Zone 1 — Registry (strong, small, never lost)", "kind": "boundary", "dir": "row", "children": [ { "title": "Cosmos DB, multi-region writes off", "kind": "plain", "nodes": [ { "id": "z-app", "label": "Applications", "kind": "store" }, { "id": "z-ins", "label": "Installations & Grants", "kind": "store" }, { "id": "z-cmd", "label": "Commands", "kind": "store" }, { "id": "z-tok", "label": "Token Hashes", "kind": "store" } ] } ] }, { "title": "Zone 2 — Session (rebuildable by reconnecting)", "kind": "cloud", "dir": "row", "children": [ { "title": "Redis + in-pod memory", "kind": "plain", "nodes": [ { "id": "z-ses", "label": "Session Records", "kind": "store" }, { "id": "z-res", "label": "Resume Buffers", "sub": "120 s / 5k events", "kind": "store" } ] } ] }, { "title": "Zone 3 — Counters (approximate, regional)", "kind": "trust", "dir": "row", "children": [ { "title": "Redis cluster per region", "kind": "plain", "nodes": [ { "id": "z-rl", "label": "Rate-limit Buckets", "kind": "store" }, { "id": "z-quota", "label": "Identify Quotas", "kind": "store" } ] } ] }, { "title": "Zone 4 — Evidence (append-only)", "kind": "boundary", "dir": "row", "children": [ { "title": "Blob + Log Analytics", "kind": "plain", "nodes": [ { "id": "z-aud", "label": "API Audit, 90 days", "kind": "store" }, { "id": "z-sec", "label": "Security Events, 13 months", "kind": "store" } ] } ] } ], "note": "Message content is never stored here. Zones 2 and 3 are rebuilt, not restored.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture", "date": "2026-10" } }, { "id": "10-data-model", "title": "Discord Bot Platform — Data Model", "layout": "er", "canvas": { "width": 1600, "cols": 4 }, "rowGap": 260, "entities": [ { "id": "e-app", "name": "application", "kind": "store", "row": 0, "col": 1, "attrs": [ "application_id PK", "owner_id FK -> developer", "public_key", "review_state", "suspended_at" ] }, { "id": "e-dev", "name": "developer", "kind": "store", "row": 0, "col": 0, "attrs": [ "developer_id PK", "email", "verified_at" ] }, { "id": "e-ins", "name": "installation", "kind": "store", "row": 0, "col": 2, "attrs": [ "installation_id PK", "application_id FK", "server_id", "permissions_bitset", "granted_by", "revoked_at" ] }, { "id": "e-cmd", "name": "command", "kind": "store", "row": 1, "col": 1, "attrs": [ "command_id PK", "application_id FK", "server_id nullable", "name, options", "version" ] }, { "id": "e-tok", "name": "token", "kind": "store", "row": 1, "col": 0, "attrs": [ "token_id PK", "application_id FK", "hash (salted)", "created_at", "revoked_at" ] }, { "id": "e-ses", "name": "gateway_session", "kind": "store", "row": 1, "col": 2, "attrs": [ "session_id PK", "application_id FK", "shard_id, shard_count", "last_seq", "intents" ] }, { "id": "e-int", "name": "intent_approval", "kind": "store", "row": 0, "col": 3, "attrs": [ "application_id FK", "intent", "approved_at", "reviewer" ] } ], "relations": [ { "from": "e-dev", "to": "e-app", "label": "1 : N", "from_side": "e", "to_side": "w" }, { "from": "e-app", "to": "e-ins", "label": "1 : N", "from_side": "e", "to_side": "w" }, { "from": "e-app", "to": "e-cmd", "label": "1 : N", "from_side": "s", "to_side": "n" }, { "from": "e-app", "to": "e-tok", "label": "1 : N", "from_side": "s1", "to_side": "n" }, { "from": "e-ins", "to": "e-ses", "label": "1 : N", "from_side": "s", "to_side": "n" }, { "from": "e-ins", "to": "e-int", "label": "N : M", "from_side": "e", "to_side": "w", "kind": "optional" } ], "meta": { "v": "1.0", "owner": "Integration Platform Architecture", "date": "2026-10" } }, { "id": "11-slash-command-flow", "title": "Discord Bot Platform — Critical Flow: Slash Command to Reply", "layout": "sequence", "canvas": { "width": 1700 }, "lifelines": [ { "id": "u", "label": "Member", "kind": "actor" }, { "id": "cl", "label": "Chat Client", "kind": "external" }, { "id": "ix", "label": "Interaction Service", "kind": "app" }, { "id": "eg", "label": "Interaction Egress", "kind": "integration" }, { "id": "bot", "label": "Bot Endpoint", "kind": "external" }, { "id": "api", "label": "API Edge", "kind": "integration" } ], "messages": [ { "from": "u", "to": "cl", "label": "/poll question", "kind": "call" }, { "from": "cl", "to": "ix", "label": "create interaction", "kind": "call" }, { "from": "ix", "to": "ix", "label": "validate, permissions", "kind": "self" }, { "from": "ix", "to": "eg", "label": "enqueue delivery", "kind": "async" }, { "from": "eg", "to": "bot", "label": "POST + Ed25519 sig", "kind": "call" }, { "from": "bot", "to": "bot", "label": "verify signature", "kind": "self" }, { "from": "bot", "to": "eg", "label": "type 5 deferred ack", "kind": "return" }, { "from": "eg", "to": "ix", "label": "ack within 3 s", "kind": "return" }, { "from": "ix", "to": "cl", "label": "show thinking…", "kind": "return" }, { "from": "bot", "to": "api", "label": "PATCH original response", "kind": "call" }, { "from": "api", "to": "cl", "label": "update message", "kind": "async" }, { "from": "eg", "to": "ix", "label": "no ack: mark failed", "kind": "error" }, { "from": "ix", "to": "cl", "label": "ephemeral failure", "kind": "error" } ], "note": "Messages 12–13 are the timeout branch; they fire at 3.0 s, not later.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture", "date": "2026-10" } }, { "id": "12-event-fanout-pipeline", "title": "Discord Bot Platform — Event Fan-out Pipeline", "layout": "flow", "chain": true, "align": "middle", "canvas": { "width": 1700 }, "stages": [ { "title": "Commit", "nodes": [ { "id": "f-chat", "label": "Chat Commit", "sub": "message.create", "kind": "external" } ] }, { "title": "Partition", "nodes": [ { "id": "f-part", "label": "Server Partition", "sub": "key = server_id", "kind": "queue" } ] }, { "title": "Entitle", "nodes": [ { "id": "f-lookup", "label": "Installed Bots", "sub": "cached lease", "kind": "store" }, { "id": "f-filt", "label": "Intent Filter", "sub": "drop before serialise", "kind": "decision" } ] }, { "title": "Route", "nodes": [ { "id": "f-shard", "label": "Shard Router", "sub": "id >> 22 mod N", "kind": "app" } ] }, { "title": "Deliver", "nodes": [ { "id": "f-gw", "label": "Gateway Shard", "sub": "per-session buffer", "kind": "app" }, { "id": "f-drop", "label": "Shed / Close", "sub": "slow consumer", "kind": "risk" } ] }, { "title": "Bot", "nodes": [ { "id": "f-bot", "label": "Bot Socket", "kind": "external" } ] } ], "edges": [ { "from": "f-lookup", "to": "f-filt", "label": "entitled set", "kind": "sync" }, { "from": "f-gw", "to": "f-drop", "label": "buffer full", "kind": "error" } ], "note": "Hot-server handling (sampling presence, never moderation events) is a Phase 3 partition class.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture", "date": "2026-10" } }, { "id": "13-resume-after-disconnect", "title": "Discord Bot Platform — Critical Flow: Reconnect and Resume", "layout": "sequence", "canvas": { "width": 1600 }, "lifelines": [ { "id": "b", "label": "Bot", "kind": "external" }, { "id": "e", "label": "WebSocket Edge", "kind": "integration" }, { "id": "g", "label": "Gateway Node", "kind": "app" }, { "id": "s", "label": "Session Store", "kind": "store" }, { "id": "r", "label": "Registry", "kind": "store" } ], "messages": [ { "from": "b", "to": "e", "label": "connect (after jitter)", "kind": "call" }, { "from": "e", "to": "g", "label": "route by shard", "kind": "call" }, { "from": "g", "to": "b", "label": "hello + interval", "kind": "return" }, { "from": "b", "to": "g", "label": "resume(session, seq)", "kind": "call" }, { "from": "g", "to": "s", "label": "load session", "kind": "call" }, { "from": "s", "to": "g", "label": "seq window found", "kind": "return" }, { "from": "g", "to": "r", "label": "entitlement lease", "kind": "call" }, { "from": "r", "to": "g", "label": "grants current", "kind": "return" }, { "from": "g", "to": "b", "label": "replay seq+1 … n", "kind": "async" }, { "from": "g", "to": "b", "label": "invalid session: identify", "kind": "error" } ], "note": "Message 10 replaces 5–9 when the window is gone; the bot then pays the identify throttle.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture", "date": "2026-10" } }, { "id": "14-deployment-architecture", "title": "Discord Bot Platform — Deployment Architecture", "layout": "nested", "canvas": { "width": 1700 }, "boxes": [ { "title": "Azure — Region A (primary for its shards)", "kind": "cloud", "dir": "row", "children": [ { "title": "Edge", "kind": "boundary", "nodes": [ { "id": "d-fd", "label": "Front Door", "sub": "WAF, TLS" }, { "id": "d-lb", "label": "L4 Load Balancer", "sub": "WebSocket" } ] }, { "title": "AKS — gateway pool (zones 1–3)", "kind": "boundary", "nodes": [ { "id": "d-gw", "label": "Gateway pods", "sub": "StatefulSet" }, { "id": "d-fan", "label": "Fan-out workers" }, { "id": "d-api", "label": "API pods", "sub": "stateless" } ] }, { "title": "State", "kind": "boundary", "nodes": [ { "id": "d-redis", "label": "Azure Cache for Redis", "kind": "store" }, { "id": "d-eh", "label": "Event Hubs", "kind": "queue" }, { "id": "d-cos", "label": "Cosmos DB", "kind": "store" }, { "id": "d-kv", "label": "Key Vault", "kind": "security" } ] } ] }, { "title": "Azure — Region B (standby for A, primary for its own)", "kind": "cloud", "dir": "row", "children": [ { "title": "Mirror stack", "kind": "boundary", "nodes": [ { "id": "d-gw2", "label": "Gateway pods" }, { "id": "d-eh2", "label": "Event Hubs", "kind": "queue" }, { "id": "d-cos2", "label": "Cosmos DB replica", "kind": "store" } ] } ] } ], "outside": [ { "id": "d-egr", "label": "Egress Pool", "sub": "NAT, published range", "kind": "integration" } ], "edges": [ { "from": "d-fd", "to": "d-api", "label": "HTTPS", "kind": "sync" }, { "from": "d-lb", "to": "d-gw", "label": "WSS", "kind": "sync" }, { "from": "d-cos", "to": "d-cos2", "label": "replicate", "kind": "batch" } ], "meta": { "v": "1.0", "owner": "Integration Platform Architecture", "date": "2026-10" } }, { "id": "15-release-pipeline", "title": "Discord Bot Platform — Release and Environments", "layout": "flow", "chain": true, "align": "middle", "canvas": { "width": 1700 }, "stages": [ { "title": "Source", "nodes": [ { "id": "r-git", "label": "Repository", "sub": "trunk-based", "kind": "app" } ] }, { "title": "Build", "nodes": [ { "id": "r-build", "label": "Build & Test", "sub": "GitHub Actions", "kind": "app" }, { "id": "r-contract", "label": "Protocol Contract Tests", "sub": "opcodes, close codes", "kind": "decision" } ] }, { "title": "Stage", "nodes": [ { "id": "r-stage", "label": "Staging Region", "sub": "synthetic bots", "kind": "app" } ] }, { "title": "Canary", "nodes": [ { "id": "r-can", "label": "1 % of shards", "sub": "drain-aware", "kind": "app" }, { "id": "r-gate", "label": "Resume Success Gate", "sub": "≥ 99.5 %", "kind": "decision" } ] }, { "title": "Roll out", "nodes": [ { "id": "r-roll", "label": "Region by region", "sub": "node drain, 30 s", "kind": "app" } ] } ], "edges": [ { "from": "r-gate", "to": "r-build", "label": "roll back", "kind": "error", "route": "gutter" } ], "note": "A Gateway release drains a node by telling bots to reconnect with jitter; it never kills a socket cold.", "meta": { "v": "1.0", "owner": "Integration Platform Architecture", "date": "2026-10" } }, { "id": "16-observability", "title": "Discord Bot Platform — Observability", "layout": "grid", "canvas": { "width": 1700 }, "columns": [ "Edge", "Gateway", "Fan-out", "Interactions", "REST" ], "rows": [ { "title": "Metrics", "cells": [ [ { "label": "Connections by shard", "kind": "platform" } ], [ { "label": "Resume success rate", "kind": "platform" } ], [ { "label": "Event lag p99", "kind": "platform" } ], [ { "label": "Ack-in-3s rate", "kind": "platform" } ], [ { "label": "429 per bucket", "kind": "platform" } ] ] }, { "title": "Logs", "cells": [ [ { "label": "Handshake rejects", "kind": "platform" } ], [ { "label": "Close codes", "kind": "platform" } ], [ { "label": "Entitlement drops", "kind": "platform" } ], [ { "label": "Signature failures", "kind": "platform" } ], [ { "label": "Ban escalations", "kind": "platform" } ] ] }, { "title": "Traces", "cells": [ [], [ { "label": "Identify path", "kind": "platform" } ], [ { "label": "Commit to socket write", "kind": "platform" } ], [ { "label": "Click to POST", "kind": "platform" } ], [ { "label": "Request to response", "kind": "platform" } ] ] } ], "meta": { "v": "1.0", "owner": "Integration Platform Architecture", "date": "2026-10" } }, { "id": "17-session-lifecycle", "title": "Discord Bot Platform — Gateway Session Lifecycle", "layout": "cycle", "canvas": { "width": 1500 }, "centre": { "label": "Session" }, "nodes": [ { "id": "s3", "label": "Ready & streaming", "kind": "opportunity" }, { "id": "s4", "label": "Degraded: buffer high", "kind": "decision" }, { "id": "s5", "label": "Disconnected", "kind": "risk" }, { "id": "s1", "label": "Reconnecting", "sub": "server-set jitter", "kind": "app" }, { "id": "s6", "label": "Resuming", "kind": "app" } ], "ringLabels": [ "slow reader", "closed, resumable", "backoff", "session found", "replayed" ], "rx": 430, "ry": 210, "meta": { "v": "1.0", "owner": "Integration Platform Architecture", "date": "2026-10" } }, { "id": "18-security-trust-zones", "title": "Discord Bot Platform — Security and Trust Zones", "layout": "zones", "canvas": { "width": 1700 }, "zones": [ { "title": "Internet / bot side", "kind": "trust", "nodes": [ { "id": "t-bot", "label": "Bot Process", "kind": "external" }, { "id": "t-hook", "label": "Bot Endpoint", "kind": "external" } ] }, { "title": "Edge", "kind": "trust", "nodes": [ { "id": "t-ws", "label": "WebSocket Edge", "sub": "WAF, TLS 1.2+", "kind": "integration" }, { "id": "t-api", "label": "API Edge", "sub": "token auth, buckets", "kind": "integration" }, { "id": "t-egr", "label": "Egress Pool", "sub": "SSRF-safe", "kind": "integration" } ] }, { "title": "Platform", "kind": "trust", "nodes": [ { "id": "t-gw", "label": "Gateway Shards", "kind": "app" }, { "id": "t-ix", "label": "Interaction Service", "kind": "app" }, { "id": "t-tok", "label": "Token Service", "kind": "security" } ] }, { "title": "Data and trusted chat service", "kind": "trust", "nodes": [ { "id": "t-reg", "label": "Registry", "kind": "store" }, { "id": "t-kv", "label": "Key Vault", "kind": "security" }, { "id": "t-chat", "label": "Chat Service", "kind": "app" } ] } ], "edges": [ { "from": "t-bot", "to": "t-ws", "label": "WSS + token", "kind": "sync" }, { "from": "t-ws", "to": "t-gw", "label": "authenticated frames", "kind": "sync" }, { "from": "t-gw", "to": "t-reg", "label": "entitlements", "kind": "sync" }, { "from": "t-ix", "to": "t-egr", "label": "signed payload", "kind": "sync" }, { "from": "t-egr", "to": "t-hook", "label": "validated URL only", "kind": "sync" }, { "from": "t-tok", "to": "t-kv", "label": "hash keys", "kind": "sync" } ], "meta": { "v": "1.0", "owner": "Integration Platform Architecture", "date": "2026-10" } }, { "id": "19-identity-and-install", "title": "Discord Bot Platform — Identity: Install and Token Use", "layout": "sequence", "canvas": { "width": 1700 }, "lifelines": [ { "id": "a", "label": "Administrator", "kind": "actor" }, { "id": "c", "label": "Consent Screen", "kind": "integration" }, { "id": "i", "label": "Installation Service", "kind": "app" }, { "id": "t", "label": "Token Service", "kind": "security" }, { "id": "g", "label": "Gateway", "kind": "app" }, { "id": "b", "label": "Bot", "kind": "external" } ], "messages": [ { "from": "a", "to": "c", "label": "open invite link", "kind": "call" }, { "from": "c", "to": "a", "label": "list scopes + perms", "kind": "return" }, { "from": "a", "to": "c", "label": "approve", "kind": "call" }, { "from": "c", "to": "i", "label": "create installation", "kind": "call" }, { "from": "i", "to": "g", "label": "entitlement push", "kind": "async" }, { "from": "b", "to": "g", "label": "identify(token, intents)", "kind": "call" }, { "from": "g", "to": "t", "label": "verify hash", "kind": "call" }, { "from": "t", "to": "g", "label": "application id", "kind": "return" }, { "from": "g", "to": "b", "label": "ready (guilds)", "kind": "return" }, { "from": "a", "to": "i", "label": "revoke", "kind": "call" }, { "from": "i", "to": "g", "label": "close session ≤ 10 s", "kind": "error" } ], "meta": { "v": "1.0", "owner": "Integration Platform Architecture", "date": "2026-10" } } ]