docs: add the reference topology diagram to the architecture page

[evantahler]

What

Adds a Reference topology section to Platform architecture with our topology diagram, so readers see the whole deployment before the page walks through each service one at a time.

Source diagram: Arcade Reference Topology Diagram — linked in a comment above the figure in the MDX, so the next person knows where to edit it.

Screenshots

Dark mode

Light mode

Light and dark mode

The Whimsical export has a baked-in white background, so inverting it in dark mode would wreck the red/blue/teal node fills. The figure keeps a permanent white canvas and everything around it is theme-aware:

• Rounded card (rounded-xl, p-4 md:p-6, bg-white) frames the white panel as deliberate rather than a raw image floating on a dark page
• Border and ring flip per theme — border-neutral-300 / ring-black/5 to dark:border-neutral-700 / dark:ring-white/10
• Caption uses text-neutral-600 / dark:text-neutral-400

Legibility

The diagram is far too dense to read at the ~930px prose column, so:

• The whole figure links to the full-size PNG, with cursor-zoom-in and a caption that says to open it
• It breaks out of the article's horizontal padding on md and up (md:-mx-8 lg:-mx-12) to reclaim ~96px
• Long descriptive alt text covers the ingress path, both Kubernetes clusters, egress, and the data tier

Verification

Check	Result
pnpm lint	325 files, no issues
vale	0 errors, 0 warnings
pnpm test	864 passed (69 files)
pnpm build	Clean

Rendering confirmed with the screenshots above, and checked at 390 / 820 / 1600px — the figure introduces no horizontal overflow.

Note

The screenshots are hosted on the throwaway assets/pr-1194-screenshots branch so they stay out of this PR's diff and never reach main. Delete that branch whenever this merges.

~ 🎹 Evanescence, Evan's Agent

---

Note

Low Risk
Documentation-only MDX and styling changes with no runtime or security impact.

Overview
Adds a Reference topology section at the top of the Platform architecture page so readers see the full deployment (ingress, clusters, egress, data tier) before the per-service breakdown.

The section embeds the reference topology PNG via next/image, wrapped in a clickable figure that opens the full-size image in a new tab, with theme-aware framing (white canvas, dark-mode dimming) and a Whimsical edit link in an MDX comment for maintainers.

^{Reviewed by Cursor Bugbot for commit ba6b7de. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Sep 16, 2026 9:06pm UTC

[teallarson]

Can we adjust the image so it does not show as wider than the rest of the content on the page (it's wider than any text or tables currently)

Once that's done, lgtm so long as we aren't worried about blinding the vampires in dark mode.

[evantahler]

Both fixed in ba6b7de.

Width — the figure had negative margins (md:-mx-8 lg:-mx-12) pulling it past the content column. Gone. Measured in a browser at a 1440px viewport:

element	x	width
figure	304	832
services table	304	832
body paragraph	304	832

Exact match now, same in both themes.

The vampires — a real concern, it was a full-width white rectangle on a black page. Inverting would have wrecked a color-coded diagram, so instead the image is dimmed with dark:brightness-[0.83] and the panel behind it moves to dark:bg-neutral-300 — the same #d4d4d4, so the padding and the image match seamlessly with no visible seam. Brightness scales every channel equally, so the diagram’\s internal contrast is untouched; only its luminance against the page drops. Light mode is byte-identical to before.

Preview once it redeploys: https://docs-git-docs-reference-topology-diagram-arcade-ai.vercel.app/en/operate/deploy/architecture

~ 🎹 Evanescence, Evan's Agent