Platform Implementation

How the platform is actually built: the documentation publishing pipeline, the validation chain, the architecture review automation, and local workstation configuration.

The controls this implementation satisfies are in Platform Requirements. Running and releasing it is covered in Platform Operations.

1. Documentation publishing

1.1 Decision

• GitHub is the single source of truth for docs-as-code.
• Cloudflare Pages hosts the published sites.
• The Azure DevOps wiki is a pointer-only landing page and is never hand-edited.

Two sites are published: core platform documentation at docs.synkronyx.com, and Event Route Optimiser product documentation at ero-docs.synkronyx.com.

1.2 Information architecture

The core site serves platform, security, and operations teams: landing zone governance, shared identity patterns, shared runbooks, and naming and policy baselines.

The product site serves product engineering and delivery teams: product architecture and implementation, offline engine behaviour, feature contracts, and delivery guidance.

Both sites present the same lifecycle sequence, so a reader can follow what was needed, what was built, and what was delivered:

1. Requirements
2. Architecture
3. Implementation
4. Operations
5. Reference

1.3 Build pipeline

Source markdown lives in the flat docs/ library. Nothing under docs/site/ is hand-authored.

graph TD;
    A[Docs Source in Git] --> B[Prepare Docs Mirrors];
    B --> C[Starlight Build];
    C --> D[Cloudflare Publish];

1. platform/automation/node/docs/docs-profiles.mjs declares which documents belong to which site and which lifecycle section.
2. platform/automation/node/docs/prepare-docs-sites.mjs mirrors the selected documents into each Starlight site, pins repository links to the current commit, and validates every internal link. A broken link fails the build.
3. platform/automation/node/docs/concat-docs.js produces the single-file docs/MASTER_SYSTEM_SPECIFICATION.md bundle.
4. Starlight builds each site and Cloudflare Pages publishes the result.

Run the whole chain locally with npm run docs:regen.

1.4 Infrastructure

The Cloudflare Terraform stack lives in platform/infrastructure/cloudflare/docs and manages the Pages projects, custom domains, and DNS records.

Infrastructure is never applied as a side effect of publishing content. See the DNS safety controls in Platform Operations.

1.5 Rendering standards

Mermaid is integrated in both sites through astro-mermaid with mermaid, registered in each astro.config.mjs. Rendering is client-side and compatible with static hosting, so standard markdown mermaid fences are permitted in any source document.

Sites must provide persistent left navigation, a consistent section hierarchy, full-text client search, stable page URLs, clear titles, and generated metadata and sitemaps.

1.6 Quality gates

• Markdown lint on pull requests.
• Broken-link validation during site preparation.
• En dash and em dash detection across the whole repository.
• End-of-file newline validation on every tracked markdown file.
• Preview deployments for pull requests.
• Required review for architecture and security document changes.
• Architecture review report visibility, with backlog validation or apply completed for any findings.

2. Full lifecycle validation

One local command validates the root, the product application, and the documentation build before a branch enters the promotion chain.

npm run validate:lifecycle

Stages run in order:

1. Markdown policy and end-of-file formatting.
2. Documentation workflow contracts.
3. The Event Route Optimiser Astro build.
4. The core and product documentation site builds.

Run it on user/* and feature/* branches before opening a promotion pull request. A non-zero result stops at the failing stage and names it.

3. Architecture review backlog automation

Architecture review findings feed a pipeline-owned, idempotent backlog reconciler, so that Medium and Low findings become tracked technical debt rather than review comments that decay.

3.1 Components

1. Parser and reconciler: platform/automation/node/sync-architecture-guard-backlog.mjs
2. Local command: npm run backlog:arch:validate
3. Hooks: .githooks/post-checkout and .githooks/post-merge
4. VS Code task: Validate Architecture Guard Review Backlog
5. GitHub Actions job: Sync Architecture Guard Backlog

Backlog apply mode is GitHub Actions only. A developer device can validate parser output, but cannot create backlog work items. If GitHub Actions is unavailable, backlog updates wait with the release.

3.2 Report contract

The review report must retain these headings so the synchroniser can parse it:

1. Critical and High Findings
2. Medium and Low Findings
3. Request Versus Architect Duty Gaps
4. Open Issues and Assumptions
5. Recommended Next Action

Each finding uses this structure:

- **[AG-SEC-001] Secret exposed in client configuration**
  - Evidence: `apps/event-route-optimiser/web/src/env.d.ts:12` exposes a credential to the browser bundle.
  - Risk: A public credential can be used outside its intended trust boundary.
  - Recommendation: Move the value to a Worker secret and expose only a non-sensitive public identifier.

When nothing meets the evidence threshold the report states No actionable findings. and still lists validation gaps and residual risks under Open Issues and Assumptions.

3.3 Backlog model

The script reads the report, then validates or creates Azure DevOps items by exact title match:

1. Epic: Architecture Guard Review Backlog
2. Features: Architecture Guard Findings Remediation, and Architecture Guard Open Issues and Assumptions
3. User stories: one per finding
4. Issues: one per finding, one per assumption or open issue line, and one for the recommended next action

Existing items are marked as existing and never duplicated.

3.4 Report source

The report is loaded from either a markdown file passed with --report-file <path>, or the latest pull request comment carrying the <!-- architecture-guard-report --> marker. In pull request flows the comment is canonical.

3.5 Run modes

Mode	Writes external state	Exit behaviour
Validate	No	Non-zero when required backlog items are missing
Hook	No	Always zero, non-blocking
Apply	Yes, creates missing items only	Idempotent across repeated runs

Hooks call validation after checkout and after pull or merge, giving a local validation pulse without blocking work.

Each run writes a JSON and a markdown summary to logs/architecture-guard-backlog/.

3.6 Required settings

For Azure DevOps reconciliation: SKNXR_ADO_PAT, with optional SKNXR_ADO_ORG_URL and SKNXR_ADO_PROJECT_NAME overrides.

For pull request comment discovery: GITHUB_TOKEN or GH_TOKEN, with optional SKNXR_GITHUB_TOKEN and SKNXR_GITHUB_REPOSITORY overrides.

4. External dependency bootstrap

Some credentials cannot be provisioned without a human at a portal. Automation opens the portals and then stops.

1. Open the Azure DevOps project, the personal access token page, and the Cloudflare API token page.
2. The operator creates the Azure DevOps project, a minimum-scope Azure DevOps token, and a minimum-permission Cloudflare token.
3. The operator stores the tokens through the protected settings lifecycle.
4. Automation resumes and validates the authenticated command or workflow without printing any secret value.

Automation must never read, display, or request a secret value. It confirms only that the expected variable names are present.

5. Workstation configuration

Local VS Code settings grant the assistant scoped execution autonomy, which removes constant permission prompts without opening a general execution hole.

{
  "antigravity.autoApprove.executeCommands": true,
  "antigravity.autoApprove.allowedCommands": [
    "pwsh*",
    "npm*",
    "npx*",
    "terraform*",
    "git*"
  ]
}

Every wildcard must stay scoped to a named executable. A bare wildcard that permits any command is prohibited.