Architecture as Code: when the architecture is checked on every change
For architects, engineers, security and governance professionals and IT leaders at a conference or internal architecture day
Most organisations have an architecture on paper and another one in production. The keynote presents the argument of the book: when architectural specifications become executable, governance becomes continuous instead of periodic, and the distance between intent and implementation collapses. It shows what that takes in practice, a readiness the organisation must earn, a platform that validates every change, controls that are assured once and mapped to many obligations, and an organisation that codifies even its management intent. It ends with the ways programmes fail and the question of accountability for machine-authored decisions.
6 min
Two architectures: the one in the slides and the one that runs
Slideware syndrome and architectural entropy: unchecked artefacts lose coherence with implemented systems.
Microservice estates add contracts and topologies faster than static diagrams can follow.
Delivery in hours turns manual governance checkpoints into bottlenecks that teams bypass.
7 min
The claim: executable specifications
Architecture as Code describes, version-controls and automates the whole architecture in machine-readable form.
It learned from model-driven development: lightweight textual models that evolve alongside the implementation instead of replacing it.
Five causes of drift each meet a countermeasure in a version-controlled workflow.
8 min
The platform: decide, model, validate, promote
Decision records keep the rationale; one model generates the views.
Pipelines fail fast in four validation layers and promote with evidence bundles.
Declarative platforms reconcile the running state with what was declared.
8 min
Assure once, comply many
A control is written, tested and evidenced once and mapped to every framework it satisfies.
Governance moves into pull requests, with exceptions as code that expire.
Evidence is generated and signed by the pipeline, not reconstructed at audit season.
8 min
The organisation that can carry it
Readiness is a synthesis of culture, technology and economics, and automation without alignment amplifies disorder.
Teams move from siloed functions to product-aligned teams that are autonomous within guardrails.
Management intent, budgets and norms can be versioned and reviewed like any other artefact.
AI agents draft and check; named people approve consequential decisions.
8 min
How it fails, and what remains open
The recurring anti-patterns: a tool purchase in place of change, audit theatre, hero culture, scaling without maturity gates.
Four leading indicators give early warning before drift escalates.
Version control records what changed, not who held responsibility for a decision a language model proposed.
What the audience takes away
When architecture is executable, governance becomes continuous and the gap between intent and implementation can be measured and closed.
Tools come last: readiness in culture, technology and funding, and people who own the practice together, decide whether it lasts.
Start with a contained pilot, keep the rationale in decision records, and keep human accountability explicit for every consequential decision.
From slideware to executable specifications: the foundations of Architecture as Code
The lecture carries the argument of Part A. Traditional architecture drifts away from operational reality because its artefacts are static while delivery moves in hours. Architecture as Code answers by making the architecture a live, executable specification under version control. The lecture shows why readiness in culture, technology and economics comes before tooling, which principles follow from learning the lessons of model-driven development, how Git workflows act as a countermeasure against drift, and why decision records are the memory that keeps the whole practice auditable.
8 min
The problem: slideware syndrome and architectural entropy
Static decks, diagrams and committee reviews drift away from operational reality, and teams then improvise workarounds that bypass the guardrails.
Large microservice estates are the tipping point: each service adds APIs, contracts and deployment topologies faster than static diagrams can follow.
The core claim of the book: when specifications become executable, governance becomes continuous rather than periodic.
7 min
Readiness before tooling
Automation without alignment merely amplifies disorder, so a readiness review slows the rush to tool selection.
Readiness is a synthesis of culture, technical maturity and economic discipline, assessed in four loops and scored on a scorecard.
The anti-patterns to name early: tool-first enthusiasm, heroic ownership, budget whiplash, governance bypass and metrics myopia.
10 min
The principles: declarative, immutable, testable
Declarative definitions state the desired state at every level and make deviations visible.
Model-driven development promised generated implementations and fell out of sync; Architecture as Code prefers lightweight textual models, explicit version control and continuous validation.
Architectural drift has five named causes, and each has a countermeasure in a version-controlled workflow.
Requirements as Code separates what can be tested automatically from what needs stakeholder validation.
10 min
Version control as the contract between layers
Architecture as Code sits one abstraction layer above Infrastructure as Code: one publishes guardrails, the other consumes them.
Repository topology and branching strategy are foundational decisions with real trade-offs, and the hybrid topology is often the pragmatic one.
Branch protection, required status checks and signed commits turn the repository from a passive store into an active countermeasure.
10 min
Decision records as institutional memory
An ADR is the commit message of the architecture: context, decision, consequences and status.
Numbers are permanent and a changed decision is superseded by a new record, never edited in place.
Treated as code, ADRs can be scaffolded, linted, reviewed and reminded about, and their metadata feeds dashboards such as the review debt tracker.
What the audience takes away
Architecture as Code is a governing discipline, not a tooling choice: the architecture becomes a live, executable specification that stays synchronised with the running estate.
Readiness in culture, technology and economics is the evidence that an organisation can use executable architecture responsibly.
Version control, automated validation and decision records together are what stop the documented architecture and the running system from drifting apart.
Module 2 · Part B · Architecture Platform · 45 minutes
The platform that makes architecture checkable on every change
Part B argues that pipelines are where Architecture as Code stops being a description of intent. The lecture follows one architectural change through the platform: it is modelled once in a single source of truth, validated in layers that fail fast, promoted through environments with evidence attached, deployed to a container platform that reconciles declared and actual state, and governed in a microservice estate through contracts and reusable golden paths. The thread is the division of labour between Architecture as Code, which states what must be true before runtime, and Infrastructure as Code, which makes it so.
8 min
Which pipeline stage owns which decision
Architecture as Code codifies what must be true before runtime; Infrastructure as Code consumes those policies to produce compliant infrastructure.
The shift from infrastructure as pets to infrastructure as cattle made systematic automation possible.
Pipeline telemetry flows upwards, so that architecture standards evolve with evidence rather than assumption.
10 min
Fail fast, promote with evidence
Four validation layers: syntax and static analysis, security and compliance scanning, cost estimation, and policy validation.
Promotion through environments is deterministic: template-driven parity, policy-controlled approvals and evidence bundles.
Approvals belong on the protected environment, not in the pipeline definition, so authors cannot weaken a gate by editing the pipeline.
Maintainability telemetry such as the pipeline stability index and policy breach density makes automation debt visible.
9 min
One model, many views
The C4 model gives four levels of abstraction, each narrowing audience and scope.
Diagram decay is the divergence that follows when diagrams are updated by hand; generating views from one model removes the manual step.
The DSL holds the model and the views, the workspace JSON holds the manual layout, and both belong in version control.
9 min
Declared state and reconciliation
The Kubernetes control plane continuously reconciles actual state with the declarations, enforcing Architecture as Code in real time.
GitOps treats the Git repository as the source of truth, so a rollback is a reverted commit.
Guard rails validate every manifest before production, and scheduled diffs detect drift that reconciliation alone does not explain.
9 min
Autonomy with guardrails in a microservice estate
Each service is a bounded context whose architecture definition lives beside its code.
Contract-first integration and an executable catalogue reveal coupling before it breaks consumers.
Golden paths give autonomous teams approved defaults, and deviations are reviewed through decision records.
What the audience takes away
A pipeline for Architecture as Code validates applications, data, infrastructure, security and governance as one whole, and leaves evidence at every stage.
A single architecture model that generates its diagrams is the practical answer to diagram decay.
Declarative platforms and reusable golden paths let teams move independently while the architecture stays coherent and auditable.
Module 3 · Part C · Security, Governance & Assurance · 50 minutes
Assure once, comply many: security, governance and evidence as code
Part C argues that controls written in natural language and checked by hand cannot keep pace with continuous delivery. The lecture follows one control objective, multi-factor authentication for human identities, through the whole part: it is motivated by Zero Trust and threat modelling, tied to a risk definition, written as a policy, approved through a pull request, mapped once to several frameworks in a Control Mapping Matrix, and proven by evidence that the pipeline generates and signs. The principle that holds the part together is assure once, comply many.
8 min
From perimeter to Zero Trust
The hard shell, soft centre model fails when workloads, staff and service-to-service calls are spread across clouds and home networks.
Never trust, always verify becomes trust as code when segmentation, mesh rules and identity configuration are declared and enforced consistently.
STRIDE must be applied to infrastructure definitions, pipelines and secrets management, not only to the application.
8 min
Patterns that run on every change
Infrastructure state holds inventories and secrets, so it needs a remote backend, locking, encryption, versioning and monitored access.
Risk registers and threat playbooks belong in the repository: a risk has an owner and a review date, and a playbook subscribes, assesses, acts and documents.
Exceptions are code artefacts with explicit expiry dates and approval chains.
10 min
Policy engines and a language for controls
Security management matured through four phases, from manual validation to holistic governance frameworks.
Open Policy Agent enforces policies; OSCAL describes controls, evidence and assessments in machine-readable form.
Policies are themselves tested, positively and negatively, before they gate anyone else's work.
8 min
Governance through pull requests
Draft, review, validation, documentation and production stages give governance artefacts an explicit state and a formal audit trail.
Governance professionals keep ownership through repository roles, training, pairing and low-code tooling.
Six metrics, from policy coverage to remediation lead time, show whether automated controls can be relied upon.
8 min
The compliance loop and one matrix
Regulatory intelligence, policy templates, automated controls, evidence collection and governance reinforcement form a closed loop.
The Control Mapping Matrix links one control identifier to its assurance artefacts and to every framework it satisfies.
The worked control SEC-ID-001 executes once and satisfies several attestations.
8 min
Evidence as the currency of trust
Evidence is captured deterministically from automated checks, not manual screenshots, and links back to commits and pull requests.
A software bill of materials and signed provenance make the supply chain verifiable without taking the producer's word.
Evidence has a lifecycle from capture to expiry, with access control on the store itself.
What the audience takes away
A control that is expressed, tested and evidenced once can be mapped to many obligations, which is what reduces audit fatigue.
Risk, threat handling, policy and governance approvals become reviewable and testable when they live in the same repository as the architecture.
Machine-generated, signed and versioned evidence turns compliance from a periodic reconstruction into a continuous by-product of delivery.
Module 4 · Part D · Delivery & Operations · 45 minutes
Testable, recoverable, affordable: delivering Architecture as Code in practice
Part D asks what it takes to run Architecture as Code as an everyday delivery practice. The lecture argues that four questions must be answerable for every change: how it is tested before anything is deployed, how the organisation adopts the practice in stages without overwhelming teams, what the change costs and who sees that cost in the pipeline, and how the estate that is still managed by hand shrinks step by step. The common thread is that every change request must show how it stays testable, recoverable and reversible.
10 min
The test pyramid for codified infrastructure
Infrastructure testing targets configuration, resource compatibility and environmental consistency, not business logic.
Unit tests run without deploying anything; mocks and built-in test frameworks have narrowed the gap between programmatic and declarative tools.
Policy engines act preventively in the pipeline, while detective rules evaluate resources after deployment.
Start with security scanning and policy testing, and add end-to-end tests where the risk justifies their cost.
10 min
An adoption journey in four stages
Discovery, Pilot, Scale and Optimise, each with a lead team and one milestone.
Front-loaded stakeholder alignment avoids the most common integration issues later.
The resilience checklist asks every change for artefacts on pre-change validation, state resilience, recovery drills and rollback readiness.
8 min
Cost as a property of the architecture
Cost is declared in code, estimated in the pipeline and reviewed alongside the change that causes it.
Allocation tags and chargeback make spending transparent and give developers an incentive to design cost-consciously.
Commitments are made only after a usage baseline and after rightsizing, because committing to the wrong size locks in waste.
10 min
Migration as small, reversible steps
Assessment comes first: inventory, dependency mapping, risk assessment and cost-benefit analysis.
Four strategies, from lift-and-shift to application retirement, suit different applications; lift-and-improve fits the majority of enterprise migrations.
Existing resources are imported into code and then checked for drift, so that the template is proven to describe reality before any further change.
7 min
Why the technical part is not enough
Pilots with non-critical systems let teams learn before critical systems are touched.
Systems administrators and network engineers need training, mentorship and cross-functional teams to move into code-based workflows.
Technical migration succeeds only with the organisational readiness that Part E describes.
What the audience takes away
A layered test strategy catches problems early in the development cycle, when they are cheaper and simpler to fix.
Every change should carry evidence that it is testable, recoverable and reversible, and cost should be visible in the same review.
Adoption and migration both proceed in stages: pilot on something non-critical, prove value, then scale with repeatable patterns.
Module 5 · Part E · Organisation & Leadership · 50 minutes
People, process and technology in equal measure: the organisation behind Architecture as Code
Part E argues that Architecture as Code succeeds only when organisations invest equally in people, process and technology. The lecture traces how the same operating model, structured representation, version control and automation, moves from infrastructure into the softer fabric of the organisation: team charters, competency frameworks, budgets, decisions, norms and lessons learned. It then examines two extensions of that idea, a team of AI agents that drafts and checks under named human approval, and a digitalisation strategy in which provider choice and data sovereignty are written as policy. The constant is transparency: decisions leave a searchable record.
8 min
From siloed functions to product-aligned teams
Organisations move through four stages, each with its own team structure, decision making and automation maturity.
Psychological safety and blameless retrospectives let teams learn from incidents without defensive behaviour.
Resistance often signals legitimate concerns about job security, skill gaps or process disruption.
8 min
Designing teams and growing competence
Platform teams act as internal service providers and treat infrastructure as a product.
A skills matrix with four levels and a balanced scorecard make expectations and progression explicit.
Communities of practice and co-maintained runbooks reduce the bus factor.
9 min
Management intent as executable artefact
Management as Code differs from management documentation in three ways: it is executable, it follows change management discipline, and it is instrumented with telemetry.
Issues record decisions and Discussions host deliberation, and both link to the code change that implements them.
Budgeting as Code defines budget envelopes that are adjusted through pull requests and validated by tests.
8 min
The soft disciplines compound
All share a common DNA: structured representation, version control and automatability.
Compliance as Code is the quality engine, Architecture as Code the hub and Documentation as Code the communication layer.
Codified rules do not capture every interpretation, so manual controls and clear governance remain necessary.
8 min
AI agents as structured participants
Specialist agents work from a single backlog, common documentation practices and shared quality thresholds.
Four categories of decision remain with people; agents draft and humans approve.
Every agent-generated artefact stays traceable to a commit, a pull request and an accountable individual.
9 min
Digitalisation within European boundaries
Regulatory drivers such as the GDPR and the NIS2 Directive shape cloud-first strategies in the EU.
Provider selection is written as policy that distinguishes inherently sovereign providers from those acceptable only with EU-only controls in force.
A keyword search for encryption in a pipeline is not a meaningful compliance check; policy-as-code tooling is.
What the audience takes away
Tools create possibilities, but sustained transformation depends on culture, capability development and structures that reward collaboration over individual heroics.
Management intent, budgets, norms and lessons can be versioned, reviewed and measured like any other code artefact, which makes leadership auditable.
AI agents and cloud providers alike are governed through explicit, codified guardrails with named human approval for consequential decisions.
Module 6 · Part F · Experience & Best Practices · 40 minutes
Explaining an architecture is not the same as enforcing it
Part F makes one distinction and draws one synthesis. The distinction: Documentation as Code communicates knowledge to people, while Architecture as Code defines structure and enforces constraints for people and machines. A diagram drawn as text is still a diagram; only a model can be queried, validated and used to drive automation. The synthesis: mature programmes layer their capabilities across seven practice clusters, and the most successful pair disciplined engineering routines with human-centred ways of working, so that automation never removes context or accountability.
8 min
Two disciplines, two purposes
Documentation as Code answers how a system is configured, operated and why decisions were made; its audience is human.
Architecture as Code answers what components exist, how they communicate and whether the running system matches the approved design.
Success is measured differently: reduced onboarding time on one side, prevented drift and automated compliance on the other.
9 min
Modelling tools and diagram tools
With CALM and Structurizr the model is the source of truth, and diagrams, documentation and compliance reports are derived from it.
With Mermaid and PlantUML the diagram itself is the primary artefact, with limited metadata, no automated validation and manual synchronisation.
The book itself uses Mermaid because its diagrams are documentation, not executable models.
7 min
How the two reinforce each other
Architecture feeds documentation with generated diagrams, component catalogues and compliance statements.
Documentation explains architecture through decision rationale, usage guides and conceptual overviews.
Five integration practices keep both in one reviewed, version-controlled ecosystem.
9 min
Seven practice clusters
Code organisation, secure foundations, performance management, governance, people enablement, collaborative ecosystems and continuous improvement.
An orderly codebase is the first visible signal of a mature programme.
Part G holds two views side by side. Looking forward, the discipline is shaped by intelligent automation, quantum-resistant cryptography, distributed infrastructure, sustainability and sovereignty, and the book's advice is to invest in adaptive capabilities instead of individual technologies. Looking back at how programmes fail, the same causes recur: buying a tool in place of changing an organisation, governing by exception, relying on a few experts. The lecture closes with the book's constants, declarative intent, repeatability, automated testing and continuous delivery, and with the question it leaves open: how human accountability is kept over artefacts that a language model proposed.
9 min
The drivers of change
AI services ingest observability data and propose or execute configuration changes; in the EU this meets the risk-based framework of the AI Act, Regulation (EU) 2024/1689.
Post-quantum standards exist, and hybrid patterns bridge the transition; algorithm agility belongs in infrastructure definitions.
Sustainability moves from optional consideration to design requirement, with carbon-aware scheduling as a concrete pattern.
7 min
Adaptive capability over individual technologies
Flexible architectures, modular codebases and automated testing form a foundation that can absorb new paradigms.
Platform engineering offers golden paths and self-service with compliance built in.
Six clusters of anti-patterns: strategy, governance, delivery, tooling, culture and sustainability, with blind spots that pass risk from one to the next.
Each anti-pattern has a stated recovery, for example time-boxed exceptions stored as code in place of spreadsheets of waivers.
Four leading indicators give early warning: contribution imbalance, exception backlog growth, pipeline failure clustering and shadow tooling.
A three-step remediation playbook and four severity levels turn detection into response.
7 min
A six-step way in
Foundational education, pilot projects, security integration, scaling and automation, readiness and risk management, future readiness.
Pilots should demonstrate tangible value without jeopardising critical services.
Centres of excellence or platform teams accelerate adoption with reusable modules and reference implementations.
7 min
The open question
Version control captures what changed; it does not yet capture whether the reasoning was sound or who held responsibility.
The book's challenge: find one AI-assisted decision without a traceable human rationale and write a decision record for it.
Making the implicit explicit is the habit on which trustworthy programmes are built.
What the audience takes away
Prepare for the future by building adaptive capabilities, not by betting on individual technologies.
Anti-patterns emerge gradually and can be caught early by a small set of leading indicators and a blameless remediation routine.
Declarative intent, repeatability, automated testing and continuous delivery stay constant as tooling evolves, and human accountability must be kept explicit.
