# Detailed design and interfaces

## Content schema

`src/content.config.ts` extends Starlight's documentation schema. Required custom fields are `documentType`, nonempty `audience`, literal baseline `gcp-cbbc807`, review date, status, and arrays for controls/sources/evidence/prerequisites/related. `src/lib/schemas.mjs` supplies stricter standalone validation, including calendar-date checks and catalogue referential integrity.

| Record | Required contract | Relationships |
| --- | --- | --- |
| Source | ID, repository URL, full commit SHA, path, kind, symbols, SHA-256, URL, inspection status/date | Control source IDs and page source IDs |
| Control | Question, asset, threat, property, phase, component, inputs/outputs, dependencies, scope/exclusions, failure behavior, limits, status | Source IDs, concept routes, stage IDs, evidence IDs |
| Stage | ID/title, control ID, route, input/output, verifier | Guided release sequence |
| Evidence | Claim, controls, origin/environment, nullable observed date/revision, category/phase/result, expected/actual, original URL, transcript, caption, limits, redaction and verification notes, visibility | Optional approved display asset and dimensions |
| Reading path | ID/title, audience, ordered routes, duration | Navigation across groups |

Dates and source SHA patterns are not interchangeable. `observedDate: null` and `revision: null` mean unknown, not automatically equal to baseline or review date. An evidence display asset requires `publicVisibility: display-approved`; a gap cannot masquerade as a recorded-live result. A control's evidence association must agree with the evidence's control IDs.

## Component interfaces

| Component | Props | Behavior |
| --- | --- | --- |
| `BaselineNotice` | None | Reads manifest; names historical context and scope route |
| `PageTitle` | Starlight override | Delegates standard title and adds the baseline notice |
| `ArchitectureMap` | None | Selected stage details, inputs/outputs/verifier, linked routes |
| `ReleaseJourney` | `active?: number` | Complete static sequence; enhanced previous/next progression with bounded index |
| `ReadingPath` | `id?: string` | All configured paths or selected path cards |
| `SecurityContract` | `id: string` | Control question/property/component/scope/failure/limitations |
| `RelatedControls` | `ids: string[]` | Fail-fast control lookup and concept links |
| `SourceReference` | `ids: string[]` | Full-SHA implementation links; unknown ID throws |
| `Diagram` | `id: string` | Lookup diagram, render SVG, caption, semantics, text equivalent; unknown ID throws |
| `EvidencePanel` | `id: string` | Claim/result/provenance, optional approved image, transcript, limitations, original reference |
| `EvidenceCatalogue` | None | Static records; optional control/phase/result/category filters and live count |
| `Footer` | Starlight override | Site/baseline context and standard footer |

Components use checked-in data rather than HTTP APIs. Unknown control/evidence IDs throw in `catalogue.ts`; a source or diagram miss also throws during rendering. These are authoring failures, not silently omitted content. A reading-path ID must be checked by content validation because its component filters a list.

## URL helper contracts

`withBase(path, base)` preserves external schemes, protocol-relative URLs, and fragments; prefixes an internal path once; and supports the root base. `routeUrl(route, base)` creates a trailing-slash route. `sourceUrl(repository, commit, path)` rejects a commit without a full 40-character SHA and encodes path segments. Unit tests cover external/fragment cases, repeated prefixes, root/custom base, and invalid source revisions.

MDX authors use relative article links or the base helper for public assets. A route's prerequisites/related metadata stores catalogue route IDs without the deployment prefix. Rendered links still need output auditing because metadata validation cannot observe every transformed Markdown link or generated anchor.

Documentation routes/assets default to the custom domain `https://security.devsatym.xyz` at `/`. The validated deployment resolver selects independent `custom`, actual-repository `github`, and `legacy` compatibility profiles; public evidence/social URLs use `publicAssetUrl` and imported editorial images use Astro-generated responsive WebP paths. Source URL generation retains `https://github.com/devSatym/gcp-supply-chain-security` and the full GCP baseline SHA; handbook edit URLs use `https://github.com/devSatym/gcp-security-handbook/edit/main/website/`. `SOURCE_REPO_PATH` explicitly selects the separate read-only implementation checkout for hash verification. The newly initialized handbook Git database is not assumed to contain historical implementation objects.

`documentation.json` defines handbook repository, default branch, visibility, site origin, base, and source repository. These are separate from the source baseline's `currentMainCommit`. `scripts/revision.mjs` records actual documentation repository/main/head/dirty information; the pre-migration uncommitted record is preserved as historical evidence rather than converted into a fabricated commit.

## Diagram and evidence pipelines

`diagrams.json` stores ID/title/caption/nodes/steps/semantics. The SVG has a title and description, a labelled horizontally scrollable region, theme-aware nodes/arrows, and an ordered equivalent. Most diagrams use a four-node sequence; the identity split uses two distinct authority lanes. They clarify a handoff; arrows do not imply independent roots of trust or live state. Unique component-derived IDs label SVG elements, so avoid repeating the same diagram ID twice on one page without extending instance IDs.

Evidence derivatives are public only after review. The evidence component displays unknown dates/revisions explicitly and links the untouched pinned original. Transcript text is escaped by Astro; it is not inserted as HTML. Image alt/caption must state the demonstrated result and context. Build processing copies only approved publication inputs; output checks confirm neither the internal ledger nor raw operational files escaped into `dist`.

## Validation and generated artifacts

Content validation checks metadata, IDs, routes, source URL revision, active component coverage, and substantive content. Isolated negative fixtures intentionally create bad metadata/reference/evidence/route cases. Unit tests exercise helper/schema contracts. `prepare.mjs` prepares explicitly allowed public build assets; Astro creates static pages, search assets, and routes. `audit-site.mjs` examines generated HTML links, fragments, assets, metadata, and publication boundaries. Playwright operates on production preview and records failures/screenshots separately from website evidence.

Dependency caches, raw test reports, operational state, and local provider installs are build/test inputs or internal outputs, never website publication assets. The final report must identify actual executed checks after all content/report changes; this interface description does not assert their outcome.


## Audit-driven interface refinements

The Head override maps Starlight head tags unchanged except the special404 canonical path, which points to actual404.html output. Search delegates native search behavior and observes inserted Pagefind markup to give the input an explicit accessible label. TwoColumnContent preserves native MIT layout/styles while labeling the local-contents landmark. SourceReference and RelatedControls also have unique landmark names.

Catalogue validation binds HTTPS source URLs to the baseline repository, full SHA and exact path; validates the baseline manifest, diagram identities, required approved-image dimensions and34 source-component coverage families. Coverage evidence is curated per component: upstream historical files do not cite owner results, and disabled alerting cites its explicit gap. Negative fixtures prove gates fail. Publication checks validate public inputs and complete emitted output, allowing only approved assets/routes plus Astro/Pagefind generated directories. Build directly validates catalogues before rendering.

Diagram uses a four-node sequence by default; identity-split renders two separate horizontal lanes with no cross-path arrow. Image dimensions are conditionally required when displayAsset exists; they are absent for transcript/reference-only records.

Evidence originals require `originalPath`, whose known source path binds `originalReference` to the exact baseline repository/full SHA. Approved display paths are restricted to the reviewed `/evidence/` namespace. Negative fixtures reject mutable original URLs and unknown paths.

## Complete evidence gallery

The subsequent owner request adds all14 original PNGs through typed `screenshots.ts`/`screenshots.json`, `ScreenshotGallery` and `failure-cases/screenshots`. Every source path/URL/hash binds to the original full-SHA catalogue; display SHA/dimensions are verified from PNG bytes. Complete collection coverage rejects missing captures. The public-input/output allowlist accepts reviewed gallery assets explicitly. Eight historical evidence records now display their original images, with five selected transcripts retained. Each gallery card separates expected/recorded observation, collection date, revision context, direct/context relation and limits. The owner subsequently authorized publishing these approved originals with the handbook on Cloudflare. No PNG pixel edit was performed; retained terminal/account metadata is disclosed. Any future redacted derivative requires separate direction and recorded display provenance.

## Gallery layout stability

The desktop TOC uses sticky positioning within the computed sidebar width and a viewport-minus-header height; it does not size a fixed element to the entire viewport. Main content permits flex shrinking with min-width zero, while the TOC width remains stable. Evidence links and images use block layout and an explicit aspect ratio from reviewed pixel dimensions, reserving space before lazy decode. A deferred-image browser check compares panel geometry before/after PNG loading and verifies desktop TOC bounds and scrolling. This repairs the first gallery Lighthouse CLS regression without changing capture pixels.