Architecture One-Pager

Discord Bot Platform · Solution Architecture v1.0 · Microsoft Azure · Integration Platform Architecture · 2026-10 · 19 views · 12 architecture decision records

Bots are untrusted consumers on the far side of a one-way boundary: entitlement is enforced before an event is produced, the shard is an address you compute, and every promise states what it loses.

A chat service with 150 million users lets anyone register code that reacts to messages. Some bots are slow. Some are offline for days. A few are hostile. One, at any moment, is a viral slash command running on a serverless function with a cold start — and a person is staring at a spinner waiting for it. In the obvious architecture each of these problems leaks back into the chat service: a slow bot slows a message, a reconnecting fleet takes down the registry, and a revoked bot keeps reading for an hour.

The chat service commits and emits an event, and its involvement ends. Fan-out consumes events partitioned by server, filters them by the bot's intents and the server's permissions before anything is serialised, and routes each to a shard that is simply arithmetic on the server identifier. Gateway pods hold the sockets, with a bounded buffer per session and a 120-second resume window; a bot that reads too slowly is closed resumably, not allowed to grow memory. Slash commands arrive by signed HTTPS or the socket and carry a three-second acknowledgement the platform enforces, with deferral to fifteen minutes. REST actions pass a per-route-bucket limiter whose headers tell the client exactly what to do. Installations belong to the server, and revocation pushes to every node with a ten-second lease as the backstop. Reconnect storms are smeared by server-directed jitter and an identify throttle.

What it is, and what it is not

• Entitlement enforced at the source — not send-everything-and-filter-in-the-client, which leaks data and spends bandwidth.
• Shard as arithmetic — not a routing table that becomes a hot, replicated dependency.
• A published loss boundary at 120 seconds — not an exactly-once claim the platform cannot keep.
• A three-second acknowledgement — not unbounded waiting on a stranger's endpoint.
• Server-owned installations — not grants tied to developer accounts that vanish.
• State classed by how it may be lost — not one strongly consistent store for everything.
• Topological containment of egress — not an SSRF validator as the only defence.

The decisions that are the architecture

1. The chat service never waits on a bot (ADR-01) — Events leave over a one-way stream; bot actions return through a separate API edge.
2. Filter before serialising, route by arithmetic (ADR-02) — Nothing unentitled is produced, and shard placement needs no lookup.
3. Three seconds, then a visible failure (ADR-03) — The wait on a stranger is bounded and the expiry is shown to the user.
4. A loss boundary that is published (ADR-04) — Ordered replay for 120 s, explicit loss after, bounded buffers throughout.
5. Partition by server (ADR-05) — A hot server is one partition, not many copies.
6. The server owns the grant (ADR-06) — Permissions are evaluated on every call against current roles.
7. Directed, throttled reconnects (ADR-07) — The recovery path is cheaper than the failure path.
8. Revocation has a deadline (ADR-08) — Push plus a ten-second lease.
9. Limits that can be read (ADR-09) — Bucketed, with headers, escalating to bans only for offenders.
10. Egress contained by topology (ADR-11) — A separate zone with a published range.

Why this should still be right in ten years

A bot platform outlives its first generation of bots, because developers write against the protocol and never rewrite it. These are the properties that should survive a change of scale, of cloud and of staff.

• The trust boundary depends on no technology. ADR-01 survives replacing Event Hubs, AKS and Azure. What would erode it is an exception for a first-party bot that blocks sending a message.
• The shard formula is public API. Changing it breaks every deployed bot, which is exactly why it is arithmetic and documented, not infrastructure.
• Explicit loss boundaries age well. Numbers change; the stance that every promise states what it drops does not.
• Ownership follows consequence. The server bears the risk of a bot, so the server holds the grant. That rule is independent of scale.

Non-functional targets

Every number here is a stated assumption from the requirement, chosen to be argued with. The right-hand column names the view where the mechanism that meets it is drawn.

Scope

In scope

• Gateway sessions, sharding, intents, resume.
• Interactions with signing, acknowledgement and deferral.
• REST with route-bucket limits and permission evaluation.
• Installation, grants, tokens and revocation.
• Developer-facing health and test tooling.
• Egress isolation for bot-supplied URLs.

Explicitly out of scope

• Message storage and the chat service itself.
• Voice media.
• Bot hosting and runtimes.
• A paid marketplace.
• User-facing clients.
• Abuse model training.

What a four-week prototype should prove

Three claims are cheap to test and expensive to be wrong about.

1. Reconnect storm: kill a node holding 40,000 sessions and measure registry p99 and time-to-resume with and without the identify throttle.
2. Slow consumer: one bot reading at 1 % of event rate, measuring pod memory and the effect on neighbouring sessions at the buffer bound.
3. Revocation: revoke a grant under a registry brownout and measure the worst-case time until the session stops receiving events.

• A gateway node holding 40,000 sessions is killed during peak: every session resumes or re-identifies inside 10 minutes and registry p99 stays under 50 ms.
• One bot stops reading while its server posts 5,000 messages per second: its session closes resumably at the buffer bound, and no neighbouring session on the pod sees added latency.
• An administrator revokes a bot during a registry brownout: the bot stops receiving events inside 10 seconds, or the scenario records exactly how long it took.

Open risks, carried rather than hidden

The reasoning behind every component and technology choice is in the Architecture Decision Record: 12 records across 11 areas, each with the alternatives that lost and what the choice costs.