Architecture and Decision Tools
This chapter serves one activity: describing an architecture so that it can be versioned, reviewed and tested, and recording why it looks the way it does. It treats all four kinds of tool. The artefacts are the workspaces, reference models, overlays, templates and decision records that the series defines. The own tools are the small scripts that validate and render them. The third-party tools and standards are the modelling notations and documentation toolchains that the volumes name, and the methods are the named practices that tie the rest together. Most of the material comes from Architecture as Code (Chapters 4, 6 and 22) (1, Nordqvist, 2025), which defines the architecture-as-code discipline; the AI volumes extend it with the AI Decision Record, the reference architecture and security properties on model elements: AI Governance (2, Nordqvist, 2026), AI Platform and Security (3, Nordqvist, 2026), AI Red Team (4, Nordqvist, 2026), The Transformed Security Architect (6, Nordqvist, 2026), AI Boss (7, Nordqvist, 2026), AI Purple (9, Nordqvist, 2026) and AI Operations (10, Nordqvist, 2026).
The inventory assigns 70 entries to this chapter. The chapter treats the principal ones in full entries, names the rest in family tables, and leaves minor variants to Appendix A. Policy engines and the pipelines that run these checks are in Chapter 5, and the AI Decision Record itself, which extends the architecture decision record treated here, is in Chapter 7. Inclusion of a tool is a statement about what the series says of it and nothing more: for third-party software the facts come from its own documentation, and an earlier volume is cited only to show where the series uses the tool.
Figure 4.1: From model to decision record. The model, the requirements it must satisfy and the decision that explains it travel in one pull request through the same reviewers and the same validation.
Architecture modelling
Architecture drawn in a graphical tool decays: the diagram and the system drift apart because updating the diagram is a separate, manual act. Architecture as Code (Chapter 6) calls this diagram decay and answers it by keeping one text model under version control from which the diagrams are generated (1, Nordqvist, 2025). The tools in this family are a modelling approach (the C4 model), two languages that make the approach or an alternative to it machine-readable (the Structurizr DSL and CALM), and the workspaces, templates and scripts built on them. All three languages appear in the series in the same role, and the later volumes use the first two without changing them.
C4 model
| Kind | Third-party tool (modelling approach) |
| Origin | Architecture as Code, Chapters 6 and 22; AI Platform and Security, Chapter 4; The Transformed Security Architect, Chapters 5 and 19 |
| Purpose | A notation-independent approach to diagramming software architecture in four levels: system context, container, component and code |
| Use when | You need diagrams for different audiences from one model, from leadership to developers |
| Inputs | A model of people, software systems, containers and components |
| Outputs | Views at the level of abstraction each audience needs |
The C4 model is Simon Brown's approach to diagramming software architecture, and its source states that each level narrows scope and audience (32, Brown, n.d.). Architecture as Code (Chapter 6) tabulates the four levels and adds that the code level is optional (1, Nordqvist, 2025). AI Platform and Security (Chapter 4) names the C4 model in passing as a diagram method, and The Transformed Security Architect uses it as the model that security properties attach to. The series claims the approach is suitable for versioned models; it makes no claim about how widely it is adopted.
Structurizr (DSL, local, export)
| Kind | Third-party tool (software and language) |
| Origin | Architecture as Code, Chapters 2, 6, 22 and 24 and Appendix B; AI Platform and Security, Chapter 4; The Transformed Security Architect, Chapters 1 to 3, 5, 6, 19 and 25 |
| Purpose | A text language and tooling for C4 models, in which security properties and decision records attach to model elements |
| Use when | The architecture should be a reviewable text file from which views are generated and against which rules can run |
| Inputs | A workspace in the Structurizr DSL (workspace.dsl, optionally split with !include) |
| Outputs | Interactive views (local), and exports to PlantUML, Mermaid, WebSequenceDiagrams, Structurizr JSON or a static site (export) |
Structurizr's documentation describes one distribution whose commands cover local (viewing and layout on your own machine), server (publishing to a wider audience) and export (134, Structurizr, n.d.) and (136, Structurizr, n.d.). The standalone Structurizr Lite, the standalone CLI and the cloud service have reached end of life (135, Structurizr, n.d.), and Architecture as Code (Chapter 6) therefore uses only the consolidated tooling. The language reference documents every keyword used in the series (133, Structurizr, n.d.). Two practical points recur. Layout changes made in the diagram editor are saved to a workspace.json beside the DSL, so both files belong in version control. And the workspace can carry free-form properties on elements and relationships, which is how The Transformed Security Architect (Chapter 5) attaches trust zones, data classes and usage modes so that a rule can test them.
CALM (FINOS Common Architecture Language Model)
| Kind | Third-party tool (open specification) |
| Origin | Architecture as Code, Chapters 1, 2, 6 and 22 and Appendices B and C; The Transformed Security Architect, Chapters 3, 5 and 19 |
| Purpose | A machine-readable architecture language, with a JSON schema, in which controls are first-class |
| Use when | You want an architecture model that pipelines can validate against reusable patterns, and you accept a younger ecosystem than C4 tooling has |
| Inputs | A JSON document of nodes, relationships, interfaces, controls, flows and metadata that declares the schema release it conforms to |
| Outputs | Validation results, visualisations and generated documentation from its command-line tool |
CALM is developed in the open under FINOS, which describes its aim as a human- and machine-readable, version-controlled description of software architecture (33, FINOS, n.d.) and (34, FINOS, n.d.). Architecture as Code (Chapter 22) gives a small example valid against the release 1.0 schema with two nodes and one connects relationship (1, Nordqvist, 2025). The Transformed Security Architect (Chapter 5), where the inventory lists it as FINOS CALM, offers a cautious reading, which the three-label convention of the series makes explicit: CALM's open development is observable, wider evaluation in regulated sectors is expected, and whether it displaces C4-based workspaces is speculation (6, Nordqvist, 2026). Its advice on choosing is practical: prefer the model whose properties a rule can read without custom parsing and that can be kept current.
Workspaces, templates and reference models
| Tool | Kind and origin | One-line purpose |
|---|---|---|
AaC reference Structurizr workspace (aac_reference_workspace.dsl) and manifest |
Artefact; Architecture as Code, Chapters 6, 24 and Appendix B | Curated workspace of the book production platform, with a manifest recording its digest |
| Structurizr example workspaces (E-Commerce, Microservices, Event-Driven, Multi-Tenant SaaS) | Artefact; Architecture as Code, Chapter 6 | DSL workspaces and patterns for common system shapes |
| 06_CODE_5: Structurizr workspace for a complete e-commerce platform | Artefact; Architecture as Code, Chapter 6 and Appendix A | A full retail platform with applications, services, data stores and deployment views |
Structurizr multi-file workspace layout (workspace.dsl, model/*.dsl) |
Artefact; Architecture as Code, Chapter 6 | Include-based organisation of a large workspace |
New-service DSL template (templates/new-service.dsl) and onboarding guide |
Artefact; Architecture as Code, Chapter 6 | Template and short guide for adding a service to the workspace |
Market overlay (architecture/overlays/*) |
Artefact; AI Platform and Security, Chapters 4 and 24 | Jurisdiction-specific constraints applied on top of the reference model |
| Reference-architecture variant derivation (practical guide) | Artefact; AI Platform and Security, Chapter 4 | Six steps for deriving an organisation's own variant |
| Requirements-to-capability matrix | Artefact; AI Platform and Security, Chapter 3 | Table mapping high-risk requirements to platform capabilities |
scripts/check_structurizr_manifest.py and update_structurizr_manifest.py |
Own tools; Architecture as Code, Chapter 6 | Check and update the workspace manifest digest and the ADR references |
scripts/render_structurizr_diagrams.sh |
Own tool; Architecture as Code, Chapter 6 and Appendix B | Validates and exports the reference workspace, then refreshes the manifest |
The reference workspace is the series' worked model of an architecture that tools can check. It sits in the repository of Architecture as Code at docs/examples/structurizr/, and the surrounding pieces form one small system. The manifest aac_reference_workspace.manifest.json records the workspace path, its SHA-256 digest, the export formats (json, plantuml), the export directory and a generation timestamp. The render script validates the workspace, exports to build/structurizr/ with the pinned structurizr/structurizr image and refreshes the manifest, falling back to printed java -jar structurizr.war commands when neither Docker nor Podman is present. The manifest check then fails a pipeline when the DSL changed without new exports. A caution follows from the workspace's own header: its ADR files are named ADR-NNNN-title.md, which the Structurizr importers behind !adrs do not parse, so the workspace links the records from elements by URL instead. A team that wants the !adrs directive must name its files in the form an importer expects.
The multi-file layout and the new-service template solve adoption, not modelling: they let a developer add a service by copying a template, replacing three placeholders and including the file. Architecture as Code (Chapter 6) is candid that the template is a starting point, and its onboarding guide ends with a validate-and-pull-request step. Of these entries, the Structurizr example workspaces and the e-commerce listing are teaching material. They are useful when an architect needs a pattern to copy, and nothing in the series says they model a real estate.
Declarative reference architecture model
| Kind | Artefact |
| Origin | AI Platform and Security, Chapter 4 |
| Purpose | Declares the six layers, patterns and control plane of the AI reference architecture as code |
| Use when | Pipelines should check that a deployed system uses only components the model declares, and documentation should be generated from the model |
| Inputs | The reference architecture of the organisation, with its components and responsibilities |
| Outputs | A pinned, versioned model that overlays and component manifests refer to |
| Identifier family | kind: ReferenceArchitecture, with a pinned version such as enterprise-ai-platform@2.0.0 |
| Full template | Below, from AI Platform and Security, Chapter 4, quoted in full |
# architecture/reference-model.yaml - declarative model of the AI reference architecture
apiVersion: ai-architecture.example.org/v1
kind: ReferenceArchitecture
metadata: {name: enterprise-ai-platform, version: 2.0.0, owner: ai-platform-team}
layers:
- id: data-foundation
components: [data-products, lineage-catalogue, feature-store, vector-index]
- id: model-and-feature
components: [experiment-tracking, training-pipelines, model-registry, evaluation-service]
- id: serving-and-inference
components: [ai-gateway, internal-model-serving, external-model-connectors]
- id: orchestration-and-agents
components: [workflow-engine, agent-runtime, tool-registry, prompt-repository, guardrails]
- id: application-and-channel
components: [assistants, decision-support-apps, partner-apis]
controlPlane:
identity: workload-identity-with-oidc
policy: {engine: open-policy-agent, repository: ai-platform/policies}
observability: {standard: opentelemetry-genai-semantic-conventions}
evidence: {store: evidence-bucket-eu-north, retentionMonths: 6}
components:
ai-gateway:
responsibilities: [authenticate, authorise, route, apply-guardrails, log]
dependsOn: [model-registry, prompt-repository, policy-engine]
model-registry:
stages: [candidate, evaluated, approved, retired]
promotionBy: pipeline-only
aiActRoles:
provider: {ownsLayers: [data-foundation, model-and-feature, serving-and-inference]}
deployer: {ownsLayers: [orchestration-and-agents, application-and-channel]}
The file is a template for the form, not a prescription of the contents. AI Platform and Security (Chapter 4) states the one rule that holds for every adaptation: a team records deviations in an AI Decision Record but does not remove the gateway, the registry, the evaluation service or the control plane, because each later chapter assumes they exist. Variants are written as overlays on a pinned base, never as copies. The market overlay (kind: MarketOverlay) records regime, placement and timing for one jurisdiction and a list mayNotRelax; the series' rule is that an overlay may add or tighten controls but never relax the group baseline, and a pipeline check fails an overlay that tries. The six-step practical guide for deriving a variant ends in a definition of done that is checkable: the variant and its overlays are in version control with a decision record, and every production AI system has a component manifest that passes the pipeline check.
Structurizr workspace with trust-zone properties
| Kind | Artefact |
| Origin | The Transformed Security Architect, Chapter 5 |
| Purpose | Security architecture modelled in a Structurizr workspace, with trust zone, data class, usage mode, identity, owner and policy point as element and relationship properties |
| Use when | A rule in a pipeline must be able to fail a pull request that creates an unprotected crossing between trust zones |
| Inputs | A Structurizr workspace with a closed vocabulary of zones and data classes, kept as a versioned file |
| Outputs | A model a policy engine can read; pull requests that fail when a property is missing or a crossing has no named policy point |
| Full template | Below, from The Transformed Security Architect, Chapter 5 (Hansa Mutual, illustrative) |
workspace "hansa-estate" {
model {
triage = softwareSystem "Claims-triage agent" "Mode 5 agent" "Agent" {
properties {
"trustZone" "agent-runtime"
"dataClass" "personal"
"usageMode" "5"
"identity" "workload/hansa/claims-triage"
"owner" "claims-product-line"
}
}
gateway = softwareSystem "AI gateway" "Authenticates, authorises, routes and logs every call" "Policy point" {
properties {
"trustZone" "platform-control"
}
}
claims = softwareSystem "Core claims system" "System of record for claims" {
properties {
"trustZone" "core-systems"
}
}
triage -> gateway "Model and tool calls" { properties { "policyPoint" "AI gateway" } }
gateway -> claims "Route update within approval rules" { properties { "policyPoint" "AI gateway" } }
}
}
The agent has no direct relationship to the core claims system, so the model states its only write path in a form a test can check. The Transformed Security Architect (Chapter 5) runs a Rego rule against a flattened export of this workspace; the rule belongs to the policy-as-code tools of Chapter 5 of this book. The point for this chapter is that a closed vocabulary matters more than a rich one, because a rule cannot test a property that two teams spell differently.
Methods that act on the model
| Method | Origin | Purpose in one line |
|---|---|---|
| Architecture fitness functions (evolutionary architecture) | Architecture as Code, Appendix B | Automated checks of workspace validity, structural coverage, tag conformance and fitness scores (178, Ford et al., 2017) |
| Placing a new security AI capability on the reference architecture | AI Red Team, Chapter 4 | Eight steps that place a capability on the platform's controls and layers before it reads production telemetry or acts |
| Cell-based architecture | AI Operations, Chapter 9 | Limit the blast radius of a failure or change by deploying independent, complete cells (231, AWS, 2023) |
| Zero Trust architecture | Architecture as Code, Chapter 9 | Shift from static network perimeters to protecting users, assets and resources (35, Rose et al., 2020) |
The fitness functions are the model's tests. Architecture as Code (Appendix B) lists five: workspace validity through the validate command, structural coverage thresholds, tag conformance against an approved list, a fitness score export and change intelligence that correlates DSL diffs with incidents. The placement guide of AI Red Team is the clearest example of a method that produces a record: its eighth step is an AI Decision Record that names the owner of the identity and the holder of the decision to change the autonomy level. Cells are an architectural pattern more than a modelling tool; AI Operations (Chapter 9) treats them as the way to turn a rollout schedule into a structural fact, and notes that they duplicate capacity and add a routing layer that is itself a shared dependency. Chapter 16 returns to them as a change tool. Zero Trust is a security architecture, not a tool. Architecture as Code (Chapter 9) describes it as the guiding principle of never trusting and always verifying, which demands granular identity management, continuous posture assessment and policy-driven access control, and the inventory lists it as a method because the series applies it as a named procedure for modelling trust boundaries.
Architecture and decision records
A model says what the architecture is. A decision record says why, and what was given up. Architecture as Code (Chapter 4) defines the format and the tools around it, and the later volumes extend it twice: to AI systems (the AI Decision Record, Chapter 7) and to decision forums (the decision minute).
Architecture Decision Record (ADR) template
| Kind | Artefact (method of Nygard) |
| Origin | Architecture as Code, Chapter 4; AI Governance, Chapters 3, 13 and 16; The Transformed Security Architect, Chapters 4, 5, 14, 17 and 19 |
| Purpose | A short text document that captures one architecture decision with its context, the decision and its consequences |
| Use when | A choice shapes the architecture and someone may later ask why |
| Inputs | The context, the options considered and the named decision authority |
| Outputs | A numbered file under version control, with status, review dates and a link to the pull request that discussed it |
| Identifier family | ADR-NNNN; the number is permanent, even if the record is later deprecated or superseded |
| Full template | Below, from Architecture as Code, Chapter 4 |
The format starts with Nygard's blog post (126, Nygard, 2011), and the Thoughtworks Technology Radar placed lightweight ADRs in Adopt in November 2017 on the argument that records belong in source control, beside the code, not in a wiki (127, Thoughtworks, 2016). Community templates and tool listings are collected by the ADR GitHub organisation, though no standards body governs the format (128, ADR GitHub organisation, n.d.). Architecture as Code (Chapter 4) standardises the record with YAML front matter for identity, status and review cadence and a Markdown body:
---
adr_id: ADR-XXXX
title: [Short Description of the Decision]
status: Proposed
date: "2025-01-15"
last_reviewed: "2025-01-15"
next_review_due: "2025-07-15"
deciders:
- [Named decision authority]
reviewers:
- [Reviewer ensuring technical accuracy]
summary: Concise statement explaining why the decision matters.
change_notes:
- YYYY-MM-DD – Short description of adjustments or supersessions.
---
# ADR-XXXX: [Short Description of the Decision]
Status: [Proposed | Accepted | Deprecated | Superseded]
Context:
- Description of the problem that needs to be solved
- Circumstances and constraints that led to the decision
- Stakeholders affected by the outcome
Decision:
- Clear statement of the chosen approach
- Implementation details and scope
Consequences:
- Positive:
- Expected benefits and improvements
- Negative:
- Identified risks and limitations
Mitigation:
- Measures that offset negative consequences
Review and Documentation Workflow:
- Link to the pull request or merge request where the ADR was discussed
- Notes on which automation results were captured and how the change was validated
The book states that its own repository extends the template with related_chapters, related_diagrams, related_backlog_items and automation_hooks, and says these fields are specific to the toolchain and not standard ADR metadata. A reader adopting the template should keep the core and add only fields a script will read. Two companion artefacts complete the format. The directory layout (docs/adr/0001-record-architecture-decisions.md and so on) keeps records beside the documentation, and the status lifecycle fixes four statuses with an action each: Proposed (team review and impact assessment), Accepted (begin implementation and communicate), Deprecated (plan a migration path and a deprecation timeline) and Superseded (reference the successor and keep the history). Versioning is by Git history, not by editing: a changed decision is a new ADR that supersedes the old one.
Decision records in the AI volumes
| Tool | Kind and origin | One-line purpose |
|---|---|---|
| Architecture decision record (Nygard) | Method; AI Governance, Chapters 3, 13 and 16 | The short decision record that AI Decision Records extend |
| Architecture Decision Records (Nygard) | Third-party tool; The Transformed Security Architect, Chapters 4, 5, 14, 17 and 19 | Record architecture decisions beside the code |
| Decision record on model origin and hosting | Artefact; AI Platform and Security, Chapter 13 (AIDR-*) |
An AI Decision Record example that uses the sovereignty decision matrix |
| Go/no-go decision record | Artefact; AI Platform and Security, Chapter 23 | Records who accepted residual risk for a production go-live, with stop criteria |
| Decision record (minute) | Artefact; AI Governance, Chapter 13 (DEC-*) |
A filled-in decision minute of a governance forum |
The three artefacts show how the format bends without breaking. In AI Platform and Security (Chapter 13) the record for the staff assistant's model origin keeps the ADR front matter (adr_id: AIDR-0211, status, date, deciders, reviewers) and adds classification; the body lists options with weights fixed before scoring, a section of legal points attributed to a counsel's note and not offered as general advice, the decision and its consequences, among them a yearly exit test. The go-live record (AIDR-0034) adds relates_to, next_review_due, measurable stop criteria and a named accountable owner, so a rollback depends on a threshold, not a meeting. The decision minute in AI Governance (Chapter 13) is a different object with a different job: DEC-2026-031 records the forum, the evidence pack, quorum with recusal, reasons, conditions with owners, dissent, residual risk, stop authority and a review date, and it is approved by merge (approved_by_merge: PR-1187). One identifier question needs care. From The Transformed Security Architect onwards, each volume reserves its own range of AI Decision Record numbers (AIDR-0500 to AIDR-0599 in that volume, AIDR-0900 to AIDR-0999 in AI Operations), so an identifier is read together with its volume; Chapter 25 returns to identifier families.
Tools for the decision log
| Tool | Kind and origin | One-line purpose |
|---|---|---|
| adr-tools and adr-log | Third-party tool; Architecture as Code, Chapter 4 | Command-line tools to create ADRs and to generate the decision log; the adr-tools documentation describes a command-line tool for working with a log of ADRs stored as Markdown files (258, Pryce, n.d.) |
ADR directory layout (docs/adr/) |
Artefact; Architecture as Code, Chapter 4 | Repository structure for numbered ADR files |
| ADR status lifecycle | Artefact; Architecture as Code, Chapter 4 | Table of ADR statuses and the action each requires |
scripts/new_adr.sh |
Own tool; Architecture as Code, repository | Creates the next numbered ADR from a template |
scripts/validate_adrs.py |
Own tool; Architecture as Code, Chapter 4 and repository | Validates ADR metadata (front matter completeness) |
scripts/generate_adr_catalogue.py |
Own tool; Architecture as Code, repository | Generates docs/adr/adr_catalogue.md from ADR metadata |
scripts/adr_impact_analysis.py |
Own tool; Architecture as Code, repository | Reports which chapters reference which ADRs |
| Kafka, PostgreSQL | Third-party tools; Architecture as Code, Chapter 4 | Technologies used as subjects of the example ADRs, named in passing |
The repository of Architecture as Code ships four scripts for its own ADRs, and only one of them, validate_adrs.py, is described in a chapter. The validator requires the scalar fields adr_id, title, status, date, last_reviewed and next_review_due, accepts only the four lifecycle statuses, and in the repository's extended form also requires the list fields deciders, reviewers, related_chapters, related_diagrams and related_backlog_items. The catalogue generator turns that metadata into a table of identifier, title, status, linked chapters, backlog items and next review. Architecture as Code (Chapter 4) describes the same idea as a CI job that lints front matter and fails the build when metadata is missing, and as scheduled reminders when next_review_due passes. Dashboards built on the log (a lifecycle timeline, a policy-coverage heat map and a review-debt tracker) are treated in Chapter 14, and the discovery, review and supersession workflow in Chapter 5. The two community tools adr-tools and adr-log are named by the book and listed by the ADR GitHub organisation; the series does not compare them with alternatives.
Plans and timelines as records
| Tool | Kind and origin | One-line purpose |
|---|---|---|
First-90-days plan (PLAN-HM-SA-PL-90) |
Artefact; The Transformed Security Architect, Chapter 27 | Plan for a new architect to establish authority, boundary knowledge and calibrated judgement |
Year timeline (timeline: NR-SA-*) |
Artefact; The Transformed Security Architect, Chapter 25 | Timeline generated from the year's AI Decision Records and ADRs by quarter |
| Writing a two-year loop plan | Method; AI Purple, Chapter 28 | Plan written as a decision record, with gates for each increase in delegation |
| Writing tender requirements for management systems in a public authority | Method; AI Boss, Chapter 24 | Writes specifications, award criteria and contract conditions, and verifies them before acceptance |
These four are decision records at larger scale. The first-90-days plan lists the post, the charter, the hiring decision and the competence record it depends on, and names what the post-holder may not yet do (approve Tier 3 changes, for instance) so that a limit is a written rule. The year timeline lists, by quarter, the decisions made, what went wrong and the shifts concerned, so that the year-end review and an auditor read the same account. The two methods are procedures: the two-year loop plan has nine steps, ends with at most six measures and requires that every increase in delegation is a gate on recorded evidence, and the tender-requirements guide has ten steps and may not allow Level 4 Autonomous for the management function that carries consequences for a person (M3 Consequence in AI Boss). They belong to this chapter because each ends in a record under version control.
Documentation, requirements and knowledge as code
Architecture as Code (Chapter 22) separates two disciplines. Documentation as Code keeps narrative in version control and builds it in CI, with illustrative diagrams written in text. Architecture as Code defines the system in executable models. The tool families differ accordingly: the first uses Mermaid, PlantUML and static site generators, the second CALM, Structurizr, Terraform modules and policy engines. The book states why it draws its own figures in Mermaid: its diagrams are documentation, not executable models.
Documentation as Code and its toolchain
| Tool | Kind and origin | One-line purpose |
|---|---|---|
| Documentation as Code | Method; Architecture as Code, Chapters 2 and 22 | Documentation kept in version control and built in CI |
| Mermaid and Mermaid CLI | Third-party tool; Architecture as Code, Chapters 2, 6, 9c, 20, 22 and Appendices B and D | Text-based diagrams; mmdc renders PNG (137, Mermaid, n.d.) |
| PlantUML | Third-party tool; Architecture as Code, Chapters 6 and 22 | Text-based diagrams, and a target of the Structurizr export (138, PlantUML, n.d.) |
| PlantUML and Mermaid diagram examples | Artefact; Architecture as Code, Chapter 22 | Diagram-as-code examples |
| MkDocs | Third-party tool; Architecture as Code, Chapters 2 and 22 and Appendix B | Static documentation site generator for project documentation written in Markdown and configured in YAML (257, MkDocs, n.d.) |
| Docusaurus, Sphinx, Jekyll | Third-party tools; Architecture as Code, Chapter 22 | Documentation generators and static site generators for documentation as code, named in passing |
| Draw.io / Lucidchart | Third-party tools; Architecture as Code, Chapter 6 | Graphical diagram tools, contrasted with diagrams as code |
| Mermaid, Pandoc, XeLaTeX, MkDocs | Third-party tools; AI Threat, About the Author | The toolchain that produced that book, named in passing |
Mermaid Designer Bot (mermaid-designer-bot.yml) |
Own tool; Architecture as Code, Chapter 20 | An issue labelled mermaid or diagram yields a new .mmd file, a pull request and a comment |
Mermaid is the most widely named tool in the series. Every volume from AI Governance to AI Operations names it, mostly as the diagram language or renderer of its own figures (AI Red Team names the command-line interface and notes that the repository, not a chapter, uses it; AI Threat names Mermaid, Pandoc, XeLaTeX and MkDocs together as the toolchain that produced the book, and the inventory records that entry as "Mermaid, Pandoc, XeLaTeX, MkDocs"). These entries are repository tooling; none of those volumes discusses the tool in a chapter, and the series makes no claim beyond naming it. Architecture as Code (Chapter 22) does discuss Mermaid, noting its syntax is easy for non-technical contributors and that GitHub, GitLab and many site generators render it. The contrast with PlantUML is one of coverage: PlantUML supports sequence, class and deployment diagrams in more depth, and Structurizr exports to it. The graphical tools are included for contrast only; the series prefers diagrams as code where the diagram must survive review.
Two of the entries deserve a closer note. The MkDocs entries list the site generator that builds the series' websites, and the book states that its workflow publishes to GitHub Pages; the bibliography of this book holds a primary source for MkDocs only, so Docusaurus, Sphinx and Jekyll are named without a claim. The Mermaid Designer Bot is the one own tool in this chapter that involves an AI agent: the series describes it as turning a labelled issue into a diagram source, a pull request and a comment, and the pull request goes through the same review as any other change.
Requirements, review gates and ownership as code
| Tool | Kind and origin | One-line purpose |
|---|---|---|
| Requirements as Code with traceability | Method; Architecture as Code, Chapters 2 and 13 | Requirements as versioned YAML tested against infrastructure |
13_CODE_G: Requirements as Code definition (requirements/catalogue.yaml) |
Artefact; Architecture as Code, Chapter 13 and Appendix A | Requirements catalogue with identifiers, classification, rationale and tests |
| Mandatory architectural review gates via pull requests | Method; Architecture as Code, Chapters 2, 3 and 11 | Two-role approval of architecture changes in protected branches |
| CODEOWNERS for architectural review | Artefact; Architecture as Code, Chapters 2, 6 and 19 | Maps architecture paths to required reviewers |
Requirements as Code turns a specification into data that tests can read. Architecture as Code (Appendix A, listing 13-G) gives a catalogue whose entries carry an id (SEC-001, PERF-003, GOV-010), a title, a priority, a classification, a rationale and a list of tests, each test naming its tool. The listing is quoted here with two of its three requirements removed.
# requirements/catalogue.yaml
metadata:
version: 1
generated: 2024-04-15
owner: platform-risk-office
requirements:
- id: SEC-001
title: Encrypt customer data at rest
priority: high
classification: gdpr
rationale: Protect personally identifiable information across EU jurisdictions.
tests:
- id: test-encryption-s3
description: Validate that S3 buckets containing GDPR data enable default encryption.
tooling: opa
- id: test-encryption-rds
description: Confirm RDS instances with GDPR tags have storage encryption enabled.
tooling: terratest
The platform version in AI Platform and Security (Chapter 3) is richer: a PlatformRequirementsCatalogue whose entries name an AI Act article or control, an applicability condition, the control, the evidence and the release gate, and which pipelines read. That artefact is in the inventory slice of Chapter 6 and is treated there; the requirements-to-capability matrix above is its tabular form. The review-gate method and its CODEOWNERS file complete the loop. The file maps /docs/architecture/** and /structurizr/** to the architecture and platform teams, *.adr.md to the architecture team and /policy/** to the security and architecture teams. The book adds a caution about protected branches: administrators are exempt by default unless the rule's option not to allow bypassing is enabled.
Documents that generate documents
| Tool | Kind and origin | One-line purpose |
|---|---|---|
| Datasheet (for datasets) | Artefact; AI Platform and Security, Chapters 5, 6 and 20 | Documents dataset composition, gaps, uses and maintenance |
| Datasheets for datasets | Third-party tool (documentation format); AI Governance, Chapter 4 | Dataset documentation format of Gebru and colleagues (129, Gebru et al., 2021) |
| Model cards | Third-party tool (documentation format); AI Threat, Chapter 29 | Short documents that accompany trained machine learning models and report their intended use and benchmarked evaluation; AI Threat names them for open-weight models (130, Mitchell et al., 2019) |
| Annex IV technical documentation mapping | Artefact; AI Platform and Security, Chapter 5 | Maps repository content to AI Act Annex IV and generates the documentation |
| Obsidian with Git synchronisation | Third-party tool; Architecture as Code, Chapter 23 | Note-taking application with a graph view of linked notes (Git synchronisation comes from a community plugin), used for the knowledge registry and named in passing |
The datasheet and the Annex IV mapping show the AI volumes' main addition to documentation as code. In AI Platform and Security (Chapter 6) the datasheet's four headings (composition, known gaps and skews, uses, maintenance) feed forward: a known gap becomes a slice in the fairness evaluation and a stated limitation in the model card. In Chapter 5 of that volume the Annex IV mapping assigns each repository path (decisions/, systems/<name>/system_card.md, models/<name>/model_card.md, data/<name>/datasheet.md, evaluation/, risk/register.yaml, pipelines/, monitoring/, conformity/) to the Annex IV points it serves, and a generator emits the technical documentation on every model promotion. The legal basis is the volume's: Article 11 and Annex IV of Regulation (EU) 2024/1689 require technical documentation for high-risk AI systems, and the architectural implication is that one place holds the evidence for each heading. AI Threat names model cards as documentation of open-weight models and observes that they are often released without a framework; the series does not claim a card is a conformity document. Obsidian is named once, as the knowledge graph tool, with Git synchronisation through a community plugin, that Architecture as Code (Chapter 23) suggests using beside a YAML knowledge registry.
Methods that explain the architecture's shape
| Method | Origin | Purpose in one line |
|---|---|---|
| Conway's law applied to AI | AI Governance, Chapter 12 | Align team structure with the intended AI architecture (179, Conway, 1968) |
| Migration approach: assessment, wave planning, lift-and-shift versus re-architecting, gradual codification | Architecture as Code, Chapter 16 | Phased migration of unmanaged infrastructure |
Conway's observation, that organisations design systems whose structure copies their communication structure, is the reason the series treats team design as architecture by other means. The migration method belongs here because its first phase is an inventory and a model: Architecture as Code (Chapter 16) tabulates four strategies (lift-and-shift, re-architecting, lift-and-improve and application retirement) with their benefits, challenges and best-suited cases, and ties gradual codification to import tooling that Chapter 6 treats.
Across the usage modes
The architecture and decision tools differ across the usage modes in one way: how much of the architecture the organisation itself operates, and therefore how much it has to model and record. The table combines the two relevant tables of AI Platform and Security (Chapters 4 and 5, usage modes as defined there).
| Mode | Layers the organisation operates | Decision recorded | Threshold |
|---|---|---|---|
| Mode 0 Ambient AI | None; the feature lives in supplier software | Accepting or declining a supplier-enabled feature | Each feature that processes personal or confidential data |
| Mode 1 Conversational assistants | None beyond the channel | Approving a conversational service and its data tier | One record per service, not per user |
| Mode 2 Embedded workplace assistants | None of its own | Enabling an embedded assistant, its scope and data boundaries | One record per rollout and per significant change of scope |
| Mode 3 Agentic work tools | Orchestration, as an agent runtime on a workstation or sandbox | Approving an agentic tool and its permission configuration | One record per tool |
| Mode 4 Built AI applications | All five layers, partly through external model connectors | The full AI Decision Record for each system | Always; high-risk records carry every field |
| Mode 5 Autonomous production agents | All five, with the agent runtime and tool registry at the centre | The full record for each agent, and a record for any write access | Always, and again whenever permissions widen |
The consequence for tooling is that Modes 0 to 3 need a short ADR or AI Decision Record and an inventory entry, while Modes 4 and 5 need the workspace with security properties, a component manifest checked against the reference model and the full record. The ADR template and the C4 model do not change between modes; what changes is the number of elements the model must contain.
Nordvik Region and Hansa Mutual
Both organisations appear here as the earlier volumes describe them, and the examples are illustrative. Nordvik Region, a regional public authority that mostly procures its AI systems, runs the reduced variant of the reference architecture as an overlay on a pinned base, recorded in AIDR-0002; it keeps the gateway, the registry, evaluation and the control plane and leaves training and feature machinery to the providers of the systems it buys. Its decision log for the benefits-triage system runs through AIDR-0007, AIDR-0011 and AIDR-0018, and a short workflow in the triage repository validates the front matter of each record, refuses edits to the body of an accepted record except its status fields, and regenerates the index, so that supersession is the only way to change a decision. Its records are written to be read outside the authority, because residents may request them under public-access law.
Hansa Mutual, a multinational insurance group that builds as well as buys, runs the full reference architecture as a shared group platform and records one assistant's retention deviation as a declared adaptation (AIDR-0022) so that it is not drift. Its security architect's workspace declares the claims-triage agent, the AI gateway and the core claims system with trust-zone properties, and its governance forum records decisions as DEC-* minutes approved by merge. Consider how a pull request combines the pieces (this walk-through is illustrative and uses no identifiers beyond those the volumes establish). A change that adds a write path from the claims-triage agent changes the workspace fragment, and the agent's decision records (AIDR-0063 for the triage assistant it grew from and AIDR-0034 for its go-live) must be read and, where the write path changes the facts they rely on, superseded in the same change. The same pull request is held by CODEOWNERS for the architecture and platform teams, runs the workspace validation and the zone rule, and lints the record's front matter. If the rule finds a crossing without a policy point, the pull request does not merge.
Summary
The tools of this chapter share one design: the model, the requirements and the reason for a decision are text under version control, reviewed in the same pull request, validated by the same pipeline and exported to the documents people read. This is the series' own conclusion, drawn from the volumes above, and it has four consequences. First, choose the model language by whether a rule can read it: the C4 model in the Structurizr DSL is the series' default, and CALM is an alternative whose adoption is observable but whose standing in regulated sectors is still expected, not established. Second, keep the format of a decision record small and extend it only with fields that a script reads; the ADR, the AI Decision Record and the decision minute are one family with different jobs. Third, treat a script that validates a record or a manifest as part of the record's definition: the series ships four for its own ADRs, only one of them described in a chapter, and the directory each script reads should be stated. Fourth, state for each mode how much of the architecture the organisation operates, because that decides how much it has to model and record.
All 70 inventory entries assigned to this chapter are accounted for. Six full entries (the C4 model, Structurizr, CALM, the declarative reference architecture model, the Structurizr workspace with trust-zone properties and the ADR template) also cover the volume-level duplicates of C4, Structurizr and CALM, the ADR directory layout and the ADR status lifecycle. The other entries are named in the family tables with their origin and a one-line purpose, among them the ten volume-level mentions of Mermaid and the passing mentions of MkDocs, Docusaurus, Draw.io and Obsidian. Appendix A holds all 70, and the entries that the editor may reassign to other chapters are listed in the findings file for this chapter.
Sources
- Nordqvist, G. Architecture as Code. (1, Nordqvist, 2025)
- Nordqvist, G. AI Governance: Governing Artificial Intelligence in European Enterprises and Public Authorities. (2, Nordqvist, 2026)
- Nordqvist, G. AI Platform and Security: Building and Securing AI Platforms in European Enterprises and Public Authorities. (3, Nordqvist, 2026)
- Nordqvist, G. AI Red Team: AI as an Active Part of Cyber Defence in European Enterprises and Public Authorities. (4, Nordqvist, 2026)
- Nordqvist, G. The Transformed Security Architect: Role, Craft and Career in the Age of AI in European Enterprises and Public Authorities. (6, Nordqvist, 2026)
- Nordqvist, G. AI Boss: When Artificial Intelligence Manages People in European Enterprises and Public Authorities. (7, Nordqvist, 2026)
- Nordqvist, G. AI Purple: How Red and Blue Learn Together When AI Joins the Loop in European Enterprises and Public Authorities. (9, Nordqvist, 2026)
- Nordqvist, G. AI Operations: How Artificial Intelligence Transforms IT Operations in European Enterprises and Public Authorities. (10, Nordqvist, 2026)
- Brown, S. The C4 model for visualising software architecture. (32, Brown, n.d.)
- FINOS. Architecture as Code: What is CALM?. (33, FINOS, n.d.)
- FINOS. Architecture as Code: Common Architecture Language Model (CALM) specification repository. (34, FINOS, n.d.)
- Rose, S., Borchert, O., Mitchell, S., Connelly, S. Zero Trust Architecture. (35, Rose et al., 2020)
- Nygard, M. Documenting Architecture Decisions. (126, Nygard, 2011)
- Thoughtworks. Lightweight Architecture Decision Records. (127, Thoughtworks, 2016)
- ADR GitHub organisation. Architectural Decision Records (ADRs). (128, ADR GitHub organisation, n.d.)
- Gebru, T., Morgenstern, J., Vecchione, B., Vaughan, J., Wallach, H., Daumé III, H., Crawford, K. Datasheets for Datasets. (129, Gebru et al., 2021)
- Mitchell, M., Wu, S., Zaldivar, A., Barnes, P., Vasserman, L., Hutchinson, B., Spitzer, E., Raji, I. D., Gebru, T. Model Cards for Model Reporting. (130, Mitchell et al., 2019)
- Structurizr. Structurizr DSL language reference. (133, Structurizr, n.d.)
- Structurizr. Getting started. (134, Structurizr, n.d.)
- Structurizr. End-of-life notices for Structurizr Lite, the Structurizr CLI and the Structurizr cloud service. (135, Structurizr, n.d.)
- Structurizr. export. (136, Structurizr, n.d.)
- Mermaid. Mermaid: Diagramming and Charting Tool. (137, Mermaid, n.d.)
- PlantUML. PlantUML: Open-source Tool for Creating UML Diagrams. (138, PlantUML, n.d.)
- Ford, N., Parsons, R., Kua, P. Building Evolutionary Architectures: Support Constant Change. (178, Ford et al., 2017)
- Conway, M. How Do Committees Invent?. (179, Conway, 1968)
- MkDocs. MkDocs: Project documentation with Markdown. (257, MkDocs, n.d.)
- Pryce, N. ADR Tools: a command-line tool for working with a log of Architecture Decision Records. (258, Pryce, n.d.)
- Amazon Web Services. Reducing the Scope of Impact with Cell-Based Architecture. (231, AWS, 2023)