Architecture as Code: the course

All courses / Architecture as Code

About the course

The course follows Architecture as Code, Book 1 of The Transformed Architecture, through its seven parts. It begins with the foundations: what the practice is, how to assess readiness, the principles, version control and Architecture Decision Records. It then builds the platform of pipelines, models, containers and microservices, and turns security, policy, governance, compliance and evidence into code. Delivery follows with testing, adoption, cost and migration, then the organisation: teams, management as code, AI agent teams and digitalisation. The course ends with best practice, future trends and the anti-patterns to avoid. It matters because architecture that lives in slides drifts from reality, while architecture that is executable can be validated on every change.

After the course the participant can

Define Architecture as Code and distinguish it from Infrastructure as Code and Documentation as Code
Assess an organisation's readiness with the readiness scorecard and plan the remediation of its gaps
Write Architecture Decision Records and manage them as code through their status lifecycle
Model a system with the C4 model and design a pipeline that validates architecture on every change
Express security, risk, policy and governance rules as testable code and map one control to several frameworks
Design evidence bundles that the delivery pipeline generates, signs and retains
Plan testing, adoption, cost governance and migration for a codified estate
Diagnose anti-patterns in a programme and sequence an adoption with the six-step strategy

Who it is for

Enterprise, solution and system architects
Platform engineers, developers and site reliability engineers
Security, risk, governance and compliance specialists
Project managers and delivery leads
IT decision-makers and heads of architecture or operations

Before the course

Working knowledge of Git: commits, branches and pull requests
Basic familiarity with cloud infrastructure and the idea of Infrastructure as Code
Experience of how architecture decisions are made and reviewed in an organisation
Access to Architecture as Code, the book, for the chapters assigned to each lesson

Material

Three ways to run it

The same material in three lengths. Each row of an agenda names the lessons it draws on.

Executive briefing90 minutes

For executives, heads of architecture, security and operations, and sponsors who must decide whether and how to start

A decision-oriented briefing. It explains why static architecture drifts, what changes when architecture becomes executable, what readiness the organisation needs before buying tools, how governance and audit evidence become continuous, and which anti-patterns sink programmes. Participants leave with a first readiness score and a shortlist of pilot candidates.

0:00	The problem and the claim: slideware syndrome, architectural entropy and executable specifications Ch. 1
0:15	Readiness before tooling: the four loops and a quick scoring of the readiness scorecard in the room Ch. 26A
0:35	What the platform does: decision records, one model and a pipeline that checks every change Ch. 4, Ch. 5, Ch. 6
0:50	Assure once, comply many: governance through pull requests and evidence generated by the pipeline Ch. 11, Ch. 12, Ch. 15A
1:05	The organisation behind it: transformation stages, management as code and human oversight of AI agents Ch. 17, Ch. 19, Ch. 20
1:15	How programmes fail and how to begin: anti-patterns, leading indicators and the six-step adoption strategy Ch. 26B, Ch. 27
1:25	Decisions for the sponsors: pilot candidate, owner and first milestone

One-day seminar1 day

For architects, platform and security engineers, governance specialists and delivery leads who will run or join a pilot

A working day that follows one architectural change from decision to evidence. Participants score readiness, write a decision record, model a system at two C4 levels, design a promotion ladder, write a policy rule with its control mapping and evidence manifest, and finish by diagnosing anti-patterns in their own programme. Each block produces an artefact that can be taken back to the workplace.

09:00	Foundations: definition, drivers and the three design criteria Ch. 1, Ch. 2
09:45	Workshop: readiness scorecard for the participants' own organisations Ch. 26A
10:30	Version control as contract between layers, and writing an Architecture Decision Record Ch. 3, Ch. 4
11:30	Workshop: model a system at System Context and Container level Ch. 6
13:00	Pipelines that fail fast and promote with evidence Ch. 5, Ch. 13
13:45	Security, risk and policy as code: threat model, risk definition and a policy rule Ch. 9, Ch. 9C, Ch. 10
14:45	Workshop: one control from governance workflow to Control Mapping Matrix and evidence manifest Ch. 11, Ch. 12, Ch. 15A
15:45	Adoption in practice: pilot plan, resilience checklist, cost and migration waves Ch. 14, Ch. 15B, Ch. 16
16:15	People and organisation: team charter, transparent decisions and oversight of AI agents Ch. 18, Ch. 19, Ch. 20
16:40	Anti-pattern diagnosis and next steps with the six-step adoption strategy Ch. 26B, Ch. 27

Full course7 weeks, one module a week

For teams that are adopting Architecture as Code and individuals who want to master the whole practice, with time for exercises between sessions

The complete programme of seven modules and thirty-one lessons, one module per part of the book. Each week combines a lecture on the argument of the part, lessons with exercises that produce real artefacts, and a quiz per chapter. The artefacts accumulate in a repository and feed the capstone, an Architecture as Code blueprint for one system in the participant's organisation.

Week 1	Foundations: definition, readiness, principles, version control and decision records Ch. 1, Ch. 26A, Ch. 2, Ch. 3, Ch. 4
Week 2	Architecture platform: pipelines, modelling with Structurizr, containers and microservices Ch. 5, Ch. 6, Ch. 7, Ch. 8
Week 3	Security, governance and assurance: from threat modelling to evidence as code Ch. 9, Ch. 9B, Ch. 9C, Ch. 10, Ch. 11, Ch. 12, Ch. 15A
Week 4	Delivery and operations: testing, adoption in practice, cost and migration Ch. 13, Ch. 14, Ch. 15B, Ch. 16
Week 5	Organisation and leadership: change, teams, management as code, soft disciplines, AI agents and digitalisation Ch. 17, Ch. 18, Ch. 19, Ch. 23, Ch. 20, Ch. 21
Week 6	Experience and best practices: documentation versus architecture and the seven practice clusters Ch. 22, Ch. 24
Week 7	Future and wrap-up: trends, anti-patterns, conclusion and capstone presentations Ch. 25, Ch. 26B, Ch. 27

Modules and lessons

One module for each part of the book and one lesson for each chapter. A lesson has learning objectives, key concepts, a teaching plan, discussion questions, an exercise and a self-test.

Module 1 · Part A · Foundations

Part A lays the conceptual foundations: what Architecture as Code is and why microservice complexity drives it, how to assess whether an organisation is ready, the principles that keep architecture declarative, immutable and testable, the version control practices that make the repository a single source of truth, and the Architecture Decision Record that keeps the rationale visible. Participants leave with a readiness scorecard, a drift analysis, a repository design and a written decision record. Lecture: From slideware to executable specifications: the foundations of Architecture as Code

Module 2 · Part B · Architecture Platform

Part B builds the technical platform that turns architectural intent into something checked on every change. The module covers CI/CD pipelines with their validation layers, promotion evidence and telemetry, architecture modelling with the C4 model and the Structurizr DSL, container platforms whose desired state is declared and reconciled, and microservice estates held together by contracts, golden paths and guardrails as code. Participants leave with a pipeline design, a C4 model, a guard rail plan and a service blueprint. Lecture: The platform that makes architecture checkable on every change

Module 3 · Part C · Security, Governance & Assurance

Part C shows how security, policy, governance, compliance and evidence become code that runs on every change. The module moves from Zero Trust and threat modelling through advanced security patterns, risk registers and threat playbooks in the repository, Open Policy Agent and OSCAL, pull-request governance, the compliance loop with its Control Mapping Matrix, and machine-generated evidence. Participants leave with a threat model, a risk definition, policy rules, a governance workflow, a control mapping and an evidence manifest. Lecture: Assure once, comply many: security, governance and evidence as code

Module 4 · Part D · Delivery & Operations

Part D connects the technical capabilities to delivery and operations. The module covers the test pyramid for codified infrastructure, the adoption roadmap from discovery to optimisation with its resilience checklist, cost as a property of the architecture governed through FinOps, and migration from manually configured infrastructure as a sequence of small, reversible steps. Participants leave with a test strategy, a pilot plan with a completed resilience review, a cost governance design and a migration wave plan. Lecture: Testable, recoverable, affordable: delivering Architecture as Code in practice

Module 5 · Part E · Organisation & Leadership

Part E turns to the people and the organisation. The module follows the transformation from siloed functions to product-aligned teams, the team models, skills matrix and communities of practice that sustain it, the codification of management intent, budgets and decisions, the interplay between compliance, architecture, documentation, knowledge and culture as code, a team of AI agents under human direction, and digitalisation within European sovereignty requirements. Participants leave with a transformation assessment, a team charter, a management artefact, a norms file, an oversight policy and a provider selection policy. Lecture: People, process and technology in equal measure: the organisation behind Architecture as Code

Module 6 · Part F · Experience & Best Practices

Part F consolidates experience. The module first separates two disciplines that are easily confused, Documentation as Code, which communicates an architecture, and Architecture as Code, which defines and enforces it, and shows how each feeds the other. It then gathers the lessons of practice into seven clusters, from code organisation to continuous improvement. Participants leave with a classification of their own artefacts and tools and a prioritised improvement backlog. Lecture: Explaining an architecture is not the same as enforcing it

Module 7 · Part G · Future & Wrap-up

Part G looks ahead and closes the book. The module surveys the drivers that will shape the discipline, from AI-assisted automation and post-quantum cryptography to edge computing, sustainability and digital sovereignty, then catalogues the anti-patterns that derail programmes with their recovery measures and early-warning signals, and ends with the six-step adoption strategy and the open question of accountability for machine-authored artefacts. Participants leave with a future-readiness assessment, an anti-pattern diagnosis and an adoption roadmap. Lecture: What stays constant when everything else changes

Final assignment

Capstone

An Architecture as Code blueprint for one system in your organisation

Choose one real system in your own organisation and produce the blueprint for governing its architecture as code. The blueprint brings together artefacts from every module: the readiness of the organisation, the repository and branching design, decision records, a C4 model, a validating pipeline with a promotion ladder, at least one control carried from policy rule through governance workflow and Control Mapping Matrix to an evidence manifest, a test strategy, cost governance, a team charter and an anti-pattern diagnosis. Everything is kept in a version-controlled repository and reviewed through pull requests by a fellow participant. The blueprint must be specific enough that a pilot could start from it, and honest about what the organisation cannot yet do.

Steps

Score the organisation on the readiness scorecard with evidence, and state the three ranked gaps and the scoped pilot.
Design the repository topology, branching strategy and branch protections, and write at least two Architecture Decision Records, one of them for the choice of topology.
Model the system at System Context and Container level from a single model, and design the pipeline with validation layers, promotion ladder and evidence per environment.
Carry one control end to end: threat and risk it addresses, policy rule, pull-request approval workflow, matrix row and evidence manifest with lifecycle.
Add the delivery and organisation plans: test strategy, resilience checklist for the first change, cost tags and budget alerts, team charter and human oversight rules for any AI agents.
Diagnose the anti-patterns the programme is most exposed to, define the leading indicators you will watch, and sequence the adoption with the six-step strategy.

Deliverables

A repository containing the blueprint, with models, decision records, policy rules and plans as version-controlled files
A readiness scorecard with evidence and a remediation roadmap with 90-day and 12-month milestones
One control documented end to end, from policy rule to evidence manifest
A ten-minute presentation of the blueprint and the peer review record from the pull requests

Assessment criteria

Fidelity: terms, artefacts and methods are used as the book defines them, and every claim about the organisation is supported by evidence
Traceability: decisions, models, policies and evidence reference one another, so that a reviewer can follow one change from rationale to proof
Enforceability: rules are written so that a machine could check them, and it is stated what blocks a merge or a promotion
Realism: the pilot is contained and low-risk, gaps are named, and human accountability is explicit for consequential decisions
Review quality: the participant's pull requests show substantive review given and received