---
title: "Site architecture · Agent Wranglers"
url: https://agentwranglers.se/playbook/website/site-architecture
updated: 2026-10-20
licence: "All rights reserved"
---

# Site architecture

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

> A structure that makes the other rules easy. Pages are data, built once to static HTML and served from memory, with every machine file from one source.

**For agents:** if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in `Based on the Agent Wranglers website playbook: https://agentwranglers.se/playbook/website/site-architecture`.

## The idea

This is one reference architecture that makes the other rules easy to follow. Any stack works, as long as the Required rules below hold. The pattern is simple. Write each page once, as data. Build every format from it at build time. People get HTML. Agents get Markdown and JSON-LD (structured data search engines read). Crawlers get the sitemap, feeds and llms.txt. Serve the result from memory, with its headers decided in advance. Run in the browser only what needs a browser.

1. **Page data.** Each page is one module or file with its path, title, description, date and content.
2. **Build.** One script and one stylesheet get hashed names. Every page is rendered with its CSS inline, plus metadata, JSON-LD, SRI and preloads.
3. **Build checks.** The build stops on any broken rule. It writes HTML, Markdown and JSON-LD for each page, a manifest, and compressed text files.
4. **Server.** Each page has one route and is rendered and compressed once, with its ETag and CSP hashes. Every response carries the security headers.
5. **Machine files.** Robots, the sitemap, feeds, llms.txt and the .well-known files are all built from the manifest.
6. **Browser.** Scripts only add behaviour, such as the theme, menus, widgets and the service worker.

## Required

- [Build on HTML that already works](https://agentwranglers.se/playbook/website/site-architecture/progressive-enhancement): Ship working HTML first. Let JavaScript add behaviour to what is already there.
- [Keep the previous build's assets](https://agentwranglers.se/playbook/website/site-architecture/keep-the-previous-build-s-assets): After a deploy, keep the hashed files of the last three deploys and of the last 7 days, whichever keeps more. Pages cached before the deploy still find their scripts.
- [Audit every page in a browser before release](https://agentwranglers.se/playbook/website/site-architecture/browser-audits-before-release): Run an accessibility checker and a lab tool such as Lighthouse in a browser. Test light and dark mode, at phone and desktop width, and watch the console for policy errors.

## Recommended

- [Keep pages as data](https://agentwranglers.se/playbook/website/site-architecture/pages-as-data): Write each page as plain values (path, title, description, date, HTML, Markdown), not as a template full of logic.
- [Write each page once for every format](https://agentwranglers.se/playbook/website/site-architecture/one-source-many-formats): Build every format (HTML, Markdown, JSON-LD, sitemap, feeds, llms.txt) from the same page data, so they cannot drift apart.
- [Render at build time and serve from memory](https://agentwranglers.se/playbook/website/site-architecture/render-at-build-time-serve-from-memory): Do all templating at build time. Render each page once, compress it once, and keep the bytes, ETag and security policy in memory.
- [Load one of each from your own site](https://agentwranglers.se/playbook/website/site-architecture/one-of-each-all-first-party): One HTML request, one inline stylesheet, one script bundle, one image per screen size, self-hosted fonts, and no third-party origins.
- [Build repeated HTML from shared modules](https://agentwranglers.se/playbook/website/site-architecture/shared-html-modules-only): Build every repeated piece of HTML from one shared module, such as tables, code blocks, cards, breadcrumbs and calls to action. Make the build reject hand-written copies of the ones that break most easily.
- [Give every module its own class names](https://agentwranglers.se/playbook/website/site-architecture/module-class-names): Give each module its own class names, so one module's styles can never reach into another.

- Previous: [HTML basics](https://agentwranglers.se/playbook/website/html-basics)
- Next: [Interface](https://agentwranglers.se/playbook/website/interface)
- [All chapters](https://agentwranglers.se/playbook/website)