How this site works, part 1: from constants to pages
The interface copy lives in one folder, every page reads content through one door, and a record that fails its schema stops the build instead of reaching the page.
Contents · 6 sections
A guided tour of andreasheige.cc, in three parts. Part 1 follows the content: where the text and the ideas live, the one data API every page reads through, the atomic component layers and the static build that turns it all into HTML.
The first line on the home page is a job description:
I build AI-native systems end to end: the information agents work from, the architecture they run in, and the harness that lets them work on their own.
This series takes the site apart in that order. Part 1 is the information: where everything the site says is kept, and how a page gets hold of it. Part 2 is the architecture: the small scripts that run in the browser, and the one route of server code, where a model answers questions from the site’s own text. Part 3 is the harness: the tests, the headers and the deploy that decide what reaches production.
How agents built it is told in the companion post. This one is about how it works. The site’s repository is private, so the code is quoted here; the full reference is the repo’s docs/deep_dive.md.
Rules that a test can fail
The site has a short list of principles, and the first thing to know about them is that nearly every one has a test behind it (the deep dive, §2). Three carry this part:
- No loose strings. User-facing text, URLs, labels and formats live in
src/constants/. Components get text through props. - One way in for data. Pages read content only through
src/data/. - Tokens, not values. No hex colour,
rgb()or raw font size outside the theme, motion and layout constants.
Each is a file in tests/guards/ that reads every file under src/ and parses it: TypeScript with the TypeScript parser, .astro markup with a small tokenizer, CSS with a comment-aware parser. A hard-coded user-facing string in a component, an import that crosses a boundary or a stray #c33 fails the test with the file and the line. Every guard also runs itself on planted violations held in memory, so a guard that has quietly stopped finding anything fails too. The import rule, as its file states it (tests/guards/import-boundaries.test.ts):
// Guard: import boundaries. Absorbs the fourth check of the deleted
// tests/site/source.test.ts (pages import through the @/ alias, never by a
// relative path). Rules: every file under src/ outside pages, lib, data,
// constants, schema, content and styles (components, islands, any new UI
// folder) never imports src/constants or src/data, except `import type` from
// src/data/types and the allowlist in tests/guards/allowlist.ts; such files
// import only literal specifiers; src/lib never re-exports constants or data;
// only data/local/posts.ts and content.config.ts import astro:content; nothing
// outside src/data imports src/data/local; pages reach data only via @/data
// and never import projects, talks, ideas, figures or content directly.
The site’s words, in one folder
src/constants/ holds the interface copy, routes, nav items, projects, talks, ideas, figures, themes and motion timings. Post bodies are the exception: long prose lives as markdown in src/content/posts/. The copy is split by page (copy/home.ts, copy/post.ts, copy/ask.ts …), and text with a number in it is a small typed function, such as post.tokensRead(read, total), never string concatenation inside a component. The intro line quoted above is home.title in src/constants/copy/home.ts.
The thread itself is here too. The red line on the home page, the graph that connects posts, projects and talks, runs through seven ideas (src/constants/ideas.ts):
export const ideas = [
{ id: "harness", label: "harness engineering" },
{ id: "memory", label: "information engineering" },
{ id: "ai-native", label: "AI-native architecture" },
{ id: "review", label: "review" },
{ id: "guardrails", label: "guardrails" },
{ id: "self-rewriting", label: "self-rewriting" },
{ id: "small-models", label: "small models" },
] as const satisfies readonly DeepReadonly<Idea>[];
The ids are a closed enum in src/schema/idea.ts, so a post that names an idea that does not exist fails the build. Seven is a hard limit: the graph layout has seven slots (MAX_IDEAS in src/lib/graph-layout.ts), and an eighth idea makes the layout throw. The first three ideas are the three parts of the job description.
One door for data
Pages never import constants or Astro’s content collection for content. They call data, and src/data/index.ts is the one place that says where data comes from:
// The one place that picks the active source (docs/deep_dive.md section 4).
export const data: DataSource = localSource;
A DataSource has a handful of async methods: getPosts(), getPost(slug), getProjects(), getTalks(), getGraph(), getFigure(id) and their single-item siblings. An unknown slug returns undefined, never an error. The local source reads posts from src/content/posts/*.md (besides the collection config, only src/data/local/posts.ts imports astro:content) and projects, talks, ideas and figures from the constants. Swapping it for a database is a new folder with its own DataSource and a one-line change to that export (the deep dive, §4); nothing is fetched at runtime and no component changes.
Every record is parsed by a zod schema from src/schema/ before it leaves the adapter. The schemas are strict objects, so a typo in a key is an unknown key, and unknown keys fail. When a record fails, the error names it (src/data/local/parse.ts):
const result = schema.safeParse(value);
if (result.success) return result.data;
const issues = result.error.issues
.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`)
.join("; ");
throw new Error(`Invalid ${kind} "${id}": ${issues}`);
The build stops on Invalid post "<slug>": ideas.0: …, which is something to grep for. The content types are z.infer of a schema, so there is no second, hand-written description of a post to drift away from the first.
The graph is built from the same records. Nodes are posts, projects, talks and ideas; each item gets one edge per idea it names. Posts link to projects and talks only through ideas, so “writing about it” on a project page is simply every post that shares one of its ideas.
Atoms to pages
The components come in five layers: atoms, molecules, organisms, templates, pages. The lower a layer, the less it knows.
Atoms (Text, Heading, Link, Rule, Dot, TextButton, Input, Image, Icon) know nothing about posts. Text arrives in the slot or as a prop, never by importing a constant. Every enum prop is checked when the page renders, and a bad value throws an error naming the atom and the prop, so the build fails instead of shipping a dead class. Link has one URL policy: https:, mailto:, site-relative and # links, nothing else.
Molecules (Citation, PostRow, StageStep, PreferenceSwitch …) and organisms (AskBox, ThreadGraph, FlowFigure, SiteHeader …) follow the same rules: typed props, every string a prop, no imports from constants or data.
Templates (ArticleLayout, ProjectLayout, TalkLayout, AboutLayout over BaseLayout) get their data from the page and their copy as one copy bundle, built in src/constants/templates.ts.
Pages are the only layer that reads data. A post page, src/pages/writing/[slug].astro, asks for every post at build time and then for its own:
export async function getStaticPaths() {
return (await data.getPosts()).map((post) => ({
params: { slug: post.slug },
}));
}
const { slug } = Astro.params;
const post = await data.getPost(slug);
if (!post) throw new Error(`writing/[slug]: data.getPost found no ${slug}`);
The body goes through one shared renderMarkdown. It drops raw HTML, keeps only the link schemes the URL policy allows, and turns a fenced block whose info string is figure <id> into an empty marker. The page then swaps each marker for the figure’s organism, numbered “Fig. n —”. An unknown figure id throws and names the post that asked for it. The figures in this series are written that way; the first one is below.
The build
npm run build is two lines in package.json:
"build": "npm run check && npm run test && npm run build:site",
"build:site": "astro build && npm run build -w apps/godel --",
The check and the tests run first (part 3). Of the two builds, Astro runs first because astro build empties dist/ before it writes. The previous version of this site, Gödels machine, is a separate Vite app in apps/godel/, built second, into its own folder under dist/projects/godels-machine/live/.
The output is static HTML (output: "static"), one file per post, project and talk, plus the files built from the same data: the RSS feed, the sitemap, llms.txt and llms-full.txt, and search-index.json: every post section, slide, project summary and About paragraph as a passage for Ask. After Astro’s last page, a build hook hashes every inline script and style into the security headers (part 3). Then wrangler deploy hands dist/ to a Cloudflare Worker, which serves it as static files and sends one path, /api/ask, to code before any file.
- src/constants and src/content/posts
- src/data zod parse, one door
- src/pages → dist/ HTML, feeds, CSP
- Worker blog assets + /api/ask
- src/constants and src/content/posts leads to src/data zod parse, one door: parsed by src/schema
- src/data zod parse, one door leads to src/pages → dist/ HTML, feeds, CSP: astro build
- src/pages → dist/ HTML, feeds, CSP leads to Worker blog assets + /api/ask: wrangler deploy
A bad record that a page reads never gets as far as dist/. The data layer throws while the pages render, so npm run build fails, and on Cloudflare a failed build means no deploy. A figure no page uses is not rendered, so the site build cannot catch it; the tests that run before it do (part 3).
Where this sits on the thread
Why Astro? Mostly because I wanted to know it. I considered Cloudflare’s vinext too, but I use it in another project instead: a proof of concept that is a good place to play with vinext and the TypeScript 7 betas. Static pages were the right call for a site that changes when I publish, not when someone visits. And the strings live in constants because they always should: a loose string in a component is the kind of thing that is very nice right up until you want to change it.
On the graph this post hangs on two ideas. Information engineering, because this part is about shaping what the site knows so that one door leads to it: the constants, the schemas and the one data API are the “information agents work from” in the opening line. The About page describes that step as “an index first, detail only when needed”; here the index is search-index.json, which feeds the Ask box in part 2. The same step’s project on the graph is Autograph, which does it for a working week instead of a website. Guardrails, because the principles only hold since a test fails when one is broken; part 3 is about the rest of those tests.
Next: part 2, islands and the Ask Worker, where the static page gets its few moving parts.
Follows the thread to
- How Claude, Codex, Copilot and Gemini talk to each other
- How this site works, part 3: deploy and guards
- How this site works, part 2: islands and the Ask Worker
- Old knowledge into new work, part 2: the library draws itself
- Old knowledge into new work, part 1: the loop watched the wrong thing
- review-loop: a second model family reviews every ticket, and code decides what blocks
- security-floor: the server-side check that --no-verify can't skip
- How Autograph turns your work into a vault
- My Claude Code setup: guardrails, a plan gate, shared memory and a wiki that dreams
- Autograph
- Throw away your IDE?