Architecture — System

• Status: Current
• Last updated: 2026-11-01
• Related ADRs: ADR-0013, ADR-0014, ADR-0015, ADR-0017, ADR-0011, ADR-0020, ADR-0021

Snapshot of the system as it stands today. Edit in place; never record what changed.

ContextCopy Anchor Link

A Next.js 16 App Router site built on Fumadocs. It renders the MDX pages in content/ as a documentation site, and serves every page again as Markdown, as an Open Graph image, and as a search record. Search runs on Algolia. There is no database, no sign-in and no server-side state. Cache Components is on (cacheComponents and partialPrefetching in next.config.mjs, ADR-0016), and every page and route handler is prerendered at build time: none reads request data yet. The sign-in ADR adds the first request-time part, the home page's private group, inside a <Suspense> boundary, so the rest of / stays in the static shell.

Every top-level folder in content/ is a catalogue entry, published at /<slug>: a package or project whose root meta.json carries a catalog field (ADR-0013, ADR-0015). Inside it, use/ and maintain/ are the two tracks. A versioned use/ holds one folder per version line, each with version and channel in its meta.json: use/dev/ for unreleased work in progress, and released lines whose URL segment comes from their name (v1.0, 2024 LTS → 2024-lts). Maintain is not versioned. The only entry today is this site itself, project docs, whose Maintain track (content/docs/maintain/) holds its decisions and design documents; no package is documented yet, so the home page shows its empty states.

RoutesCopy Anchor Link

Pages share the root with the site's own routes. The proxy leaves those routes and everything below them alone (isSiteRoute), handles line redirects and Markdown on paths whose first segment is a catalogued slug (isEntryPath), and answers any remaining path that is not a page with a 404 (isKnownPath). The build fails if its list of pages differs from the site's, and refuses a slug that would collide with a route (api, og, static, …). Contracts for the machine-readable routes are in ../api/.

ComponentsCopy Anchor Link

How navigation is scopedCopy Anchor Link

Fumadocs shows the sidebar of the deepest root folder on the current path, and groups root folders of the same type into one switcher whose options keep the reader on the same page (fumadocs-ui/contexts/tree). The catalogue plugin marks folders so that:

• on a package's Use page the sidebar holds only that line's pages, with a version menu (v4.0 / 4.0.1 · Latest, dev / 5.0.0-dev · In development, older lines) that keeps the reader on the same page when it exists, matched by file path, not URL;
• on a Maintain page the sidebar holds only the Maintain pages;
• on an overview the sidebar is its default track's: the plugin's root hook takes the overview off the entry folder and puts an Overview item for it first in each Use line (or an unversioned Use) and in Maintain, with Use first, so the path search finds the overview in the latest Use line, or in Maintain when there is no Use (ADR-0025). The catalogue's links (src/lib/catalog.ts) and the version menu's (lineLink() in src/lib/overview-sidebar.ts) skip the item, and llms.txt reads the tree without it;
• TrackSwitch switches between the two tracks, and on an overview marks the default track as current;
• the site-wide switcher of root folders is not shown: the layout passes only line roots as tabs. Entries are reached from the home page and the header.

DiagramCopy Anchor Link

Key decisions in forceCopy Anchor Link

• ADR-0013: the catalogue shape, tracks, version lines, URLs, scoped navigation, search fields and build checks.
• ADR-0014: the home page.
• ADR-0015: root addresses, dev and named lines, the site as project docs, one look and one header, light/dark.

ConstraintsCopy Anchor Link

• Mermaid is not rendered. Diagrams in these pages show as highlighted code.
• Every page is public on every surface. Nothing filters a page out of the site, the Markdown routes, llms.txt / llms-full.txt, static.json, the share images or the search index; noindex keeps a page out of search results only. The catalogue schema rejects a private entry, so the build fails instead of publishing one (AGENTS.md §6.1).
• lastmod needs a full clone. It comes from git log, so a shallow clone would date every page to the last commit, and an uncommitted page has none. The hosting ADR must clone in full.
• The build needs the network, for next/font and the share images' fonts.
• Demos are not published. A use/<line>/demo.mdx page would be linked from the catalogue, but ADR-0011's embed takes only /diagrams/… files, so how a demo runs needs its own ADR; the home page has no demo section.
• defineCollections({ type: 'meta' }) is broken in fumadocs-mdx 15.4.10 (its generated call passes meta where the runtime reads entries), so catalog-routes.ts uses a defineDocs whose page pattern matches nothing.
• bun run build publishes. Its second step overwrites the live search index.
• Hosting is not decided. .gitignore lists .vercel, from the scaffold; no host is configured in the repository.