Website software design

Purpose and system boundary

This static publication serves reviewers, learners and operators of Resilience Gate. It teaches the application and release platform while exposing the scope of evidence. It has no backend, credentials, live metrics, authentication, database, analytics or runtime external content retrieval. The separate integrated platform design describes the application and infrastructure.

Website code and authoring sources live in the standalone private repository devSatym/resilience-gate-docs. The public Resilience Gate implementation remains a separate upstream repository. No application, infrastructure, platform tests, or release workflows are tracked here.

Enlarge diagram: Canonical content through validation, Astro, Pagefind and static hosting · Version-controlled diagram source

Canonical storage and registry

site/config/content-map.json is the only route/publication registry. Its version-1 records contain source, stable route, title, description, section, type, related routes, references, reviewedRevision and evidenceIds. Six section names and five document types are validated. Routes use lowercase URL-safe segments. Duplicate sources/routes, missing relations/references, invalid revisions and evidence IDs fail preparation. All required sections must have a home.

Existing platform configuration remains canonical upstream at the logical path docs/configuration-reference.md. Teaching articles live locally in docs/website/content/; website engineering artifacts remain in docs/website/. Generated Starlight files are ignored and never independently edited. The adapter does not copy the documentation tree. Only listed articles, ten listed diagrams and manifest-approved captures become assets. Unexpected files in site/public and unmapped custom page files fail preparation before Astro can copy or render them. Audit screenshots and raw traces are outside the public asset graph.

Pinned upstream inputs

site/config/source-repository.json identifies the upstream repository, reviewed revision 2420ff4c2a88b1fa4a19e413cb0752e271480081, and ignored checkout .source/resilience-gate. After npm ci, npm run source:prepare obtains the pinned checkout before content checks or builds. This build-time source acquisition is separate from runtime serving; the resulting site does not fetch platform content at runtime.

Source-relative links retain logical repository paths so source citations do not depend on a developer’s absolute checkout location. The resolver distinguishes locally owned website files from upstream implementation, reference, manifest, and evidence files. Publication inputs retain their virtual paths and an origin of website or upstream. Local authoring URLs name the documentation repository; implementation URLs name the public upstream repository and reviewed commit. Private authoring links require repository access, while rendered articles remain usable independently of those links.

The generated publication inventory records documentation HEAD and dirty state separately from upstream {repository, revision} and publicInputDigest. A new documentation commit is not a new platform implementation revision. Updating the upstream pin requires renewed factual review of affected source, tests, diagrams, and evidence, rather than silently following upstream main.

Preparation and failure behavior

prepare-content.mjs validates the registry and all inputs before changing any generated files. Safe resolution rejects absolute paths, traversal, excluded directories, and symlinks, and checks each resolved input remains inside its approved website or upstream source root. This is a publication boundary, not a replacement for evidence review. A credential accidentally written inside approved prose still requires editorial/disclosure review.

A Unified Markdown AST handles headings, links, definitions and images; MDX is enabled only for the homepage and gallery. Imports are limited to approved local project components. The initial Markdown H1 is removed and its original anchor preserved; additional H1s are rejected. Link resolution decodes filesystem paths, checks mapped anchors, converts mapped documents to base-aware routes, and sends intentionally unmapped source links to the appropriate documentation or reviewed upstream GitHub paths. Ordinary external links remain unchanged. Source Markdown retains logical filesystem conventions.

Diagrams require accessible SVG metadata and reject scripts, event handlers, external resources and foreign objects. Validated page/diagram/image buffers are cached and reused through rendering preparation so their hashes describe the same bytes. Preparation checks original screenshot bytes against the canonical manifest and creates 720px WebP derivatives without overwriting PNGs. Unknown observation/result fields do not become successful outcomes. Preparation updates changed files in place, pruning unmapped leftovers rather than deleting the collection during watch mode. It owns site/src/content/docs/, site/public/generated/ and the gallery data in site/src/data/; it refuses symlink output roots. Repeated preparation produces the same content and input digest while browser captures have independent timestamps.

Rendering and component boundaries

Astro reads generated content through Starlight’s docsLoader and docsSchema, then builds static HTML. Starlight owns accessible navigation, theme persistence, search dialog, heading anchors, table of contents, pagination and code-copy controls. Supported Hero, MarkdownContent, and Footer overrides compose native Starlight components.

HomeHero renders a static release-decision model and three routes. EvidenceCard accepts claim/category/result/window/scope/href; unavailable is its conservative result default. WorkflowStep exposes owner/input/output/failure. FailureComparison exposes normal/impact/observations/recovery. DiagramFigure accepts name/alt/caption/scope and renders an image, enlargement link and canonical source link. EvidenceGallery renders normalized reviewed records with original hash, timestamp/window and identities; its browser script enhances filters and a native modal dialog. The modal closes with Escape, makes the background inert through native dialog behavior, and restores focus. Static original links work without JavaScript.

ProjectFooter retains Starlight’s default Footer and adds static maintainer/profile/source links plus related-project navigation. Its maintainer name, Satyam Agnihotri (devSatym), and headline are owner-published in the pinned handbook author record and public GitHub profile. The security handbook link names its available documentation; Azure links to the public source repository. Planned portfolio/AKS documentation hosts are not presented as active destinations. The block uses data-pagefind-ignore, native links, and responsive wrapping, with no JavaScript or images. It was added after the first publication checkpoint and needs its own served-build verification.

ArticleContent renders the original MarkdownContent component and an ignored-for-search canonical source/related-reading footer. Article body rendering needs no client UI runtime. Pagefind loads its index when search is opened; gallery JavaScript is emitted only where the gallery is imported. No Mermaid runtime is loaded.

Routing, indexing and hosting

paths.mjs normalizes root/project bases and prevents duplicate prefixes. SITE_BASE defaults to / and the publication origin is https://resilience-gate.devsatym.xyz. These are configured targets, not proof of live serving. Routes use trailing slashes. The final output includes Starlight’s 404, canonical metadata, sitemap, favicon, and static social preview. A local compatibility base can still be rebuilt and checked separately; Cloudflare publication requires the root-base artifact.

Pagefind indexes built article content and captions. Navigation and canonical-source footers are excluded by Starlight and explicit attributes. Private/unmapped files cannot enter the index because they never enter rendering. Search is a progressive enhancement; article bodies and destinations remain usable without it.

Cloudflare Pages serves the prerendered dist/ files through its native Git integration with the private documentation repository. The Pages project uses root site, output dist, and Node 22.20.0. Its native build command is DOCS_SITE=<reviewed stable origin> npm run build:cloudflare, using the confirmed Pages origin initially and the custom origin only after active-domain/TLS verification. Astro remains fully static without an SSR adapter, Pages Functions, application Worker, or storage bindings. Local Wrangler Pages configuration preserves directory-index routes and a real missing-page response; browser checks exercise nested refresh and 404 behavior rather than accepting a homepage fallback.

The dedicated GitHub workflow validates pull requests and relevant pushes to main with read-only permissions. Manual workflow dispatch also runs checks. It has no GitHub Pages deployment job, Cloudflare publishing job, or deployment secrets. Pages’ native Git builds are separate: initialization pauses both production and previews; configuration enables branch previews while automatic main production remains paused, then explicit first-build verification precedes enabling automatic main builds. Native Pages builds do not wait for GitHub browser checks, so maintainers review passing checks and previews before merging.

Production builds require an explicit stable DOCS_SITE supplied by the configured nonsecret shell prefix. With pages_build_output_dir, Wrangler configuration is authoritative; dashboard vars alone did not reach the initial native build. Wrangler retains no vars, bindings, or runtime. Wrangler configuration precedence The first campaign uses the confirmed assigned pages.dev origin. After the target Pages domain is registered, the owner adds one new external-DNS CNAME at Spaceship; normal custom-host TLS must work before the origin is promoted and metadata rebuilt. Non-main native previews use a validated CF_PAGES_URL and CF_PAGES_BRANCH, with noindex/robots controls. Private source and preview noindex do not provide visitor authentication.

The Cloudflare runbook defines account/Git-source inspection, build controls, Free limits, and the exact-host owner DNS handoff. This external-DNS subdomain does not require an active Cloudflare zone, Billing Read, or a nameserver migration. Configuration, local checks, native build identity, domain activation, and strict HTTPS verification remain distinct observations under docs/website/audit/cloudflare-pages/. Earlier Workers results remain historical under docs/website/audit/cloudflare/; the repository transfer remains separately recorded in docs/website/audit/migration/repository-transfer.json.

Development and validation

npm run dev prepares once and watches canonical content, engineering artifacts, diagrams, public configuration and the screenshot manifest. A serialized rebuild queue prevents overlapping output mutation. Preparation errors are reported while the last valid output remains available; a later correction retriggers preparation. Production build always prepares and performs a parsed HTML internal-link/anchor/asset check.

Unit tests exercise schema, routing, missing sources, traversal/symlinks, unknown evidence, hashes and AST links. Browser tests crawl routes and check UI interactions at desktop/mobile sizes in both themes, using actual production search. Accessibility uses axe plus explicit focus/keyboard checks. Lighthouse captures repeated simulated mobile measurements. Existing platform validation remains separate evidence. Historical monorepo audits remain in migration-evidence/monorepo-audit/, and repository-separation checks remain in docs/website/audit/migration/. New Pages local command outcomes and input identities belong to docs/website/audit/cloudflare-pages/local-checks.json; native deployment/HTTPS status belongs to that campaign’s separate receipts. The retained Workers campaign is not rewritten as a Pages result. No previous pass count is reused as a new hosting result.

npm run test:e2e exercises Astro production preview, while npm run test:cloudflare exercises local wrangler pages dev routing. audit:cloudflare writes real screenshots, axe scans, and repeated mobile Lighthouse samples to the new Pages campaign. The public verifier accepts the intended origin through --origin, performs strict HTTPS/page/asset-hash checks, and then launches the full browser suite against SITE_TEST_ORIGIN only after those checks pass. Each result remains bound to its actual server mode and tested artifact.

Trade-offs and residual boundaries

A small explicit adapter costs registry maintenance but creates a reviewable public inventory. Native SVG diagrams are easy to inspect and avoid runtime rendering, though they require coordinated updates when mechanisms change. The gallery loads thumbnail derivatives lazily; originals remain download-only until opened. Public summarized evidence can be informative while its private raw provenance remains unavailable. This website cannot make an uncollected platform scenario proven.

See the maintenance guide, requirements, UI contracts, and audit report.

Framework references checked

Initial framework APIs were checked against official Starlight configuration, content authoring, component overrides, site search, Astro collections, and Playwright accessibility. Dependency peer requirements and Node engines were inspected from the npm registry and installed packages. The Cloudflare migration uses current primary documentation linked in the runbook and hosting decision.