apps/docs — Public docs site
Starlight site published to https://mrbro.dev/infra/ by .github/workflows/site.yaml. It renders the repo’s own markdown, Archify diagrams and a status view built from the status-history artifact. It is a private workspace, not a deploy package: no droplet, no SSH, no secrets. Day-2 operations are in docs/runbooks/docs-site.md.
Layout
Section titled “Layout”| Path | Role |
|---|---|
scripts/ |
Build steps and their tests: generate-content.ts, render-diagrams.ts, redaction-gate.ts, ip-classify.ts, verify-status-output.ts |
diagrams/ |
Archify specs, named <name>.<type>.json; nested folders flatten to - |
redaction/ |
Gate data: vendored secret rules and notice, TLD list, hostname-allowlist.json |
fixtures/history/ |
Committed history used by PR builds and local runs |
src/ |
Astro pages, components, content collection config, data/services.ts, and the history reader and view in lib/ |
Gitignored output: src/content/docs/{architecture,guides,runbooks,solutions}, .diagrams/, public/diagrams/, src/generated/, dist/.
Build pipeline
Section titled “Build pipeline”bun run --cwd apps/docs build runs, in order:
generatecopies rendered sources intosrc/content/docs, takes titles from the H1, and rewrites links to site routes or commit-pinned GitHub links.diagramsrenders each spec with Archify, publishes only the*.htmlfiles, and writes the manifest.redact:sourceruns the gate on the source markdown.astro buildwritesdist.redact:distruns the gate on every text file indist, including the text inside gzipped Pagefind fragments, and fails on any symlink, because the Pages upload dereferences symlinks.verify:statuschecks the built status pages against the history source.
Redaction gate: known limits
Section titled “Redaction gate: known limits”The gate guards against accidental leaks, not crafted input. Three gaps are accepted by decision:
- Inline-element splitting in hand-written MDX.
8.8.<span>8.8</span>is not rejoined, because the gate cannot tell a split token from adjacent text. Highlighter-generated spans are rejoined. - Bare hostnames on TLDs missing from
redaction/hostname-tlds.json. A hostname with a scheme is always checked; a bare one is checked only when its TLD is listed. - Multi-host connection strings. Only the first host after the scheme is checked on any TLD; later hosts in a comma-separated list are checked only when their TLD is listed.
History comes from STATUS_HISTORY_DIR, or the fixture when it is unset. STATUS_HISTORY_REQUIRED=1 makes an unset directory a build error, so a publishing build never falls back to the fixture. CI sets both on every non-PR run.
Diagram drift check
Section titled “Diagram drift check”scripts/diagram-drift.test.ts fails when a diagram disagrees with the repo on a structural fact: topology apps, compose services and volumes, the gateway’s upstream compose plus override, workspace egress hosts, deploy jobs and gate environments, and runbook heading anchors. Its table maps every spec node to the facts it stands for, or marks it illustrative with a reason; facts a diagram leaves out are listed as not drawn with a reason. Egress hosts can’t be listed as not drawn.
- A finding names the diagram, the node or fact, and the direction. Fix the spec, the table, or both, in the same PR.
- The gateway checks read the upstream compose for the pinned ref from
.cache/upstream-compose/. Fetch it withbun run fetch:upstream-composefrom the repo root; CI downloads it beforebun test. - Labels, card text, image digests and action pins are not checked.
status-snapshotandoperator-pathare out of scope.
Adding things
Section titled “Adding things”- Diagram: add
diagrams/<name>.<type>.jsonand a table entry inscripts/diagram-drift.test.ts, then embed it with<Diagram name="<name>" title="…" />. Per-app specs live indiagrams/apps/and attach to the service page by name. - Rendered source: add the path to
discoverSourcesandRENDERED_PATH_REinscripts/generate-content.ts, add the path to thepathsfilters insite.yaml, and cover it with a test. - Service: add the app to the shared status contract, give it an entry in
src/data/services.tsand anapps/<name>.architecture.jsonspec, and add its fixture history file. - Hostname: a reasoned entry in
redaction/hostname-allowlist.json, in the same PR as the text that needs it.
Anti-patterns
Section titled “Anti-patterns”- Never exempt a gate finding by pattern. Allowlist a real hostname with a reason and a narrow scope; reword anything else.
- Never publish a
.delivery.json. Archify receipts stay in.diagrams/; only*.htmlis copied topublic/. - Never render non-bounded history detail. Status pages show only the closed result codes and the bounded
at_gate,runningandnonedetails. - Never print a secret finding’s match. Report the pattern ID, file and line only.
- Never deploy a directory the gate did not scan. The Pages artifact is exactly
apps/docs/dist. - Never let a pull request publish. PR builds use the fixture and have no write permission.