DFD — System (Level 0)
The whole site as one data flow, from authoring through the build and publishing to reading, with its trust boundaries.
- Status: Current
- Last updated: 2026-11-01
- Related ADRs: ADR-0005, ADR-0010, ADR-0020, ADR-0013, ADR-0014, ADR-0016
Snapshot of the system as it stands today. Edit in place; never record what changed. Conventions:
content/docs/maintain/dfd/index.mdx. Levels balance — a child's flows match its parent's.
Scope
The whole site: authoring, build, publishing and reading. No parent diagram.
Diagram
External entities
| Entity | Role |
|---|---|
| Owner | Writes the content; reviews and commits every change; runs the build |
| Consuming repositories | The owner's project and package repositories, which include this one as a git submodule and write their own folder, content/<slug>/ (ADR-0010) |
| Reader | Reads pages; searches from the browser, in the search dialog or the home page's hero field |
| LLM tools / crawlers | Read the pages, the Markdown routes, llms.txt / llms-full.txt, robots.txt and sitemap.xml |
| Google Fonts | Serves font files during the build, for next/font and the share images (ADR-0035) |
| Algolia | Hosts the search index document |
| GitHub | Serves the avatar in each profile chip, github.com/<user>.png, redirecting to avatars.githubusercontent.com (ADR-0020) |
Processes
| # | Process | Input → Output |
|---|---|---|
| 1.0 | Build (next build) | content/ → static pages and routes |
| 2.0 | Sync search index (scripts/sync-content.ts) | Built static.json → Algolia index |
| 3.0 | Serve | Built output → readers and tools |
Data stores
| ID | Store | Contents | Classification |
|---|---|---|---|
| D1 | content/ | Published documentation, one folder per package or project, including this site's own design documents (docs/maintain/) | Public — see ../security/data-classification.mdx |
| D2 | .env.local (gitignored) | Algolia app ID, search-only key, write key | The write key is Restricted; the others are Public |
Trust boundary crossings
| Flow | Direction | Authorisation | Private content? |
|---|---|---|---|
Pages from a consuming repository → content/ | Submodule → repository | The owner's review and commit; agents there never commit (PROJECT_AGENTS.md §10) | Could carry a private project's text if written into its folder; the owner's review is the control, and PROJECT_AGENTS.md §2 forbids it |
| Records → Algolia | Build → Algolia | ALGOLIA_WRITE_KEY | Would carry any page in content/. Each record also carries its scope tag and, for catalogue pages, package, kind, ecosystem, track, line, channel (ADR-0013) — public metadata about public pages |
| Search query → Algolia | Browser → Algolia | Search-only key, public by design | Can read every record in the index. The query is the reader's text only; the dialog adds no filter |
| Pages and machine-readable routes → readers and tools | Site → public | None | Would carry any page in content/ |
| Font request → Google Fonts | Build → Google Fonts | None | No. The request names a font family and weight, and no page's words |
| Avatar → reader | Browser → GitHub | None | No. The request carries the reader's IP address and user agent and, with referrerpolicy="no-referrer", no page address. The username in it is already on the page (Public) |
| "View on GitHub" link | Site → GitHub | GitHub's own access rules | Points at the page's source in the repository named in gitConfig |
Every crossing carries everything in content/. That is why no private project content
may go there until its ADR is approved (AGENTS.md §6.1).