Architecture
How the site fits together, from a piece's folder to a rendered page, the layers around it, and the rules that keep each part described once.
drksci is a Next.js 16 site on Fumadocs. Articles, called pieces, are MDX files in git. Documentation is MDX in the same repository. Nothing is edited in a database: publishing a piece is a pull request, and an agent that writes one works through an MCP endpoint and a plugin that the site serves about itself.
From folder to page
A piece is a folder, content/pieces/<slug>/, holding its index.mdx and
everything it owns: data, images, bespoke components and styles. The audit
fails a piece that imports from another piece's folder, and shared code that
imports from any piece.
The loader in src/lib/pieces.ts reads each folder with the schema in
src/lib/piece-schema.ts. The route src/app/(pieces)/[slug]/page.tsx serves
it at /<slug>, with static params and dynamicParams off, so a path that no
folder names is a 404. The route hands the piece to PiecePage, which asks
src/templates/registry.ts for the template the piece's kind selects, and
renders the MDX with the shared blocks registered in src/blocks/mdx.tsx.
Blocks take their colour, type and space from tokens, so the active theme
restyles every page without touching a piece.
A piece may contain parts, for an anthology. content/pieces/<slug>/<part>/index.mdx
is a part of <slug>, served at /<slug>/<part> by the route in
src/app/(pieces)/[slug]/[part]. The folder implies the parent, parts do not
nest further, and a part keeps its assets in the parent's folder. The parent is
an ordinary piece: it lists its parts as cards in the order they were published,
and each part links to the parts either side. Parts are in the route inventory,
so the sitemap, the feeds, llms.txt and the page metadata cover them, and a
part's breadcrumbs run through its parent. A part's folder name may not be the
name of a route under its parent.
Layers
| Layer | What it holds | Where |
|---|---|---|
| Tokens and themes | Custom properties in three tiers, one file per theme. | src/tokens |
| Layout kit and block contract | Section, its layouts, and blocks that fit any slot. | src/blocks/kit |
| Plot kit and surfaces | Pens, weights, dashes and sizes for SVG figures; paper frames. | src/blocks/plot, src/blocks/surface |
| Templates | The page around a body: width, contents list, masthead. One registry. | src/templates |
| Writing guide and lint | Length, voice and examples per element; the lint checks them. | src/writing, scripts/lint-prose.ts |
| Catalog | The spec each unit carries, collected into one list. | src/catalog |
| MCP endpoint and plugin | Read-only tools at /mcp; the Claude Code plugin and its skills. | src/mcp, src/app/mcp, plugin |
| Audit | Housekeeping rules, structure and naming conventions, and budgets. | src/audit |
| Discovery | Route inventory, metadata, sitemap, feeds, llms.txt, social images. | src/seo |
| Résumé and sign-in | One validated data file, rendered as a page and a letter; sign-in. | src/resume, content/resume, src/auth |
The reference pages beside this one describe each layer in full. They are generated from the code, so this page stays at the level of what exists and how the parts meet.
Rules that hold it together
One source of truth
Tokens are defined once, in a theme file. The block registry, the writing guide, the résumé data and the audit budgets each have one file. A page that restates one of them is generated from it, and the audit fails when the generated copy is out of date.
Everything describes itself
A shared unit carries a spec beside its code:
what it is, when to use it, when not to, its inputs and an example. The catalog
collects them, catalog_list and catalog_get serve them, and the reference
pages are rendered from them. The audit fails a shared block, layout or
template without a complete spec.
Harmonise
A piece is a unique work and keeps its own figures and data.
Colour, type, space and chart styling come from the shared system. A piece that
differs says so under bespoke in its frontmatter, with a reason. The audit
reports raw literals, near-duplicate components, unused tokens and blocks,
orphaned assets and styles a piece overrides, and fails when a budget in
src/audit/config.ts is exceeded. A component that a second piece needs moves
to the shared registry in the same pull request.
Flat links
A piece is at /<slug> whatever its kind. The kind only
decides which index lists it, and a slug may not take the name of a route.
Where an agent starts
The MCP tools read and validate. They never write: the endpoint has no
authentication and no repository access, so a change is a pull request from a
checkout. catalog_list and catalog_get show what exists, validate_draft
checks an MDX file the way CI will, and audit reports drift. propose_consolidation ranks what the audit found into a plan that changes nothing. The skills in
plugin/skills say in what order to call them.
bun run check runs the type check, lint, tests, prose lint, audit and link
check. Only error-severity audit findings fail it. A hand-written docs page
lists the files it describes under covers; the audit warns when one of them
changes after the page.