WA Government Architecture Decision Records

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

Reusable architecture patterns for WA Government digital services, maintained by the Office of Digital Government (DGOV) Digital Transformation and Technology Unit (DTT).

For WA Public Sector Agencies

These decisions and patterns help agencies design secure digital services without starting from scratch. They support WA Government security outcomes but do not by themselves prove project or agency compliance.

Getting Started

1. Review the ADR Design Guardrails - Six guiding principles for all technology decisions
2. Use the Decision Finder - Match a project need to the right ADRs and reference architectures
3. Choose a Reference Architecture - Accepted architectures are active project-kickoff guidance. Proposed architectures require project approval and approval of their Proposed dependencies:
   • Proposed: AI-Assisted Digital Services - Low-risk AI assistance for services, staff workflows, CMS, and portals
   • Accepted: Content Management - Websites, intranets, and content portals
   • Accepted: Data Pipelines - Analytics, reporting, and data processing
   • Proposed: Federated Application Portal - Standalone apps using shared account, identity, notification, and SDK services
   • Proposed: Identity Federation - OIDC, legacy SAML, and privileged federation
   • Accepted: OpenAPI Backends - Agency-controlled HTTP APIs
4. Check the Compliance Mapping - Find which ADRs apply to your security and compliance requirements

Find Guidance by Need

Compliance Alignment

These ADRs align with:

• WA Cyber Security Policy
• ACSC Information Security Manual (ISM)
• WA Government AI Policy and Assurance Framework

Supporting training: DGOV Technical - DevSecOps Induction

Browse online | Printable long view

Contributing

New ADRs document the context (problem), decision (solution), and consequences (trade-offs). See the Contributing Guide for workflow and templates.

For AI-assisted contributions, see the guidance in CONTRIBUTING.md.

All maintained guidance includes a review date. Set review dates one year after the document date unless a shorter review cycle is needed.

Repository Structure

This project uses mdBook to generate documentation:

• development/, operations/, security/ - ADRs by domain
• reference-architectures/ - Project kickoff templates
• SUMMARY.md - Navigation structure

just setup    # One-time tool installation
just serve    # Preview locally (port 8080)
just build    # Build website and print view

ADR Design Guardrails

Status: Accepted | Date: 2025-03-07 | Review: 2026-03-07

These six guardrails guide day-to-day technical design decisions in this repository. They help teams make consistent trade-offs when writing and reviewing Architecture Decision Records (ADRs).

They are not enterprise architecture principles, procurement policies, or technology standards for whole-of-government or agency-level use.

1. Establish secure foundations

Integrate security practices from the outset, and throughout the design, development and deployment of products and services, per the ACSC Foundations for modern defensible architecture.

2. Understand and govern data

Use authoritative data sources to ensure data consistency, integrity, and quality. Embed data management and governance practices, including information classification, records management, and Privacy and Responsible Information Sharing, throughout information lifecycles.

3. Prioritise user experience

Apply user-centred design principles to simplify tasks and establish intuitive mappings between user intentions and system responses. Involve users throughout design and development to iteratively evaluate and refine product goals and requirements.

4. Preference tried and tested approaches

Adopt sustainable open source software, and mature managed services where capabilities closely match business needs. When necessary, bespoke service development should be led by internal technical capabilities to ensure appropriate risk ownership. Bespoke software should preference open standards and code to avoid vendor lock-in.

5. Embrace change, release early, release often

Design services as loosely coupled modules with clear boundaries and responsibilities. Release often with tight feedback loops to test assumptions, learn, and iterate. Enable frequent and predictable high-impact changes (your service does not deliver or add value until it is in the hands of users) per the CNCF Cloud Native Definition.

6. Default to open

Encourage transparency, inclusivity, adaptability, collaboration, and community by defaulting to permissive licensing of code and artifacts developed with public funding.

Decision Finder

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

Use this page to find the right starting point for common delivery needs. Start with a reference architecture when one matches the project. Use ADRs directly when you need a specific decision or control.

Reference architectures display their status at the top of each page. Accepted architectures are active project-kickoff guidance. Proposed architectures remain evaluation aids and require explicit project approval, including approval of their Proposed dependencies.

Project Preflight

Before choosing a pattern, record:

• Users, service outcome, accountable owners, critical journeys, and non-goals
• Existing and legacy constraints, agency capability, support model, and budget
• Information classification, privacy, sharing, records, processing locations, suppliers, and offshoring requirements
• Accessibility and assisted-digital needs
• Criticality, service levels, RTO, RPO, degraded operation, and incident coverage
• Migration, interoperability, data/configuration export, rollback, and exit needs

Start by Project Type

Adoption Bundles

Use these bundles to start project discovery, not as universal control sets. Add or remove ADRs according to the preflight, selected architecture variant, and project risk. A Proposed reference architecture or ADR still requires explicit project approval.

Public Website or Content Service

Start with: Accepted Content Management.

Minimum ADR set: ADR 020: Frontend UI Foundations, ADR 016: Edge Protection, ADR 004: CI/CD, ADR 009: Release Standards, ADR 007: Logging, and ADR 014: Backups and Recovery. Add ADR 013: Identity Federation when users or editors sign in.

Kickoff deliverables:

• Service and content brief, audiences, critical journeys, content ownership, publication workflow, and selected architecture variant
• Accessibility and design-system assessment with representative user testing
• Content, media, URL, redirect, integration, records, and retention inventory
• Edge and origin design, release path, service objectives, support model, recovery test, migration plan, and export or exit plan

Agency-Controlled HTTP API

Start with: Accepted OpenAPI Backends.

Minimum ADR set: ADR 003: HTTP API Contract Standards, ADR 004: CI/CD, ADR 005: Secrets Management, ADR 007: Logging, and ADR 009: Release Standards. Add ADR 013: Identity Federation for user delegation, ADR 016: Edge Protection for Internet exposure, and ADR 014: Backups and Recovery for stateful services.

Kickoff deliverables:

• Version-controlled OpenAPI contract, named consumers, ownership, lifecycle, compatibility policy, and deprecation plan
• Exposure and trust-boundary diagram, authentication and operation or resource authorisation model, data classification, limits, and abuse cases
• Contract, behaviour, security, compatibility, and failure test plan
• Service objectives, monitoring, support and incident runbooks, recovery plan, consumer migration plan, and provider-exit record

Data Pipeline or Analytical Data Service

Start with: Accepted Data Pipelines.

Minimum ADR set: ADR 015: Data Pipeline Quality, ADR 018: Databases and Lakehouses, ADR 004: CI/CD, ADR 005: Secrets Management, ADR 007: Logging, ADR 010: Infrastructure as Code, and ADR 014: Backups and Recovery. Add ADR 017: Analytical Publications for bounded publications and Proposed ADR 021: Workload mTLS when approved for Kubernetes-hosted pipeline services.

Kickoff deliverables:

• Source, consumer, authority, purpose, classification, sharing, retention, and processing-location record
• Versioned data contracts, data-flow diagram, quality thresholds, lineage design, quarantine, replay, and reconciliation approach
• Freshness and service objectives, capacity and cost forecast, RTO, RPO, support model, and incident runbooks
• Representative quality, lineage, performance, recovery, migration, interoperability, and exit tests

AI-Assisted Service or Workflow

Start with: Proposed AI-Assisted Digital Services, with explicit project approval, and ADR 011: AI Tool and Agent Governance.

Minimum ADR set: ADR 011: AI Tool and Agent Governance, ADR 001: Application Isolation, ADR 005: Secrets Management, and ADR 007: Logging. Add ADR 004: CI/CD for released software and the ADRs required by the authoritative source service.

Kickoff deliverables:

• Bounded use case, excluded uses, risk tier, accountable human, human decision boundary, and non-AI fallback
• Information classification, privacy, records, supplier, processing-location, offshoring, retention, and threat assessments
• Representative evaluation set with quality, safety, accessibility, security, refusal, and human-review acceptance thresholds
• Prompt and model change controls, monitoring and incident runbook, usage and cost limits, data and configuration export, and provider-exit test

Federated Application Set

Start with: Proposed Federated Application Portal, with explicit project approval. Select only shared capabilities with demonstrated user or operational value.

Minimum ADR set: ADR 013: Identity Federation, ADR 003: HTTP API Contracts for shared APIs, ADR 020: Frontend UI Foundations, ADR 005: Secrets Management, and ADR 007: Logging. Add ADR 012: Privileged Remote Access for administration and ADR 016: Edge Protection for Internet-facing capabilities.

Kickoff deliverables:

• Selected shared capabilities, accountable boundaries, funding and support model, application inventory, direct-access paths, and degraded modes
• Cross-application journeys, accessibility and assisted-digital needs, identity assurance, claim definitions, and application-owned authorisation model
• Versioned API, message, SDK, component, and native-bridge contracts where used
• Trust-boundary and data-flow diagrams, service objectives, onboarding and offboarding checks, resilience tests, migration plan, and exit plan

Start by Capability

ADR Catalogue

This generated catalogue is the authoritative index of ADR status, review dates, and direct dependencies. Dependencies come from each ADR’s synopsis; update the source ADR and run just update-catalogue rather than editing this table.

Quality Checks Before Delivery

Before using a decision in a project kickoff, confirm that:

• The ADR or reference architecture is not superseded
• Accepted ADRs are used as active decisions; Proposed material has explicit project approval and does not silently establish a standard
• The review date has not passed, or the decision owner accepts the risk
• Compliance obligations are checked in Compliance Mapping
• Related ADRs have been reviewed together, not in isolation
• Project-specific deviations are documented in the project record

Proposed Decision Backlog

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

This backlog tracks guidance that is useful but not yet accepted as an active decision. Use it during annual reviews and planning to decide whether each item should move to Accepted, stay Proposed, or become Superseded.

Proposed ADRs

Proposed Reference Architectures

Acceptance Criteria

Move a proposed item to Accepted when:

• The scope and non-goals are clear enough for delivery teams to apply
• Required related ADRs are linked
• Implementation steps are practical and testable
• Mandatory statements trace to Accepted ADRs or authoritative policy
• Proposed dependencies are accepted, removed, optional, or explicitly labelled
• Minimum, higher-assurance, and legacy-transition variants have representative agency validation
• Provider examples remain non-normative and cover realistic cloud, SaaS, and legacy contexts where relevant
• Required artifacts, ownership, accessibility, data handling, operations, resilience, migration, and exit checks are complete
• Compliance mapping is complete where relevant
• A reviewer confirms the technology and policy assumptions still hold
• The annual Review date is set one year after the document Date

Keep a proposed item as Proposed when the guidance is directionally useful but still depends on technology, policy, or operating-model confirmation.

Move a proposed item to Superseded when another ADR or reference architecture has replaced it.

Annual Review Schedule

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

All maintained guidance is reviewed annually. Set each Review date to one year after the document Date, then advance it by one year when the review is completed.

Review Process

1. Confirm the document status is still correct.
2. Check policy, compliance, and technology references for changes.
3. Validate links with just lint.
4. Confirm related ADRs still agree with the decision.
5. Update the document if guidance has changed.
6. Advance the Review date by one year when complete.

Schedule

ADR 001: Application Isolation

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

Synopsis

• Use when: Designing boundaries between applications, environments, trust domains, data stores, or administrative paths.
• Avoid when: The design relies on a Kubernetes namespace or cloud resource group alone as a security boundary or permits undocumented cross-boundary traffic.
• Decision: Isolate applications and environments by default using the strongest practical combination of administrative, network, compute, and workload boundaries with default-deny flows.
• Required evidence: Trust-boundary diagram, approved flow allow-list, default-deny and environment-separation configuration, workload controls, and prohibited-path tests.
• Dependencies: Proposed ADR 021: Workload mTLS and Service Authorisation for Kubernetes workload controls, ADR 006: Automated Policy Enforcement for ingress and egress policy, and ADR 007: Centralised Security Logging for traffic logging.

Context

Not isolating applications and environments can lead to significant security risks. The risk of lateral movement means threats of vulnerability exposure of a single application can compromise other applications or the entire environment. This lack of isolation can enable the spread of malware, unauthorised access, and data breaches.

• Open Web Application Security Project (OWASP) Application Security Verification Standard (ASVS)
• Australian Cyber Security Centre (ACSC) Guidelines for System Hardening
• ACSC Guidelines for Networking

Decision

Applications and environments must be isolated by default. The selected boundary must reflect information sensitivity, criticality, trust, administrative ownership, and the consequence of compromise.

flowchart LR
    account[Cloud administrative boundary]
    cluster[K8s Cluster]
    namespace[Namespace]

    account -->|nested isolation| cluster -->|nested isolation| namespace

Use the strongest practical combination of these nested boundaries:

1. Cloud administrative boundary: Separate environments or security domains using an AWS account, Azure subscription, or Google Cloud project. An Azure resource group is a lifecycle and organisation scope; it is not equivalent to an account, subscription, or project isolation boundary.
2. Network or compute boundary: Use separate virtual networks, clusters, or equivalent runtime boundaries where workloads have different trust, ownership, or exposure.
3. Workload boundary: Use namespaces, identities, network policy, quotas, and runtime controls for related workloads that may safely share infrastructure. A namespace alone is not a security boundary.

Within each boundary:

• Deny network traffic by default and allow only documented flows required for service operation
• Separate production from non-production and separate administrative paths from user traffic
• Isolate data stores from direct Internet access and from workloads that do not require them
• Apply Kubernetes NetworkPolicy, security groups, firewalls, or equivalent controls; a namespace alone is not a network security boundary
• Authenticate and encrypt supported Kubernetes service-to-service traffic and authorise it by workload identity. Proposed ADR 021: Workload mTLS and Service Authorisation defines the preferred Linkerd implementation profile and requires project approval until accepted
• Control and log ingress, egress, and cross-boundary traffic per ADR 006: Automated Policy Enforcement and ADR 007: Centralised Security Logging

Provider Examples

These examples map the durable boundary requirement; they are not mandated products:

• AWS accounts
• Azure subscriptions
• Google Cloud projects

Legacy Transition

Legacy and on-premises systems may migrate progressively. Agencies must inventory trust boundaries, first restrict and monitor cross-boundary traffic, then separate administrative access and production from non-production. Migrate the highest-consequence systems first against owned milestones; record interim segmentation and monitoring as compensating controls.

Required Evidence

• Current data-flow or network diagram identifying trust boundaries
• Approved allow-list of cross-boundary flows and business owners
• Configuration showing default-deny controls and environment separation
• Service identity, mTLS, and service-authorisation evidence for supported Kubernetes workloads
• Periodic test results demonstrating that prohibited paths are blocked

Exceptions

An exception must identify the unavailable primary control, compensating controls, affected services and information, residual risk, executive approval, expiry date, and reassessment date.

Consequences

Benefits:

• Enforceable network microsegmentation that limits lateral movement
• Simplified incident containment and forensic analysis
• Compliance with regulatory isolation requirements

Risks if not implemented:

• Single vulnerability compromising multiple applications
• Difficult incident response across shared environments
• Data breaches through unauthorised cross-system access

ADR 005: Secrets Management

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

Synopsis

• Use when: Storing, delivering, rotating, or auditing application, automation, or administrative secrets.
• Avoid when: Source code, configuration, images, logs, prompts, or Kubernetes Secrets would become the authoritative long-term secret store.
• Decision: Use an agency-approved managed secret service as the system of record, prefer workload identity and short-lived credentials, and enforce ownership, least privilege, encryption, rotation, scanning, and auditing.
• Required evidence: Secret inventory, access and encryption configuration, rotation and secret-scan results, and central administrative-access records.
• Dependencies: None.

Context

Per the Open Web Application Security Project (OWASP) Secrets Management Cheat Sheet:

Organisations face a growing need to centralise the storage, provisioning, auditing, rotation and management of secrets to control access to secrets and prevent them from leaking and compromising the organisation.

Static secrets create disclosure and rotation risk. Location alone does not make a secret safe: access policy, identity, encryption, auditability, lifetime, and recovery determine the effective control.

Decision

An agency-approved managed secret service must be the system of record for application, automation, and administrative secrets. Segment stores and access policies by environment and trust boundary. Workloads should authenticate using workload identity and short-lived, dynamically issued credentials instead of stored credentials wherever the target service supports them.

Secret Rotation

Each secret must have an owner, expiry or review date, and a rotation method based on its lifetime, privilege, exposure, service capability, and impact of compromise. Revoke and replace secrets immediately after suspected disclosure.

Automate rotation where practical, prioritising high-consequence and widely shared secrets. Manual rotation is acceptable when risk-assessed, owned, tested, and evidenced; being manual does not by itself require an exception.

Kubernetes Secrets

A Kubernetes Secret is a delivery and storage object, not inherently safer than a managed secret service. Namespace scoping does not prevent access by cluster administrators or a compromised control plane. If used, enable encryption at rest, tightly scope RBAC and workload identities, prevent logging or environment leakage, and minimise persistence. Direct runtime retrieval, a CSI driver, or a synchronisation operator are all acceptable when the managed service remains authoritative and the threat model supports the delivery method.

One-time operations should retrieve secrets only for the task lifetime and must not expose them in command arguments, shell history, logs, or temporary files. Runtime secrets must not be stored in source repositories; encrypted test fixtures must keep decryption identities outside the repository.

Provider Examples

Equivalent managed systems of record include:

• AWS Secrets Manager
• Azure Key Vault secrets
• Google Secret Manager

Required Controls

• Do not hard-code secrets in source code, images, infrastructure definitions, logs, prompts, or configuration files
• Encrypt secrets in transit and at rest and restrict decryption to the workload or administrator that requires it
• Prefer short-lived, dynamically issued credentials over static secrets
• Grant retrieval and management permissions separately and by least privilege
• Scan repositories, build artifacts, and logs for exposed secrets and revoke exposed credentials immediately
• Record secret ownership, purpose, consumers, rotation method, and last rotation without recording the secret value
• Log administrative access, rotation, and failed retrieval without logging secret material

This ADR covers application secrets, credentials, and their encryption. It does not define an agency-wide cryptographic algorithm, key-management, certificate-management, or post-quantum transition standard.

Required Evidence

• Secret inventory containing owner, consumer, storage location, and rotation requirements
• Access-policy and encryption configuration
• Rotation and secret-scanning results
• Central audit records for administrative access and failed retrieval

Exceptions

Storage outside an agency-approved system of record, unencrypted secret storage, or inability to meet the assessed rotation requirement needs a time-bound exception with compensating controls, residual risk, accountable executive approval, expiry date, and reassessment date.

Consequences

Benefits:

• Consistent access control, audit, and lifecycle management
• Defined rotation periods and automation where practical reduce human error
• Meets compliance and auditing requirements

Risks:

• Security exposure from manual handling
• Non-compliance without proper implementation

Trade-offs:

• Runtime retrieval and synchronisation components add availability and operational dependencies

ADR 008: Email Authentication Protocols

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

Synopsis

• Use when: Managing any active, delegated, parked, sending, receiving, or non-sending agency-controlled domain.
• Avoid when: Moving DMARC to reject before legitimate sender alignment is measured or enabling forensic reporting without assessing privacy, retention, processor, and cross-border risks.
• Decision: Apply SPF, DKIM, DMARC, inbound impersonation controls, and protected mail transport to every controlled domain, progressing enforcement through measured, owned stages.
• Required evidence: Domain and sender inventory, DNS records and independent tests, DMARC progression reports, transport status where used, and spoofing alerts and incidents.
• Dependencies: None.

Context

Government email domains are prime targets for cybercriminals who exploit them for phishing attacks, business email compromise, and brand impersonation. Citizens and businesses expect government emails to be trustworthy, making email authentication critical for maintaining public confidence and preventing fraud.

Without proper email authentication, attackers can easily spoof government domains to conduct social engineering attacks, distribute malware, or harvest credentials from unsuspecting recipients.

References:

• ACSC How to combat fake emails
• RFC 7208: SPF
• RFC 6376: DKIM
• RFC 7489: DMARC
• RFC 8460: SMTP TLS Reporting
• RFC 8461: MTA-STS

Decision

Apply email authentication to every agency-controlled domain, including active sending and receiving domains, non-sending domains, delegated subdomains, and parked domains.

Required Standards:

• SPF: Authorise only known sending services and target -all. Use ~all only during a measured transition with an owner and deadline.
• DKIM: Sign outbound mail using agency-approved algorithms, key sizes, and cryptoperiods. Document selector rollover, rotate before the approved cryptoperiod expires or after compromise, and remove superseded keys after delivery queues have cleared.
• DMARC: Start active sending domains at p=none with aggregate rua reporting. Progress through sampled or full quarantine to p=reject when measured reports show legitimate senders have aligned SPF or DKIM and false-positive risk is acceptable. Each domain must have an owned, risk-approved deadline for reject enforcement rather than a fixed generic interval. Set subdomain policy deliberately; do not assume every subdomain has the same sending pattern.
• Forensic reports: Enable ruf only after assessing personal, sensitive, cross-border disclosure, retention, and report-processor risks.
• Non-sending domains: Publish a null SPF record and DMARC p=reject for parked domains and domains that must not send email. Use null MX where the domain must not receive email.
• Inbound protection: Email gateways must evaluate SPF, DKIM, and DMARC, detect display-name and lookalike-domain impersonation, and quarantine or reject messages according to the assessed risk.
• Mail transport: For receiving domains, deploy MTA-STS in testing mode, validate delivery, then enforce it. Publish TLS-RPT to monitor TLS policy failures. An approved DANE design may provide equivalent protection.

Recommended:

• BIMI: Implement verified brand logos with Verified Mark Certificates (VMCs) for high-profile citizen-facing domains.

Implementation:

• Monitor DNS records for tampering
• Maintain an inventory of agency domains and authorised sending services
• Record the owner, sending and receiving status, DMARC enforcement deadline, DKIM cryptoperiod, and reporting destinations for each domain
• Regular authentication testing and effectiveness reviews
• Incident response procedures for authentication failures
• Integration with email security gateways

Required Evidence

• Domain and authorised-sender inventory
• Current DNS records and independent SPF, DKIM, and DMARC test results
• DMARC reporting that demonstrates measured alignment and policy progression against the approved deadline
• MTA-STS and TLS-RPT records, reports, and enforcement status where used
• Alerts and incident records for spoofing or unauthorised DNS changes

Exceptions

Any missed DMARC enforcement deadline must identify the affected domain and sender, migration plan, compensating gateway controls, residual risk, executive approval, expiry date, and reassessment date.

Consequences

Benefits:

• Automated email authentication blocking domain spoofing
• Enhanced brand protection and citizen trust
• Comprehensive threat visibility through DMARC reporting

Risks if not implemented:

• Phishing attacks exploiting government domain reputation
• Reduced email deliverability affecting citizen communications
• Non-compliance with government security requirements

ADR 011: AI Tool and Agent Governance

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

Synopsis

• Use when: Any development, content, analysis, testing, operational, generative, or agentic AI tool processes data, generates outputs, or invokes tools.
• Avoid when: An unapproved public AI service would receive sensitive data or an AI system would take consequential, privileged, or hard-to-reverse action without required human approval.
• Decision: Assign human accountability, risk-tier every AI use case, constrain data and privileges, validate outputs, monitor tool activity, and require explicit human gates for high-impact actions.
• Required evidence: Approved register entry, provider and data assessments, agentic risk assessment, human approvals, and tool-call, denial, output, and approval logs.
• Dependencies: ADR 001: Application Isolation for isolated or local AI execution environments.

Context

Generative and agentic AI tools used for development and operations can process sensitive data, call tools, and produce outputs that affect security, privacy, and compliance. Without governance, they can expose data, make biased or incorrect recommendations, misuse privileges, and create compliance failures.

Agentic AI adds autonomy: models can use tools, external data, memory, planning workflows, and execution privileges. This increases the attack surface through prompt injection, unsafe tool use, privilege creep, identity spoofing, third-party component compromise, cascading failures, and opaque audit trails.

High-risk scenarios include:

• Automated Decision-Making: policy, approval, or resource allocation decisions without human review
• Government Data Processing: sensitive organisational data processed by offshore or unapproved AI services
• Uncontrolled Outputs: generated content, code, or analysis used without qualified validation
• Privacy Violations: personal information processed without consent or required controls
• Agentic Tool Use: shell, network, API, email, data, or infrastructure actions beyond a tightly approved scope

References:

• ACSC Information Security Manual (ISM)
• ACSC: Careful adoption of agentic AI services
• WA Cyber Security Policy
• Privacy Act 1988
• WA Government Artificial Intelligence Policy and Assurance Framework
• WA Data Offshoring Governance
• WA Information Classification Policy
• Linux Foundation Agentic AI Foundation
• Oxide RFD 576: Using LLMs at Oxide - values-based approach to AI tool governance

Decision

Assign a human owner accountable for every AI-assisted system and decision. Governance depth, approval gates, validation, and monitoring must be proportionate to risk rather than triggered by AI use alone.

AI security, including agentic AI security, must be managed inside normal cyber security governance: secure-by-design, defence in depth, identity and access management, monitoring, incident response, and supply chain risk management.

Risk Tiers:

Assess each use case using the sensitivity and volume of data, consequence to people or government, degree of autonomy and privilege, and whether effects are detectable and reversible:

Reassess the tier when data, model, tools, autonomy, users, or consequences materially change.

Human Accountability:

Adopt a values-based approach to AI governance (per Oxide RFD 576):

• Responsibility: Humans are accountable for AI-generated artifacts
• Rigor: AI should support rigorous thinking, not replace it
• Validation: Validation must match the risk and intended use
• Accountability: AI-assisted decisions must have a clear human owner

Human approval gates must be set by system designers and operators, not by the AI system. Prior human approval is required for high-impact or hard-to-reverse actions. Lower-risk, bounded, observable, and reversible actions may run under prior system approval with monitoring, limits, and an accountable owner.

Approval Matrix:

Covered AI Tools:

This ADR applies to all AI tools including:

• Development and coding assistants
• Content generation and writing assistants
• Data analysis and business intelligence platforms
• Automated testing and code review tools
• Agentic AI systems, autonomous agents, multi-agent workflows, and tools with API, shell, network, memory, or execution privileges

Requirements:

AI tools must not:

• Receive sensitive, security-classified, personal, or Tier 1 Risk information through public or consumer AI services
• Take high-impact or hard-to-reverse actions without prior human approval
• Process sensitive data with third parties without a formal contractual arrangement
• Alter production state outside approved risk-tier controls and rollback
• Receive broad or unrestricted access to sensitive data, critical systems, logs, credentials, networks, or production environments
• Decide when human approval, escalation, rollback, or audit deletion is required

AI tools must:

• Be risk-tiered, approved for their data and consequence, and assigned an accountable owner before use
• Run in isolated or local environments (refer to ADR 001: Application Isolation) with minimal permissions and bounded blast radius
• Use explicit workspace, shell/process, network, model-provider, local-state, and approval boundaries
• Default to read-only or approval-gated modes for untrusted repositories and first-look analysis
• Apply least privilege to every agent, tool, credential, API, and sub-task, scoped to the required resource, operation, and timeframe
• Prefer ephemeral or just-in-time credentials for privileged actions
• Validate inputs, prompt context, tool responses, third-party components, and generated outputs before consequential use
• Log tool calls, approvals, denied actions, policy decisions, model-provider disclosures, and official AI-generated outputs
• Fail safe: stop and escalate when uncertain, rate-limited, degraded, or denied by policy
• Apply information classification before disclosure and minimise prompts, retrieval context, logs, memory, and retained outputs
• Assess provider processing and support locations, subcontractors, retention, model-training use, deletion, incident notification, and exit arrangements before enterprise use
• Prevent processing outside approved locations and purposes through contract and technical configuration; assess all offshoring under WA Data Offshoring Governance

Agentic AI Adoption Controls:

Agentic AI adoption must follow ACSC-aligned controls:

• Start with low-risk, non-sensitive tasks and expand access or autonomy only after monitoring, testing, and risk review
• Threat model prompt injection, confused-deputy abuse, identity spoofing, third-party tools, data exfiltration, cascading failures, and credential compromise
• Test agents in sandboxes before production use, including adversarial and failure-mode testing
• Maintain trusted inventories for model providers, tools, prompts, datasets, and agent components
• Monitor runtime behaviour, including anomalous resource use, guardrail triggers, denied actions, and attempts to bypass approval or logging
• Separate high-risk agents into distinct security domains and avoid implicit trust between agents

Required Evidence:

Approved AI tool use must retain enough evidence for review:

• Approved tool or register entry
• Data disclosure and model-provider assessment where applicable
• Information classification, retention, processing-location, and supplier assessment where applicable
• Risk assessment for agentic workflows
• Human approval records for high-impact actions
• Logs of tool calls, denied actions, generated outputs, and approvals

Exceptions:

Exceptions require documented risk acceptance by the accountable owner, time-bound approval, and compensating controls. Exceptions must not remove human accountability for consequential decisions or high-impact actions.

Non-Normative Implementation Examples:

Products are options only and require the same agency assessment. Examples include oy-cli for repository research, Amazon Bedrock, Microsoft Foundry, and Google Vertex AI Model Garden.

Provider statements, model cards, certifications, or assurance features are inputs to assessment, not proof that an agency use case is safe, compliant, accurate, unbiased, or fit for purpose. Agencies must validate controls and outcomes against their own data, threats, users, and consequences.

Strategic Research

Future research may evaluate simple agent workflows with inspectable boundaries: explicit workspace scope, approval-gated mutation, least privilege, deterministic audits, continuous monitoring, fail-safe defaults, and reversible deployment. Research involving oy, Bedrock, Foundry, or Model Garden is non-normative and does not establish a preferred provider.

Service-facing AI integrations should follow Reference Architecture: AI-Assisted Digital Services: applications call an internal Open Responses-compatible gateway, not model providers directly. The gateway should enforce data minimisation, approved models, logging, and provider privacy settings such as store: false where supported.

Model and backend selection must consider:

• Evidence of better quality or security on representative development, audit, and operations tasks
• Data disclosure to the configured model provider, including snippets, command output, tool results, and audit chunks
• Portability, exit arrangements, and the justification for proprietary model or agent features
• Compatibility with required approval modes, workspace boundaries, least privilege, audit logging, safe rollback, and human approval gates

Consequences

Benefits:

• Ensures human accountability for all AI-assisted decisions
• Supports applicable privacy, information-classification, and data-location obligations
• Requires prior approval for high-impact or hard-to-reverse actions
• Establishes an audit trail for responsible AI usage
• Aligns agentic AI adoption with ACSC guidance: low-risk initial use, least privilege, monitoring, progressive deployment, and human approval for high-impact actions

Risks if not implemented:

• Unauthorized data exposure to offshore AI services
• AI making critical decisions without human oversight
• Compliance violations and regulatory breaches
• Operational errors from unchecked AI outputs
• Agent compromise, confused-deputy abuse, identity spoofing, tool misuse, cascading failures, or audit gaps from over-privileged autonomous agents

ADR 012: Privileged Remote Access

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

Synopsis

• Use when: Administrators need remote privileged access to production, cloud, legacy, or on-premises targets.
• Avoid when: The path requires direct Internet-exposed administration, standing privilege, shared credentials, unmanaged jump hosts, missing MFA, or unrecorded sessions.
• Decision: Broker privileged access through an approved identity-aware service using named identities, MFA, just-in-time approval, automatic expiry, managed devices, recording, logging, and tested break-glass access.
• Required evidence: Privileged identity and entitlement inventory, MFA and approval records, access reviews, session records, and break-glass tests.
• Dependencies: ADR 007: Centralised Security Logging for session records and ADR 010: Infrastructure and Configuration as Code for routine infrastructure changes.

Context

Persistent administrative exposure, standing privilege, shared credentials, and unrecorded sessions create material risk. A managed bastion, VPN, or other transport is not inherently unsafe when identity-aware access, just-in-time elevation, recording, and equivalent controls are enforced.

• ACSC Information Security Manual (ISM)
• WA SOC Cyber Network Management Guideline

Decision

Privileged remote access must pass through an agency-approved, identity-aware access broker that grants recorded, just-in-time (JIT) access to named users for an approved task. Targets must not expose direct administrative ports to the Internet.

flowchart LR
    admin[Administrator]
    ssm[Identity-aware access broker]
    systems[Target Systems]

    admin -->|MFA + identity| ssm
    ssm -->|temporary session| systems

Direct production SSH/RDP, shared credentials, unmanaged jump hosts, and standing privileged entitlements are prohibited. A managed bastion or VPN may carry administrative traffic only when the same identity, MFA, JIT, approval, expiry, device, session recording, and logging controls are met.

Access Controls:

• Use dedicated privileged identities that are separate from standard user identities and are not used for email or general web browsing
• Require phishing-resistant multi-factor authentication for privileged access where supported; document any temporary fallback method
• Validate access before granting it and recertify privileged entitlements at least quarterly
• Grant access just in time for an approved task and automatically expire sessions and elevated entitlements
• Bind access to a named identity and approved target, role, command or protocol, purpose, and duration
• Require approval appropriate to privilege and consequence
• Session recording and audit logging per ADR 007: Centralised Security Logging
• Use managed and compliant administrative devices or isolated secure administration environments for privileged sessions
• Maintain separately controlled, monitored, and tested break-glass access for identity or control-plane failure

Implementation:

• Prefer outbound target connections or private paths over inbound administrative exposure
• Use short-lived credentials and prohibit reusable private keys where a brokered alternative exists
• Real-time monitoring and alerting
• Integration with SIEM systems
• Use Infrastructure as Code for routine changes per ADR 010: Infrastructure as Code

Provider Examples

These are non-exclusive mappings and must be configured to meet all controls:

• AWS Systems Manager Session Manager
• Azure Bastion with Microsoft Entra PIM
• Google Cloud IAP TCP forwarding with Privileged Access Manager

Legacy Transition

Legacy and on-premises targets may retain a managed bastion or VPN during transition. Federate named identities, remove shared credentials, require MFA and JIT approval, centralise logs, and add session recording where technically possible. Prioritise Internet-exposed and high-consequence systems under an owned migration plan; document interim controls and dates.

Required Evidence

• Privileged identity and entitlement inventory, including owners
• MFA policy, approval record, session expiry, and quarterly access-review evidence
• Session and administrative activity records in the central logging platform
• Break-glass custody, alerting, and test records

Exceptions

Persistent privilege, direct Internet administrative access, shared credentials, non-MFA access, or unrecorded sessions require a time-bound risk record with compensating controls, residual risk, executive approval, expiry date, and reassessment date.

Consequences

Benefits:

• Zero-trust network access with session recording
• Enhanced audit capabilities through centralised logging
• Short-lived credential security reducing persistent threats

Risks if not implemented:

• Unauthorised lateral movement across network systems
• Prolonged security breaches from persistent access
• Non-compliance with government zero-trust requirements

ADR 013: Identity Federation Standards

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

Synopsis

• Use when: Integrating new interactive user identities or workload identities across enterprise, citizen, privileged, or cloud identity domains.
• Avoid when: SAML is selected despite available OIDC support, identity domains are collapsed despite different assurance needs, or legacy authentication can bypass MFA.
• Decision: Standardise new interactive federation on OIDC, retain SAML only for unavoidable legacy integration, use workload federation for non-human identities, and govern identity domains separately.
• Required evidence: Relying-service register, identity-policy exports, authentication events and alerts, and annual federation, key-rollover, recovery, and fallback tests.
• Dependencies: ADR 012: Privileged Remote Access for privileged access and ADR 007: Centralised Security Logging for authentication audit trails.

Context

Applications need to integrate with multiple identity providers including jurisdiction citizen identity services, enterprise directories, and cloud identity platforms. Current approaches use inconsistent protocols (SAML, OIDC, proprietary) creating integration complexity and security inconsistencies.

The controls differ for employees, citizens, administrators, and software. Treating them as one identity domain creates inappropriate assurance, lifecycle, privacy, and access decisions.

• Digital ID Act 2024
• OpenID Connect Core 1.0
• OWASP Authentication Cheat Sheet
• EU Digital Identity Wallet Architecture and Reference Framework (ARF) - European digital wallet standards
• ISO/IEC 18013-5:2021 Mobile Driving Licence - mobile identity document standard

Decision

Standardise on OpenID Connect (OIDC) as the primary protocol for new interactive user federation, with SAML 2.0 support only where an upstream provider or legacy relying party cannot support OIDC. Use the applicable workload-federation protocol for non-human identities.

Define separate policies and trust boundaries for:

• Workforce identities: employees, contractors, and partners, with joiner, mover, leaver and entitlement governance
• Customer or citizen identities: privacy-preserving registration, recovery, consent, fraud controls, and service-specific assurance
• Privileged identities: separate administration identities with JIT elevation and controls from ADR 012
• Workload identities: non-human identities using federation and short-lived tokens instead of user accounts or long-lived keys

Protocol Standards:

• Primary: OpenID Connect for modern identity providers and new integrations
• Legacy Support: SAML 2.0 only when upstream providers require it and OIDC is unavailable
• Security: Use the OIDC Authorization Code flow with PKCE for browser, native, and public clients; do not use the implicit flow. Validate issuer, audience, signature, nonce, state, expiry, and authorised redirect URIs.
• Compliance: Assess the Digital ID Act 2024, Accreditation Rules, and Australian Government Digital ID System requirements only where the agency is providing, seeking accreditation for, or participating in a service within their scope. The Act is not a blanket technical mandate for every agency login.

Architecture Requirements:

• Use a managed identity platform where it reduces security and lifecycle risk. Introduce an identity broker only when multiple upstream providers, protocol translation, central policy, or migration needs justify the added dependency and concentration risk
• Separate privileged and standard user domains for administrative access isolation (see Reference Architecture: OpenAPI Backend)
• Support the upstream identity providers required by the service without embedding provider-specific identity logic throughout application code
• Maintain audit trails per ADR 007: Centralised Security Logging
• Require multi-factor authentication (MFA) for workforce users, remote access, privileged access, and Internet-facing services according to information sensitivity and service risk
• Prefer phishing-resistant authenticators such as passkeys, security keys, or certificate-backed device authentication; do not use SMS or voice as the target state
• Disable legacy authentication protocols that bypass MFA
• Record successful and failed authentication, MFA registration and reset, token anomalies, account recovery, and privileged elevation events
• Define fallback authentication for critical services without weakening normal MFA requirements or leaving an unmonitored bypass

Identity Federation Flow:

flowchart TB
    subgraph standard[Standard User Domain]
        users[Users]
        idp[Identity Providers]
    end

    subgraph privileged[Privileged User Domain]
        admins[Administrators]
        pim[Privileged Identity Management]
    end

    platform[Managed Platform]
    apps[Applications]

    users -->|authenticate| idp
    idp -->|OIDC/SAML tokens| platform
    admins -->|authenticate| pim
    pim -->|elevated claims| platform
    platform -->|validated claims| apps

Where used, the managed platform handles protocol translation, token validation, policy, and audit logging.

Provider Examples:

Customer and citizen identity options include Amazon Cognito user pools, Microsoft Entra External ID, and Google Cloud Identity Platform. These examples are not mandated and do not replace assurance, privacy, residency, accessibility, recovery, and exit assessments.

Roadmap:

• Monitor W3C Verifiable Credentials, OpenID4VC, and ISO/IEC 18013-5. Adopt them only for an approved use case with mature interoperability, privacy, revocation, recovery, and trust-framework support. They are not current federation requirements.

Implementation Requirements:

• Choose identity platforms with high availability and data export capabilities
• Document the required authentication assurance for each relying service
• Test federation metadata, signing-key rollover, account recovery, and critical-service fallback at least annually

This ADR covers federation and authentication. Detailed identity lifecycle, entitlement review, compromised-password filtering, and workload identity standards remain agency implementation requirements.

Required Evidence

• Relying-service register with protocol, MFA, assurance, and fallback requirements
• Identity-provider policy exports showing MFA and legacy-authentication settings
• Authentication-event coverage and alert tests in the central logging platform
• Annual federation, key-rollover, recovery, and fallback test records

Exceptions

Any service that cannot meet the required MFA or federation controls must record compensating controls, affected identities and information, residual risk, executive approval, migration date, expiry date, and reassessment date.

Consequences

Benefits:

• Consistent modern federation standard across all applications
• Better security through OIDC’s improved token handling and PKCE support
• Simplified integration with jurisdiction citizen identity services
• Clear separation of administrative and standard user access

Risks if not implemented:

• Fragmented authentication systems across applications
• Legacy SAML limitations hindering citizen service integration
• Inconsistent security posture across identity touchpoints

ADR 016: Web Application Edge Protection

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

Synopsis

• Use when: Exposing a web application or API to the Internet.
• Avoid when: A CDN or WAF is mandated without demonstrated need, clients can bypass the edge, or edge controls are treated as substitutes for secure design, patching, authentication, or application testing.
• Decision: Require risk-appropriate managed edge and DDoS controls, add WAF or CDN capabilities where justified, restrict origin access, and stage enforcement with monitoring and tested failure handling.
• Required evidence: Edge and origin configuration, Internet service inventory, WAF and penetration tests, tuning records, alerts, and central logs.
• Dependencies: ADR 019: Shared File Access for file-backed assets and ADR 007: Centralised Security Logging for WAF and security logging.

Context

Government web applications face heightened security threats including state-sponsored attacks, DDoS campaigns by activist groups, and sophisticated application-layer exploits targeting public services. These attacks can disrupt critical citizen services and damage public trust.

Traditional perimeter security is insufficient for modern web services. Managed edge, DDoS, and application controls can reduce exposure before traffic reaches an origin, but the appropriate services depend on threat, availability, performance, architecture, and consequence.

References:

• ACSC Information Security Manual (ISM)
• ACSC Guidelines for System Hardening
• OWASP Web Application Security Testing Guide

Decision

Internet-facing web applications and APIs must use agency-approved, risk-appropriate managed edge and DDoS protection. Use a WAF where HTTP threats warrant it. Use a CDN when caching, geographic delivery, origin shielding, or edge capacity provides a documented benefit; a CDN is not required for every service.

flowchart LR
    users[Internet Users]
    cdn[Managed edge controls]
    apps[Applications]

    users -->|requests| cdn
    cdn -->|filtered traffic| apps

The edge may provide TLS termination, routing, caching, WAF filtering, bot controls, and DDoS mitigation before traffic reaches the origin.

Edge Requirements:

• Size DDoS protection and escalation support for the assessed service availability risk
• Configure caching and origin shielding only where content and privacy rules permit them
• Prefer object-backed origins for cacheable static and media assets, using ADR 019: Shared File Access when authoring or processing workloads need file-system access
• Enable IPv6 dual-stack at the edge where the selected service and client compatibility support it; document any material accessibility or transition constraint
• Prevent clients from bypassing the edge by restricting origins to authenticated edge traffic or an equivalent private path
• Use agency-approved TLS versions and certificates at the edge and origin
• Apply appropriate HTTP security headers, including transport security and content-type protection; define Content Security Policy per application

WAF Protection:

• Select managed and custom rules for evidenced threats. WAF rules do not cover all OWASP Top 10 risks and do not fix insecure application design
• Layer 7 DDoS protection and rate limiting
• Apply geo-blocking and bot management only where justified and tested for service accessibility impacts
• Custom rules for application-specific threats
• Introduce new and materially changed rules in log or count mode, review false positives, then progress through sampled or scoped blocking to full enforcement. Urgent threat rules may use expedited approval and review

Provider Examples:

Options include AWS WAF and Shield, Azure Web Application Firewall and DDoS Protection, and Google Cloud Armor. CDN options include Amazon CloudFront, Azure Front Door, and Cloud CDN. These mappings are non-exclusive and must meet the same durable controls.

Implementation:

• WAF logs integrated with SIEM per ADR 007: Centralised Security Logging
• Default to fail secure. Document and pre-approve any emergency failure mode, including who may activate it, service and data scope, compensating monitoring and rate limits, maximum duration, notification, and review
• Regular penetration testing and rule tuning
• CI/CD integration for automated deployments
• Alert on direct-origin attempts, WAF bypass, material rule changes, and sustained blocking or rate-limit events

The WAF and CDN are compensating layers, not substitutes for patching, server hardening, application security testing, authentication, or secure coding.

Required Evidence

• Applicable edge, DDoS, WAF, TLS, origin-access, and security-header configuration, including the risk rationale where CDN or WAF is omitted
• Current Internet-facing service and origin inventory
• WAF rule tests, penetration-test results, and rule-tuning records
• Alerts and central logs for blocked traffic and configuration changes

Exceptions

Any public origin or service without its assessed edge controls, or use of an emergency failure mode beyond its approval, needs a time-bound exception that records compensating controls, residual risk, executive approval, expiry date, and reassessment date.

Consequences

Benefits:

• Automated threat detection and mitigation at network edge
• Content delivery and caching where the service needs them
• Reduced origin exposure through filtering
• Real-time traffic analysis and bot management

Risks if not implemented:

• Critical citizen services disrupted by attacks
• Direct server exposure to malicious traffic
• Slow response times affecting user adoption
• No early warning of emerging attack patterns

ADR 021: Workload mTLS and Service Authorisation

Status: Proposed | Date: 2026-07-11 | Review: 2027-07-11

Synopsis

• Use when: Protecting production application traffic between workloads on supported Kubernetes clusters.
• Avoid when: Traffic is outside the supported mesh scope or an existing cluster would switch directly to broad deny without flow inventory, compatibility testing, rollback, and break-glass preparation.
• Decision: Prefer Linkerd for Kubernetes workload identity and mTLS, then progress compatible services to explicit default-deny inbound authorisation tied to dedicated workload service accounts.
• Required evidence: Workload and flow inventory, version-controlled policy, positive and negative tests, health and certificate monitoring, and trust, performance, upgrade, and rollback records.
• Dependencies: ADR 001: Application Isolation, Proposed ADR 006: Automated Policy Enforcement, ADR 010: Infrastructure and Configuration as Code, and ADR 007: Centralised Security Logging.

Context

Private network location does not authenticate a workload or authorise a service call. Kubernetes pod addresses are ephemeral, shared clusters contain multiple trust boundaries, and network controls alone cannot express service or route identity reliably.

Internal service traffic needs authenticated workload identity, encryption in transit, explicit authorisation, and evidence that policy is enforced. Installing a service mesh is insufficient if plaintext remains accepted or all authenticated workloads can call every service.

• Linkerd automatic mTLS
• Linkerd authorization policy
• Linkerd CNI plugin
• Kubernetes NetworkPolicy

Applicability

Apply this ADR to production application traffic between workloads on supported Kubernetes clusters. Apply it to development and test environments where needed to validate production identity and policy.

Do not assume this ADR covers:

• Traffic to unmanaged external, SaaS, database, or legacy endpoints
• User authentication or application-level resource authorisation
• UDP, host-network, control-plane, or platform traffic that does not traverse the selected mesh
• Confidentiality from either authorised endpoint

System namespaces and third-party workloads should be meshed only after compatibility and support validation. Non-Kubernetes traffic needs an equivalent approved identity, mTLS, gateway, or application TLS design.

Decision

Use Linkerd as the preferred Kubernetes implementation for authenticated and encrypted service-to-service traffic. It provides a consistent implementation across Amazon EKS, Azure Kubernetes Service, Google Kubernetes Engine, and conformant Kubernetes platforms without selecting a provider-specific mesh.

Application namespaces must be meshed by default where compatibility is demonstrated. Production services must progress to default-deny inbound authorisation based on authenticated workload identity and explicitly approved traffic flows.

Workload Identity and mTLS

• Assign a dedicated Kubernetes ServiceAccount to each independently authorised workload; do not use the namespace default ServiceAccount for applications
• Bind mesh identity to the workload ServiceAccount and keep service identity stable across replica, node, and provider changes
• Require mTLS for traffic between meshed workloads and verify it from both traffic telemetry and negative tests
• Prevent plaintext access from non-meshed sources once a service enters enforcement
• Prohibit proxy bypass and skipped inbound ports unless documented and approved
• Use fail-closed admission for namespaces that require the mesh so a workload cannot start without its proxy; use the Linkerd CNI plugin where supported to avoid granting network-administration capability to application pods
• Treat mTLS as workload authentication and transport protection, not as user identity or business authorisation

Linkerd automatically uses mTLS between meshed pods, but its permissive defaults can accept plaintext from non-meshed sources. Each protected service therefore needs an enforced inbound policy, not only proxy injection.

Service Authorisation

Define policy from the approved service-flow matrix:

• Identify the destination workload, port, protocol, and route where applicable
• Allow only named source workload identities that need the operation
• Use Linkerd Server, HTTPRoute or GRPCRoute, MeshTLSAuthentication, and AuthorizationPolicy resources as appropriate
• Keep the default closed; do not use broad namespace or cluster authentication where specific workload identities are practical
• Authorise health probes, ingress, jobs, operators, and monitoring explicitly where their traffic differs from normal service calls
• Test alternate routes, direct pod access, old versions, and non-meshed clients to confirm they cannot bypass policy

Ingress traffic terminates at an approved gateway or ingress controller. Mesh the gateway where supported so gateway-to-service traffic uses an authenticated workload identity. Preserve and validate end-user identity separately at the application.

Defence in Depth

Linkerd policy complements rather than replaces:

• Default-deny Kubernetes NetworkPolicy under ADR 001: Application Isolation
• Cloud firewalls, routing, protective DNS, and flow controls under ADR 006: Automated Policy Enforcement
• Application authentication, operation and resource authorisation, and input validation
• TLS appropriate to external endpoints and protocols outside the mesh

NetworkPolicy limits reachable network paths. Mesh policy authenticates workload identity and authorises service traffic. Both are required for production application boundaries unless an approved equivalent control applies.

Trust and Certificate Operations

• Scope trust anchors to the smallest practical administrative and security domain; do not share a trust anchor across agencies or unrelated environments by default
• Protect trust-anchor and issuer material separately from application workloads
• Keep private key material out of OpenTofu or Terraform state
• Automate short-lived workload certificate issuance and issuer rotation, monitor all expiry dates, and test rollover before production
• Require an explicit trust, routing, failure, incident, and revocation design before enabling multi-cluster or non-Kubernetes mesh expansion
• Run the Linkerd control plane in its supported high-availability configuration for production, configure proxy injection to fail closed for protected namespaces, and test loss or degradation of control-plane and admission components

Policy Delivery and Observability

• Provision the cluster add-on and supporting infrastructure through OpenTofu or Terraform under ADR 010, using pinned and reviewed Linkerd and chart versions
• Keep workload injection, identity, server, route, authentication, and authorisation policy in version control with the owning platform or application configuration
• Validate policy in CI/CD and prevent production deployment of an application that should be meshed but lacks a proxy or required policy
• Export policy denials, proxy health, mTLS coverage, identity and certificate health, and service metrics to the monitoring controls in ADR 007
• Do not enable retries, timeouts, or traffic shifting globally without application testing; mesh and application retry behaviour can multiply load and failures

Adoption

1. Inventory service flows, ServiceAccounts, protocols, probes, ingress, jobs, and known direct or external clients.
2. Deploy Linkerd in a non-production cluster, validate protocol compatibility, capacity, latency, failure behaviour, proxy injection, and certificate operations.
3. Mesh selected namespaces and observe traffic before changing authorisation.
4. Define policies in audit mode, reconcile unexpected flows, and assign owners.
5. Enforce default-deny policy service by service, starting with new and higher-consequence workloads.
6. Validate mTLS and negative access tests, then expand coverage with a monitored rollback path.

Do not switch an existing cluster directly from permissive defaults to cluster-wide deny without a tested flow inventory, probe handling, break-glass path, and staged rollout.

Required Evidence

• Workload, ServiceAccount, namespace, and mesh-coverage inventory
• Approved service-flow matrix linked to version-controlled NetworkPolicy and Linkerd authorisation policy
• CI/CD checks showing required injection and policy are present
• Positive and negative connectivity tests, including proof that plaintext, unauthorised identities, and bypass paths are rejected
• mTLS coverage, policy-denial, proxy-health, and certificate-expiry monitoring
• Trust-anchor ownership, issuer rotation, rollover, recovery, and multi-cluster trust records where applicable
• Performance, capacity, upgrade, control-plane failure, and rollback test results

Exceptions

Unmeshed production application traffic, accepted plaintext, shared workload identity, broad authenticated access, skipped ports, or an alternative mesh requires a time-bound exception. Record compatibility constraints, affected flows and data, equivalent or compensating controls, residual risk, owner, executive approval, remediation date, expiry, and reassessment date.

Consequences

Benefits: workloads receive provider-neutral identity, automatic mTLS, explicit service authorisation, consistent telemetry, and policy evidence.

Trade-offs: every pod gains a proxy and policy dependency; certificate, control plane, protocol, capacity, upgrade, and troubleshooting responsibilities increase.

ADR 002: Managed Kubernetes for Compatible Workloads

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

Synopsis

• Use when: A compatible containerised bespoke workload has a justified need for Kubernetes scheduling, scaling, or ecosystem capabilities.
• Avoid when: The workload needs unsupported host privileges, specialist hardware, unvalidated state semantics, unavailable regional capabilities, or disproportionate platform overhead.
• Decision: Use managed Kubernetes with provider-managed compute only for validated compatible workloads, while preferring simpler supported hosting when it meets the need.
• Required evidence: Workload-fit, security, region, recovery, support, cost, exit, performance, resilience, scaling, and recovery assessments and tests.
• Dependencies: ADR 018: Managed Relational Databases and Open Lakehouses for durable database state, ADR 019: Shared File Access for shared file state, and Proposed ADR 021: Workload mTLS and Service Authorisation when relying on the preferred workload-security profile.

Context

WA public-sector estates span multiple clouds and legacy or on-premises platforms. Kubernetes can provide a consistent orchestration API for suitable bespoke software, but it adds cost and operational complexity and does not by itself make a workload portable.

• CNCF Certified Kubernetes conformance
• ACSC Guidelines for Cloud Security

Decision

Use a managed Kubernetes service with provider-managed compute as the default Kubernetes pattern only for compatible, containerised bespoke workloads. Do not use Kubernetes as the default hosting model for every application.

A workload is a suitable candidate when it can use supported containers, standard health and lifecycle controls, externalised durable state, and the service’s networking and identity model. The team must also have a justified need for Kubernetes scheduling, scaling, or ecosystem capabilities.

Prefer a simpler managed application, container, function, database, virtual machine, or existing supported platform when it meets the service need.

Exclusions

Do not select this pattern without an approved exception for:

• Commercial or legacy software that requires certified hosts, privileged access, unsupported kernels, fixed appliances, or in-place administration
• Workloads requiring mainframe integration, specialist hardware, disconnected operation, or latency that the managed service cannot meet
• Stateful software whose locking, storage, clustering, recovery, or licensing requirements have not been validated on the target service
• Small or stable services for which cluster and platform overhead is not proportionate
• Workloads whose required service, support tier, data location, or dependency is unavailable in an approved region

Keep durable state in an appropriate managed data service or tested shared file service. See ADR 018 and ADR 019.

Production application traffic crossing workload boundaries must use authenticated workload identity, encryption in transit, and explicit service authorisation where the platform supports them. Proposed ADR 021: Workload mTLS and Service Authorisation defines the preferred Linkerd implementation profile; a project must approve that Proposed dependency before relying on it. Validate sidecar, protocol, probe, capacity, and managed-compute compatibility during the workload-fit assessment.

Provider Options

These are implementation options, not interchangeable mandates:

For legacy or on-premises estates, retain an existing supported platform when migration has no service or risk benefit. A new self-managed Kubernetes platform requires a costed operating model for upgrades, security, recovery, capacity, and 24-hour support appropriate to service criticality.

Required Evidence

• Workload-fit assessment covering the exclusions, data classification, dependencies, availability, recovery, support, and team capability
• Region and feature availability, security assessment, and provider shared responsibility review
• Total-cost comparison including platform labour, observability, networking, support, data transfer, and minimum or idle capacity
• Exit assessment identifying provider-specific dependencies, portable images and manifests, data extraction, target platform, time, cost, and a tested redeployment or recovery path
• Performance, resilience, scaling, and recovery test results before production
• Service-flow, workload identity, encryption, and authorisation assessment, plus mesh compatibility where the project adopts proposed ADR 021

Exceptions

Record a time-bound exception when an excluded workload must use this pattern or when a compatible workload cannot use managed compute. Include the reason, alternatives, compensating controls, residual risk, owner, approval, expiry, and reassessment date.

Consequences

Benefits: managed infrastructure reduces routine node operations while standard Kubernetes APIs support common deployment practices.

Trade-offs: managed modes impose feature constraints, retain provider dependencies, and may cost more than simpler hosting or an existing platform.

ADR 006: Automated Policy Enforcement

Status: Proposed | Date: 2026-07-11 | Review: 2027-07-11

Synopsis

• Use when: Establishing automated governance, compliance, network, and policy controls across cloud, Kubernetes, SaaS, or legacy estates.
• Avoid when: Broad preventive or deny policies would be enabled before resources, dependencies, impact, rollback, and break-glass paths have been inventoried and tested.
• Decision: Implement provider-neutral governance capabilities through native enforcement points, version-controlled policy, staged audit-to-enforce adoption, drift management, and time-bound exceptions.
• Required evidence: Policy definitions and tests, approvals, inventory and drift reports, flow matrix, enforcement and break-glass results, and linked exceptions.
• Dependencies: Proposed ADR 021: Workload mTLS and Service Authorisation for Kubernetes workload controls, ADR 010: Infrastructure and Configuration as Code for provisioning, and ADR 007: Centralised Security Logging for telemetry.

Context

Governance must work across AWS, Azure, Google Cloud, and legacy or on-premises estates. Manual review does not scale, but enabling broad deny policies before understanding existing resources can disrupt essential services.

Decision

Implement provider-neutral governance capabilities and map them to the native controls of each estate. Required capabilities are:

• An organisation hierarchy, landing-zone baseline, approved regions and services, accountable ownership, and resource inventory
• Preventive controls for high-risk actions and detective controls with an owner and remediation deadline where prevention is not practical
• Version-controlled policy definitions, change review, policy testing, and validation in delivery pipelines
• Least privilege, encryption, required metadata, data-location restrictions, supported technology versions, and default-deny network boundaries with explicitly approved flows
• Approved protective DNS with blocked-request monitoring
• Continuous compliance reporting, drift detection, remediation, and time-bound exception handling

Provider Mapping

Native controls may be supplemented by policy-as-code and configuration tools for Kubernetes, SaaS, network appliances, servers, and other platforms that are outside a cloud organisation hierarchy.

For Kubernetes east-west traffic, enforce workload identity, mTLS, and explicit service authorisation under ADR 021: Workload mTLS and Service Authorisation. Mesh policy complements NetworkPolicy and cloud network controls rather than replacing them.

Provision and configure these native organisation controls through the preferred OpenTofu or Terraform workflow in ADR 010 where supported. The native service remains the enforcement point; the common infrastructure layer provides consistent review, plans, state, testing, and audit evidence across providers.

Network Controls

Transit services centralise routing; they do not automatically authorise or inspect traffic. Apply route controls, workload firewalls or security groups, DNS controls, and an inspection service where the risk assessment requires it. This applies to AWS Transit Gateway, Azure hub or Virtual WAN, Google Cloud Network Connectivity Center, and equivalent on-premises networks.

AWS VPC Flow Logs, Azure virtual network flow logs, and Google Cloud VPC Flow Logs record network-flow metadata subject to each service’s scope, aggregation, sampling, and delivery behaviour. They are not complete packet capture or proof of all egress. Combine relevant flow logs with firewall, DNS, proxy, identity, and application telemetry under ADR 007.

Adoption

1. Inventory resources, dependencies, existing exceptions, and policy impact.
2. Deploy new policies in test, dry-run, audit, or detective mode and assign remediation owners.
3. Remediate the baseline, then enforce high-confidence controls for new and changed resources with tested break-glass and rollback paths.
4. Expand enforcement in risk order and monitor denied actions, false positives, coverage gaps, and policy drift.

Emergency access and policy administration must be separated, strongly authenticated, logged, and regularly tested.

Required Evidence

• Version-controlled policy definitions, tests, approvals, and deployment history
• Current hierarchy, landing-zone, inventory, compliance, and drift reports
• Approved network-flow matrix and evidence from applicable firewall, DNS, flow-log, and inspection controls
• Audit-to-enforce results, remediation records, denied-action monitoring, and tested break-glass procedures
• Exception records linked to controls that remain non-compliant

Exceptions

Policy exclusions must be narrowly scoped and time-bound. Record the failed control, affected resources, compensating controls, residual risk, accountable owner, executive approval, expiry date, and reassessment date.

Consequences

Benefits: consistent controls reduce preventable misconfiguration and produce evidence across heterogeneous estates.

Trade-offs: staged adoption takes time, native policy semantics differ, and poorly tested preventive controls can interrupt services.

ADR 007: Centralised Security Logging

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

Synopsis

• Use when: Collecting, retaining, analysing, and operating security telemetry from cloud, SaaS, on-premises, or legacy services.
• Avoid when: Central forwarding is assumed to replace tested source retention, or collection unnecessarily exposes sensitive data.
• Decision: Collect and buffer events on source platforms, route security-relevant telemetry to the central analysis platform, and use risk-based logging profiles, detections, retention, and operating coverage.
• Required evidence: Source inventory, logging profiles, detection catalogue, parsing and end-to-end test records, access reviews, and tamper-protection evidence.
• Dependencies: None.

Context

Security monitoring requires reliable telemetry from cloud and legacy estates without unnecessarily collecting personal or sensitive information. Collection, analysis, retention, and operating coverage are separate capabilities.

• ACSC Guidelines for System Monitoring
• WA SOC Technical Baseline for Detection Coverage

Decision

Use source-platform logging services to collect and buffer events, then route security-relevant telemetry to the agency’s central analysis platform. Where WA Government SOC onboarding or agency direction applies, integrate with the WA SOC and use Microsoft Sentinel in accordance with the WA SOC Sentinel guidance.

Source Collection

Do not treat a native collector as the security analytics platform, or central forwarding as a replacement for source retention, until replay and recovery have been tested.

Service Logging Profile

Each service must maintain a risk-based profile that defines:

• Required security, audit, authentication, administrative, network, application, control-plane, endpoint, and data-access events
• Source and service owners, parsing and normalisation, time synchronisation, collection-health monitoring, and expected event volume
• Detection use cases, triage path, severity, response target, and operating coverage, including out-of-hours escalation for critical services
• Searchable and archive retention, retrieval time, records-disposal authority, investigation or legal holds, data location, privacy, and access controls

Retention and analyst coverage must follow service criticality, threat and investigation needs, WA SOC requirements, and agency record-keeping decisions; one period or operating model is not suitable for every log source.

Minimise personal and sensitive data. Where collection is necessary, restrict access and retention. Protect critical logs from alteration or deletion and separate log administration from workload administration.

Legacy Onboarding

Inventory legacy sources and onboard them in risk order. Start with identity, privileged access, internet gateways, critical servers, security controls, and high-value applications. Validate event completeness, timestamps, parsing, delivery under outage, buffering, duplicate handling, and collection-health alerts before relying on a source for detection.

Continuously analyse required events in Microsoft Sentinel where mandated, maintain documented detections and escalation paths, and test priority detections and WA SOC hand-offs at least annually and after material changes.

Required Evidence

• Current source inventory, logging profiles, owners, classification, retention, operating coverage, and collection-health status
• Detection catalogue mapped to priority threats and critical services
• Parsing and end-to-end event tests, outage or replay tests, alerts, triage, escalation, and annual detection-test records
• Access reviews and evidence that protected logs cannot be altered or deleted by workload administrators

Exceptions

Logging, retention, or monitoring gaps require a time-bound risk record naming affected threats and services, compensating telemetry, residual risk, owner, executive approval, expiry date, and reassessment date.

Consequences

Benefits: central analysis and tested source collection improve detection, investigation, and WA SOC coordination.

Trade-offs: broad collection can increase cost and privacy exposure, while legacy sources require engineering and ongoing health monitoring.

ADR 010: Infrastructure and Configuration as Code

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

Synopsis

• Use when: Provisioning or recovering cloud, network, identity, Kubernetes, operating-system, or supported platform configuration.
• Avoid when: Changes would remain manual, unreconciled, non-reproducible, or dependent on a developer workstation without recorded justification and equivalent controls.
• Decision: Manage infrastructure declaratively in version control, preferring OpenTofu or Terraform, with protected promotion, reviewed plans, secured state, drift detection, controlled imports, and tested recovery.
• Required evidence: Baselines, plans and approvals, artifact and dependency versions, state protection and recovery, import records, scans, and drift remediation.
• Dependencies: ADR 009: Release Standards for protected promotion of immutable configuration commits or artifacts.

Context

Cloud and legacy environments must be reproducible and recoverable without assuming one provider, repository layout, branch name, or release-tag scheme. Uncontrolled manual changes and insecure state create drift and recovery risk.

• OWASP Infrastructure as Code Security Cheat Sheet
• ACSC Guidelines for System Hardening

Decision

Manage infrastructure and supported platform configuration declaratively from version control. Scope includes cloud resources, networks, identity and policy assignments, Kubernetes resources, operating-system and platform baselines, and the configuration needed to recover a service.

Use OpenTofu or Terraform as the preferred infrastructure provisioning layer across cloud providers. Their mature provider ecosystems, declarative plans, state model, policy integration, import workflows, and common review experience provide a more consistent capability and audit trail than using a different proprietary framework for each provider.

Prefer OpenTofu for new implementations where its providers and ecosystem meet the requirement. Terraform remains supported where existing modules, managed services, vendor support, or organisational capability justify it.

Required Practices

1. Select a repository model by ownership and change coupling. Application, environment, and platform repositories may be separate; document how a released service resolves every required configuration version.
2. Promote an immutable commit or build artifact through environments using protected approvals under ADR 009. Tags and semantic versions are optional release mechanisms, not assumed requirements.
3. Validate syntax, security, policy, and supported-version baselines; produce a reviewed change plan before apply; record the apply result.
4. Detect drift. Automatically remediate high-risk drift only where the action and rollback are tested; otherwise alert an accountable owner.
5. Disable unnecessary services and insecure defaults, apply least privilege, and expose only approved interfaces.
6. Keep modules, providers, deployment tooling, and static artifacts pinned or otherwise reproducible. Test bootstrap and recovery without relying on a developer workstation.
7. Capture a saved, reviewed plan for controlled production changes and apply the approved plan or otherwise verify that the applied change matches review.
8. Keep reusable modules small, versioned, tested, and owned. Review provider and module provenance before adoption.

Environment names and their mapping to AWS accounts, Azure subscriptions, Google Cloud projects, clusters, or on-premises zones must be documented, but this ADR does not prescribe folder names or a one-account-per-folder layout.

State and Existing Resources

Store remote state with encryption, least-privilege access, concurrency control, version recovery, audit logging, and backup. Separate production state administration from ordinary workload access. Prevent secrets entering state where possible and protect unavoidable sensitive state as a secret.

Discover and import existing resources before bringing them under management. Review the import and a no-op baseline plan to ensure adoption will not replace, delete, or reset production resources. Reconcile unsupported settings and record resources that must remain outside declarative management. See the Terraform import workflow as one implementation example.

Native Frameworks and Bootstrap

Provider-native frameworks can be used where OpenTofu or Terraform lacks a required capability, where a managed service generates and controls the deployment, or to bootstrap the remote state, identity, and organisation foundations needed by the preferred layer. Record the reason and preserve equivalent review, plan, state, testing, and audit evidence.

Examples include AWS CloudFormation, Azure Bicep, and Google Cloud Infrastructure Manager. These are exception or bootstrap options, not the default delivery layer.

Use configuration-management and image-building tools alongside OpenTofu or Terraform for guest operating systems, network appliances, and legacy or on-premises platforms. Keep inventories versioned, changes idempotent, and recovery tested.

This ADR controls configuration deployment and drift. It does not by itself set vulnerability-scanning cadence, patch deadlines, or technology replacement plans.

Required Evidence

• Version-controlled baseline, environment mapping, approvals, plans, apply records, and resolved artifact versions for each production release
• OpenTofu or Terraform version, provider lock file, module versions, saved or reviewed production plan, and evidence that the approved change was applied
• State access configuration, audit records, backup, and successful state or control-plane recovery test
• Existing-resource inventory, import records, reviewed baseline plan, and exclusions from declarative management
• Security and policy results, drift findings, remediation records, and current supported-version settings

Exceptions

Use of a provider-native framework as the primary provisioning layer, emergency manual changes, or baseline deviations must be recorded and justified. Manual or out-of-band changes must be time-bound, monitored for drift, reconciled back into code where possible, and approved with compensating controls, residual risk, owner, expiry, and reassessment date.

Consequences

Benefits: reviewed, declarative configuration improves consistency, recoverability, and evidence across providers.

Trade-offs: importing existing estates is effortful, state is sensitive, and not every legacy interface can be safely automated.

ADR 014: Independent Backups and Recovery

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

Synopsis

• Use when: A service needs recoverable copies of data, configuration, software, keys, audit information, or other recovery dependencies.
• Avoid when: Replication, snapshots, versioning, point-in-time recovery, or immutability alone are being treated as an independent tested backup.
• Decision: Maintain at least one logically and administratively independent, retention-protected backup copy with separated access and a tested isolated restoration path.
• Required evidence: Backup inventory, independence and access design, encryption and key recovery, monitoring records, and annual and post-change restoration tests with measured RTO and RPO.
• Dependencies: None.

Context

Critical services require recoverable copies of data, software, configuration, keys, and security information. Geographic replication improves availability but can copy deletion, corruption, or malicious changes.

• ACSC Information Security Manual

Decision

Maintain at least one tested backup copy that is logically and administratively independent of the production workload. Protect that copy from alteration or deletion for its approved retention period, including by a compromised production administrator.

flowchart LR
    service[Production Service] -->|controlled backup| copy[Independent Backup Copy]
    copy -->|tested restore| recovery[Isolated Recovery Environment]

Replication, object versioning, snapshots, and database point-in-time recovery are useful availability or operational-recovery controls. None is a backup by itself unless the resulting copy has the required failure independence, retention protection, access separation, monitoring, and tested restore path. Immutability protects a retained copy; it does not create that copy.

Required Capabilities

• Coverage of all data and dependencies required for service recovery, including application data, file assets, infrastructure and deployment configuration, source or releasable artifacts, critical audit records, and separately recoverable keys or key procedures
• Encryption in transit and at rest, dedicated backup identities, strong authentication, least privilege, and separation of backup and workload administration
• Approved retention and disposal, legal or investigation holds, data classification and location, and storage separation based on correlated failure and jurisdiction risk
• Application-consistent recovery across interdependent stores and a clean, isolated restoration path
• Monitoring for backup, copy, retention, capacity, and restoration failures
• Recovery tests that validate service operation and include destructive or ransomware scenarios, not only object retrieval

Derive RTOs and RPOs from approved business continuity and service-criticality assessments. Configure backup frequency, transfer, retention, and restoration capacity to meet them. Cross-region or off-site copies are required when the continuity assessment identifies a site or regional failure risk, subject to approved data-location constraints.

Immutable Object Options

These controls can protect a backup target and are not complete backup solutions on their own:

Legacy and on-premises implementations may use supported object, appliance, tape, or offline media where they provide equivalent independence, retention, inventory, monitoring, and tested recovery.

Required Evidence

• Backup inventory mapped to services, data owners, classification, RTO, RPO, retention, disposal authority, dependencies, and storage locations
• Architecture and configuration showing copy independence, encryption, immutable retention, key recovery, and separate administrative access
• Backup and copy success records, failed-job alerts, capacity monitoring, and reconciliation showing expected recovery points are present
• At least annual restore and ransomware-recovery test results, and tests after material recovery-architecture changes, with measured RTO and recovered RPO

Exceptions

Where an independent or immutable backup cannot be implemented, record the missing control, recovery impact, compensating controls, residual risk, owner, executive approval, expiry date, and reassessment date.

Consequences

Benefits: independent, tested copies reduce correlated failure and ransomware risk and provide defensible recovery evidence.

Trade-offs: protected copies, separate administration, data transfer, and realistic recovery tests add cost and operational effort.

ADR 015: Data Pipeline Contracts, Quality and Lineage

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

Synopsis

• Use when: Operating production data pipelines that publish transformed data to consumers.
• Avoid when: Git history is being substituted for runtime lineage or invalid records would be silently discarded without reconciliation and replay.
• Decision: Require versioned contracts, measurable quality thresholds, fail-safe publication, quarantined-record handling, and authoritative runtime lineage independent of tool or cloud choice.
• Required evidence: Approved contracts, quality and reconciliation results, quarantine and replay records, sampled end-to-end lineage, and transformation approvals.
• Dependencies: ADR 007: Centralised Security Logging for pipeline operational and quality events.

Context

Data pipelines need explicit interfaces, measurable quality, and evidence of what actually ran. Source history describes intended transformations but does not prove runtime lineage or that failed records were handled.

• Australian Government Data Governance Framework
• Reference Architecture: Data Pipelines

Decision

Implement versioned data contracts, quality controls, and runtime lineage for production data pipelines. The requirements are independent of transformation, catalogue, cloud, and query-engine choices.

Pipeline Requirements

• Define contracts for input and output schema, types, meaning, owner, compatibility, keys, freshness, and expected delivery behaviour
• Set approved, measurable thresholds for completeness, validity, uniqueness, referential integrity, timeliness, and volume where relevant; identify which failures warn, quarantine data, or stop publication
• Capture runtime lineage from authoritative inputs through each executed job to published outputs, including run identifier, code and contract version, parameters, timestamps, and source or snapshot identifiers
• Treat Git history as design evidence, not a substitute for runtime lineage
• Quarantine or dead-letter invalid records without silently dropping them; preserve reason codes, counts, secure access, retry or replay paths, owner alerts, and reconciliation to accepted, rejected, and published totals
• Send pipeline operations and quality events to the controls in ADR 007, without exposing sensitive record contents

Contracts must have a documented compatibility and consumer-notification process. Production publication must fail safely when a blocking threshold or contract check fails.

Implementation Options

Ibis expressions are one code-based transformation and validation example, not a mandated governance or lineage platform. Microsoft Purview data governance and Dataplex data lineage are provider options where they fit the estate. Teams may use other tools that capture equivalent runtime evidence and interoperable exports.

This ADR does not replace agency controls for information classification, privacy assessment, records retention and disposal, offshoring, access, or data-location approval.

Required Evidence

• Approved, versioned contracts and compatibility or consumer-change records
• Quality rules, thresholds, run results, alerts, quarantined-record counts, reconciliation, and replay or disposition records
• Queryable runtime lineage from authoritative source to published output for sampled production runs
• Transformation versions, approvals, audit events, and access controls for sensitive quality and lineage metadata

Exceptions

Missing contracts, quality checks, or runtime lineage require a time-bound record of affected datasets and consumers, compensating reconciliation, residual risk, owner, approval, expiry, and reassessment date.

Consequences

Benefits: explicit contracts and runtime evidence make data failures detectable, containable, and traceable across platforms.

Trade-offs: thresholds require ownership and tuning, while lineage and failed-record handling add storage and operational complexity.

ADR 017: Reproducible Analytical Publications

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

Synopsis

• Use when: Publishing a controlled analytical output built from versioned narrative and code as HTML, a document, a presentation, or a bounded report.
• Avoid when: The requirement is governed enterprise business intelligence, real-time operational monitoring, broad self-service analytics, row-level security, or application-style interaction.
• Decision: Use Quarto by default only for suitable reproducible publications, with controlled builds, pinned inputs, retained artifacts, disclosure controls, accessibility testing, and approved publishing paths.
• Required evidence: Suitability decision, reproducible build records, calculation and disclosure reviews, accessibility tests, publishing approval, and retention decision.
• Dependencies: ADR 016: Web Application Edge Protection for public HTML hosting.

Context

Some analytical outputs combine narrative, code, tables, and charts and need a reviewable, reproducible publication process. Enterprise BI, operational dashboards, self-service exploration, and transactional applications have different governance and interaction needs.

• Quarto documentation
• Australian Government Digital Service Standard

Decision

Use Quarto as the default only for suitable reproducible analytical publications: outputs built from versioned narrative and code, generated on a controlled schedule or release, and delivered as HTML, documents, presentations, or bounded interactive reports.

Do not require Quarto for governed enterprise BI, real-time operational monitoring, broad self-service analytics, or applications that need row-level security and interactive workflows. Select an approved BI, dashboard, or application platform for those needs and document its governance and evidence.

Publication Requirements

• Pin or record source code, dependencies, build image or environment, parameters, and source-data snapshot, query, or release identifier
• Build through reviewed automation, retain the generated artifact and build log, and record the source commit and artifact hash
• Keep secrets and classified or personal source data out of repositories, build logs, and published artifacts; apply disclosure and small-cell checks where relevant
• Test calculations, failed builds, links, rendering, and representative historical rebuilds

Quarto provides accessibility authoring features, but it does not make every output WCAG conformant. Follow the Quarto HTML accessibility guidance and test the final format against applicable accessibility requirements, including manual keyboard, screen-reader, structure, colour, and alternative text checks. PDF and office-document outputs may need separate remediation.

Publishing Paths

Publish public HTML only through an approved public hosting and edge path under ADR 016. Publish internal, sensitive, or classified outputs only to an approved access-controlled environment at the required classification, with identity, audit, retention, download, and sharing controls. Do not use a public static-hosting path for those outputs.

Required Evidence

• Suitability decision showing why Quarto or another analytics platform fits
• Source and dependency versions, data identifier, parameters, build logs, artifact hash, approvals, and a successful reproducibility test
• Calculation tests, accessibility assessment and remediation, disclosure review, and publishing access or classification approval
• Retention and disposal decision for source, build evidence, and publications

Exceptions

Non-reproducible builds, inaccessible formats, or publication outside the approved path require a time-bound record of need, audience, compensating controls, residual risk, owner, approval, expiry, and reassessment date.

Consequences

Benefits: suitable publications are reviewable, portable, and reproducible without imposing one tool on all analytics.

Trade-offs: controlled builds and accessibility testing require effort, and Quarto does not replace governed BI or secure content-management capabilities.

ADR 018: Managed Relational Databases and Open Lakehouses

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

Synopsis

• Use when: Selecting transactional database hosting or an analytical lakehouse pattern across cloud or legacy estates.
• Avoid when: Durable database state would be kept in Kubernetes, a transactional database would become the default data lake, or managed snapshots would be treated as complete backup compliance.
• Decision: Prefer evidence-selected managed relational services for new transactional workloads and decoupled open-format lakehouse components for analytical workloads, while retaining viable supported legacy databases.
• Required evidence: Selection and exit record, performance and recovery tests, independent backup evidence, lakehouse interoperability and lineage, and migration reconciliation.
• Dependencies: ADR 014: Independent Backups and Recovery for independent copies and tested restoration.

Context

Transactional applications and analytical platforms need different data patterns. The selection must work across AWS, Azure, Google Cloud, and legacy estates without mandating one database product or claiming that a managed feature satisfies every operational or compliance control.

Decision

Prefer a supported managed relational database for new transactional workloads when it meets functional, security, region, recovery, cost, and exit needs. Keep durable database state outside Kubernetes. Existing supported databases may remain where migration risk or cost outweighs the benefit and an adequate operating and recovery model exists.

Select the engine and service using tested requirements for SQL and extension compatibility, consistency, availability, maintenance, private connectivity, identity, encryption, observability, capacity, latency, Australian-region and data-location needs, support, total cost, and data export.

Connection pooling is a separate design decision. Use and test a service, proxy, or application pool only when workload concurrency requires it; do not assume every managed database includes suitable pooling.

Managed snapshots and point-in-time recovery support operational recovery but do not by themselves prove backup or retention compliance. Apply the independent-copy and restore-test requirements in ADR 014.

Open Lakehouse Pattern

For analytical data, separate object storage, open table format, catalogue, governance, and query or processing engines. Prefer open formats, such as Apache Iceberg, where they meet interoperability and lifecycle needs. Select engines by concurrency, update semantics, workload size, cost, support, and portability rather than using a transactional database as a default data lake.

DuckLake with DuckDB is an option for lightweight, local, or scheduled analytical workloads. Distributed or managed engines are appropriate when concurrency, scale, governance, or operating support requires them.

Provider Examples

Products are options rather than exact equivalents; validate current region, engine, feature, and open-format support.

Migration

Before migration, inventory schemas, data types, extensions, collation, stored code, clients, integrations, availability and recovery behaviour, performance, and licensing. Pilot representative load; define data reconciliation, cutover, rollback, and coexistence; test restore and export; then remove old copies and access only after acceptance and retention requirements are met.

Required Evidence

• Selection record covering requirements, provider and region fit, security, availability, support, total cost, and exit or export path
• Performance, failover, connection, maintenance, restore, and recovery test results against approved service objectives
• Backup evidence under ADR 014 rather than reliance on a feature declaration
• For lakehouses, table-format and catalogue ownership, interoperability and schema-evolution tests, lineage, retention, and engine compatibility
• Migration reconciliation, rollback test, approvals, and decommission record

Exceptions

Self-managed databases, closed analytical formats, unavailable independent backups, or unmet region and exit requirements need a time-bound exception with alternatives, compensating controls, residual risk, owner, approval, expiry, and reassessment date.

Consequences

Benefits: services are selected by workload evidence while open analytical formats reduce unnecessary engine coupling.

Trade-offs: portability is not automatic, managed products differ, and migration and independent recovery still require engineering and testing.

ADR 019: Shared File Access

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

Synopsis

• Use when: An application needs object-backed file access or true managed NFS or SMB semantics.
• Avoid when: An object adapter has not demonstrated required locking, atomicity, metadata, concurrency, or consistency semantics, or the design creates uncontrolled dual canonical stores.
• Decision: Select an object-backed adapter or managed file service using representative semantic testing, define one canonical store, and apply explicit access, lifecycle, recovery, and migration controls.
• Required evidence: Canonical-store decision, semantic and performance tests, access and lifecycle controls, backup and restore results, and migration reconciliation and rollback records.
• Dependencies: ADR 016: Web Application Edge Protection for public delivery and ADR 014: Independent Backups and Recovery for recovery.

Context

Applications may need object access, file paths, NFS or SMB protocols, or specific file-system semantics. Treating an object-backed adapter as a general network file system can cause corruption or incompatibility, while copying data between object and file stores creates synchronisation and ownership risk.

Decision

Choose between an object-backed file adapter and a true managed NFS or SMB file service using tested application semantics.

Use an object-backed adapter when object storage is the canonical source, the application tolerates the adapter’s consistency and metadata model, and testing confirms its file-operation, concurrency, latency, and failure behaviour. This can suit media, static assets, exchange areas, and batch or AI/ML datasets.

Use a managed file service when software requires documented POSIX or Windows semantics, file or byte-range locking, atomic operations, in-place writes, stable low-latency metadata, protocol-specific ACLs, or vendor-certified NFS or SMB storage. Keep a file service as the canonical source unless a tested synchronisation design defines otherwise.

Provider Options

These products are not exact equivalents. Protocol versions, POSIX behaviour, locking, identity and ACL models, consistency, quotas, performance, Kubernetes drivers, regional availability, and object interoperability differ.

Legacy or on-premises file services may remain when supported and when their security, availability, capacity, backup, and recovery controls meet the service need.

Validation Requirements

Test representative clients and concurrent workloads for open, create, close, append, overwrite, rename, delete, directory listing, locking, atomicity, consistency, links where required, permissions, case handling, file names, large and small files, throughput, metadata latency, disconnect and retry, capacity limits, and backup or restore behaviour.

Define the canonical store, owner, access boundary, lifecycle, retention, recovery objectives, and public-delivery path. Use workload identity and least privilege. Publish public assets through an approved CDN and edge control under ADR 016.

Snapshots, replication, synchronisation, and object versioning are recovery or availability features, not automatically independent backups. Immutability can protect a retained copy but does not create one. Apply ADR 014 to both object-backed and managed file stores.

Migration

Inventory required semantics, permissions, ownership, metadata, links, sizes, and access patterns before selecting a target. Pilot representative workloads, copy with checksums and count reconciliation, preserve required metadata, freeze or control writes for cutover, run application acceptance and recovery tests, and retain a documented rollback path. Avoid uncontrolled dual writes.

Required Evidence

• Decision record identifying canonical storage and why the tested adapter or file service meets application semantics and provider or region constraints
• Functional, concurrency, reconnect, performance, capacity, and recovery test results from representative clients
• Access, encryption, audit, lifecycle, retention, data-location, RTO, RPO, and independent-backup configuration and restore evidence
• Migration inventory, checksum and count reconciliation, acceptance, rollback, and source decommission or retention records

Exceptions

Untested semantics, dual canonical stores, unsupported protocols, or missing independent backup require a time-bound exception with compensating controls, residual risk, owner, approval, expiry date, and reassessment date.

Consequences

Benefits: evidence-based selection avoids assuming object and file semantics are interchangeable and reduces unnecessary duplication.

Trade-offs: testing and migration take effort, and true file semantics can reduce object interoperability or increase cost.

ADR 003: HTTP API Contract Standards

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

Synopsis

• Use when: Creating or materially changing an agency-controlled public, partner, administrative, or service-to-service HTTP API.
• Avoid when: The interface is non-HTTP, GraphQL, an event stream, a static route, a non-business health probe, or an unchangeable third-party API.
• Decision: Maintain a version-controlled machine-readable HTTP contract, preferably OpenAPI, with compatibility conventions and automated contract, behaviour, and risk-based security testing.
• Required evidence: Contract and compatibility policy, CI/CD test results, applicable exposure approval, and breaking-change migration records.
• Dependencies: None.

Context

HTTP APIs need stable, discoverable contracts so consumers can integrate safely and teams can test security and compatibility. Existing domain or protocol standards should be preferred over bespoke HTTP APIs where they meet the service need.

Compliance Requirements:

• ACSC Software Development Guidelines
• OWASP API Security
• OpenAPI Specification

Decision

Applicability

This ADR applies to new or materially changed HTTP APIs controlled by the agency, including public, partner, administrative, and service-to-service APIs. The depth of documentation and testing should reflect the API’s consumers, data sensitivity, and operational risk.

It does not require OpenAPI for non-HTTP protocols, event streams, GraphQL schemas, static web routes, health probes with no business contract, or third-party APIs the agency cannot change. Use the applicable protocol-native contract for those interfaces. This ADR does not mandate REST, public documentation, an API gateway, or a particular framework or test product.

API Requirements

Applicable APIs must have automated contract conformance, behaviour, and security testing in CI/CD.

Development Guidelines

• Prefer contract-first development or frameworks that generate the contract from code, provided the published contract is reviewed and tested for drift.
• Prefer standard data types and formats over custom encodings.
• Separate APIs by purpose and trust boundary where this reduces privilege or exposure (see Reference Architecture: OpenAPI Backend).
• Use any maintained tools that satisfy the testing requirement. Examples include Restish, framework-native tests, schema validators, fuzzers, and dynamic security test tools.
• Frameworks such as Huma and Litestar are implementation examples, not requirements.

API Development Flow:

flowchart LR
    contract[Machine-readable Contract]
    implementation[Implementation]
    testing[Automated Tests]

    contract --> implementation
    contract --> testing
    implementation --> testing

Generate or maintain the contract with the implementation, then validate both with automated contract, security, and behaviour tests.

Legacy Adoption

Existing APIs do not need a disruptive rewrite. Inventory consumers and sensitive operations first, capture the current contract, add tests around high-risk and frequently changed behaviour, and address drift through normal change delivery. Record a prioritised improvement plan for material gaps.

Required Evidence

• Version-controlled contract and compatibility or deprecation policy
• CI/CD results for contract, behaviour, and security tests
• Security review and approved exposure design for Internet-accessible administrative operations
• Consumer communication and migration evidence for breaking changes

Exceptions

Where OpenAPI cannot accurately describe an applicable HTTP API, record the reason and use a maintained machine-readable alternative where available. Deferring a required contract, test, or exposure control requires documented scope, consumer and security impact, compensating controls, accountable approval, an expiry date, and a remediation plan.

Consequences

Benefits:

• Consistent, testable API contracts
• Enhanced security through consistent validation patterns
• Reduced integration and maintenance overhead through automated testing

Risks if not implemented:

• Documentation drift creating integration difficulties
• Security vulnerabilities from inconsistent API patterns
• Increased development time debugging undocumented APIs

ADR 004: CI/CD Quality Assurance

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

Synopsis

• Use when: A pipeline builds, tests, packages, releases, or deploys agency software.
• Avoid when: A documentation-only repository or unreleasable prototype has an approved reduced pipeline, or CI/CD is being treated as a substitute for operational vulnerability management.
• Decision: Use repeatable, security-gated pipelines that produce immutable releases with testing, scanning, a software bill of materials, provenance, protected environments, and short-lived cloud privilege.
• Required evidence: Pipeline and branch controls, test and scan results, software bill of materials, provenance, approvals, and linked exceptions.
• Dependencies: ADR 003: HTTP API Contract Standards for applicable API testing and ADR 010: Infrastructure and Configuration as Code for infrastructure delivery.

Context

Ensure security and integrity of software artifacts that are consumed by infrastructure repositories per ADR 010. Threat actors exploit vulnerabilities in code, dependencies, container images, and exposed secrets.

Compliance Requirements:

• OWASP CI/CD Security
• ACSC Software Development Guidelines

Decision

Applicability

This ADR applies to pipelines that build, test, package, release, or deploy agency software. Controls should be proportionate to artifact type, exposure, data sensitivity, and deployment privilege. Documentation-only repositories and short-lived prototypes that cannot be released may use a reduced pipeline approved by the repository owner.

It does not mandate a CI/CD platform, cloud provider, container format, or deployment service. It controls build-time and released-artifact assurance; it does not replace deployed asset discovery, patching, endpoint application control, or operational vulnerability management.

CI/CD Pipeline Requirements

Pipeline Flow: Code Commit → Build & Test → Quality Assurance → Release

Mandatory security checks must fail the pipeline when an artifact contains an unapproved critical finding, a confirmed secret, an applicable unsupported runtime or base image, or incomplete provenance. A documented, time-bound exception is required before release when a finding cannot be remediated within the applicable agency or ACSC timeframe.

Execution Environment

• Pin a consistent local and CI toolchain. The WA Government devcontainer-base is one option.
• Define repeatable build and task commands. Docker Bake and Just are examples.
• Keep unprivileged build, test, and scan work on an agency-approved CI platform. GitHub Actions and Woodpecker CI are examples.
• Run cloud-privileged release and deployment steps only in an agency-approved trust boundary with protected environments, short-lived identity, and operations-controlled production access.

Cloud-Privileged Automation

Keep privileged steps separate from general CI where release or deployment needs cloud credentials or direct access to protected systems. Repository-hosted or self-hosted automation may be used where it meets the required trust, identity, network, approval, and audit controls.

Required controls:

• Obtain short-lived, least-privilege workload credentials at runtime; do not store long-lived cloud credentials in pipeline systems where federation or managed identity is supported
• Use dedicated, operations-managed hosts or workloads where the risk assessment requires isolation
• Limit network access to the cloud services and internal systems required for the job
• Apply strong access control, audit logging, and minimal administrative access
• Keep build, release, and deployment logs for audit and incident review
• Separate development, test, release, and production roles; developers must not use standing production deployment credentials
• Pin and verify third-party actions, dependencies, build images, and release artifacts using immutable versions and integrity information
• Generate and retain a Software Bill of Materials (SBOM) and build provenance for every released artifact
• Continuously rescan supported release artifacts and dependencies so newly disclosed vulnerabilities enter the vulnerability-management process

Official cloud-native options include:

These products are examples, not requirements. Equivalent approved services may be used when they provide the same identity, approval, integrity, and audit controls.

CI/CD Pipeline:

flowchart LR
    code[Code Commit]
    build[Build]
    scan[Scan + Analyse]
    release[Release]

    code --> build --> scan --> release

Build produces release artifacts with SBOM/provenance. Scan runs vulnerability and static analysis. Release publishes immutable artifacts consumed by ADR 010: Infrastructure as Code. Keep unprivileged build, test, and scan work on general CI, including long-running jobs. Isolate only the cloud-privileged release or deployment steps that need the stronger trust boundary.

Legacy Adoption

Existing pipelines should first inventory release paths and credentials, remove standing production credentials, and protect deployment environments. Introduce artifact integrity, security gates, SBOM/provenance, and broader testing in a risk-prioritised plan rather than blocking all legacy releases at once.

Required Evidence

• Pipeline definitions and protected-branch settings
• Scan, test, secret-detection, SBOM, and provenance results for each release
• Approval and deployment records demonstrating role and environment separation
• Linked vulnerability or exception record for any accepted finding

Exceptions

Bypassing a mandatory security gate requires compensating controls, residual risk, accountable executive approval, an expiry date, and a linked remediation plan. Emergency releases must run deferred checks immediately after deployment.

Consequences

Benefits:

• Automated security scanning and vulnerability remediation
• Standardised artifact integrity and compliance alignment
• Consistent deployment pipelines with audit trails
• Clear separation between general CI checks and cloud-privileged automation

Risks if not implemented:

• Vulnerable containers deployed to production
• Exposed secrets or excessive cloud privilege in automation systems
• Manual security processes prone to human error
• Compliance violations and audit failures

References

• ADR 003: HTTP API Contract Standards
• ADR 010: Infrastructure as Code

ADR 009: Release Standards

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

Synopsis

• Use when: Releasing deployable agency software or packaged artifacts.
• Avoid when: Applying the full process unchanged to documentation-only changes or unreleased prototypes, or rebuilding an artifact between user acceptance testing and production.
• Decision: Use Markdown release notes, protected source-control workflows, immutable identifiers, and promotion of the same digest-identified artifact from testing to production.
• Required evidence: Release identifier, digest, source revision, approvals, tests, scans, release notes, promotion record, and linked exceptions.
• Dependencies: ADR 007: Centralised Security Logging for release change tracking.

Context

Release notes should be standardised so security and infrastructure operations teams can quickly understand what changed, why it changed, and what action is required.

Release standards also need a clear promotion model. Without one, integrated code can be released before testing is complete, rebuilt differently between environments, or detached from its release evidence.

Compliance Requirements:

• Australian Cyber Security Centre (ACSC) Guidelines for Software Development

Decision

Use Markdown release notes, protected source-control workflows, and immutable artifact promotion.

Applicability

This ADR applies to deployable software and packaged artifacts produced by the agency. Release-note depth and approval should be proportionate to operational and consumer impact. Documentation-only changes and unreleased prototypes may use a lighter process defined by the repository owner.

It does not mandate a repository host, release cadence, branching model, or semantic versioning. It also does not replace agency change-management or emergency-response procedures.

Release notes must include:

• Summary of features, fixes, security updates, and infrastructure changes
• Security and operational impacts, including deployment, logging, monitoring, and Infrastructure as Code (IaC) changes
• Links to changelogs, test results, security scans, and approvals

Protected Release Workflow

Teams may use protected Gitflow, GitHub Flow, or trunk-based development when the chosen strategy provides:

• Protected release branches or refs with reviewed changes and required checks
• Traceability from source revision to build, approvals, artifact digest, and deployment
• An expedited, controlled path for urgent fixes without bypassing required evidence
• Least-privilege release rights and separation of production approval where required by risk or agency policy

Gitflow, GitHub Flow, and trunk-based development are examples, not additional requirements.

Use a documented, immutable release identifier. Use Semantic Versioning where major, minor, and patch changes communicate meaningful compatibility to consumers, such as for libraries or versioned APIs. Other services may use a documented date, build, or release-number scheme.

Environment promotion:

• DEV and integration environments may deploy approved source revisions or release candidates.
• UAT and production must deploy an approved immutable artifact identified by its cryptographic digest, not by a mutable tag alone.
• Promote the same tested artifact digest from UAT to production without rebuilding.
• Keep the release identifier, source revision, artifact digest, evidence, and deployment record linked. Evidence may be recorded in the repository, release service, or agency change system without altering the released artifact.
• Use the expedited release path for security remediations within the applicable agency or ACSC patching timeframe; record the vulnerability, severity, decision date, deployment time, and affected versions
• Do not treat the release-note template as a substitute for the current policy timeframe or a risk-based vulnerability decision

A template is provided below that can be tailored per project. A completed release notes Markdown document should be provided with all proposed changes.

## Release Notes

### Overview

- **Name:** Name
- **Version:** [Version Number](#)
- **Previous Version:** [Version Number](#)

### Changes and Testing

High level summary

**New Features & Improvements**:

- [Feature/Improvement 1]: Brief description including testing.
- [Feature/Improvement 2]: Brief description including testing.

**Bug Fixes & Security Updates**:

- [Bug Fix/Security Update 1]: Brief description with severity level and response timeline.
- [Bug Fix/Security Update 2]: Brief description with severity level and response timeline.
- **Required Timeline**: [Applicable policy or approved risk deadline]

### Changelogs

*Only include list items changed by this release*

- **Code**: Brief description. [View Changes](#)
- **Infrastructure**: Brief description. [View Changes](#)
- **Configuration & Secrets**: Brief description.

### Known Issues

- [Known Issue 1]: Brief description.
- [Known Issue 2]: Brief description.

### Action Required

- [Action 1]: Brief description of any action required by users or stakeholders.
- [Action 2]: Brief description of any action required by users or stakeholders.

### Contact

For any questions or issues, please contact [Contact Information].

Required Evidence

• Immutable release identifier, artifact digest, source revision, approvals, test and scan results
• Release notes identifying security fixes and affected versions
• UAT-to-production promotion record demonstrating no rebuild
• Linked risk acceptance for deferred remediation

Exceptions

Deferred security releases require compensating controls, residual risk, accountable executive approval, expiry date, and a scheduled remediation release. Where a legacy platform cannot promote the same artifact without rebuilding, record the technical constraint, compare resulting artifacts, retain both digests, and maintain a time-bound migration plan approved by the service owner.

Legacy Adoption

Existing services should first protect their release refs, link deployments to source revisions, and record artifact digests. Then remove environment-specific rebuilds and improve release notes and approvals through a prioritised migration plan. A branching-model migration is not required where the current protected workflow satisfies this ADR.

Consequences

Benefits:

• Release communication is consistent across teams
• Teams can retain a branching strategy suited to their delivery context
• UAT and production promotion uses immutable artifact digests
• Change tracking supports ADR 007: Centralised Security Logging

Risks if not implemented:

• Critical release information may be lost between teams
• Integration changes may be promoted before release validation is complete
• Security or operational issues may be introduced through undocumented system changes

ADR 020: Frontend UI Foundations

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

Synopsis

• Use when: Building or materially changing public or staff-facing websites, portals, content-management templates, previews, or embedded web widgets.
• Avoid when: The interface is native, an email or document, a specialised visualisation, an unchangeable vendor interface, or a functioning legacy interface that would be replaced only to adopt a component library.
• Decision: Use the applicable government design system first, otherwise use semantic HTML and an approved component approach, with WCAG 2.2 AA and user research governing outcomes.
• Required evidence: Design-system decision, user research, accessibility results, browser and device tests, and any approved improvement plan or exception.
• Dependencies: None.

Context

WA Government digital services need accessible, consistent web interfaces across public sites, portals, CMS templates, preview tools, widgets, and staff applications. Teams also need UI patterns that work with agency design systems, third-party widgets, and independently delivered applications.

Interfaces must reflect applicable agency standards, use the web platform well, and be informed by the people who use the service. A component library can support this work but cannot establish accessibility, usability, or policy compliance by itself.

Decision

Use the applicable agency or whole-of-government design system as the primary frontend foundation. Where no design system is mandated, use semantic HTML and an agency-approved component approach. Bootstrap 5 is an approved fallback option, not a requirement, where it fits the product and no mandated design system applies.

This means teams should:

• Confirm and apply the relevant design system, brand, content, and digital-service requirements before selecting implementation products
• Start with semantic HTML, accessible names, keyboard support, and progressive enhancement
• Meet WCAG 2.2 AA for user-facing web interfaces
• Conduct proportionate user research and usability testing, including people with disability and users at risk of digital exclusion where relevant
• Reuse approved accessible components before creating new variants
• Scope CSS and JavaScript so shared components work safely in CMS templates, portals, embedded apps, and third-party widget contexts
• Keep design-system styling separate from business logic and service APIs

Record the design-system applicability decision and any approved fallback in the project decision log.

Applicability and Non-Goals

This ADR applies to public and staff-facing web interfaces, including sites, portals, CMS templates, previews, and embedded widgets. Research and assurance depth should reflect user impact, transaction risk, audience diversity, and change scope.

Native applications should follow the applicable native and agency design system. Emails, documents, data visualisations, and vendor interfaces that cannot be changed need their own accessibility controls. This ADR does not mandate visual uniformity, a JavaScript framework, a static-site generator, or replacement of a functioning legacy interface solely to adopt a component library.

Implementation Examples

Products in this table are implementation examples, not standards.

Static Preview Example

Hugo can provide local builds and generated static outputs when a static site generator is sufficient for previews, documentation, or review packs.

Its content adapters can create pages from existing content libraries or read-only exports such as JSON, TOML, YAML, or XML. This lets teams build CMS-aligned previews without changing the CMS workflow first.

Docsy is one optional reference theme for technical documentation and review sites.

Accessibility Expectations

Design systems and component libraries can help with accessible patterns, but the finished interface must be tested against WCAG 2.2 AA. Testing should combine automated checks with keyboard, browser, and assistive-technology review, including:

• Keyboard operation and visible focus
• Colour contrast and non-colour cues
• Accessible names, labels, and error messages
• Heading, landmark, table, and form structure
• Reduced-motion behaviour where animation is used
• Screen-reader behaviour for dynamic components such as modals, alerts, and menus

Required Evidence

• Design-system applicability decision and approval for any fallback
• User-research findings, tested journeys, and resulting design decisions
• Automated and manual accessibility results for representative pages and states
• Component, browser, and device test results proportionate to supported users
• Improvement plan or approved exception for known material gaps

Exceptions

A deviation from a mandated design system or an unresolved WCAG 2.2 AA issue requires documented user impact, policy or legal review where applicable, compensating controls or an accessible alternative, accountable approval, an expiry date, and a remediation plan. Product limitations alone do not demonstrate accessibility.

Legacy Adoption

Legacy services do not need a wholesale redesign. Inventory templates, components, and critical journeys; fix barriers with the greatest user impact first; and require new or materially changed interfaces to follow this ADR. Track remaining material gaps in a prioritised, time-bound improvement plan informed by user feedback.

Consequences

Benefits:

• Gives teams a clear hierarchy for frontend decisions
• Improves portability across CMS, portal, preview, and standalone tool contexts
• Supports accessible, semantic, progressively enhanced interfaces
• Reduces bespoke component maintenance
• Prioritises agency consistency and evidence from users

Trade-offs:

• Design-system components still need accessibility and usability review in context
• Some products will need documented alternatives for native, highly bespoke, or specialist user interfaces
• Research, content design, and testing require ongoing delivery effort

Related Reference Architectures

• AI-Assisted Digital Services
• Content Management
• Federated Application Portal

References

• Bootstrap 5 documentation
• Bootstrap 5 accessibility guidance
• Digital Service Standard
• HTML Standard semantics
• Web Content Accessibility Guidelines 2.2
• Hugo content adapters
• Docsy Hugo theme
• Drupal Bootstrap 5 theme

Reference Architecture: Content Management

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

Purpose

This informative reference architecture composes existing ADRs for agencies of different sizes, delivery models, and legacy estates. It does not select a CMS, require a cloud migration, or create new mandatory controls. ADRs identified as Proposed below are proposed dependencies, not accepted requirements.

Applicability and Non-Goals

Use this pattern for public websites, intranets, content portals, headless or multi-channel content, editorial workflows, and static publishing that needs content ownership, review, repeatable release, or lifecycle management.

A simple site can use only the static-publishing capabilities. A SaaS CMS or a supported legacy platform can satisfy the pattern without reproducing every component in the diagrams.

This pattern is not a case-management or transactional system, records management system, general document repository, digital-asset-management standard, or data-pipeline architecture. Integrations may connect those systems, but the authoritative owner and lifecycle of each record must remain explicit.

Prerequisites and Assumptions

Before selecting a product or hosting model, confirm:

• Service, content, technical, security, privacy, records, and accessibility owners and the author, reviewer, approver, publisher, and administrator roles
• Audiences, critical public and editorial journeys, applicable agency design system, supported languages, channels, browsers, devices, and assistive technologies
• Content types, metadata, search and integration needs, publication rules, classification, records obligations, retention/disposal authority, and privacy notices or consent needs
• Service criticality, traffic profile, RTO, RPO, support hours, data-location constraints, procurement route, budget, and platform capability
• Current content, media, URLs, redirects, integrations, customisations, licences, and supported legacy dependencies

Architecture Variants

Variants can be combined. SaaS authoring can publish statically; a managed CMS can use headless delivery; and legacy authoring can feed a modern public tier. Products and variants are not assurance levels by themselves.

Capability View

flowchart LR
    editors[Authors, reviewers, and publishers]
    access[Editorial identity and access]
    author[Authoring and workflow]
    content[Canonical content and metadata]
    media[Canonical media capability]
    publish[Validation, preview, and publishing]
    delivery[Public delivery and search]
    edge[Risk-based edge, WAF, and optional CDN]
    users[Public or staff audiences]
    evidence[Audit, monitoring, backup, and records evidence]

    editors --> access --> author
    author --> content
    author --> media
    content --> publish
    media --> publish
    publish --> delivery
    delivery --> edge --> users
    author --> evidence
    publish --> evidence
    delivery --> evidence

The capabilities can be delivered by one SaaS product or several agency-managed components. Keep editorial administration separate from anonymous delivery where practical, and prevent the public path from gaining authoring privileges.

Storage and Edge Choices

Do not assume a CDN, WAF, object store, or shared file service is always needed:

• Apply agency-approved, risk-appropriate edge and DDoS protection to Internet-facing services under ADR 016: Web Application Edge Protection. Use a WAF when HTTP threats warrant it and a CDN when caching, origin shielding, performance, or capacity has a documented benefit.
• Prefer object-backed origins for cacheable static and media assets where the CMS and processing tools support object semantics. Do not treat object storage as a general file system.
• Apply ADR 019: Shared File Access when the CMS, migration, or media-processing workload needs paths, NFS/SMB, locking, atomic changes, or other tested file semantics. Define one canonical store and avoid uncontrolled dual writes.
• Keep private, draft, personal, licensed, security-sensitive, or embargoed content out of public origins and caches. Test cache keys, invalidation, direct-origin blocking, and rollback for the selected publication design.

Provider, SaaS, and Legacy Options

Product links are implementation examples, not preferences or approvals:

These products are not equivalent. Validate content model and workflow fit, Australian region and support access, identity, accessibility, APIs, extension model, file semantics, performance, recovery, licensing, cost, export, deletion, and service responsibility. Managed and SaaS services do not transfer agency accountability for content, records, privacy, security, or accessibility.

Use OpenTofu, or Terraform where justified, for provisionable infrastructure under ADR 010: Infrastructure and Configuration as Code. Provider-native tooling is an exception or bootstrap option as described by that ADR. Keep CMS schema, workflow, templates, configuration, redirects, and deployment inputs versioned and recoverable where the product permits.

Project Kickoff Outputs

Produce these before procurement or implementation is committed:

• Service and content brief with users, critical editorial and public journeys, scope, non-goals, ownership, variant, service tier, and measurable outcomes
• Content and records inventory covering types, owners, classification, personal information, retention/disposal authority, languages, media, URLs, redirects, search, integrations, and migration disposition
• Capability and responsibility map identifying agency, platform, SaaS, and supplier duties for authoring, delivery, security, operations, and support
• Architecture and data-flow diagrams showing authoring and public trust boundaries, stores, locations, publication, cache, logs, backup, and deletion
• Product/options assessment covering non-equivalence, whole-of-life cost, design-system fit, authoring and public accessibility, support, recovery, portable export, and exit
• Acceptance plan for editorial and public paths, content/media/redirect migration, accessibility, performance, security, recovery, and decommission

Content, Records, Privacy, and Classification

• Apply the agency’s records plan, retention and disposal authorities, legal holds, ownership, and evidence requirements to drafts, approvals, published content, media, forms, audit events, and exports as applicable.
• Apply agency privacy assessment, notices, consent, minimisation, access, correction, breach, and disposal processes. Do not collect analytics, personalisation, form, or cookie data merely because the CMS supports it.
• Classify content, media, metadata, logs, backups, preview environments, and support exports; approve every storage, administration, support, backup, and offshoring location.
• Keep approval history and official records in an agency-approved system. A CMS workflow or vendor audit log is evidence only if agency records owners accept its completeness, retention, integrity, access, and export.
• ADR 015 concerns data-pipeline contracts, quality, and lineage. It applies to a CMS data pipeline when relevant, but it is not the authority for CMS records retention or disposal.

Editorial, Public, and Accessibility Acceptance

Test end-to-end editorial journeys for sign-in, draft, preview, compare, review, approval, scheduling, publishing, correction, unpublishing, restore, and urgent release. Verify least privilege, separation of approval where needed, audit events, notifications, concurrent editing, and safe failure.

Test public journeys for navigation, search, forms and integrations, language, media, metadata, canonical URLs, redirects, error pages, cache behaviour, performance, mobile use, and degraded dependencies. Use the applicable agency design system under proposed ADR 020, not Bootstrap as a default.

Assess authoring accessibility as well as public templates. Include keyboard, screen reader, zoom/reflow, focus, labels, errors, rich-text editing, media/alt text, preview, and approval with representative authors with disability. Where a vendor authoring interface has barriers, provide an effective accessible path and a time-bound remediation or replacement decision. Test public output against WCAG 2.2 AA using automated and manual methods.

An optional AI review companion may use AI-Assisted Digital Services, starting with copy/paste, export, or read-only preview. It must not approve, publish, change workflow state, or be treated as proof of policy or accessibility compliance.

Roles and Operations

Monitor public availability and latency, publishing success and age, broken links, search, forms, origin and cache errors, capacity, certificate/domain expiry, security events, privileged and editorial actions, backups, integrations, and supplier status. Keep an on-call or support model proportionate to service criticality and exercise publishing, correction, incident, and supplier escalation runbooks.

Resilience and Recovery

Derive SLO, RTO, and RPO from public impact and content-change tolerance. Define behaviour for authoring, database, media, build, search, integration, DNS, edge, and supplier failure. A static or last-known-good public tier can preserve read-only information while authoring is unavailable, but stale or time-critical content needs an owner, visible handling, and an emergency correction path.

Back up and test recovery of content, media, database, configuration, templates, redirects, identity mappings, keys/procedures, infrastructure code, release artifacts, and required audit evidence. ADR 014 describes the independent-copy pattern; document its implementation rather than treating snapshots, replication, or SaaS availability as proof of backup. Exercise isolated restoration and republishing against measured RTO/RPO.

Migration and Exit

Inventory and map content, owners, metadata, status, languages, relationships, media, licences, alt text, renditions, URLs, redirects, search data, integrations, users, approvals, and records disposition. Clean up only with owner and records approval.

Rehearse export, transformation, checksum/count reconciliation, link and redirect validation, permissions, preview, accessibility, performance, cutover, rollback, and delta migration. Preserve high-value URLs and test redirects from external referrers. Avoid uncontrolled publishing to both platforms.

Before production, demonstrate a portable, documented export of content, metadata, media, relationships, workflow/approval evidence, redirects, and configuration available under the contract. Test import into an independent tool or target where practical. After acceptance and required retention, revoke access, stop integrations and billing, remove DNS and secrets, obtain supplier deletion evidence, securely dispose of residual copies, and record platform decommission.

Required Artifacts and Acceptance Checks

To claim adoption of this pattern, retain:

• Scope, owners, prerequisites, architecture variant, responsibility map, data flow, and product/options assessment
• Content/records inventory and approved classification, privacy, location, offshoring, retention/disposal, and supplier decisions
• Versioned content model, workflow, role matrix, templates/design-system decision, integration contracts, media ownership, and redirect register
• Editorial-path acceptance results, including authoring accessibility and safe publishing/correction failure modes
• Public-path acceptance results, including representative WCAG 2.2 AA, security, cache/origin, browser/device, performance, search, link, form, media, and redirect tests
• SLO/RTO/RPO, dashboards and alerts, support/runbooks, independent recovery approach where applicable, and successful restore/republish exercise
• Content, media, and redirect migration reconciliation with cutover and rollback results
• Portable export/import test, access revocation, supplier deletion, records disposition, and source decommission evidence
• OpenTofu or Terraform plans and apply records for provisioned infrastructure, with documented exceptions under ADR 010

Related ADRs

Accepted ADRs commonly composed by this pattern:

• ADR 001: Application Isolation
• ADR 002: Managed Kubernetes for Compatible Workloads
• ADR 003: HTTP API Contract Standards
• ADR 004: CI/CD Quality Assurance
• ADR 005: Secrets Management
• ADR 007: Centralised Security Logging
• ADR 009: Release Standards
• ADR 010: Infrastructure and Configuration as Code
• ADR 013: Identity Federation Standards
• ADR 016: Web Application Edge Protection
• ADR 019: Shared File Access
• ADR 014: Independent Backups and Recovery
• ADR 018: Managed Relational Databases and Open Lakehouses
• ADR 020: Frontend UI Foundations

Proposed dependencies, to apply only if adopted or otherwise approved for the project:

• ADR 021: Workload mTLS and Service Authorisation, when agency-managed CMS components run on Kubernetes

Reference Architecture: Data Pipelines

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

Applicability and Non-Goals

Use this reference architecture for governed movement and transformation of data across WA agency cloud, SaaS, and legacy environments, including:

• Scheduled extracts, file transfers, database replication, and batch ETL or ELT
• Event and change-data-capture pipelines where the business needs lower latency than a batch service can provide
• Curated datasets for business intelligence (BI), regulatory reporting, controlled sharing, data science, or downstream applications
• Warehouse or lakehouse implementations selected against explicit workload requirements

This is not an architecture for transactional request processing, an operational API, master-data ownership, records-management policy, or ad hoc movement of data without source and sharing authority. It does not mandate a cloud, pipeline product, transformation framework, query engine, table format, catalogue, notebook, or reporting tool.

Ibis, DuckDB, DuckLake, Amazon S3 Tables, Trino, and Quarto are optional implementation examples only. They are not standards established by this reference architecture.

How to Use This Reference Architecture

This reference architecture composes existing ADRs; it does not create a new technology decision. Apply requirements from Accepted ADRs. A Proposed ADR is a dependency under consideration, not an accepted standard: obtain the project’s required design and risk approval before relying on it, and record any different project decision.

Agency obligations for privacy, information sharing, classification, records, procurement, and offshoring still apply even where no repository ADR covers them.

Assumptions and Prerequisites

Before choosing products or creating production data movement, confirm:

• A business owner, source-system owner, data custodian, pipeline owner, and each consuming owner are named.
• The authoritative source and the authority to collect, use, transform, and share each dataset and attribute are documented. Technical access is not sharing authority.
• Purpose, consumers, classification, privacy obligations, retention and disposal authority, data location, and approved use restrictions are known.
• Source interfaces can provide a stable snapshot, change marker, event identifier, or other mechanism that supports complete and repeatable reads.
• Consumers can agree contracts, freshness and quality thresholds, planned outage handling, and breaking-change notification.
• Network paths, workload identities, encryption, key management, logging, and support coverage are available in every participating cloud and legacy environment.
• Business-approved recovery time objectives (RTOs), recovery point objectives (RPOs), maximum data latency, expected volume, concurrency, and cost envelope exist before service selection.

If a prerequisite is unavailable, record the gap, interim control, owner, and resolution date rather than allowing a tool default to become the decision.

Architecture and Capability Model

flowchart LR
    sources[Authoritative Sources]
    ingest[Ingestion and Event Buffer]
    process[Orchestration and Processing]
    stores[Controlled Data Stores]
    serve[BI, Sharing, APIs, and Analysis]
    control[Contracts, Quality, Lineage, Security, and Operations]

    sources -->|snapshot, change, or event| ingest
    ingest -->|validated input| process
    process -->|versioned output| stores
    stores -->|governed access| serve
    control -.-> ingest
    control -.-> process
    control -.-> stores
    control -.-> serve

Keep the following logical capabilities identifiable even when one managed product implements several of them:

Do not infer that a product catalogue entry, replication setting, or source-code graph supplies all of these capabilities. Validate the runtime evidence.

Variants

Minimum Batch Variant

Use for bounded datasets where an approved schedule meets the maximum data latency and the source supports repeatable extraction.

• Use one managed scheduler or existing supported enterprise scheduler, a fit-for-purpose execution service, encrypted landing and curated storage, and a governed serving interface.
• Capture a source snapshot identifier or high-water mark and a unique run ID. Make writes idempotent through stable business keys, partition replacement, merge semantics, or another tested method.
• Define safe rerun and backfill windows. A failed run must not silently append duplicates, publish partial output, or advance the source checkpoint.
• Apply contracts, blocking and warning quality thresholds, runtime lineage, quarantine, replay, and source-to-output reconciliation under Proposed ADR 015 or an approved project-equivalent decision.
• Prefer private connectivity and workload identity. Use an approved managed file-transfer gateway when a legacy endpoint supports only files or SFTP.

This is the minimum production shape, not a relaxation of classification, privacy, backup, or operational controls.

Higher-Assurance Batch Variant

Use when data sensitivity, public impact, statutory reporting, volume, or recovery objectives justify additional controls.

• Separate source landing, processing, quarantine, curated publication, and backup administration according to ADR 001 trust boundaries.
• Preserve immutable source extracts or equivalent reproducible source snapshots for the approved replay period.
• Require independent control totals or record-level reconciliation and approval before publication for high-consequence outputs.
• Run representative performance, restore, corruption, partial-source, schema-change, and full-backfill tests against RTO, RPO, and cost limits.
• Use protected release promotion and explicit data-version rollback rather than replacing a known-good publication in place.

Streaming Variant

Choose streaming only when a documented business response time cannot be met economically and safely by micro-batch or scheduled batch processing. Confirm that the source produces durable events or change records and that consumers can handle the selected delivery semantics.

• Define event identity, partition key, ordering scope, event and processing time, late-arrival policy, retention, replay horizon, and schema evolution.
• State and test whether delivery is at-most-once, at-least-once, or effectively once at the business outcome. Provider claims do not remove the need for idempotent consumers and reconciliation.
• Use a durable event log or buffer between source and processing when replay, burst absorption, or failure isolation is required.
• Monitor end-to-end lag, backlog, dropped and duplicate events, poison events, watermark movement, state growth, and sink publication.
• Quarantine poison events with reason codes and controlled replay. Reconcile source offsets and business totals to sink outcomes.
• Design state checkpoint recovery and stream-processor upgrades so that rollback does not lose or duplicate an unbounded range of events.

Streaming is not automatically the higher-assurance choice. It usually adds state, ordering, support, and cost complexity.

Higher-Assurance Streaming Variant

For critical or high-volume event services, add isolated failure domains, capacity headroom, tested broker or regional failover, protected schema compatibility gates, independent event or source backups where required, and regular replay exercises. Measure recovery from the retained source through to reconciled consumer state, not only broker availability.

Workload Selection Boundaries

Do not create a lakehouse solely because object storage is available. Do not use a BI semantic model as the authoritative integration contract. A solution may compose a lakehouse for durable analytical data with a warehouse or BI serving layer when the duplicated cost, lineage, and reconciliation are owned.

Implementation Examples

The following official product links illustrate possible building blocks, not standards, endorsements, or equivalent service sets. Feature, region, support, identity, networking, recovery, export, and pricing differences must be tested.

For a lightweight bounded workload, Ibis, DuckDB, or DuckLake may be evaluated as optional transformation or query examples. S3 Tables may be evaluated as an AWS-specific managed table option, Trino as a distributed query option, and Quarto as a bounded publication option. Their selection needs the same support, security, interoperability, performance, recovery, and exit evidence as any other product.

Provision infrastructure and supported platform configuration with OpenTofu or Terraform under ADR 010. Provider-native frameworks are only the documented bootstrap or exception options allowed by that ADR. Use versioned configuration management alongside them for legacy hosts and appliances.

Project Kickoff Artifacts

Create these artifacts before implementation selection is final:

• A one-page service context showing sources, consumers, trust boundaries, data flows, environments, regions, and responsible organisations
• A dataset register recording owner, custodian, authoritative source, collection and sharing authority, purpose, classification, privacy status, retention, location, offshoring decision, consumers, and restrictions
• Versioned input and output contracts with compatibility policy, quality thresholds, freshness, keys, volume envelope, and consumer sign-off
• A selection record comparing batch, micro-batch, and streaming and comparing warehouse, BI, and lakehouse needs against latency, scale, support, recovery, portability, total cost, and team capability
• An operational design covering run identity, runtime lineage, checkpoints, idempotency, rerun, backfill, quarantine, replay, reconciliation, alerts, dashboards, and support escalation
• Approved RTO and RPO, failure-mode analysis, backup inventory, restore and replay test plan, and continuity dependencies
• A threat model, privacy assessment, access model, records plan, offshoring and supplier assessment, and logging profile
• An OpenTofu or Terraform repository and state design, environment mapping, CI/CD and release plan, and any ADR 010 exception record
• A cost and performance model with representative test data, budgets, quotas, growth assumptions, unit-cost measures, and cost-alert owners
• A migration and exit runbook covering dual-run, reconciliation, cutover, rollback, format and catalogue export, retention, and decommissioning

Information Governance

Apply the WA Information Classification Policy, Privacy and Responsible Information Sharing, and WA Data Offshoring Governance as applicable. Record agency legal, privacy, information-management, cyber-security, procurement, and data-owner approvals rather than treating a cloud region selection as approval.

• Classify source data, curated outputs, quarantine records, lineage, quality samples, logs, backups, and catalogue metadata. Derived and joined data may require a higher classification or create new privacy risk.
• Minimise collection and sharing to the approved purpose. Apply retention, disposal, legal hold, access review, and disclosure controls to every copy.
• Assess storage, processing, support access, subprocessors, telemetry, metadata, backups, and disaster recovery locations for offshoring. Include SaaS control planes and vendor support, not only the primary data region.
• Keep sensitive record content out of ordinary logs and alerts. Restrict and audit access to quarantine, samples, and data-quality evidence.
• Confirm lawful and responsible sharing before onboarding each consumer and when purpose, claims, linkage, or destination changes. Involve Aboriginal people where sharing affects Aboriginal people and communities as required by applicable WA arrangements.

Ownership and Operations

The operating model must assign named teams, support hours, delegates, and escalations for:

Maintain runbooks for delayed or missing sources, schema drift, threshold failure, partial publication, duplicate output, poison events, credential or key failure, capacity exhaustion, regional or site outage, replay, rollback, and data correction. Review access, contracts, thresholds, costs, capacity, dependencies, and unused datasets on an agreed schedule and after material change.

Resilience and Recovery

• Derive pipeline and dataset RTO and RPO from business impact. Include source re-extraction time, event-retention window, full backfill duration, catalogue and key recovery, validation, and consumer reconciliation.
• Size retention, checkpoints, throughput, quotas, and recovery capacity to meet the objectives under representative backlog and source throttling.
• Keep at least one tested, logically and administratively independent backup where ADR 014 requires it. Replication, object versioning, table snapshots, and multi-zone storage are not independent backups by themselves.
• Back up or reproducibly recover contracts, code, deployment artifacts, infrastructure state, catalogue metadata, access configuration, keys or key procedures, source positions, and required data, not only curated tables.
• Test restore into an isolated environment and then replay and reconcile to a usable publication. Measure achieved RTO and RPO and remediate gaps.
• Design degraded operation explicitly: hold publication, serve a labelled last-known-good dataset, or switch to an approved alternate path. Never hide stale or partial data from consumers.

Migration and Exit

Inventory source semantics, transformations, schedules, contracts, history, formats, catalogue metadata, lineage, quality rules, identities, consumers, retention, performance, and cost before migration.

1. Export representative data in documented, readable formats and export catalogue schemas, ownership, classifications, contracts, lineage mappings, quality rules, and access configuration through supported APIs or files.
2. Prove the destination can read historical and incremental data, preserve required type and timestamp semantics, run the same controls, and restore without the source provider.
3. Dual-run old and new pipelines from a common snapshot or event position for an approved period. Compare record counts, control totals, quality results, lineage, latency, consumer queries, performance, and cost.
4. Define source freeze or checkpoint, cutover authority, consumer validation, rollback trigger, maximum rollback window, and handling for writes or events received during rollback.
5. Keep the old path and required recovery material protected until acceptance criteria and the rollback window are complete. Then revoke access and dispose of copies under approved retention and disposal authority.

A file export alone is not an exit plan if table semantics, catalogue metadata, identity mappings, contracts, or operational history are needed to use it.

Acceptance Checks

• Accepted ADR requirements are implemented; every Proposed dependency is identified and covered by project approval or an explicit alternative
• Source authority and sharing authority are recorded for every dataset and consumer
• Classification, privacy, records, location, supplier, and offshoring assessments cover data, metadata, logs, quarantine, backups, and support
• Batch, streaming, BI, warehouse, and lakehouse choices are supported by measured latency, scale, concurrency, cost, support, and portability needs
• Versioned contracts and approved quality thresholds define warning, quarantine, stop-publication, and consumer-notification behaviour
• Production runs emit queryable runtime lineage with run, code, contract, parameter, timestamp, and source or snapshot identifiers
• Quarantine, replay, reconciliation, idempotency, rerun, and backfill have passed failure and duplicate tests
• Security, freshness, lag, quality, volume, cost, and capacity alerts reach named responders without leaking sensitive records
• Performance and unit cost meet the approved envelope at expected load and tested growth or backlog
• RTO and RPO are approved and demonstrated by restore, replay, and reconciliation; independent backup is not claimed from replication alone
• OpenTofu or Terraform plans, state controls, drift detection, and recovery evidence meet ADR 010
• Dual-run migration, portable data and catalogue export, rollback, consumer acceptance, and legacy decommissioning are tested and approved

Reference Architecture: OpenAPI Backend

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

This reference architecture is an informative composition for HTTP APIs. It does not mandate an API gateway, cloud provider, runtime, database, container platform, public exposure, or separate administration endpoint for every API.

Applicability and Non-Goals

Use this pattern for an agency-controlled HTTP API whose requests, responses, parameters, authentication schemes, and material errors can be accurately described by OpenAPI. It supports internal, partner, public, and administrative APIs across cloud and legacy environments.

Use the protocol-native contract for GraphQL, gRPC, AsyncAPI-compatible events, message queues, file transfer, database interfaces, webhooks that need an event contract beyond OpenAPI, and other non-HTTP or event-driven protocols. OpenAPI may document an HTTP ingress or callback without becoming the contract for the underlying protocol.

This pattern does not:

• Require REST, synchronous integration, JSON, authentication for deliberately anonymous public information, or Internet publication
• Turn an inaccurate generated specification into the source of truth
• Require standard and administrative operations to use separate products when equivalent risk-based isolation can be demonstrated
• Replace domain, security, privacy, records, accessibility, supplier, continuity, or data-sharing decisions
• Require replacement of a stable legacy API solely to adopt a new framework
• Apply to third-party APIs the agency cannot change, although consumers should pin, monitor, and test the contract they depend on

Assumptions and Prerequisites

Before selecting a variant, identify:

• Accountable API product, business, technical, information, security, and operational owners
• Named consumer groups, use cases, expected demand, support needs, and dependency criticality; do not design only for an unknown generic consumer
• Exposure and threat model, trust boundaries, administrative functions, abuse cases, and consequence of unauthorised access or service exhaustion
• Information classification, privacy impact, records and retention duties, sharing authority, processing locations, suppliers, and offshoring assessment
• Authentication and workload identity, resource and operation authorisation, anonymous operations, and privileged-access requirements
• Availability target, latency and throughput objectives, quotas, payload limits, RTO, RPO, consistency, idempotency, and degraded or failover behaviour
• Existing protocols, data stores, runtime constraints, network paths, and consumer migration windows

Prefer an existing authoritative protocol or domain standard where it meets the need. Treat the OpenAPI document, implementation, gateway or proxy policy, and consumer documentation as related artifacts that must be tested for drift.

Assurance Variants

Internal API

Use for agency or approved shared-network consumers where exposure and data risk are bounded:

• Publish a version-controlled OpenAPI contract and owner, consumer, support, compatibility, and SLO information in an accessible internal catalogue
• Use workload identity or authenticated user delegation where required; anonymous access is unusual internally but may be justified for non-sensitive health or discovery information
• Apply operation and resource-level authorisation, validation, quotas, logging, network controls, and dependency timeouts according to risk
• A gateway is optional. A maintained reverse proxy, load balancer, service mesh, application framework, or legacy gateway may provide required controls

Partner or Public API

Use for cross-agency, supplier, community, or Internet consumers:

• Define consumer registration where required, terms of use, support, change communication, quotas, abuse handling, and public status information
• Allow anonymous access to deliberately public information where the classification, privacy, integrity, scraping, denial-of-service, and cost risks are accepted; do not add authentication without a need
• Use risk-appropriate managed edge and DDoS protection for Internet exposure and a WAF where HTTP threats warrant it, consistent with ADR 016: Web Application Edge Protection
• Protect origins from edge bypass where an edge is part of the approved control design; apply TLS, validation, rate or resource controls, and useful errors without disclosing sensitive implementation detail
• Publish accessible, task-oriented documentation and machine-readable contracts from the same reviewed version

Higher-Assurance Administrative API

Use for privileged control-plane, bulk, destructive, security, identity, financial, or sensitive-data operations:

• First determine whether an API is needed; prefer controlled operational workflows over broad general-purpose administration surfaces
• Keep privileged operations off public networks by default. Where Internet access is necessary, use the approved exposure design required by ADR 003: HTTP API Contract Standards
• Separate standard and administrative exposure by hostname, route, gateway, runtime, identity realm, network path, or another combination proportionate to threat and consequence; document why the chosen boundaries are sufficient
• Require strong administrator identity, phishing-resistant MFA where practical, just-in-time and least-privilege access, operation and resource authorisation, protected audit, and monitored break-glass procedures
• Apply tighter quotas, change approval, dual control for selected high-impact operations, response redaction, and independent recovery where justified
• Test that standard identities and network paths cannot invoke administrative operations, including alternate routes, old versions, and direct origins

One service may combine variants at different operations. Separate edge and administration paths when that materially reduces exposure or privilege, not as an unsupported universal topology rule.

Provider-Neutral Capability Architecture

flowchart LR
    consumers[Internal, partner, public, or anonymous consumers]
    edge[Optional edge or API management]
    api[HTTP API runtime]
    dependencies[Data and downstream services]
    admins[Privileged operators]
    adminpath[Restricted administration path]
    ops[Logs, metrics, traces, and audit]

    consumers --> edge --> api
    consumers -->|direct private path where approved| api
    admins --> adminpath --> api
    api --> dependencies
    edge --> ops
    adminpath --> ops
    api --> ops

Compose only the capabilities required:

Avoid implementing business authorisation only at an edge gateway. The runtime must enforce resource and domain rules with trusted identity context.

Deployment Options

These official examples illustrate possible compositions. They are neither mandates nor one-for-one equivalents.

Products differ in gateway policy models, protocol support, identity semantics, regional availability, network integration, transformation fidelity, quotas, portability, observability, cost, and operating responsibility. Validate the whole composition and do not infer equivalence from a row. A managed API gateway does not by itself provide a runtime, complete DDoS protection, domain authorisation, records compliance, backup, or recovery.

Prefer OpenTofu or Terraform for infrastructure provisioning under ADR 010: Infrastructure and Configuration as Code. Provider-native frameworks are exception or bootstrap options under that ADR. Use versioned configuration-management and image-building tools where legacy or on-premises platforms cannot be provisioned through those providers.

Kickoff Artifacts

Create and approve these artifacts before production exposure:

• API brief with applicability, selected variant, purpose, operations, non-goals, service boundaries, owners, consumers, demand, success measures, and funding
• Version-controlled OpenAPI contract with stable operation identifiers, schemas, examples, errors, security declarations, and a generation or review method that prevents implementation drift
• Consumer and dependency register with business and technical contacts, criticality, versions, credentials or identities, quotas, migration windows, and notification channels
• Threat and exposure model showing Internet, partner, internal, direct-origin, administrative, data-store, and downstream paths plus abuse and exhaustion scenarios
• Information schedule recording classification, purpose, sharing authority, privacy assessment, retention, deletion, export, processing locations, supplier access, offshoring, records duties, and logging minimisation
• Non-functional profile with availability and latency SLOs, throughput, concurrency, payload and quota limits, RTO, RPO, consistency, idempotency, timeout, retry, circuit-breaking, and failover behaviour
• Test plan covering contract, behaviour, authentication, authorisation, anonymous access where selected, security, performance, resilience, failover, compatibility, and administration-path isolation
• Operating pack with dashboards, alerts, runbooks, support and escalation, incident and breach procedures, certificate and credential rotation, backup and restore, capacity, and dependency outage procedures
• Lifecycle plan covering version support, deprecation, consumer migration, data export, runtime or gateway replacement, supplier exit, archival, and verified deletion

Roles and Operating Model

Shared platform and API SLOs must be distinguishable. Establish support hours, on-call and escalation, maintenance communication, incident command, consumer notification, cost allocation, and periodic access and consumer reviews.

Contract and Documentation

• Maintain OpenAPI in version control and validate syntax, references, examples, operation identifiers, security declarations, and compatibility in CI
• Use contract-first or implementation-first development only if the published contract is reviewed and automated tests detect drift from runtime behaviour
• Describe all supported success and material error responses, pagination, filtering, content types, payload limits, rate-limit behaviour, correlation, idempotency, and retry safety
• Define compatibility and versioning around consumer impact rather than assuming URL versioning alone prevents breaking changes
• Publish a changelog, support policy, deprecation dates, migration guidance, status and support routes, and downloadable machine-readable contract
• Make developer documentation WCAG 2.2 AA: use semantic headings and tables, keyboard-operable navigation and consoles, text alternatives, clear errors, sufficient contrast, and code examples that do not rely on colour alone
• Provide static or no-JavaScript access to essential reference and onboarding information; an interactive API console is optional and must not be the only documentation
• Ensure examples use non-sensitive synthetic data and identify whether operations are anonymous, user-delegated, workload-authenticated, or administrative

Security, Classification, and Offshoring

• Authenticate only where required, but always enforce approved operation and resource authorisation. Treat object-level and function-level authorisation as runtime responsibilities
• Validate path, query, header, and body input and validate material output against the contract without relying only on gateway schema validation
• Define request, response, upload, query, concurrency, execution-time, and downstream resource limits; rate limits alone do not prevent expensive calls
• Minimise personal or sensitive information in URLs, errors, logs, traces, analytics, gateway caches, developer portals, and test environments
• Classify API payloads, credentials, metadata, logs, backups, exports, and support access. Apply privacy, records, sharing, retention, and disposal rules to each copy
• Assess cloud regions, gateway or CDN processing, telemetry, support access, backups, disaster recovery, subprocessors, and supplier diagnostics under WA information-classification, privacy, procurement, and data-offshoring requirements
• Protect secrets under ADR 005: Secrets Management and security-relevant telemetry under ADR 007: Centralised Security Logging
• Record and alert on authentication failures, denied authorisation, administrative operations, credential and policy changes, unusual extraction, abuse, and control bypass without logging secret or excessive payload data

Resilience and Recovery

• Define availability and latency indicators at the consumer-visible boundary; include valid request success separately from rejected invalid or unauthorised requests
• Set dependency timeouts, bounded retries with jitter, circuit breakers or equivalent isolation, concurrency protection, backpressure, and idempotency according to operation semantics
• Document behaviour for gateway, identity, runtime, database, network, downstream, certificate, DNS, region, or site failure. Do not fail open on authentication or authorisation
• Keep health endpoints minimal and distinguish process health, readiness, and dependency status without exposing sensitive topology
• Protect and test recovery of authoritative data, configuration, contracts, credentials and keys, policy, audit evidence, and deployment artifacts against approved RTO and RPO
• Test load, burst, quota, slow dependency, timeout, partial failure, retry storm, failover, restore, and failback. Validate that failover preserves identity, policy, classification, location, logging, and consistency controls
• Maintain consumer-facing status and incident communication that does not depend solely on the failed API

ADR 014: Independent Backups and Recovery and ADR 018: Managed Relational Databases and Open Lakehouses apply where those capabilities are selected.

Legacy Adoption

Do not begin with a rewrite. Inventory operations, actual consumers, network paths, identities, sensitive data, undocumented behaviour, unsupported components, and operational dependencies. Capture the observed contract, mark uncertain fields, add characterisation tests around high-risk and high-use operations, then reconcile the implementation and OpenAPI description.

Place a gateway or adapter in front of a legacy API only when it adds a defined control or migration seam. Do not imply that transformation removes unsafe backend behaviour. Preserve consumer-visible semantics until a communicated migration, and use strangler routing, versioned adapters, or parallel operation where they reduce cutover risk. Track unsupported exceptions, compensating controls, owners, expiry dates, and retirement milestones.

Deprecation, Migration, and Exit

• Publish support states and dates for operations, versions, SDKs, credentials, gateway policies, and runtimes; monitor actual use rather than assuming all registered consumers have migrated
• Give named consumers test environments or fixtures, compatibility results, change notices, migration guidance, and a route to request justified time
• Keep old and new versions isolated enough to prevent an obsolete route, direct origin, alternate hostname, or admin path bypassing current controls
• Define final response behaviour, archival, DNS and route removal, credential revocation, log and record retention, verified data deletion, and closure evidence
• Provide data export in documented, usable formats where the API or runtime is authoritative. Reconcile counts, integrity, metadata, classification, and retention before cutover
• Keep contracts, tests, deployment artifacts, configuration, policy mappings, schemas, runbooks, and data migration procedures portable enough to replace the gateway, runtime, supplier, region, cloud provider, or legacy host
• Exercise a runtime or gateway replacement in a non-production environment for critical APIs and record unresolved provider dependencies

Optional AI Gateway

An AI inference gateway is optional and only in scope when it exposes an HTTP interface accurately described by OpenAPI. It also requires separate AI governance, model and prompt controls, data-use and retention decisions, evaluation, safety, and provider-exit design. This pattern neither requires an AI gateway nor selects an OpenAI-compatible, Open Responses-compatible, or provider-native interface.

Acceptance Checks

• Applicability, variant, boundaries, owners, consumers, funding, support, non-goals, dependencies, and legacy constraints are approved
• The version-controlled OpenAPI contract accurately describes supported HTTP behaviour and passes lint, reference, example, conformance, drift, and compatibility checks
• Threat and exposure review covers public, anonymous, partner, internal, direct-origin, old-version, administrative, data, and downstream paths
• Classification, privacy, sharing authority, records, retention, deletion, export, processing location, suppliers, backup, support, and offshoring decisions are recorded
• Named consumers and owners have validated onboarding, credentials where used, quotas, examples, compatibility, support, change notification, and migration arrangements
• Authentication tests cover each protected identity type and anonymous access tests prove public operations need no accidental credential
• Authorisation tests prove operation and resource isolation, deny standard identities access to administration, and cover alternate routes, direct origins, old versions, and bulk access
• Validation, error, payload, resource limit, abuse, security, and sensitive data leakage tests pass at edge and runtime boundaries as applicable
• Performance tests meet latency, throughput, concurrency, burst, quota, timeout, retry, and capacity objectives with representative payloads
• Dependency failure, gateway or runtime outage, identity outage, failover, restore, and failback tests meet SLO, RTO, RPO, consistency, location, logging, and security expectations
• Developer documentation passes WCAG 2.2 AA checks and essential contract, onboarding, status, and support content works without JavaScript
• Dashboards, alerts, SLO reports, audit coverage, runbooks, escalation, incident communication, credential rotation, and recovery procedures are operational and exercised
• Deprecation, consumer migration, data export, archival, deletion, and gateway, runtime, supplier, or platform exit have named owners and tested procedures
• Infrastructure and supported configuration are reproducible using OpenTofu or Terraform as preferred by ADR 010, with justified exceptions

Related Decisions

Accepted dependencies:

• ADR 001: Application Isolation
• ADR 003: HTTP API Contract Standards
• ADR 004: CI/CD Standards
• ADR 005: Secrets Management
• ADR 007: Centralised Security Logging
• ADR 009: Release Standards
• ADR 010: Infrastructure and Configuration as Code
• ADR 012: Privileged Remote Access
• ADR 013: Identity Federation Standards
• ADR 016: Web Application Edge Protection
• ADR 014: Independent Backups and Recovery
• ADR 015: Data Pipeline Contracts, Quality and Lineage
• ADR 018: Managed Relational Databases and Open Lakehouses
• ADR 020: Frontend UI Foundations

Proposed dependencies and examples to assess rather than treat as mandates:

• ADR 021: Workload mTLS and Service Authorisation, when API services run on Kubernetes
• AI-Assisted Digital Services, only when an AI gateway use case is separately approved

Reference Architecture: AI-Assisted Digital Services

Status: Proposed | Date: 2026-07-11 | Review: 2027-07-11

Purpose

This informative reference architecture composes existing ADRs for agencies of different sizes and technology estates. It does not approve an AI use case, provider, model, or new mandatory control. ADRs identified as Proposed below are proposed dependencies, not accepted requirements.

Start with a low-risk, standalone companion. Keep the source system authoritative and make a person accountable for every official outcome. Increase integration only when evaluation and operational evidence justify it.

Applicability and Non-Goals

Use this pattern for bounded assistance such as:

• Drafting, summarising, rewriting, translation support, and plain-English coaching
• Content, form-help, search-help, or staff support over approved information
• Explanations of curated reports and service information
• Read-only retrieval or selected-field assistance with a defined human review

This pattern is not approval for automated eligibility, policy, enforcement, fraud, identity, payment, publishing, production change, or other consequential decisions. It is not a basis for unrestricted agents, broad data access, or privileged tools. Assess those uses separately under ADR 011: AI Tool and Agent Governance.

AI output can identify possible issues, but cannot prove policy, factual, legal, records, privacy, or accessibility compliance. Qualified human review and representative testing remain necessary.

Prerequisites and Assumptions

Before implementation, confirm:

• An accountable service owner and AI accountable officer, a defined use case, excluded uses, users, affected people, and human decision boundary
• An initial ADR 011 risk tier based on data, consequence, autonomy, privilege, reversibility, and detectability
• Agency information classification, privacy, records, procurement, security, offshoring, and accessibility owners are available as applicable
• A source of representative, lawfully usable evaluation material and qualified reviewers exists
• The source workflow can continue without AI and remains the system of record
• Identity, logging, support, incident, and supplier-management capabilities are available in proportion to the tier

Architecture Variants

High-risk use may need an independently assured design rather than either variant. Inline write-back, agentic tools, memory, or consequential automation are separate scope changes and trigger risk-tier reassessment.

Delivery can progress from manual companion, to file-based review, to read-only feed, and then to bounded inline assistance. Start with the least integrated level that can test the service outcome.

Capability View

flowchart LR
    user[Author, staff member, or service user]
    source[Authoritative source and workflow]
    input[Minimal selected input]
    assist[Assistance service]
    rules[Deterministic rules and policy controls]
    access[Approved model access]
    model[Managed or local model capability]
    review[Human review and fallback]
    evidence[Evaluation, audit, usage, and cost evidence]

    user --> source
    source -->|copy, export, or bounded read| input
    input --> assist
    assist --> rules
    rules -->|approved context only| access
    access --> model
    model -->|untrusted output| rules
    rules --> review
    review -->|accepted change through normal workflow| source
    assist --> evidence
    access --> evidence
    review --> evidence

The model is outside the trust boundary for truth and instructions. Validate input and output, keep provider credentials server-side, and do not let content supplied by users or retrieval sources redefine system policy or approval gates.

Provider, SaaS, and Local Options

Product links are implementation examples, not preferences or approvals:

These options are not equivalent in model behaviour, data processing, location, retention, training use, content filtering, identity, private connectivity, logging, availability, quotas, cost, or deletion. Evaluate the configured service, model, and region rather than relying on a product family statement.

A client may call one approved managed endpoint through a small server-side adapter, or use an internal gateway when central policy, credential isolation, multiple applications, or provider portability justify it. An Open Responses-compatible interface, Bedrock Mantle, Hugo previews, and Bootstrap are optional implementation examples, not defaults. Frontends and previews follow the applicable agency design system under proposed ADR 020.

Use OpenTofu, or Terraform where justified, for provisionable infrastructure under ADR 010: Infrastructure and Configuration as Code. Keep model IDs, prompt versions, limits, provider settings, and deployment configuration versioned and reviewable; do not place provider credentials in browsers, CMS plugins, or portal widgets.

Project Kickoff Outputs

Produce these before build or procurement is committed:

• Service brief with intended users and outcomes, non-goals, human fallback, accountable owners, initial risk tier, and risk-tier change triggers
• Current and proposed data-flow diagrams showing fields, classification, volumes, prompts, retrieval, outputs, logs, locations, subprocessors, and deletion paths
• Privacy, information-classification, offshoring, security, records, and supplier assessments proportionate to the use case
• Architecture variant and build/buy/local selection record, including non-equivalence, accessibility, total cost, support, and exit criteria
• Evaluation plan with representative corpus, prohibited outcomes, quality and safety measures, reviewer roles, thresholds, and regression cadence
• Threat model covering prompt injection, adversarial input, retrieval poisoning, data leakage, unsafe output, denial of service, and privilege abuse
• Service level objectives (SLOs), cost and usage limits, runbook, incident and complaint paths, and launch/rollback criteria

Data, Privacy, and Supplier Controls

• Send selected fields or curated extracts rather than complete records; remove unnecessary personal information, identifiers, comments, attachments, and workflow metadata
• Record classification at every data-flow boundary, including prompt, retrieval corpus, output, telemetry, support access, and provider abuse logs
• Assess processing and support locations, subprocessors, cross-border access, model-training use, retention, deletion, legal terms, incidents, and exit; apply WA Data Offshoring Governance
• Configure no-training and minimum-retention options where supported, but verify contract and observed behaviour rather than assuming a flag proves compliance
• Keep required agency evidence in agency-controlled systems and avoid logging sensitive prompt or output content unless specifically justified and protected

Evaluation, Safety, and Accessibility

• Freeze a versioned evaluation corpus that represents languages, content types, accessibility needs, edge cases, and affected cohorts without using data unlawfully
• Record baseline and release results by model, model version, prompt, retrieval version, configuration, and reviewer; investigate subgroup and failure results
• Test direct and indirect prompt injection, policy override, malicious files, encoded instructions, data exfiltration, unsafe links, denial-of-service inputs, and malformed or deceptive outputs
• Run deterministic checks before model calls where rules are known and validate schema, citations, claims, links, and actions after model calls as applicable
• Clearly label assistance, uncertainty, and the human review step; provide a usable non-AI path when the model is unavailable, declined, or inappropriate
• Test the entire interface and fallback with representative users and assistive technology against WCAG 2.2 AA; generated text or an AI accessibility review is not accessibility evidence

Roles and Operations

Maintain an inventory of use cases, owners, providers, models and versions, prompts and versions, retrieval sources, tools, data classes, locations, expiry dates, and approvals. Monitor latency, availability, refusals, harmful or invalid outputs, policy denials, injection attempts, token use, spend, user overrides, and fallback use. Enforce per-user and service quotas, token ceilings, budget alerts, and a tested stop switch.

Resilience, Recovery, and Exit

Set SLO, RTO, and RPO according to service consequence. Define behaviour for model, provider, gateway, network, quota, safety-filter, and logging failure. Prefer fail-safe human fallback over silent provider or model substitution; re-evaluate before switching because models are not equivalent.

Recover versioned prompts, policy, evaluation assets, infrastructure, and configuration independently of provider conversation state. Test restore, credential rotation, model disablement, and operation without AI.

Before production, demonstrate that the agency can export its model/prompt inventory, configuration, logs, evaluations, and approved outputs; replace the provider or return to the manual workflow; revoke access; and request and verify deletion under the contract. Record a timed provider-exit and deletion test, including residual backups or legal retention. Avoid proprietary model features unless their value and exit impact are accepted.

Required Artifacts and Acceptance Checks

To claim adoption of this pattern, retain:

• Approved use case, owners, risk tier, architecture variant, and excluded actions
• Data flow, classification, privacy/offshoring, supplier, records, security, and accessibility assessments applicable to the use case
• Representative evaluation corpus, thresholds, baseline, release results, qualified review, and known-limit register
• Prompt-injection and adversarial test results with remediated or accepted findings
• Tested human fallback, stop switch, incident/complaint route, SLO, alerts, runbook, recovery, and rollback
• Enforced rate, token, and cost limits with owner alerts
• Current model, prompt, retrieval, tool, provider, region, and approval inventory
• Manual and automated accessibility results for the assistance and non-AI journeys; no claim based only on AI output
• Provider export, replacement, access-revocation, exit, and deletion-test evidence
• Infrastructure plans and apply records using OpenTofu or Terraform where infrastructure is provisioned

Related ADRs

Accepted ADRs commonly composed by this pattern:

• ADR 001: Application Isolation
• ADR 003: HTTP API Contract Standards
• ADR 004: CI/CD Quality Assurance
• ADR 005: Secrets Management
• ADR 007: Centralised Security Logging
• ADR 009: Release Standards
• ADR 010: Infrastructure and Configuration as Code
• ADR 011: AI Tool and Agent Governance
• ADR 013: Identity Federation Standards
• ADR 020: Frontend UI Foundations

Proposed dependencies, to apply only if adopted or otherwise approved for the project:

• ADR 021: Workload mTLS and Service Authorisation, when agency-managed components run on Kubernetes

Reference Architecture: Federated Application Portal

Status: Proposed | Date: 2026-07-11 | Review: 2027-07-11

This reference architecture is an informative composition of capabilities and ADRs. It does not require every service to adopt a portal, SDK, inbox, notification service, or native shell.

Applicability and Non-Goals

Use this pattern when independently owned applications need one or more shared entry, identity, account, messaging, or cross-channel capabilities across WA agencies, cloud providers, or legacy estates. It is useful where applications must retain independent ownership and release cycles while presenting a coherent user journey.

This pattern is not intended to:

• Merge unrelated applications into one frontend runtime or data store
• Make a portal landing page or native application the only route to a service
• Require JavaScript, a shared SDK, inbox, notifications, personalised app cards, PWA features, or a native shell
• Centralise business authorisation, case management, records ownership, or application delivery
• Replace agency identity, privacy, information-sharing, records, procurement, accessibility, security, or continuity decisions

Static public services, a single application with no useful shared capability, and machine-to-machine integration normally need simpler patterns.

Assumptions and Prerequisites

Before selecting a variant, establish:

• Accountable service and information owners for each application and each shared capability
• User groups, critical journeys, assisted-digital and non-digital channels, and direct application URLs
• Identity populations, required assurance, recovery and fallback, and the attributes each application is authorised to receive
• Information classification, privacy impact, records and retention duties, sharing authority, consent model, processing locations, and offshoring assessment
• Service criticality, availability dependencies, support coverage, recovery time objective (RTO), recovery point objective (RPO), and acceptable degraded modes
• Current browser, non-JavaScript, legacy, mobile, integration, and network constraints
• Funding, operating capacity, onboarding demand, and an exit owner for shared services

Use OIDC for new interactive federation in accordance with ADR 013: Identity Federation Standards. A legacy application may use a broker, reverse-proxy integration, SAML where OIDC is unavailable, or a documented direct sign-in path rather than a disruptive rewrite.

Selectable Capabilities

Select only capabilities with a user or operational need and an accountable owner.

The portal, SDK, inbox, notification service, and native shell are separate capabilities. Selecting one does not imply selection of the others.

Assurance Variants

Minimum: Directory and OIDC

Use for low-complexity federation where discovery and common sign-in provide enough value:

• Register accessible metadata, owner, support contact, direct launch URL, and OIDC client
• Launch the standalone application; the application starts and validates its own OIDC flow and makes its own authorisation decisions
• Provide server-rendered or progressively enhanced directory navigation that remains useful without JavaScript
• Do not exchange application status, inbox, or notification data unless later approved under a separate contract

Standard: Shared SDK or Services

Add only the capabilities justified by common journeys:

• Offer a maintained SDK, web component, or server-side library for selected account, inbox, notification, telemetry, or handoff functions
• Publish the underlying protocols and APIs so legacy and non-JavaScript applications can integrate without the SDK
• Version schemas, SDKs, native bridges, and UI components; publish a support matrix, deprecation window, test fixtures, and upgrade path
• Keep shared UI peripheral to app-owned content and compatible with the applicable agency design system

Higher-Assurance

Use where sensitive information, high-impact transactions, cross-agency sharing, or critical services increase consequence:

• Isolate shared capabilities and administration according to trust, classification, and ownership; require step-up authentication for defined actions
• Use stronger service and workload identity, explicit audience restrictions, transaction-level authorisation, protected audit trails, and monitored anomaly controls
• Minimise or avoid central aggregation; use purpose-specific claims or references and short retention where central data is justified
• Test direct access, identity fallback, central outage, regional or site recovery, key rollover, consent withdrawal, and security incident procedures
• Establish independent assurance, change approval, out-of-hours escalation, and continuity arrangements proportionate to criticality

Higher assurance strengthens selected capabilities; it does not make every optional capability necessary.

Provider-Neutral Capability Architecture

flowchart LR
    user[User or assisted channel]
    directory[Optional directory]
    app[Independent application]
    identity[Identity capability]
    shared[Optional shared capabilities]
    ops[Operations and audit]

    user -->|direct URL| app
    user -->|discover and launch| directory
    directory -->|registered URL| app
    app -->|OIDC or legacy adapter| identity
    app -.->|versioned API, SDK, or adapter| shared
    directory --> ops
    app --> ops
    identity --> ops
    shared --> ops

Keep the directory, identity, optional shared services, application runtime, and operational plane independently replaceable where practical. Authorise network and data flows explicitly; a shared user identity does not grant cross-application data access.

Deployment Options

These are official service examples, not product selections or equivalent one-for-one mappings.

Products differ in identity semantics, regional availability, accessibility, delivery guarantees, data location, operational model, quotas, portability, and cost. Validate the selected composition against required capabilities; do not infer equivalence from a row. Prefer OpenTofu or Terraform for infrastructure provisioning under ADR 010: Infrastructure and Configuration as Code. Provider-native frameworks are exception or bootstrap options under that ADR. Legacy configuration may also need versioned configuration-management and image-building tools.

Kickoff Artifacts

Create and approve these artifacts before production onboarding:

• Service brief with applicability decision, selected variant and capabilities, user groups, critical journeys, exclusions, and success measures
• Capability and dependency map with direct-access paths, trust boundaries, system and information owners, RTO, RPO, and degraded modes
• Governance charter covering decision rights, RACI, funding or chargeback, product ownership, operational ownership, support hours, and dispute and exception handling
• Onboarding contract covering eligibility, metadata, identity claims, redirect and logout behaviour, scopes, data flows, SLOs, support, compatibility, security evidence, launch approval, and costs
• Information schedule covering classification, purpose, sharing authority, consent and withdrawal, notices, minimisation, retention, deletion, export, processing locations, offshoring, breach handling, and records duties
• Interface pack with OIDC registration, API or event contracts, SDK and native bridge versions if selected, accessibility expectations, test fixtures, and deprecation policy
• Operational pack with service-level objectives (SLOs), monitoring, alerts, runbooks, contact and escalation paths, capacity assumptions, recovery plans, and incident exercises
• Lifecycle plan for onboarding, suspension, offboarding, data deletion and export, credential revocation, domain or deep-link changes, and platform replacement

Roles and Operating Model

Tailor the RACI to agency arrangements, but assign each accountability once.

The governance body should review SLO performance, onboarding demand, shared risk, unresolved compatibility issues, cost allocation, and capability retirement on an agreed cadence. Cross-agency operation needs named delegations and agreements; technical integration alone does not create authority to share information or operate another agency’s service.

Information, Privacy, and Sharing

• Classify portal metadata, identity claims, inbox content, notification payloads, usage telemetry, support records, and audit logs before selecting storage or suppliers
• Document lawful purpose and authority for every cross-agency disclosure; distinguish consent from other sharing authority and do not request consent where it is not the applicable basis
• Make consent specific, informed, recorded, reviewable, and withdrawable where consent is used; define downstream action after withdrawal
• Avoid a global cross-service identifier or central activity profile unless a documented purpose and authority require it
• Put sensitive detail behind authenticated access rather than in email, SMS, push previews, URLs, analytics, or portal card metadata
• Assess all storage, support, telemetry, backup, content delivery, and supplier processing locations under WA information-classification, privacy, records, procurement, and data-offshoring requirements
• Define data subject access, correction, complaint, breach, legal hold, retention, deletion, and machine-readable export procedures

Accessibility and Channel Support

Follow the applicable agency design system and ADR 020: Frontend UI Foundations.

Meet WCAG 2.2 AA for user-facing web interfaces and test representative portal, app launch, sign-in, account, consent, inbox, notification-preference, error, and outage states with keyboard and assistive technologies. Use semantic HTML and progressive enhancement. Critical discovery, launch, sign-in, and support paths must remain usable without client-side JavaScript where the supported audience or legacy estate requires it.

An accessible journey is concise: a user discovers an application in an accessible directory or follows its direct URL, reviews the service and privacy information, signs in only if needed, completes the task in the independently owned application, and receives status through an available channel. Focus and context remain clear at redirects and handoffs. Provide assisted-digital, telephone, in-person, or other alternatives where digital exclusion or service policy requires them. A native shell or push notification cannot be the only way to complete a critical task.

Compatibility and Integration

• Publish supported browsers, identity providers, protocol and API versions, SDK versions, native-shell versions, and legacy adapters with end-of-support dates
• Use OIDC Authorization Code flow with PKCE for browser and native public clients; never place client secrets in browser or PWA code
• Test issuer, audience, state, nonce, redirect URI, session expiry, logout, signing-key rollover, account recovery, and step-up behaviour
• Keep application sessions and authorisation app-owned. Do not rely on silent authentication where browser privacy controls make it unreliable
• Keep documented APIs or protocol flows available when an SDK is offered; provide server-side and non-JavaScript paths where needed
• Version and allow-list native bridge messages, bind them to approved origins, validate payloads, record security-relevant use, and fail closed
• Define schema compatibility, idempotency, duplicate handling, ordering, freshness, retry, and dead-letter behaviour for messages and notifications

Resilience and Recovery

Set measurable SLOs for each selected shared capability, including availability, latency, support and incident response, notification acceptance or delivery where measurable, and recovery. Do not publish one aggregate SLO that hides a weaker critical dependency.

• Keep direct application URLs documented, monitored, and tested independently of the portal and native shell
• Define behaviour when the directory, identity provider, SDK asset host, inbox, notification service, network link, or native bridge is unavailable
• Avoid runtime loading of an SDK from a central origin when its outage would prevent the application’s core journey; package or degrade safely instead
• Queue and reconcile asynchronous work with bounded retries and visible status; never imply notification delivery proves that a user received or acted on it
• Back up and restore authoritative data, configuration, keys, consent records, and audit evidence according to approved RTO, RPO, retention, and location
• Test central outage and direct access, dependency timeout, regional or site recovery where applicable, corrupted data, credential or key recovery, and status communication at least annually and after material architecture changes

ADR 014: Independent Backups and Recovery and ADR 018: Managed Relational Databases and Open Lakehouses apply where those capabilities are selected.

Onboarding, Offboarding, and Exit

Onboarding should validate ownership, authority, metadata, identity, direct access, accessibility, compatibility, security, operations, data flows, cost, and support before production listing. Use a sandbox and conformance tests where shared integration is more than a launch URL and OIDC client.

Offboarding must define notice, directory removal, safe redirects, credential and scope revocation, queue draining, notification handling, user and support communications, retention or transfer of records, verified deletion, export, and closure evidence. Emergency suspension needs narrower criteria and a review path so a portal decision does not silently remove direct access to a statutory or critical service.

Maintain a platform replacement plan with exportable directory metadata, configuration, consent and preference records, inbox data where authoritative, audit evidence, API contracts, and ownership mappings. Test restoration or migration to an independent environment. Avoid provider-specific identifiers or SDK-only business logic where they would prevent an application or shared capability moving independently.

Acceptance Checks

• Applicability, selected variant, selected capabilities, non-goals, owners, funding, RACI, and cross-agency delegations are approved
• Onboarding contract, direct URLs, identity registrations, claims, scopes, data flows, support contacts, compatibility matrix, and deprecation policy are published
• Classification, privacy, sharing authority, consent where applicable, records, retention, deletion, export, processing location, supplier, and offshoring decisions are recorded
• Portal and critical app journeys pass WCAG 2.2 AA, keyboard, assistive-technology, non-JavaScript where required, browser, device, assisted-channel, and handoff testing
• Authentication, application authorisation, account recovery, logout, session expiry, step-up, key rollover, and identity fallback tests pass
• API, event, SDK, component, legacy adapter, and native bridge contracts pass compatibility and security tests for the selected capabilities
• SLOs, dependency monitoring, capacity, alerts, support, escalation, incident, breach, and recovery runbooks are operational
• Central outage and direct-access tests show that each critical application remains reachable or has an approved continuity path
• Backup and recovery tests meet approved RTO and RPO, including configuration, keys, records, and authoritative data
• Onboarding, suspension, offboarding, credential revocation, deletion, export, and platform replacement have named owners and tested procedures
• Infrastructure and supported configuration are reproducible using OpenTofu or Terraform as preferred by ADR 010, with justified exceptions

Related Decisions

Accepted dependencies:

• ADR 001: Application Isolation
• ADR 003: HTTP API Contract Standards
• ADR 004: CI/CD Standards
• ADR 005: Secrets Management
• ADR 007: Centralised Security Logging
• ADR 009: Release Standards
• ADR 010: Infrastructure and Configuration as Code
• ADR 013: Identity Federation Standards
• ADR 016: Web Application Edge Protection
• ADR 014: Independent Backups and Recovery
• ADR 015: Data Pipeline Contracts, Quality and Lineage
• ADR 018: Managed Relational Databases and Open Lakehouses
• ADR 020: Frontend UI Foundations
• OpenAPI Backend

Proposed dependencies and examples to assess rather than treat as mandates:

• ADR 021: Workload mTLS and Service Authorisation, when shared services run on Kubernetes
• Identity Federation

Reference Architecture: Identity Federation

Status: Proposed | Date: 2026-07-11 | Review: 2027-07-11

Applicability and Non-Goals

Use this reference architecture when a WA agency application or service must trust an external workforce, citizen, customer, partner, or privileged-user identity provider. It covers:

• Direct OpenID Connect (OIDC) federation for a relying party
• A broker where multiple upstream providers, protocol translation, migration, or common policy provides a documented benefit
• A separate privileged-user federation path
• Time-bounded SAML federation for a legacy provider or relying party that cannot support OIDC

This is identity federation architecture, not a complete identity and access management (IAM) architecture. Identity proofing, registration, joiner-mover- leaver lifecycle, authoritative directory design, entitlement governance, workload identity, fine-grained application authorisation, and fraud operations are non-goals. The owning agency must design those capabilities separately. Federation conveys identity and authentication context; it does not prove that an account lifecycle or application entitlement is appropriate.

Do not use this pattern to create a new identity provider by default or to add a broker where one approved provider can federate directly with the relying party.

How to Use This Reference Architecture

This reference architecture composes ADRs and does not establish a new identity standard. Apply requirements from Accepted ADRs. A Proposed ADR remains a dependency under consideration, not an accepted standard; obtain project approval or document an approved alternative before relying on it.

Agency privacy, information-classification, accessibility, records, procurement, Digital ID, and offshoring obligations still apply where no ADR defines them.

Assumptions and Prerequisites

Before product selection or relying-party integration, confirm:

• An approved upstream identity authority owns proofing, enrolment, lifecycle, compromise response, and authentication appropriate to the user population.
• The relying service has a named business owner, relying-party owner, identity provider owner, security owner, privacy owner, service desk, and application support team.
• The service has documented user populations, transaction risks, information classification, required authentication assurance, accessibility needs, support hours, and approved RTO and RPO.
• The relying party can validate OIDC tokens and keep authorisation decisions local unless a separate accepted decision establishes central entitlement policy.
• Required domains, redirect paths, private administrative access, trusted time, DNS, certificates, key management, logs, and provider support are available.
• Account and MFA recovery can re-establish the required assurance without an unmonitored bypass and without excluding users who cannot use one method.
• Each requested claim has an owner, definition, source, purpose, lawful basis, classification, release rule, retention expectation, and consumer.

If the upstream provider cannot supply the required assurance or claims, do not silently manufacture assurance in a broker. Change the service design, add an approved proofing or verification capability, or record the risk decision.

Architecture and Capability Model

flowchart LR
    users[Standard Users]
    idp[Approved Identity Provider]
    broker[Optional Justified Broker]
    rp[Relying Party]
    admins[Privileged Users]
    pidp[Privileged Identity Domain]
    adminrp[Administrative Relying Party]
    legacy[Legacy SAML Provider or Relying Party]

    users -->|authenticate| idp
    idp -->|direct OIDC| rp
    idp -.->|OIDC or SAML when justified| broker
    broker -.->|OIDC| rp
    admins -->|phishing-resistant MFA and elevation| pidp
    pidp -->|separate federation| adminrp
    legacy -.->|time-bounded SAML variant| broker

The dotted paths are optional variants, not required hops. Keep these logical capabilities identifiable even where one managed platform combines them:

Architecture Variants

Minimum Direct OIDC Variant

Use this default shape for a new relying party and one approved identity provider when direct federation meets assurance, privacy, availability, and support requirements.

• Integrate the relying party directly with the provider using OIDC Authorization Code flow with PKCE and the validation controls in ADR 013.
• Register separate clients and exact redirect URIs for environments and trust boundaries. Keep privileged administration on its separate path.
• Request only approved scopes and claims. Translate the provider subject into an application-owned internal identifier so provider details do not become business keys throughout the application.
• Keep application roles and transaction authorisation in the application or a separately approved authorisation service. Do not infer entitlement from successful login alone.
• Implement risk-appropriate MFA, recovery, logging, key rollover, fallback, provider escalation, and tested export before production acceptance.

This is a minimum component count, not reduced authentication assurance.

Higher-Assurance OIDC Variant

Use for privileged access, high-impact transactions, sensitive information, or critical services where the risk assessment requires stronger controls.

• Require phishing-resistant authentication where supported and step-up or fresh authentication before high-risk transactions.
• Use separate privileged identities, provider policy, clients, administrative endpoints, and application paths under ADRs 001, 012, and 013.
• Bind the relying-party decision to required authentication context and age; reject missing, stale, or unrecognised assurance claims rather than assuming a default.
• Add transaction or out-of-band verification where a separate risk decision requires it; federation alone does not authorise a high-risk action.
• Test provider, DNS, key, metadata, network, support, recovery, and regional failure modes against approved service objectives.
• Protect federation configuration, mapping data, audit evidence, and any local account store with stronger administrative separation and recovery controls.

Justified Broker Variant

Add a broker only when the selection record demonstrates one or more of these needs: several upstream providers, SAML-to-OIDC translation, consistent claim-release policy, controlled provider migration, or shielding many relying parties from unavoidable upstream differences.

• Record why direct OIDC is insufficient and compare the broker’s concentration risk, latency, outage impact, support burden, privacy exposure, cost, and exit path with direct integrations.
• Prefer an OIDC interface from broker to modern relying parties. Preserve the original issuer, subject mapping, claim provenance, and authentication assurance needed for audit without over-sharing them to applications.
• Do not let the broker invent identity proofing or MFA assurance, collapse standard and privileged populations, or become the default source of application entitlements.
• Isolate and monitor the broker as a critical security dependency. Test bypass, fail-closed behaviour, key rollover, configuration recovery, and migration away from it.

Privileged Federation Variant

Use a separate privileged identity domain and relying-party registration for administrative functions. Apply ADR 012 for dedicated identities, phishing-resistant MFA, just-in-time elevation, approval, expiry, session evidence, and monitored break-glass. Do not expose privileged claims through a standard-user client or allow a standard session to become privileged solely through an application role change.

Legacy SAML Variant

Use SAML 2.0 only where an upstream provider or legacy relying party cannot support OIDC, as allowed by ADR 013.

• Record the incompatible component, owner, support status, compensating controls, target OIDC architecture, migration milestone, and review date.
• Validate signed assertions and required responses, issuer, audience, destination, recipient, time conditions, request correlation, and replay controls. Restrict accepted bindings, algorithms, certificates, attributes, and endpoints.
• Prefer protocol translation at one supported gateway or broker over adding SAML logic to multiple new applications, but justify that broker under the preceding variant.
• Monitor metadata and certificate expiry and test overlapping certificate rollover. Keep rollback metadata available for the approved window.
• Do not expose LDAP binds or an Active Directory domain directly to an Internet-facing application as a substitute for federation.

Claims, Assurance, and Session Design

Maintain a versioned claims matrix for every relying party. It must distinguish required from optional claims and record source, definition, format, assurance, transformation, release condition, classification, purpose, retention, and fallback behaviour.

• Use the tuple of trusted issuer and immutable provider subject for federation correlation, mapped to an application-owned identifier. Do not use mutable email address, display name, or phone number as the durable subject key.
• Keep workforce, citizen or customer, partner, privileged, and workload identities in separate policies and trust decisions. This architecture does not cover workload federation.
• Preserve unknown, missing, conflicting, and low-assurance claim states. Do not convert them into a favourable default.
• Define token and session lifetime from transaction risk, revocation needs, user experience, provider capability, and outage behaviour. Test logout and reauthentication but do not claim universal logout where dependencies cannot provide it.
• Document which component makes identity-proofing, MFA, step-up, account status, and authorisation decisions and how the relying party verifies each signal.

Implementation Examples

These official links are non-equivalent product examples, not standards, endorsements, or a claim of feature parity. Some combine a user directory, identity provider, broker, login UI, and lifecycle features; others supply only part of the capability model. Validate current Australian-region processing, support access, protocols, authenticators, accessibility, logging, export, recovery, quotas, price, and service objectives.

Provision supported tenants, pools, projects, clients, domains, policies, logging, keys, and networking with OpenTofu or Terraform under ADR 010. Where a provider API cannot manage required identity configuration, record the ADR 010 exception and preserve equivalent review, export, drift detection, audit, and recovery evidence.

Project Kickoff Artifacts

Create these artifacts before implementation selection is final:

• A service context and trust-boundary diagram covering user populations, identity authorities, federation hops, standard and privileged paths, environments, regions, and administrative access
• A relying-party register with owner, purpose, population, URLs, protocol, issuer, client or entity ID, redirect and logout URIs, scopes, claims, assurance, MFA, session, fallback, support, criticality, and review date
• A claims and assurance matrix with privacy, classification, source, transformation, release, missing-value, and authorisation handling
• A provider and direct-versus-broker selection record comparing assurance, privacy, accessibility, resilience, support, integration, export, cost, and concentration risk
• User journeys for login, consent or notice, MFA enrolment, step-up, logout, account linking, recovery, denied access, provider outage, and assisted support, including accessibility findings
• A threat model covering token theft, login CSRF, redirect abuse, account linking, subject collision, claim injection, replay, recovery fraud, enumeration, key compromise, broker compromise, and privileged crossover
• A support RACI naming the relying-party, provider, platform, security, fraud, privacy, service-desk, communications, and supplier escalation owners
• RTO and RPO, dependency and failure analysis, key-rollover plan, fallback and failover runbook, provider status and escalation details, and recovery test schedule
• An OpenTofu or Terraform repository and state design, configuration export, CI/CD and release plan, secrets and certificate inventory, and ADR 010 exception records where needed
• A subject and claim migration plan, provider export test, dual-operation and rollback plan, retention and disposal decision, and exit cost estimate

Privacy, Classification, and Offshoring

Apply the WA Information Classification Policy, Privacy and Responsible Information Sharing, and WA Data Offshoring Governance as applicable. Record agency approvals and controls rather than treating a vendor compliance statement or selected region as approval.

• Classify identity attributes, credentials, MFA methods, recovery data, device and risk signals, subject mappings, authentication logs, support records, configuration exports, and backups.
• Request and release only the claims needed for the relying party’s approved purpose. Prefer service-specific or pairwise identifiers where supported and avoid persistent cross-service correlation without documented authority.
• Record notice, consent where applicable, access, correction, retention, disposal, breach, fraud, and disclosure handling across provider, broker, relying party, logs, and support systems.
• Assess primary processing, control plane, telemetry, messaging, support access, subprocessors, backups, and disaster recovery for offshore handling. Include identity metadata and vendor support, not only profile attributes.
• Prevent identity and authentication data being reused for unrelated analytics or marketing without separate authority. Minimise security logs while retaining the events required by ADRs 007 and 013.

Assess the Digital ID Act 2024 and associated rules only when the service participates in their scope, as ADR 013 requires. Do not represent ordinary OIDC federation as accredited identity proofing.

MFA, Recovery, and Login Accessibility

• Apply ADR 013 MFA requirements by population, information sensitivity, and service risk. For privileged access, apply ADR 012 and prefer phishing-resistant authenticators. SMS or voice is not the target state.
• Design enrolment, replacement, lost-device, compromised-account, and assisted recovery. Verify recovery to an assurance appropriate to the resulting access, notify the user, rate-limit attempts, and log administrative action.
• Provide accessible alternatives for users who cannot use a particular authenticator, device, CAPTCHA, or recovery channel without creating an unmonitored bypass.
• Test the complete login, redirect, consent or notice, error, MFA, timeout, recovery, and logout journey against WCAG 2.2 and applicable WA digital-service requirements. Include keyboard-only, screen reader, zoom and reflow, colour contrast, cognitive load, plain-language error, and mobile testing.
• Make the service desk path discoverable when the provider is unavailable or the user is locked out. Support staff must not be able to bypass proofing, MFA, or audit controls for convenience.

Ownership and Operations

The kickoff RACI must assign named teams, delegates, support coverage, and supplier escalations. At minimum it must allocate these outcomes:

Monitor login success and failure by journey, MFA and recovery outcomes, token validation errors, unknown issuers or keys, metadata age, certificate expiry, provider latency, broker health, claim-mapping failures, privileged elevation, configuration changes, suspicious linking, support demand, and synthetic login tests. Set privacy-preserving thresholds and named response actions; avoid placing tokens or unnecessary claims in logs.

Resilience, Key Rollover, and Recovery

• Set RTO and RPO for login, federation configuration, subject mappings, local account data, audit evidence, and administrative recovery. Include DNS, network, messaging, MFA, secrets, certificates, key services, and supplier support dependencies.
• Consume OIDC discovery and JSON Web Key Sets only from configured trusted issuers. Cache safely for bounded outages, refresh on an unknown key ID, and fail closed for an untrusted issuer, invalid signature, or unacceptable token. Do not dynamically trust an alternate issuer.
• Test planned signing-key rollover with overlapping keys, cache refresh, old token validation, emergency revocation, rollback, monitoring, and provider- relying-party coordination. For SAML, test equivalent metadata and certificate rollover before expiry.
• Define critical-service fallback under ADR 013. A fallback may use a tested alternate approved provider, constrained offline process, or monitored break-glass path, but must preserve appropriate assurance and authorisation, be time-bound, and produce audit evidence.
• Treat failover to a second provider as a separate trust and subject-mapping design. Pre-register and test it; define how issuer, subject, claims, MFA, sessions, account linking, and rollback behave. DNS switching alone is not identity failover.
• Under ADR 014, keep independent and tested recovery material for configuration, infrastructure state, client and claim registers, mapping data, audit evidence, and keys or key-recovery procedures. Replication and provider availability are not backups by themselves.

Migration and Exit

Test export before selecting a provider. Document supported exports and APIs for users where lawfully held, immutable identifiers, attributes, group or policy assignments where in scope, clients, redirect URIs, identity providers, claims rules, branding, templates, logs, consent or notice evidence, and configuration. Record credentials and MFA methods that cannot be exported and the user re-enrolment impact.

1. Create a protected mapping from old trusted issuer and subject to the application-owned identity and the new provider subject. Never join accounts automatically on mutable email alone.
2. Map claim names, values, provenance, assurance, missing states, and local authorisation effects. Test representative and adverse identities.
3. Run old and new federation in parallel for controlled cohorts or a defined dual-login window. Monitor login, linking, MFA, recovery, support, and authorisation outcomes without creating duplicate accounts.
4. Define cutover authority, user communications, session invalidation, rollback triggers, old-provider availability, mapping rollback, and the maximum rollback window. Exercise rollback before broad migration.
5. Retain the old configuration, mappings, logs, and recovery path until acceptance and rollback periods end. Then revoke trust, clients, keys, administrative access, and supplier access and dispose of data under approved authority.

Verifiable Credentials Roadmap

Verifiable credentials are roadmap only, not a current federation variant or requirement. Monitor W3C Verifiable Credentials Data Model 2.0, OpenID for Verifiable Credentials, and ISO/IEC 18013-5. Adopt only through a separate approved decision with a specific use case and evidence for trust framework, issuer and verifier governance, selective disclosure, consent, revocation or status, device binding, recovery, accessibility, interoperability, privacy, support, and fallback. Do not delay a suitable OIDC federation waiting for this roadmap.

Acceptance Checks

• The scope is federation; lifecycle, proofing, entitlement, workload identity, and fine-grained authorisation owners and non-goals are explicit
• Accepted ADR requirements, including ADR 014 recovery controls, are implemented
• Every relying party is in the register with owner, protocol, issuer, clients, URLs, claims, assurance, MFA, session, fallback, support, and review
• Direct OIDC is used for new integrations unless the broker or SAML variant has an approved, evidenced justification and migration boundary
• Standard and privileged identities, clients, paths, administration, and policies are separated and tested
• Claims and assurance mappings are versioned, minimised, privacy-approved, and tested for missing, conflicting, stale, and low-assurance values
• Classification, privacy, retention, supplier, location, and offshoring assessments cover profiles, mappings, logs, support, telemetry, and backups
• MFA enrolment, step-up, lost-device, compromise, assisted recovery, and accessible alternative journeys pass security and user testing
• Complete login and recovery journeys pass applicable WCAG 2.2 testing on representative browsers, devices, and assistive technologies
• Token or assertion validation, redirect restrictions, sessions, logout, account linking, enumeration, replay, and fail-closed behaviour pass tests
• Planned and emergency key or certificate rollover, metadata caching, expiry alerts, fallback, failover, and rollback meet approved service targets
• The support RACI, monitoring, synthetic tests, runbooks, provider contacts, user communications, and incident exercises are operational
• OpenTofu or Terraform plans, state controls, configuration exports, drift detection, and recovery evidence meet ADR 010
• Subject and claim migration, provider export, controlled parallel login, rollback, trust revocation, retention, and decommissioning are tested
• Verifiable credentials remain roadmap-only unless a separate approved decision establishes the use case and controls

ADR ###: Specific Decision Title

Status: Proposed | Date: YYYY-MM-DD | Review: YYYY-MM-DD

Set Review to one year after Date.

Synopsis

• Use when: One sentence describing the conditions that make this ADR applicable.
• Avoid when: One sentence describing important exclusions or simpler alternatives.
• Decision: One sentence stating the selected approach.
• Required evidence: The minimum artifacts that demonstrate implementation.
• Dependencies: Link direct ADR dependencies, including their status where relevant, or write None.

Context

What problem are we solving? Include background and constraints.

Policy and Standards

• Authoritative policy or guidance landing page
• Durable capability terms supported by this decision
• External guidance used to implement the decision

Prefer terms such as multi-factor authentication, application patching, or secure software development over policy clause numbers. Record exact policy versions and clauses in agency assurance records when point-in-time traceability is required.

State whether the ADR fully or partially supports each capability. Do not claim that use of an ADR proves compliance.

Applicability

Use this ADR when:

• Project or service condition 1 applies
• Project or service condition 2 applies

Do not use this ADR for:

• Out-of-scope condition 1
• Out-of-scope condition 2

Decision

What we decided and how to implement it:

• Requirement 1: Specific implementation detail
• Requirement 2: Configuration specifics
• Requirement 3: Monitoring approach

Implementation Checklist

• Configuration or control 1 is in place
• Configuration or control 2 is in place
• Logging, monitoring, or review evidence is captured

Required Evidence

• Configuration or policy export showing the control is enabled
• Test, monitoring, or review record showing the control is effective
• Named owner and review date for retained evidence

Exceptions

Where a mandatory requirement cannot be implemented, record the reason, compensating controls, residual risk, accountable executive approval, expiry date, and reassessment date in the implementing agency’s risk system.

Related ADRs

• ADR ###: Related Decision

Consequences

Positive:

• Benefit 1 with explanation
• Benefit 2 with explanation

Negative:

• Risk 1 with mitigation
• Risk 2 with mitigation

Reference Architecture: Pattern Name

Status: Proposed | Date: YYYY-MM-DD | Review: YYYY-MM-DD

Set Review to one year after Date.

Reference architectures are informative compositions of ADRs. Mandatory requirements must come from Accepted ADRs or other authoritative policy. Label Proposed dependencies, optional examples, and unresolved decisions explicitly.

Purpose

Describe the service outcome and the intended audience in two or three sentences.

Applicability and Non-Goals

Use this pattern when:

• Service or project condition 1 applies
• Service or project condition 2 applies

Do not use it when a simpler pattern is sufficient. State related capabilities that remain outside scope.

How to Use This Reference Architecture

Do not use this page to silently decide a missing standard. Add unresolved foundational decisions to the proposed-decision backlog.

Assumptions and Prerequisites

• Accountable business, information, technical, security, operational, and accessibility owners are identified
• Users, critical journeys, classification, privacy, sharing, records, offshoring, service objectives, budget, support, and legacy constraints are known
• Required identity, networking, logging, recovery, supplier, and delivery capabilities are available or have an owned plan

Architecture Variants

Select only the capabilities the service needs. Variants are not assurance claims by themselves.

Capability View

flowchart LR
    source[Users and Sources]
    service[Service Capabilities]
    output[Consumers and Outputs]
    control[Identity, Security, Operations, and Evidence]

    source --> service --> output
    control -.-> service

Describe trust boundaries and provider-neutral responsibilities before naming products.

Implementation Options

Examples are not standards. Prefer OpenTofu, or Terraform where justified, for provisionable infrastructure under ADR 010.

Project Kickoff Artifacts

• Service brief, scope, selected variant, outcomes, and non-goals
• Ownership and responsibility matrix
• Current and target architecture, trust-boundary, and data-flow diagrams
• Classification, privacy, sharing, records, offshoring, supplier, and accessibility assessments as applicable
• Service objectives, support model, threat model, cost envelope, recovery, migration, and exit plans
• ADR dependency and project-decision record

Roles and Operating Model

Name owners for service outcomes, information, platform, suppliers, security, privacy, records, accessibility, support, incidents, changes, recovery, cost, and exit.

Assurance Considerations

Address:

• Security, identity, classification, privacy, sharing, and offshoring
• Accessibility and assisted-digital needs
• Logging, service levels, capacity, cost, incident response, and supplier escalation
• Independent backup, resilience, degraded operation, and recovery tests
• Legacy migration, data and configuration export, rollback, and decommissioning

Acceptance Checks

• Applicability, selected variant, owners, and non-goals are approved
• Mandatory statements trace to Accepted ADRs or authoritative policy
• Proposed dependencies and project-specific decisions are explicitly approved
• Architecture, data flows, trust boundaries, and provider responsibilities are documented
• Functional, security, privacy, accessibility, performance, resilience, recovery, and operational checks pass for representative journeys
• Runbooks, monitoring, support, supplier escalation, migration, and exit are tested or have an approved plan

Related Decisions

• ADR ###: Related Decision

Contributing Guide

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

When to Create ADRs

Create ADRs for foundational decisions only:

• High cost to change mid/late project
• Architectural patterns and technology standards
• Security frameworks and compliance requirements
• Infrastructure patterns that affect multiple teams

Do not create ADRs for:

• Implementation details (use documentation)
• Project-specific configurations
• Operational procedures that change frequently
• Tool-specific guidance that belongs in user manuals

Quick Workflow

1. Open the repository - Use Codespaces, a dev container, or an agency-managed workstation with the required tools
2. Get number - just next-number
3. Create file - ###-short-name.md in correct directory (see content types)
4. Write content - Follow template below
5. Set annual review metadata - Review must be one year after Date
6. Add to SUMMARY.md - Include new ADR in navigation (required for mdBook)
7. Lint - just lint to fix formatting, check metadata, check SUMMARY.md, and validate links
8. Submit PR - Ready for review

Useful Commands

just --list      # Show all available commands
just next-number # Get next ADR number
just check-summary # Verify SUMMARY.md includes all markdown files
just check-metadata # Verify status/date/review metadata
just lint        # Run checks and fixes
just serve       # Preview locally on port 8080
just build       # Build website and print view

AI-Assisted Contributions

AI tools may help draft or review ADRs, but a human contributor remains responsible for the final content.

• Prefer isolated or local AI tooling per ADR 011: AI Tool and Agent Governance
• Review adr-design-guardrails.md before proposing changes
• Browse reference-architectures/ for project kickoff patterns
• Check existing ADRs in development/, operations/, and security/ before creating new guidance
• Human review is required for all AI-generated changes before merge
• Recommended tools include OpenCode and Goose

flowchart LR
    setup[Environment Setup]
    create[Content Creation]
    validate[Validation]
    publish[Publication]

    setup --> create --> validate --> publish
    validate -->|fix issues| create

    style setup fill:#e3f2fd
    style create fill:#e8f5e8
    style validate fill:#f3e5f5
    style publish fill:#fff3e0

Project Notes

• Documentation is built with mdBook
• Navigation is defined in SUMMARY.md; new ADRs must be added there
• just build creates the website and a single-page print view
• Use Mermaid diagrams where a simple visual explanation is clearer than text alone
• Each maintained guidance page has Status, Date, and Review metadata
• Review dates are annual by default: set Review exactly one year after Date

Directory Structure

Content Types: When to Use What

ADRs (Architecture Decision Records)

Purpose: Document foundational technology decisions that are expensive to change
Format: ###-decision-name.md in development/, operations/, or security/
Examples: “Managed Kubernetes”, “Secrets management”, “HTTP API contracts”

Reference Architectures

Purpose: Project kickoff templates that combine multiple existing ADRs
Format: descriptive-name.md in reference-architectures/
Examples: “Content Management”, “Data Pipelines”, “Identity Management”

Rules:

• Reference architectures are informative compositions, not a place to create foundational decisions
• Mandatory statements must trace to Accepted ADRs or authoritative policy
• Proposed ADR dependencies must be labelled and require project approval
• Product and provider mappings are non-normative examples unless an Accepted ADR explicitly selects them
• Add missing foundational decisions to the proposed-decision backlog
• Include minimum and higher-assurance variants, legacy adoption, required artifacts, operating ownership, acceptance checks, migration, and exit

ADR Template

See templates/adr-template.md for the complete template.

Note: ADR numbers are globally unique across all directories (gaps from removed drafts are normal)

Reference Architecture Template

See templates/reference-architecture-template.md for the complete template.

Reference Architecture Review Checklist

• Applicability, non-goals, prerequisites, and simpler alternatives are clear
• Accepted and Proposed dependencies are distinguished
• Every mandatory statement traces to an Accepted ADR or authoritative policy
• Minimum, higher-assurance, and legacy-transition variants are practical
• Capabilities are provider-neutral; AWS, Azure, Google Cloud, SaaS, and legacy examples are labelled non-equivalent where relevant
• OpenTofu or Terraform is the preferred provisionable infrastructure path under ADR 010
• Kickoff artifacts, ownership, service levels, support, and cost are explicit
• Classification, privacy, sharing, records, offshoring, accessibility, resilience, recovery, migration, rollback, and exit are addressed
• Acceptance checks are testable with representative users and journeys

Quality Standards

Before submitting:

• Title is concise (under 50 characters) and actionable
• Status, date, and annual review metadata are present
• Synopsis states when to use and avoid the ADR, the decision, minimum evidence, and direct ADR dependencies
• All acronyms defined on first use
• Active voice (not passive)
• Scope, non-goals, and related ADRs are clear
• Policy references use authoritative links and durable capability terms
• Compliance claims distinguish full, partial, and out-of-scope coverage
• Implementation checklist is specific enough for project kickoff
• Required evidence and exception handling are explicit
• Passes just lint without errors

Title Examples:

• GOOD: “ADR 002: Managed Kubernetes” (concise and capability-focused)
• GOOD: “ADR 008: Email Authentication Protocols” (specific, clear)
• BAD: “ADR 004: Enforce release quality with CI/CD prechecks and build attestation” (too long)
• BAD: “Container stuff” or “Security improvements” (too vague)

Status Guide

Use this metadata line directly below the title:

**Status:** Proposed | **Date:** YYYY-MM-DD | **Review:** YYYY-MM-DD

Set Review to the same month and day in the following year. For example, Date: 2026-06-09 uses Review: 2027-06-09.

Annual Review Checklist

Use this checklist for every scheduled review:

• Status is still correct: Proposed, Accepted, or Superseded
• Decision still reflects current WA Government policy and standards
• External links still resolve and point to the intended guidance
• Related ADR links are current
• Compliance mapping is still accurate
• Implementation checklist remains practical for new projects
• Acronyms, glossary terms, and diagrams remain clear
• Review date is advanced by one year after the review is complete

ADR References

Reference format:

• [ADR 005: Secrets Management](../security/005-secrets-management.md)
• Quick reference: per ADR 005
• Multiple refs: aligned with ADR 001 and ADR 005

Examples:

• “Encryption handled per ADR 005: Secrets Management”
• “Access controls aligned with ADR 001”

Writing Tips

• Be specific about capabilities: “Use managed Kubernetes only when the workload-fit criteria apply” not “Use containers”
• Include implementation: How, not just what
• Define scope: What’s included and excluded
• State non-goals: Help readers avoid using an ADR outside its intended scope
• Link by decision: Prefer ADR links over repeating requirements in multiple places
• Reference standards: Link to external docs
• Use durable terms: Map to capabilities such as application patching or identity and access management, not policy clause numbers
• Separate audit snapshots: Keep exact policy versions and clauses in agency assurance or risk records where point-in-time traceability is needed
• Map honestly: Say an ADR supports a capability; do not imply that adopting an ADR alone proves compliance
• Make controls testable: Use must for mandatory requirements and name the evidence an implementation must retain
• Australian English: Use “organisation” not “organization”, “jurisdiction” not “government”
• Character usage: Use plain-text safe Unicode - avoid emoji, smart quotes, em-dashes for print page compatibility
• Mermaid diagrams: Use Mermaid for diagrams with clean syntax and universal compatibility
  • Use when text alone isn’t sufficient (system relationships, data flows, workflows)
  • Keep simple: 5-7 components max, clear labels, logical flow
  • Use flowchart TB for compact layouts, flowchart LR for flows
  • Use style directives for color styling, keep labels short

Compliance Mapping

Status: Accepted | Date: 2026-07-11 | Review: 2027-07-11

This mapping uses stable cyber security capability terms to show how Architecture Decision Records (ADRs) support WA Government cyber security outcomes. It intentionally avoids policy clause numbers, which can change between policy releases without changing the underlying security outcome.

Authoritative WA Sources

Read the current requirements and applicability from these sources:

• WA Government Cyber Security Policy
• DGov policies and guidance
• DGov Cyber Security Unit
• WA Cyber Security Unit technical guidance

The capability name is the durable link between policy intent and technical decisions. Agencies should record the exact policy release and applicable clauses in their compliance plan, assurance assessment, or risk system. This keeps shared ADRs stable while retaining point-in-time audit traceability.

How to Use This Mapping

• Match obligations to the closest capability term, then apply all relevant ADRs and current WA guidance.
• Strong means the ADR contains substantial, testable technical requirements for the capability. Partial means material requirements remain outside the ADR. Gap means no current ADR provides a reusable technical baseline. Organisational means the outcome belongs primarily in an agency policy, process, contract, or risk record.
• A Proposed ADR is not accepted guidance.
• Implementing agencies must retain the evidence named in each ADR and evidence for requirements that sit outside this repository.
• Where a primary protection cannot be implemented, record compensating protections, residual risk, accountable executive approval, expiry date, and reassessment date in the agency risk system.

Core Protection Capabilities

Enterprise and Specialised Protection Capabilities

Evidence Summary

Implementing teams should assemble evidence by service rather than relying on this mapping alone:

• Asset, identity, domain, supplier, data-flow, log-source, backup, secret, and released-artifact inventories
• Version-controlled configurations and policy exports
• Scan, test, restore, detection, access-review, and incident records
• Remediation plans and dated exception records
• Executive approvals for residual risk where primary protections are absent

Other Framework Associations

The ADRs also reference Australian Cyber Security Centre (ACSC) guidance, the WA Government AI Policy and Assurance Framework, privacy obligations, and the Digital ID Act 2024. These references provide design context. Detailed compliance claims should only be added where an ADR contains a matching normative requirement and named implementation evidence.

National Guidance

• ACSC Essential Eight
• ACSC Essential Eight Maturity Model
• ACSC Information Security Manual guidance

Glossary

Status: Accepted | Date: 2026-06-09 | Review: 2027-06-09

Acronyms and Definitions

ACSC - Australian Cyber Security Centre
ADR - Architecture Decision Record
API - Application Programming Interface
ATT&CK - Adversarial Tactics, Techniques & Common Knowledge (MITRE)
AWS - Amazon Web Services
BIMI - Brand Indicators for Message Identification
CDN - Content Delivery Network
CI/CD - Continuous Integration/Continuous Deployment
CNCF - Cloud Native Computing Foundation
DBaaS - Database as a Service
DGOV - Office of Digital Government (Western Australia)
DKIM - DomainKeys Identified Mail
DMARC - Domain-based Message Authentication, Reporting and Conformance
DNS - Domain Name System
DSPF - Digital Services Policy Framework (Western Australian Government)
DTT - Digital Transformation and Technology Unit
EKS - Elastic Kubernetes Service (AWS)
ETL - Extract, Transform, Load
GCP - Google Cloud Platform
IAM - Identity and Access Management
IAP - Identity-Aware Proxy
ISM - Information Security Manual (ACSC)
JIT - Just-In-Time
OIDC - OpenID Connect
OWASP - Open Web Application Security Project
PII - Personally Identifiable Information
PITR - Point-in-Time Recovery
PKCE - Proof Key for Code Exchange
RDP - Remote Desktop Protocol
RPO - Recovery Point Objective
RTO - Recovery Time Objective
SAML - Security Assertion Markup Language
SBOM - Software Bill of Materials
SIEM - Security Information and Event Management
SPF - Sender Policy Framework
SSO - Single Sign-On
TLS - Transport Layer Security
VMC - Verified Mark Certificate
VPN - Virtual Private Network
WAF - Web Application Firewall
WCAG - Web Content Accessibility Guidelines