Design Discord

Requirements: what Discord adds to team chat

Discord looks like Slack with a dark theme. Under the same surface it is a different shape of problem. Slack is a workplace: a few workspaces, members who mostly know each other, and channels where most people can post. Discord is a set of communities: one person often sits in dozens of servers (up to 100, or 200 with Nitro, Discord's paid subscription), a few of them public servers with hundreds of thousands of members, and many of the channels have a voice room next to the text.

The core chat machinery (channels, the message list, reconnect and gap fetch, the outbox for sending, drafts, desktop notifications) is the same as in the Slack guide, and very fast chat is covered in the Live comments guide. This guide links to them and spends its time on what is specific to Discord: scale per server, the member list, roles and permissions, voice, rich content, and unread state across many servers.

So the first minutes go to questions about size and shape. The table shows the answers this guide assumes and what each one changes.

Functional requirements

• A server rail (the column of server icons) with unread pills and mention badges, a channel list per server grouped in categories, the message pane, and a member list sidebar.
• Read and send messages with Discord markdown, custom emoji, stickers, attachments, replies, and threads.
• A member list grouped by role and by online or offline, live as people come and go, in servers of any size.
• Hide or disable every action the user is not allowed to take, per channel: sending, attaching files, managing messages, joining voice, speaking.
• Join a voice channel, see who is in it and who is speaking, mute and deafen, use push-to-talk, turn on video, and share a screen. Keep the call running while browsing text channels.
• Reactions with counts, including animated super reactions, and link embeds that appear after the message is sent.
• Unread and mention state per channel and per server, with mute and notification settings at both levels, synced across devices.
• Moderation surfaces: slowmode, timeouts, AutoMod blocks shown to the author, and the audit log.
• Full keyboard use, a quick switcher (Ctrl+K), and screen reader support.

Non-functional requirements

• Fast start: with a warm cache, the server rail and the last channel paint in under 1 second, before the live connection finishes its handshake.
• Bounded traffic: the event rate the client must handle depends on what is on screen, not on the size of the servers it is in. A user in ten 500,000-member servers must not receive every presence change in them.
• Instant feedback: a click in the member list or a mute toggle reacts within 100 ms; Interaction to Next Paint (INP, how fast the page reacts to input) stays under 200 ms.
• Voice quality: speaking indicators within about 100 ms of the sound, and no audio gap when the user switches text channels.
• Flat memory: a desktop client left open for a week stays in the same memory range as after the first hour.
• Accessible: WCAG 2.2 AA, every feature by keyboard, reduced motion respected for animated emoji and reactions.

Out of scope

• The media server (the SFU, a server that forwards each person's stream to the others) and codec tuning: the Video conferencing guide and the WebRTC lesson cover them.
• Bots and slash command backends; the client only renders their messages and components.
• Search, which works the same as in the Slack guide.
• Mobile apps, payments for Nitro, and server discovery.

What makes Discord hard

Five traits drive every later decision. Each one is easy alone. Together they are why the Discord client is a hard design question.

1. Lopsided scale. One user's servers range from 4 friends to 1,000,000 strangers. A design that loads "the server" works for the first and melts on the second. Every per-server structure (members, presence, typing, voice states) needs a plan for the huge case.
2. Many servers on one connection. All servers share a single WebSocket (the gateway). If every server pushed every event, the busiest server would decide how much work the client does, even while the user looks at a quiet one.
3. Rules that shape the UI. Whether the composer, the attach button, the delete option, or the voice join button appear depends on roles, their order, and per-channel overrides. The client has to compute this locally, fast, for every channel.
4. Two kinds of real time. Text is ordered events over the gateway. Voice is a media stream over WebRTC to a different server. The two have different connections, failure modes, and lifetimes, but one UI.
5. Heavy, long-lived pages. Messages are full of animated emoji, GIFs, images, and embeds. People keep the desktop app open for days. Memory and frame rate matter as much as network.

The math that rules out the naive client

Take one public server with 500,000 members and 25,000 of them online. People change presence (online, idle, do not disturb, offline, or start a game) all the time. Say each online member changes something once every 10 minutes on average: that is 25,000 / 600 seconds, about 42 presence events a second, from one server. Add typing events, member joins, and voice state changes and it passes 60.

A user in five such servers would get 300 events a second, each one parsed, put into a store, and possibly rendered. A laptop can parse that, but the battery and the main thread pay for it every second the app is open, for events about people the user will never see. And the initial payload is worse: 500,000 member objects at about 300 bytes each is about 150 MB for one server. No client can load that.

The table points at the main idea of the whole guide: the client subscribes to what is on screen. Small, structural data (channels, roles, the user's own membership) is loaded for every server, because the UI needs it to compute permissions and draw the channel list. Big, fast-changing data (members, presence, typing, message bodies) arrives only for the server, channel, and member range the user is looking at.

One gateway connection for every server

The client needs live updates from every server the user is in. The transport is a WebSocket (see the WebSockets lesson; Slack and Chat app guides make the same pick). The real question is what that connection carries, and who decides.

The handshake, resume, and what READY holds

Discord's documented gateway protocol works like this, and it is a good model to reuse. The server first sends Hello (opcode 10) with a heartbeat_interval in milliseconds (the docs' example shows 45 seconds; clients commonly see about 41). The client sends Identify (opcode 2) with its token and gets back a READY event with a session_id and a resume_gateway_url. Every event after that carries a sequence number s.

What else READY holds differs by client. For bots, the docs list each server as an unavailable stub, and the server's data follows in its own GUILD_CREATE event. For the official client, community documentation describes a READY that already holds every server's small structural data (channels, roles, emoji, the user's own membership) plus read states. Either way, nothing big arrives in the first payload.

Heartbeats have two documented details worth copying. The first heartbeat waits a random fraction of the interval (jitter), so a million clients reconnecting after an outage do not all beat at once. And if the server has not acknowledged the previous heartbeat when the next one is due, the connection is a "zombie": the client closes it and resumes instead of waiting for the operating system to notice.

The bot side of the same protocol shows how Discord bounds traffic. In Identify, a bot sends intents, a bit mask of the event groups it wants, and presence and member events sit behind privileged intents that are off by default. A large_threshold (50 to 250 members) makes the gateway stop sending offline members of bigger servers. Each one is the rule this guide applies to the user client: send only what was asked for.

When the socket drops, the client reconnects to the resume_gateway_url and sends Resume (opcode 6) with the session_id and the last s it processed. The server replays what was missed. If the session cannot be resumed, it answers Invalid Session (opcode 9) and the client identifies again from scratch. This is the same gap-fetch idea the Slack guide covers, done by the gateway instead of by a REST call per channel.

Active and passive servers

Each server is in one of two modes for this client. A passive server is one the user is not looking at. Discord's engineering posts describe passive sessions: the server stops sending most events and instead sends a periodic compact update with the server's channels (each with its latest message id), members, and who is in voice.

That is enough to draw unread pills and voice rooms. Mentions of the user cannot wait for the next periodic update, so in this design they arrive as their own small event. An active server is the one on screen. When the user opens it, the client subscribes and starts receiving full messages, typing, and member list updates for the open channel.

The official client does this with an opcode that is not in Discord's public bot documentation. Community documentation (unofficial "lazy guilds" docs by people who reimplement the protocol) calls it opcode 14: the client sends the server id and, per channel, the member list ranges it wants, such as [[0, 99]]. Newer community docs mark opcode 14 as deprecated in favor of a bulk version (opcode 37) that updates several servers in one message. Treat the shape as unofficial: what matters is a subscription message that says what is on screen.

type Range = [number, number];
type Wanted = { guildId: string; channelId: string; ranges: Range[] };

let sent: Wanted | null = null;
let pending: Wanted | null = null;
let timer: ReturnType<typeof setTimeout> | null = null;

export function setOnScreen(next: Wanted) {
  pending = next;
  if (timer) return;
  timer = setTimeout(flush, 250);
}

function flush() {
  timer = null;
  if (!pending || sameAs(pending, sent)) return;
  gateway.send({
    op: 14,
    d: { guild_id: pending.guildId, typing: true, activities: true,
         channels: { [pending.channelId]: pending.ranges } },
  });
  sent = pending;
}

Two details make it work. Batching: scrolling the member list fires scroll events 60 times a second, but the server should hear about a new range at most a few times a second. Re-subscribe on resume: after a reconnect the server may have dropped the subscription, so the client sends its current sent value again as soon as the session is back.

Keeping bytes down

Discord's gateway compresses its traffic as one continuous stream, chosen with a compress parameter: zlib-stream or zstd-stream. The client keeps one decompression context for the life of the connection. With zlib it buffers incoming bytes until the 4-byte flush suffix 00 00 ff ff and then inflates them. Because the context remembers earlier data, repeated field names and ids across events compress well.

Discord wrote in 2024 that switching its apps from zlib to Zstandard, together with sending passive sessions only what changed instead of full snapshots, cut gateway bandwidth by almost 40 percent; the post describes native Zstandard bindings in the desktop and mobile apps. For the client, the lesson is that decompression runs on every event. It must be a streaming decoder fed frame by frame, never a fresh decode of each frame from zero.

The member list: a live window into a million people

The member list is the column on the right of a text channel. It shows people grouped by role (for roles the admins chose to display separately, called hoisted roles), then everyone else who is online, then offline members. Each row has an avatar, a name in the color of the person's highest colored role, a status dot, and maybe a custom status or the game they are playing.

In a server with 20 people this is trivial. In a server with 500,000 it is one of the hardest parts of the client. The Slack guide already subscribes to presence only for avatars on screen; Discord goes a step further and lets the server own the order of the whole list.

One flat list of headers and rows

The trick that makes ranges simple: the server flattens groups and members into one list of items. Item 0 is the header "Moderators, 12", items 1 to 12 are moderators, item 13 is the header "Online, 24,301", and so on. A range like [100, 199] is just items 100 to 199, whatever mix of headers and people that is. The client keeps a sparse array of items by index and renders it with a virtualized list (see the Virtualization lesson and the Virtualized list guide).

Which list? A member list depends on who can see the channel. Two channels with the same view rules have the same list, so the community docs describe a list id derived from the channel's view permissions: channels anyone can see share one list called everyone, and private channels get a hash of their allow and deny rules. The client keys its cache by that list id, so moving between 30 public channels reuses one list instead of 30.

type Item = { group: { id: string; count: number } } | { member: Member };
type Op =
  | { op: "SYNC"; range: [number, number]; items: Item[] }
  | { op: "INSERT" | "UPDATE"; index: number; item: Item }
  | { op: "DELETE"; index: number }
  | { op: "INVALIDATE"; range: [number, number] };

export function applyOps(list: (Item | undefined)[], ops: Op[]) {
  for (const o of ops) {
    if (o.op === "SYNC") o.items.forEach((it, i) => (list[o.range[0] + i] = it));
    else if (o.op === "INSERT") list.splice(o.index, 0, o.item);
    else if (o.op === "UPDATE") list[o.index] = o.item;
    else if (o.op === "DELETE") list.splice(o.index, 1);
    else for (let i = o.range[0]; i <= o.range[1]; i++) list[i] = undefined;
  }
}

Ops must be applied in the order received, because each index assumes the previous op already ran. A person going online is two ops: DELETE at their old offline index and INSERT at their place in the online group. Applied out of order, every row after them shifts by one.

Scrolling: which ranges to hold

• Rows are a fixed height (about 44 px for a member, a bit less for a header), so the total height is the item count times the row height, known from the group counts before any row loads. The scrollbar is honest from the first paint.
• On scroll, compute the visible item indexes, round out to the 100-row ranges they touch, and add one range of lookahead in the scroll direction. Keep range [0, 99] always: it holds the top groups people jump back to.
• Hold at most about 3 ranges. When the user flings to row 40,000, the client drops the old ranges (the server stops sending ops for them) and subscribes to the new ones. Until the SYNC arrives, rows show gray placeholder bars, not a spinner over the whole list.
• Keep the scroll position stable when rows are inserted above the viewport: measure the first visible item before applying ops and restore its offset after.

Presence: throttled on the server, batched on the client

Even inside 300 subscribed rows, a busy server changes status often. Two layers keep this cheap. The server can batch: collect operations for a range for a short window and send one event. The client batches too, with the same per-frame flush as the Slack guide: incoming ops go into a queue, and one requestAnimationFrame callback applies them all and renders once, so a person who flips online, idle, online inside one batch shows only the end state.

Some updates are worth less than others. A status dot change is cheap to render, but a row moving between groups shifts everything below it, which looks jumpy if it happens every second. A reasonable rule: apply in-place updates at once, and if more than a few moves land in the visible area within a second, apply them together. The Presence and cursors lesson covers the same idea of trading freshness for calm.

Permissions in the UI: roles, overwrites, and bit math

In Discord, what a person can do depends on three things: the roles they have in the server, the order of those roles (the role hierarchy), and per-channel overwrites that allow or deny single permissions for a role or a single member. The same person can post in #general, only read #announcements, and not even see #mod-chat.

The server checks every action; the client can never be trusted with security. But the UI still needs to know the answer, constantly: whether to show the composer or a "you cannot send messages here" note, whether the attach button exists, whether "Delete message" appears on other people's messages, whether the voice channel can be joined. A user who clicks a button only to get an error has been let down by the UI.

Permissions are bits in a big number

Each permission is one bit. A role's permissions are one number with the bits it grants set to 1. In Discord's documented list, VIEW_CHANNEL is bit 10 (0x400), SEND_MESSAGES bit 11 (0x800), MANAGE_MESSAGES bit 13, ATTACH_FILES bit 15 (0x8000), ADD_REACTIONS bit 6 (0x40), CONNECT bit 20, SPEAK bit 21, and ADMINISTRATOR bit 3. There are more than 40 permissions, and some sit above bit 31 (MODERATE_MEMBERS, for timeouts, is bit 40).

The algorithm, step by step

1. Owner: the server owner has every permission. Stop.
2. Base: start from the @everyone role's permissions, then OR in the permissions of each role the member has.
3. Administrator: if the base has ADMINISTRATOR, the member has every permission in every channel. Stop.
4. @everyone overwrite for this channel, if any: clear its denied bits, then set its allowed bits.
5. Role overwrites: for all of the member's roles that have an overwrite here, OR together all their denies and all their allows. Clear the combined denies, then set the combined allows. So if one role denies a bit and another allows it, allow wins.
6. Member overwrite for this person, if any: clear its denies, then set its allows. This one wins over everything above.
7. Implicit rules: without VIEW_CHANNEL, every other permission in the channel is off. Without SEND_MESSAGES, the permissions that only make sense when sending (ATTACH_FILES, EMBED_LINKS, MENTION_EVERYONE, text to speech) are off too. A member in a timeout keeps only VIEW_CHANNEL and READ_MESSAGE_HISTORY (owners and administrators cannot be timed out).

const ALL = (1n << 64n) - 1n;
const ADMIN = 1n << 3n, VIEW = 1n << 10n, SEND = 1n << 11n;
// Text to speech, embed links, attach files, mention everyone
const SEND_DEPENDENT = (1n << 12n) | (1n << 14n) | (1n << 15n) | (1n << 17n);
const TIMEOUT_KEEP = VIEW | (1n << 16n); // view, read message history

export function channelPerms(
  g: Guild, roles: Record<string, Role>, me: Member, ch: Channel,
): bigint {
  if (g.ownerId === me.userId) return ALL;
  let p = roles[g.id].permissions; // @everyone role id equals the guild id
  for (const r of me.roleIds) p |= roles[r].permissions;
  if (p & ADMIN) return ALL;

  const ow = ch.overwrites;
  const every = ow[g.id];
  if (every) p = (p & ~every.deny) | every.allow;
  let allow = 0n, deny = 0n;
  for (const r of me.roleIds) {
    if (ow[r]) { allow |= ow[r].allow; deny |= ow[r].deny; }
  }
  p = (p & ~deny) | allow;
  const mine = ow[me.userId];
  if (mine) p = (p & ~mine.deny) | mine.allow;

  if (!(p & VIEW)) return 0n;
  if (!(p & SEND)) p &= ~SEND_DEPENDENT;
  return (me.timedOutUntil ?? 0) > Date.now() ? p & TIMEOUT_KEEP : p;
}

A worked example

Maya is in a server with roles Member and Artist. The @everyone role grants view, send, add reactions, connect, and speak: 0x400 + 0x800 + 0x40 + 0x100000 + 0x200000 = 0x300C40. Member adds ATTACH_FILES (0x8000), so her base is 0x308C40. Now the #showcase channel has three overwrites.

So in #showcase Maya sees the composer (send is on), no attach button (attach is off), no add-reaction button on hover (reactions are off), and could still join a voice channel with the same overwrites. Toggle the same inputs in the lab below and watch each step.

Role hierarchy: who can act on whom

Roles have a position. Moderation actions follow it: a member can kick, ban, time out, or change the nickname of someone only if their own highest role is above that person's highest role, and they can only grant or edit roles below their own highest role.

The client uses this to decide the context menu on a member: "Kick" appears only when the user has KICK_MEMBERS and outranks the target. The role list in settings grays out roles the user cannot drag. Name colors come from the same order: the highest role that has a color wins.

Hide, disable, or explain

Cache results per channel in a permission store, keyed by channel id. Invalidate the whole server's cache on a role update, the user's own member update, or a channel update; that is rare, and recomputing 300 channels takes well under a millisecond.

Hiding a channel only protects its name if the name never reached the device. Discord announced in August 2026 that users stop receiving full data for channels they cannot view: over the gateway such a channel arrives with its name replaced by ___hidden___ and a CHANNEL_OBFUSCATED flag, and a CHANNEL_UPDATE with the real data follows when access is granted. Its overwrites are reduced to one that denies VIEW_CHANNEL to @everyone, so the same permission function hides it with no special case.

Voice and video channels

A voice channel in Discord is a room you drop into by clicking it. There is no ringing and no meeting link. People stay for hours, often while reading and typing in text channels of the same or another server. That changes three things compared with a meeting app: the call has to outlive navigation, the channel list must show who is in each voice room without joining, and the media connection is separate from the text gateway.

This chapter covers the client side of voice. How media reaches the others (a selective forwarding unit, codecs, bandwidth estimation, simulcast) is in the WebRTC lesson and the Video conferencing guide, and works the same here.

Two connections: the gateway says where, the voice server carries sound

Discord's documented flow for voice uses both connections. The client sends a voice state update (opcode 4) on the main gateway with the server id, the channel id, and its own mute and deafen flags. The gateway answers with two events: VOICE_STATE_UPDATE (the user is now in that channel, with a voice session_id) and VOICE_SERVER_UPDATE (a token and an endpoint: the voice server for this call).

The client then opens a second WebSocket to that endpoint, identifies with the token, and sets up the media connection. Discord has written that its browser app uses the browser's WebRTC, while the desktop and mobile apps share one C++ media engine built on the native WebRTC library. Because every client talks only to Discord's media servers, the native engine skips the offer and answer exchange (SDP) and the path-finding step (ICE, which tries network routes until one works); the browser keeps them. This guide follows the browser path.

The voice connection as a state machine

A voice connection goes through several steps, and each can fail. Modeling it as a state machine keeps the UI honest: "Connecting", "RTC connecting", "Voice connected", "No route" are each a state with its own label in the voice bar. Discord's own voice bar shows labels like these.

• Moved by a moderator or channel deleted: the gateway sends a new VOICE_STATE_UPDATE with a different channel or none. The machine goes to the new channel or to idle without the user doing anything.
• Voice server change (the server moved the call to another region or machine): a new VOICE_SERVER_UPDATE arrives; the client closes the old voice socket and connects to the new endpoint, keeping the local microphone track.
• Network change (Wi-Fi to Ethernet): WebRTC's ICE restart finds a new path; the voice bar shows "RTC connecting" for a moment, then recovers.

Who is here, who is speaking

Under each voice channel in the channel list, the client shows who is in it, with mute and deafen icons. That data comes from VOICE_STATE_UPDATE events for the whole server, which is small (people in voice are a few percent of members) and needed even in passive servers, so people can see where their friends are.

The speaking indicator is the green ring around an avatar. The signals are the ones the Video conferencing guide uses: a Web Audio AnalyserNode on the user's own microphone, and RTCRtpReceiver.getSynchronizationSources(), which gives an audioLevel from 0 to 1 for each incoming audio source. The voice server's speaking messages tell the client which user each audio source (its SSRC, the stream id carried in every packet) belongs to.

What Discord adds is how many avatars show the ring: everyone in the channel list's voice rooms, not just a call grid. Poll levels every 100 ms and flip a per-user boolean only when it crosses a threshold. That keeps renders rare: one when someone starts speaking and one when they stop, not 10 a second.

Push-to-talk shows a platform limit. In a browser, the page only hears keydown and keyup while it has focus, so push-to-talk stops working when the user is in another window; Discord's web app labels its push-to-talk as limited for this reason. The desktop app registers a global key hook through the native shell, so the key works while the user plays a game. The design point: put the key source behind an interface (onTalkStart, onTalkEnd) with a browser implementation and a desktop one.

Video and Go Live

Camera video in a voice channel is a video track on the same WebRTC connection. Screen sharing, called Go Live in a server, uses getDisplayMedia() and is treated differently: viewers choose to watch with a "Watch stream" button instead of receiving it automatically. That opt-in matters at scale: a stream to 3 viewers costs the server's fanout only for those 3.

Going live needs the STREAM permission (called "Video" in the settings UI). Higher resolutions and frame rates are a Nitro perk, so the quality picker disables those options with a Nitro badge for others.

End-to-end encrypted calls (DAVE)

Since September 2024, Discord has been moving voice and video in DMs, group DMs, voice channels, and Go Live streams to end-to-end encryption with its DAVE protocol, and its developer docs say only end-to-end encrypted calls are supported from March 1, 2026. Members of a call agree on keys through a Messaging Layer Security group (MLS, RFC 9420), with the voice gateway delivering the messages. Each sender encrypts its frames with its own key, so the media server forwards packets it cannot read.

Three things change in the client. In the browser, encryption runs in WebRTC's encoded transform API, a hook that sees each encoded frame after the encoder and before the network. Each join or leave starts a new key epoch, which the voice service must apply without a gap in audio. And the UI gains a Voice Privacy Code, a number derived from the current keys that members can compare out of band to check that nobody is impersonated.

The persistent voice bar

The call must survive the user clicking a text channel in another server. So the voice connection cannot live inside a route component, which would unmount on navigation. It lives in a voice service created once at app start, outside the React tree, with a small store the UI reads: the channel, the state, the ping, and the mute flags.

The voice bar at the bottom of the channel list is a view of that store, shown on every route, with disconnect, mute, deafen, and the call's server and channel name as a link back. When the user leaves the voice channel's text view while watching a stream, the video moves into a small floating picture-in-picture window.

Rich messages: markdown, custom emoji, embeds, and reactions

A Discord message is a short string that can expand into a lot: formatting, mentions that need names and colors from stores, custom emoji images, a spoiler that hides text, a highlighted code block, link embeds that arrive a second later, and a row of reactions. A busy channel shows 50 of these on screen and scrolls through thousands. Rendering them correctly and cheaply is most of the message list's cost.

What is in the string

The text uses Discord's markdown: **bold**, *italic*, __underline__, ~~strike~~, ||spoiler||, inline code in single backticks, fenced code blocks with a language name (three backticks then js), > quotes, # headings, -# small subtext, and masked links [text](url). Rich references are tokens with ids, not names, so renames never break old messages.

• Masked links can lie: [docs](https://evil.example). Show the real host on hover and confirm before leaving for an untrusted domain. Allow only https: and http: URLs; never javascript:.
• Spoilers render as a covered button labelled "Spoiler". Click or Enter reveals it for that message only. Images marked as spoilers are blurred the same way. A screen reader hears "Spoiler, button" rather than the hidden text.
• Code blocks need syntax highlighting, which is heavy. Load the highlighter on first use, only for the languages seen, and highlight blocks over a few KB off the main thread in a worker, showing plain monospace text until it is ready.

Custom emoji and stickers

Each server has its own emoji and stickers: 50 static and 50 animated emoji slots by default, with more as the server unlocks boost levels. Emoji images come from a CDN by id, in the size the UI needs: about 22 px inline and 48 px when a message is only emoji ("jumbo"), so one 48 px file serves both. Stickers are bigger images, and some are Lottie animations (vector animation described as JSON), drawn by a player loaded only when the first Lottie sticker appears.

Nitro gating is a UI decision driven by data. Without Nitro, a user can use a server's custom emoji only in that server, and cannot use animated emoji. The emoji picker still lists other servers' emoji, grayed out with a lock and an upsell, because seeing them is part of the product.

The picker needs every emoji of every server the user is in: a few thousand entries, loaded from READY data and searched in memory. A channel can also deny USE_EXTERNAL_EMOJIS, which locks emoji from other servers for everyone in it.

Animated emoji are the main memory and CPU cost in a long session. A channel full of animated emoji can have 200 GIFs decoding at once. So: animate only emoji in the viewport (an IntersectionObserver swaps the animated source for a static one when off screen), offer a setting to animate only on hover, and respect prefers-reduced-motion by showing static frames.

Embeds arrive later

When a message has a link, the server fetches the page's preview data (title, description, image, its size) after the message is sent. The client first gets the message without embeds, and up to a few seconds later a MESSAGE_UPDATE adds them. A message can carry up to 10 embeds. Three rules keep this from wrecking the list:

1. Images in embeds and attachments come with width and height, so the client reserves the box before the image loads. No layout shift when the bytes arrive.
2. When an embed is added to a message above the viewport, keep the visible message where it is (scroll anchoring), or the text the user reads jumps down.
3. Images go through a media proxy that resizes to the box size the client asks for (Discord has written about resizing 150 million images a day this way), so a 4,000 px photo shown at 400 px costs a 400 px download, in WebP when the client asks for it.

Reactions and super reactions

A message's reactions come as an aggregated list: for each emoji, a total count, whether the current user reacted (me), and, since super reactions, a split of normal and burst counts plus the colors for the burst animation. The client never loads who reacted until someone opens the reactions view, which pages through users.

Toggling a reaction is an optimistic update (see the Slack guide): flip me, change the count by one, send the request, and roll back with a short message if it fails. The server then broadcasts MESSAGE_REACTION_ADD to the channel's subscribers, including the user's own other devices; the device that made the change recognizes its own echo by the event's user_id and does not count it twice. In a 20,000-viewer channel a popular message gets many reaction events a second, so reaction updates are batched into one render per frame, like presence.

Super reactions (a Nitro feature) play a short burst animation. Play it once when the user adds one, and once when it first scrolls into view for others, never in a loop, and never with reduced motion on. Without these limits, a message with 50 super reactions would replay 50 animations every time the list re-renders.

Unread and mentions across 60 servers

The server rail is the user's map of where something is waiting. Each server icon can show a white pill on its left edge (something unread) and a red badge with a number (mentions of the user). The app icon's badge sums the mentions.

Getting this right across 60 servers and thousands of channels, most of them passive, with per-server and per-channel settings, is a data problem more than a UI one. The Slack guide covers how a read marker moves when the user reads; this chapter covers what is different here: many servers, mute settings at several levels, and mass mentions.

Unread is a comparison of two ids

Discord ids are snowflakes: 64-bit numbers whose top bits are a timestamp (milliseconds since the first second of 2015). So a later message has a larger id. For each channel the client keeps a read state: the id of the last message the user acknowledged and a mention count.

Each channel object carries its last_message_id, and a channel is unread when that id is greater than the acknowledged one. No message bodies are needed: a passive server's compact update only has to carry each channel's newest message id, plus any new mention of the user, and the pill updates.

export function serverBadge(g: GuildState, s: Settings) {
  let unread = false;
  let mentions = 0;
  for (const ch of g.textChannels) {
    if (!canView(g, ch)) continue;
    const rs = g.readStates[ch.id];
    mentions += rs?.mentionCount ?? 0;
    const muted = s.isMuted(g.id, ch.id, ch.parentId);
    const newer = BigInt(ch.lastMessageId ?? 0) > BigInt(rs?.lastAckedId ?? 0);
    if (newer && !muted) unread = true;
  }
  return { unread: unread && !s.isMuted(g.id), mentions };
}

Note what the code does with mute: a muted channel or server shows no pill, but mentions still count. Muting means "do not tell me about chatter", not "hide it when someone needs me". Mention counts come from the server, which knows who was mentioned; the client only adds them up.

Settings at four levels

Each server has a default chosen by its admins ("All messages" or "Only @mentions"; big public servers almost always pick the second). The user can override it for the server, for a category of channels, and for a single channel. For each, the choices are all messages, only mentions, or nothing, plus mute for a time (15 minutes up to "until I turn it back on"). At the server level there are extra switches: suppress @everyone and @here, and suppress role mentions.

The client resolves these with a lookup from the most specific level down, cached per channel like permissions, and recomputed when a setting changes. Settings are user data synced through the server: change them on the phone and the desktop hears a settings update event on the gateway.

@everyone, @here, and role mentions

• @everyone notifies every member who can see the channel; @here only those online. Both need the MENTION_EVERYONE permission, so the composer's autocomplete offers them only to users who have it, and in this design warns how many people they will reach ("This will notify 48,210 people").
• A role mention (@Moderators) notifies everyone with the role. Members can mention a role only if the role is marked mentionable or they have MENTION_EVERYONE.
• The message arrives with mention_everyone and mention_roles set by the server. The client decides if it counts for this user: does the user have that role, and has the user suppressed @everyone or role mentions in this server?
• The Maxjourney post notes that an @everyone in a huge server is one of the most expensive server operations, since it must find every member who can see the message. Another reason the client should make it hard to do by accident.

Acknowledging and syncing across devices

When the user is looking at a channel, scrolled to the bottom, with the window focused, the client acknowledges the newest message: it sends the channel id and message id to the server, debounced so a fast channel sends at most one ack every few seconds. The server stores it and sends a read state update to the user's other sessions, so the phone clears its badge within a second or two. Keyboard shortcuts let the user mark read on purpose: Escape for the channel, Shift+Escape for the whole server.

Notifications follow the same data. A desktop notification fires when a message counts as a notification under the resolved settings and the user is not already looking at that channel. To avoid buzzing every device at once, Discord's settings include a timeout: mobile push is held back while the desktop app is active, and sent only after the desktop has been idle for a few minutes. The Notifications center guide covers the notification UI itself.

Moderation in the UI: slowmode, timeouts, AutoMod, audit log

Large communities live or die by moderation, and most moderation reaches the user as UI: a composer that counts down, a message that was blocked, a menu that lets a moderator time someone out. Each is a small state machine on top of the send flow. The send flow itself (optimistic message, outbox, retry, dedupe by a client nonce) is the same as in the Slack guide; here we add the ways the server can say no.

Slowmode

A channel's rate_limit_per_user sets slowmode: each member may send one message every N seconds, from 0 (off) up to 21,600 (6 hours). Since February 2026 only members with the BYPASS_SLOWMODE permission (bit 52, split out of MANAGE_MESSAGES and MANAGE_CHANNELS) are exempt, so the client checks permissions first.

Timeouts

A moderator with MODERATE_MEMBERS can time a member out for up to 28 days. The member object gets communication_disabled_until, a timestamp. While it is in the future, the permission function keeps only view and read history (the implicit rule from the Permissions chapter), so the UI updates by itself: the composer becomes a note with the end time, reaction buttons vanish, and voice channels show as locked.

The client sets one timer for the end time to recompute permissions, so the composer comes back the moment the timeout ends without waiting for an event.

AutoMod: the message that was blocked

AutoMod runs rules on the server before a message is stored: keyword lists, spam detection, too many mentions. A rule can block the message, alert moderators in a log channel, or time the author out. When it blocks, the API rejects the send with a specific error code (Discord documents code 200000, "Message was blocked by automatic moderation"). The client must handle this as its own case, not as a generic failure:

• Remove the optimistic message from the list. Do not offer "Retry": sending the same text again will be blocked again.
• Show a notice only the author sees, in the message list where the message would have been, with the custom explanation the admins configured (up to 150 characters), if any.
• Put the text back in the composer so the author can fix it, rather than losing what they typed.
• If the rule also timed the author out, the member update arrives on the gateway and the composer locks through the permission function.

The audit log

Moderators with VIEW_AUDIT_LOG see who did what: bans, role changes, deleted messages, channel edits. Discord keeps entries for 45 days. The API pages by entry id (before and limit up to 100) and filters by user and action type.

Each response includes the users, roles, and channels its entries reference, because many of them may have been deleted or may be members the client never loaded in this huge server. The client normalizes those into the stores (see the Normalization lesson) so each row can show names. Filters live in the URL, so a moderator can share a link to "all bans by Alex this week".

Client architecture, data model, and API

With the hard parts decided, the architecture follows. The guiding rule: connections and long-lived things live in services outside React; data lives in stores; components only read stores and call actions. That way navigation never tears down the gateway or the call, and a gateway event updates every view that cares with one dispatch.

Data model: complete where small, partial where big

The data model splits by size and speed. Small structural data is complete for every server. Big data is partial and keyed by what is on screen. Everything is normalized: one record per id, references by id (see the Normalization lesson).

type Guild = { id: string; name: string; iconHash?: string; ownerId: string;
  roleIds: string[]; channelIds: string[]; defaultNotifications: 0 | 1 };
type Role = { id: string; name: string; position: number; color: number;
  hoist: boolean; mentionable: boolean; permissions: bigint };
type Overwrite = { id: string; type: "role" | "member"; allow: bigint; deny: bigint };
type Channel = { id: string; guildId: string; type: "text" | "voice" | "category";
  parentId?: string; position: number; lastMessageId?: string;
  rateLimitPerUser: number; overwrites: Record<string, Overwrite> };
type Member = { userId: string; guildId: string; nick?: string; roleIds: string[];
  timedOutUntil?: number };
type MemberList = { listId: string; groups: { id: string; count: number }[];
  items: (Item | undefined)[]; subscribed: [number, number][] };
type Message = { id: string; channelId: string; authorId: string; content: string;
  editedAt?: string; embeds: Embed[]; attachments: Attachment[];
  reactions: { emoji: EmojiRef; count: number; burst: number; me: boolean }[];
  nonce?: string; status: "sent" | "pending" | "failed" };
type ReadState = { channelId: string; lastAckedId: string; mentionCount: number };
type VoiceState = { userId: string; channelId: string | null; selfMute: boolean;
  selfDeaf: boolean; mute: boolean; deaf: boolean; selfStream: boolean };

Gateway messages

{ "op": 10, "d": { "heartbeat_interval": 41250 } }
{ "op": 2,  "d": { "token": "...", "properties": { "os": "Mac OS X" } } }
{ "op": 0,  "s": 1, "t": "READY", "d": { "session_id": "...",
  "resume_gateway_url": "wss://...", "guilds": [], "read_state": [] } }
{ "op": 14, "d": { "guild_id": "8135", "typing": true,
  "channels": { "9244": [[0, 99], [300, 399]] } } }
{ "op": 0,  "s": 812, "t": "GUILD_MEMBER_LIST_UPDATE", "d": { "id": "everyone",
  "guild_id": "8135", "groups": [{ "id": "online", "count": 24301 }],
  "ops": [{ "op": "DELETE", "index": 5 }, { "op": "INSERT", "index": 2, "item": {} }] } }
{ "op": 4,  "d": { "guild_id": "8135", "channel_id": "9301",
  "self_mute": false, "self_deaf": false } }
{ "op": 6,  "d": { "token": "...", "session_id": "...", "seq": 812 } }

Opcodes 10, 2, 0, 4, and 6, and the session_id and resume_gateway_url fields of READY, are in Discord's public gateway docs. The read_state field, opcode 14, and GUILD_MEMBER_LIST_UPDATE come from community documentation of the official client. In an interview, present those as "a subscribe message and a list update event" and name them as Discord's only if asked.

REST calls

Errors carry a numeric code and a message, and the client maps codes to UI, not messages, because messages are for developers and may change. A small table in the client turns each known code into a state: countdown, locked composer, "blocked" notice, or a generic retry.

Data flow, end to end

Follow one message from someone else. The server sends MESSAGE_CREATE on the gateway. The gateway client decompresses the frame, parses it, and dispatches an action.

The message store appends it to the open channel's window; the channel store moves last_message_id; the read state store adds a mention if needed; the member store saves the author's member data that came with it. The derived badge store recomputes the server's pill. React re-renders only the message list and maybe one server icon, once for this frame. In a passive server only the compact update arrives, and only the channel and read state stores change.

Memory in a process that runs for days

The desktop app is Electron: a Chromium renderer running the same web code. People leave it open for days, in voice, with dozens of servers. Memory that grows by 1 MB an hour is 168 MB a week.

Discord has been open about this: in late 2025 it tested having its Windows app restart itself when memory passed 4 GB, but only after the app had run for an hour and the user had been idle for 30 minutes, was not in a call, and at most once a day, restoring the open channel and drafts. A restart as a safety net only works if the app can rebuild its state fast, which is one more reason for the local cache.

• Bounded message windows: keep full message data for about the 10 most recently visited channels, up to a few hundred messages each, and evict the rest by least recent use. Reopening an evicted channel paints from IndexedDB, then fetches.
• Member data by reference: member and user records are kept while something on screen or in a cached window refers to them, and swept when member list ranges are dropped.
• Media: off-screen animated images switch to static frames; image elements are removed by the virtualized list, not hidden; object URLs are revoked.
• Listeners and timers: every subscription has an unsubscribe tied to component unmount or service teardown. Leaks here are the classic slow growth; see the Memory leaks lesson for heap snapshot diffing.
• Measure in production: report memory samples (where the platform exposes them) with session age, so a leak shows up as a slope in the dashboards before users notice it.

IndexedDB: a cache, not a source of truth

On start, the client reads a snapshot from IndexedDB (see the IndexedDB lesson): servers, channels, roles, emoji, read states, and the last 50 messages of recent channels. It paints the rail, the channel list, and the last channel from that, then connects. When READY arrives it replaces the snapshot's structural data wholesale, and the open channel fetches messages newer than its newest cached id.

The cache is written in the background, throttled to once every few seconds, in one transaction per write. It is wiped on logout, and its schema has a version number: on a mismatch the client discards it instead of migrating, since everything in it can be fetched again.

Performance, accessibility, and keyboard

Where the milliseconds go

• Split code by feature, not just by route. Voice and video (WebRTC setup, audio processing), server settings, the audit log, the Lottie player, and the syntax highlighter are each loaded the first time they are needed. A user who never joins voice never downloads voice code.
• Variable row heights. Messages range from one line to an image grid with embeds. The virtualized list measures rows after render with a ResizeObserver and keeps estimated heights for rows it has not measured, anchoring on the newest message (see the Virtualized list guide).
• Parsing off the main thread, carefully. Moving gateway decompression and JSON parsing to a worker frees the main thread, but every event then crosses postMessage, which copies data. It pays off for big payloads like READY; for a stream of small events, batching them per frame matters more than where they are parsed. Measure before moving.
• Images are requested at the displayed size from the media proxy, with loading="lazy" and decoding="async", and width and height set so nothing shifts.

Keyboard: four regions and a quick switcher

Discord's screen has four regions: the server rail, the channel list, the messages, and the member list. Discord wrote about making its whole desktop app usable by keyboard and found that the hard part was showing where focus is: CSS outlines got clipped by scroll containers and did not match rounded shapes. Its answer was to draw focus rings in a separate layer per scrollable area (components it calls FocusRing and FocusRingScope), detached from the focused element.

• Between regions: one key moves focus to the next region (this design uses F6, the common desktop convention), and each region remembers its last focused item.
• Inside a region: one tab stop per list, then arrow keys move between items (roving tabindex, see the Keyboard navigation lesson). In the server rail, Up and Down move between servers and Enter opens one.
• Shortcuts: Discord documents hotkeys to move to the previous or next channel (Alt+Up, Alt+Down), the next unread channel (Alt+Shift+Down), and the previous or next server (Ctrl+Alt+Up, Ctrl+Alt+Down). They read from the same stores as the UI, so "next unread" respects mute settings.
• Quick switcher: Ctrl+K (Cmd+K on Mac) opens a search over servers, channels, DMs, and people, with prefixes to narrow it, such as # for text channels and @ for people. It is a command palette over local stores, ranked by recent use; the Command palette guide covers the ranking and the combobox pattern.

Screen readers and motion

• Each region is a labelled landmark ("Servers", "Channels", "Messages in #general", "Members"). The member list's group headers are real headings with counts, so a screen reader user can jump between "Moderators, 12" and "Online, 24,301".
• New messages in the open channel are announced through a polite live region, throttled: in a channel with 10 messages a second, announce "12 new messages" every few seconds, not each one. Messages in other channels are never announced; their unread state is in the channel's accessible name ("general, 3 mentions").
• Voice events (someone joined, someone left, you were muted by a moderator) get both a short sound and a text announcement. The speaking ring is not announced: it would be noise.
• Discord's accessibility settings include reduced motion (which can follow the operating system's prefers-reduced-motion), a saturation slider, a switch for playing animated emoji, and a choice of when stickers animate: always, on interaction, or never. Every animation in this design reads one motion setting.
• Role colors are chosen by server admins and can have poor contrast on the theme's background. The renderer can adjust a role color's lightness until it meets a 4.5 to 1 contrast ratio, keeping its hue.

Security in a desktop shell

Content from strangers is rendered in a process that, in Electron, could reach the operating system. So the renderer runs with contextIsolation on, nodeIntegration off, and the sandbox enabled, and talks to native features only through a small, typed preload bridge. Researchers reported a remote code execution chain in the Discord desktop app in 2020 that relied on context isolation being off, and Discord fixed it; it is the standard story for why these flags matter.

On top of that: the parse-tree renderer never builds HTML from message text, embeds are drawn from structured fields, links open in the system browser, and a strict Content Security Policy blocks inline scripts.

Running it in the interview

"Design Discord" is wide enough to fill two hours. In 45 minutes the risk is spending 30 of them on chat basics the interviewer has heard a hundred times. Get the basics on the board quickly, then spend the time on what is specific: scale per server, the member list, permissions, and voice.

When the interviewer pushes on one area, go deep there and drop something else; say which part you are dropping and why. A clear "I will skip rich content and spend the time on voice failures" reads as judgment, while rushing through everything reads as a checklist.

Follow-up questions to expect