Platform Requirements

What was needed. This document holds the mandatory controls that constrain every Synkronyx platform application: governance, architecture standards, backlog structure, documentation rules, and branch policy.

It is written as Center of Excellence policy, not as application strategy. The architecture that satisfies these controls is described in Platform Architecture.

1. Governance control model

Governance operates in three layers:

• Control policy. Mandatory controls for architecture, identity, security, release, and operations.
• Implementation guidance. Standard patterns and templates that application teams adopt.
• Conformance evidence. Application records showing how each control is implemented and validated.

Every application on the platform must produce conformance evidence mapped to these controls. Event Route Optimiser is the reference implementation.

2. Architecture Guard standards

These standards are the mandatory review baseline. The Architecture Guard agent evaluates only the change under review, and reports a finding only when it has evidence, a consequence, and a feasible corrective action.

Authority runs in this order. Where sources conflict, the higher control wins and the conflict is recorded.

1. Applicable law, contract, and regulatory obligations.
2. Approved architectural decisions.
3. These standards.
4. Product and implementation documents.

2.1 Mandatory standards

Identifier	Standard	Required evidence
AG-ARC-001	Client reads and mutations must remain local-first. Remote synchronisation runs asynchronously and preserves local user overrides.	Changed client data flow and focused test coverage.
AG-ARC-002	Interactive behaviour belongs in React TypeScript JSX. Astro remains the page and routing shell.	Changed UI component and route files.
AG-SYNC-001	Synchronisation uses logical timestamps and version vectors. Server-wins is the default unless a documented client mutation is newer by more than five seconds.	Conflict-resolution implementation and tests.
AG-EDGE-001	Public APIs use TypeScript Cloudflare Workers with Hono, and D1 where edge persistence is required.	Worker entry point, bindings, and API contract.
AG-ID-001	Microsoft Entra External ID is the application identity provider. Initial sign-in requests only openid; extra scopes require a documented just-in-time consent purpose.	Identity configuration, scope diff, and consent rationale.
AG-ID-002	Initial sign-in must not collect personal data. Tokens, claims, redirect URIs, and transport settings must preserve zero-trust boundaries.	Claim, redirect URI, and authentication validation evidence.
AG-SEC-001	Secrets must not enter source control, generated artefacts, logs, workflow output, or client bundles. Local secrets reside only under settings/.	Secret scan and configuration diff.
AG-IAC-001	Cloud infrastructure changes must be declarative, provider-scoped, and traceable through CI and CD. Azure Bicep resides in platform/infrastructure/azure; Cloudflare Terraform resides in platform/infrastructure/cloudflare.	IaC diff, format or build result, and workflow provenance.
AG-IAC-002	Production infrastructure changes require a reviewed plan or what-if result before apply. Direct workstation production deployment is prohibited.	CI and CD workflow evidence.
AG-REL-001	Production release and documentation publishing gates must run required validation before publish or deployment. A manual bypass is a High finding.	Workflow dependency graph and validation results.
AG-REL-002	Automation must be idempotent, least-privileged, and safe to rerun. External write operations require an explicit apply mode or protected CI and CD stage.	Script contract, permissions, and dry-run or apply separation.
AG-DOC-001	Architecture and runbook sources live in the flat docs/ library. Generated master specifications and docs/site/ output are not hand-authored sources.	Source document, generated-output exclusion, and markdown quality result.
AG-OPS-001	Operational changes must expose actionable diagnostics, preserve rollback capability, and include focused validation for changed behaviour.	Logs, health checks, rollback procedure, and test result.
AG-PERF-001	Changes to critical client, Worker, or routing paths must state expected latency, capacity, or cost impact when the change can affect them materially.	Benchmark, load test, cost estimate, or justified exemption.

2.2 Severity and gate policy

Severity	Meaning	Pull request policy
Critical	A credible path to secret exposure, data loss, production compromise, or uncontrolled infrastructure change	Block promotion until fixed or explicitly rejected by the Architect of Record.
High	A control failure with broad security, reliability, privacy, or release impact	Block promotion until fixed or approved through a time-bound waiver.
Medium	A material design, operability, performance, or cost risk with a clear remediation path	Create a linked backlog item with an owner and target iteration.
Low	A contained maintainability or observability gap	Record when it improves an active change; do not block promotion.

2.3 Evidence requirements

Every finding must carry a standard identifier, a file path and line reference or reproducible command output, the affected boundary, a concrete risk statement, and a scoped recommendation.

The agent must not report speculative issues, pre-existing defects unrelated to the change, or style preferences as architecture findings.

2.4 Waivers

A waiver is valid only when it states the affected standard identifier, scope, risk acceptance owner, compensating controls, expiry date, and linked backlog item. Waivers live in the pull request discussion and are referenced by the report.

Four things can never be waived: committed secrets, a bypass of required production validation, removal of authentication controls, and an unreviewed direct production deployment.

3. Backlog governance

Backlog structure must use a consistent hierarchy so that lifecycle traceability holds across products.

• Epic. Broad capability and release outcomes.
• Feature. A deployable service, module, or platform increment.
• User story. A functional behaviour requirement in behaviour-driven format.
• Task. A concrete implementation step linked to a story.

User stories use this template, so that agent tooling can parse acceptance criteria into work item descriptions and keep specification, implementation, and validation aligned.

As a <role>
I want <action>
So that <benefit>

Acceptance Criteria:
Given <initial state / context>
When <action / event occurs>
Then <expected result / system state change>

4. Documentation requirements

All platform documentation is maintained in version control under docs/. Architecture, contracts, and runbooks have a single source of truth in the repository. Published wikis and documentation sites are generated from that source and are never hand-edited.

4.1 Mandatory standards

• Root documents use unique, semantic, lower-case, hyphenated filenames with no positional prefixes.
• Core and product site content is generated from source profiles.
• The documentation release version must be visible as version: <value> in site navigation.
• Build and publish flows must be idempotent and script-driven.

4.2 Authoring rule: extend before adding

The docs/ library is a flat namespace, so an unchecked new-file habit produces sprawl and duplicated content. These rules are mandatory.

1. Extend an existing document by default. Adding a section to the owning document is the expected action for new material.
2. A new file must earn its place. Before creating one, identify the owning document and state why the material cannot live there as a section.
3. A new file must be registered in platform/automation/node/docs/docs-profiles.mjs in the same change. Unprofiled documents fall into the supplementary part of the master bundle and lose their curated reading position.
4. A new file must stand alone. Material that is only meaningful as a subsection of another document must be written as that subsection.
5. Each fact has one owner. When the same table, field list, or command sequence is needed twice, one document owns it and the other links to it.
6. Retire on merge. When content moves into another document, the source file is deleted in the same change and every inbound reference is repointed.

Reviewers must reject a change that adds a document without a profile entry, or without a stated reason that it cannot be a section of an existing document.

4.3 Language rules

• Avoid the words ensure and ensures.
• Use open issues rather than outstanding issues.
• Avoid possessive apostrophe forms for product and framework names.
• Use and rather than an ampersand in narrative text.
• Never use an en dash or an em dash anywhere in the repository. Use a plain hyphen, a comma, or reword. This is enforced by npm run check:dashes.

4.4 Ownership

Accountable owner: Synkronyx architecture and governance. Operating owner: the documentation architect, who owns information architecture, semantic filename policy, publishing strategy, authoring standards, review gates, and architecture review visibility.

5. Repository branching policy

The repository is trunk-based. main is the only long-lived branch and is always in a releasable state.

5.1 Branching model

1. Work happens on short-lived branches cut from main, named feature/<topic> or user/<name>/<topic>.
2. Each branch merges back into main through exactly one pull request, then is deleted.
3. Branches are expected to live hours or days. A branch that lives longer has usually grown too large and should be split.

There is no develop and no permanent release/*. Environments are reached by deploying a commit, not by merging it again, so promoting work does not require copying it between branches.

A release branch may be created on demand for one purpose only: patching an already released version without shipping unreleased trunk work. It is cut from the release tag, and deleted once the patch is tagged.

5.2 Merge methods

Pull request	Required method	Rationale
user/* or feature/* to main	Merge commit	Preserves the shape of each change in trunk history.

A different method may be used only when the reason is recorded in the pull request. Confirm the method against .github/pull_request_template.md before merging.

This is enforced rather than documented: the ruleset on main permits merge commits only. Review requirements are covered in Platform Operations.

5.3 Why trunk-based

Long-lived branches drift, and every reconciliation is an opportunity to lose or duplicate work. Short-lived branches barely have time to diverge.

The second reason matters more. When work is promoted by merging it through several branches, the commit that reaches production is created by the final merge and has never existed anywhere before, so it is not the commit that was tested. With one trunk and tag-based release, the commit that was tested is the commit that ships.

Trunk-based depends on two things being true. Automated checks must be trustworthy, because every merge is immediately visible to everything downstream. Unfinished work must be safe to have on the trunk, behind a flag or an unreferenced code path. Reconsider this model if either stops holding, or if the platform ever needs to support more than one released version at a time.

6. Support and escalation

Operational support follows a three-tier triage model.

graph TD
    A[Incoming Ticket] --> B[Tier 1: Triage and Standard Scripts]
    B -->|Resolved| C[Close Ticket]
    B -->|Complex or Unknown| D[Tier 2: Escalation and Root Cause Analysis]
    D -->|Resolved or Workaround| C
    D -->|Platform Bug or Change| E[Tier 3: Platform Team and Bug Fix]
    E -->|Release Deploy| C

• Tier 1. Frontline operational checks and known-runbook validation.
• Tier 2. Deep diagnostics across logs, data state, and service behaviour.
• Tier 3. Platform remediation, change delivery, and control updates.

7. Conformance evidence

Event Route Optimiser demonstrates conformance through:

• Backlog governance: Platform Operations
• Identity and security: Platform Architecture and the ERO identity runbooks
• Operations and release: Platform Implementation and the workflow controls under .github/workflows/

Future applications must provide equivalent evidence against this same policy set.