Skip to Content
drksci
System

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.

Folder to pageRead from the same sourcesPiece foldercontent/pieces/<slug>Loadersrc/lib/pieces.tsRoutesrc/app/(pieces)Templatesrc/templatesBlockssrc/blocksTokens and themessrc/tokensCatalogsrc/catalogMCP and pluginsrc/mcp, pluginAuditsrc/auditDiscoverysrc/seo
Figure 1A piece passes through the loader, the route, a template and the blocks, which read the tokens. The four units on the right read the same sources.

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

LayerWhat it holdsWhere
Tokens and themesCustom properties in three tiers, one file per theme.src/tokens
Layout kit and block contractSection, its layouts, and blocks that fit any slot.src/blocks/kit
Plot kit and surfacesPens, weights, dashes and sizes for SVG figures; paper frames.src/blocks/plot, src/blocks/surface
TemplatesThe page around a body: width, contents list, masthead. One registry.src/templates
Writing guide and lintLength, voice and examples per element; the lint checks them.src/writing, scripts/lint-prose.ts
CatalogThe spec each unit carries, collected into one list.src/catalog
MCP endpoint and pluginRead-only tools at /mcp; the Claude Code plugin and its skills.src/mcp, src/app/mcp, plugin
AuditHousekeeping rules, structure and naming conventions, and budgets.src/audit
DiscoveryRoute inventory, metadata, sitemap, feeds, llms.txt, social images.src/seo
Résumé and sign-inOne 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.

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.

On this page