Security Architecture as Code: From Documents to Executable Design

A security reference architecture that exists as a document has one reader at a time and no way to answer a question it was not written for. The question "which of our systems cross from the agent runtime into the core claims system, and what stands in the path?" takes a person an afternoon to answer from a document, and the answer is out of date by the time it is finished. The same question put to a model kept as code takes seconds, and the answer is checked on every change. This chapter shows how security architecture becomes executable design: the architecture model kept as code, security properties attached to its elements, policy as code that enforces those properties, and the pull request as the unit of architectural change. It concerns two of the four shifts. Shift 1, from documents to code, is the subject of the whole chapter, because the model, the policies and the decision records are the architect's artefacts in their executable form. Shift 2, from gatekeeper to boundary designer, enters through the review triggers and policy checks that let the architect delegate routine decisions to the pipeline and keep human review for the changes that alter a boundary.

The chapter builds on conclusions the earlier volumes reached. Architecture as Code (Chapters 6, 9, 10 and 11) established that security architecture has four dimensions that the codebase must carry, that policy is written once and mapped to many obligations, and that the architecture model belongs in version control (167, Nordqvist, 2025). AI Platform and Security, Chapters 4, 5 and 17, showed that the declarative model of the AI reference architecture can be checked against the running estate, that the architecture repository rather than the document is the single source of the technical documentation, and that a code-ownership rule routes changes to review triggers to the security architect (169, Nordqvist, 2026). Those volumes describe the artefacts. This chapter describes what the security architect does to own them, and leaves the control catalogue and its evidence to Chapter 9 and the threat models generated from the model to Chapter 6.

The architecture repository as the single source: the model, the policies and the decision records, with a pull request flowing through review triggers, policy checks and drift comparison

Figure 5.1: The architecture repository as the single source: the model, policies, decision records and ownership file, with a change flowing through review triggers and policy checks, and the deployed estate compared with the declared one.

From the reference document to the model

A reference architecture document is a good artefact for a reader who wants to understand a design once. It fails the architect in four ways that the later sections of this chapter correct.

It cannot be queried. A document states that "systems in the agent zone reach core systems only through the gateway", and a reader must open every system diagram to find the exceptions. It cannot be checked, because nothing compares the sentence with the estate. It cannot be changed in step with the estate, since the document and the systems have different owners, different release cycles and no common change record. And it has no identity for the things it describes: a box in a diagram is not an element with an owner, a data classification and a trust zone that a program can read.

A model kept as code removes each of those limits. ISO/IEC/IEEE 42010 gives the useful frame: an architecture description consists of views addressed to stakeholders' concerns, and the views are meant to be consistent with one another because they describe one architecture (28, ISO/IEC, 2022). A document keeps the views and loses the architecture beneath them. A model keeps the architecture and generates the views. Rozanski and Woods make the same point in their treatment of viewpoints and perspectives, and treat security as a perspective that cuts across views rather than a separate document (75, Rozanski & Woods, 2011). The model carries security as properties of elements and relationships, and the views a board, a supplier or an auditor needs are projections of it.

Two limits apply. The model does not replace the reasoning that decides which properties matter, which stays with the architect. And a model is only as good as the process that keeps it in step with the estate, which is why the later sections give as much room to change workflow and drift as to notation.

Modelling the estate as code

C4 and Structurizr

The C4 model describes software at four levels, context, container, component and code, and asks for a consistent vocabulary of people, software systems, containers and components (59, Brown, n.d.). Structurizr turns that vocabulary into a text language: a workspace declares elements, relationships, deployment nodes and views in a domain-specific language that a version-control system can diff and a pipeline can parse (60, Structurizr, n.d.). Hansa Mutual's estate is already described this way, following Architecture as Code (Chapter 6) (167, Nordqvist, 2025). The security architect's contribution is not the notation but the discipline of what goes into it.

Three rules keep the model useful to security work. First, model what crosses a boundary, not everything that exists: the relationships between zones, the identities that make them, and the data classes they carry matter more than the internals of a container. Second, give every element a stable name or reference, so that policies, decision records and the ownership file can point at it. Third, treat the views as outputs. The context diagram that goes to a board is generated from the workspace and never edited by hand.

Security properties on model elements

Structurizr lets any element or relationship carry named properties. That feature is what turns a diagram into a security model. The properties the architect needs are few, and each must be one that a rule can test:

  • trustZone: the zone in which the element runs, drawn from a closed list (for example agent-runtime, platform-control, core-systems, external-supplier).
  • dataClass: the highest classification of data the element holds or passes.
  • identity: the workload or agent identity the element acts with, which links the model to the identity records of Chapter 8.
  • usageMode: the usage mode of any AI element, from Mode 0 Ambient AI to Mode 5 Autonomous production agents, so that rules can treat a Mode 5 agent differently from a Mode 2 assistant.
  • policyPoint on relationships: the element that enforces policy on this flow, where the flow crosses a zone.
  • owner: the team accountable for the element, which feeds the ownership file.

A closed vocabulary matters more than a rich one. The rule cannot test a property that two teams spell differently, so the list of zones and classes is itself a versioned file in the repository, changed by pull request like everything else.

Worked example: trust-zone properties in a Structurizr fragment

Illustrative example. The fragment below is part of Hansa Mutual's workspace. It declares the claims-triage agent (a Mode 5 agent working through the Polish service centre), the AI gateway that is its policy point, and the core claims system. Each element carries its zone, data class and owner, and each relationship that crosses a zone names its policy point.

workspace "hansa-estate" {
  model {
    triage = softwareSystem "Claims-triage agent" "Mode 5 agent working through the Polish service centre" "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 model and tool call" "Policy point" {
      properties {
        "trustZone" "platform-control"
        "dataClass" "personal"
        "owner" "ai-platform-team"
      }
    }
    claims = softwareSystem "Core claims system" "System of record for claims" {
      properties {
        "trustZone" "core-systems"
        "dataClass" "personal"
        "owner" "claims-product-line"
      }
    }
    triage -> gateway "Model and tool calls" "HTTPS" {
      properties { "policyPoint" "AI gateway" }
    }
    gateway -> claims "Route update within approval rules" "API" {
      properties { "policyPoint" "AI gateway" }
    }
  }
}

Two features of the fragment deserve comment. The agent has no direct relationship to the core claims system: its only write path runs through the gateway, and the model says so in a form that can be tested. And the gateway plays two roles: it is an element tagged Policy point, and its name is the value of the policyPoint property on both relationships, which lets a rule check that the named point exists and is what it claims to be.

FINOS CALM as an emerging alternative

Structurizr is not the only way to keep architecture as code. The FINOS Architecture as Code project publishes CALM, an open specification that describes architectures as machine-readable documents with nodes, relationships and attached controls, and is designed so that tools can validate an architecture against a pattern (61, FINOS, n.d.). Its attraction for a security architect is that controls are first-class in the specification rather than a property convention. It is observable that the specification exists and is developed in the open within FINOS; it is expected that more organisations in regulated sectors will evaluate it. Whether it displaces C4-based workspaces is speculation, and nothing in this chapter depends on the answer. The practical advice is to choose by two tests: whether the format lets a rule read properties without custom parsing, and whether the organisation can keep the model current. A workspace that is current beats a richer specification that is not.

Policy as code for architecture

A property that nothing tests is a comment. The step that makes security architecture executable is a policy that reads the model and fails when the model breaks the architect's principles. Open Policy Agent and its policy language Rego are the established tools for this (62, Open Policy Agent, n.d.), and Architecture as Code (Chapters 10 and 11) already uses them for infrastructure and governance. The same engine applies to the architecture itself, with the exported workspace as its input. Conftest, a utility built on Open Policy Agent, runs such policies against structured files in a pipeline (177, Conftest, n.d.).

Three kinds of rule cover most of what a security architect states as a principle:

  • Completeness rules require that every element has the properties the other rules need, because a rule that skips an element with no zone silently approves it.
  • Boundary rules require that a relationship between two zones names a policy point and that the policy point exists. They are the executable form of "nothing crosses a boundary unobserved".
  • Content rules restrict what may sit where, for example that an element holding a restricted data class does not run in the external-supplier zone, or that a Mode 5 agent has an identity of its own.

The Secure Software Development Framework asks that software be designed to meet security requirements and mitigate risks, with the design reviewed against those requirements (34, Souppaya et al., 2022). Policy over the model is a way to make that practice mechanical for the requirements that can be stated precisely, and it leaves the architect's time for the requirements that cannot.

Worked example: a Rego rule that fails a pull request at a zone crossing

Illustrative example. The rules below run in the pipeline against a flattened export of Hansa Mutual's workspace. A build step turns the exported JSON into input.elements, keyed by element name, each with a properties object and a tags list, and input.relationships. The first rule fails any element that lacks a trust zone, and the second fails any relationship that crosses zones without naming a policy point that exists.

package architecture.zones

import rego.v1

zone(name) := object.get(input.elements[name].properties, "trustZone", "")

deny contains msg if {
    some name, element in input.elements
    zone(name) == ""
    msg := sprintf("%s has no trustZone property", [name])
}

deny contains msg if {
    some rel in input.relationships
    zone(rel.source) != zone(rel.destination)
    not named_policy_point(rel)
    msg := sprintf("%s -> %s crosses %s to %s without a policy point",
        [rel.source, rel.destination, zone(rel.source), zone(rel.destination)])
}

named_policy_point(rel) if {
    point := object.get(rel.properties, "policyPoint", "")
    "Policy point" in input.elements[point].tags
}

deny contains msg if {
    some name, element in input.elements
    element.properties.usageMode == "5"
    not element.properties.identity
    msg := sprintf("%s is a Mode 5 agent without an identity of its own", [name])
}

Suppose a product team adds a relationship from the claims-triage agent directly to the core claims system, to save a hop. The change passes review in the team's own repository and reaches the architecture repository as a model change. The second rule reports that the agent crosses from agent-runtime to core-systems without a policy point, the pipeline fails, and the pull request cannot merge. The architect did not read the diagram. The architect wrote the principle once, and the pipeline applied it to a change the architect never saw. That is the practical meaning of Shift 2: the architect designs the boundary and the rule that holds it, and the routine case is decided without the architect in the path.

Assure once, comply many, at design time

Architecture as Code (Chapters 10 and 11) argues that a control should be written once and mapped to many obligations, with evidence linked to enforcement (167, Nordqvist, 2025). In the architecture model the same principle applies earlier: a design principle is written once and applied to every system the model describes. The boundary rule above does not mention the claims-triage agent. It applies to the IT-operations agent, the SOC investigation agent and any agent a team adds next quarter, because it reads a property, not a name.

The obligations that this design-time rule serves are several, and the mapping belongs in the control catalogue of Chapter 9 rather than in the rule. As architectural implications, not legal advice, three instruments make the model a more useful artefact than a document:

  • NIS 2 Article 21(2) lists the cybersecurity risk-management measures that essential and important entities must take, among them policies on risk analysis and information-system security and security in the acquisition, development and maintenance of systems (6, European Union, 2022). A boundary rule enforced on every change is a measure that can be shown to operate.
  • DORA Article 8 requires financial entities to identify, classify and document their ICT-supported business functions and information and ICT assets, and Article 28 requires a register of information on contractual arrangements with ICT third-party service providers (9, European Union, 2022). The model, with owners, zones and supplier elements, is a natural source for both, and the Hansa Mutual register of information can be generated from the elements tagged as external suppliers rather than compiled in parallel.
  • AI Act Article 11 and Annex IV require technical documentation for high-risk AI systems, including a description of the system's architecture, and Article 15 requires an appropriate level of cybersecurity (1, European Union, 2024). AI Platform and Security, Chapter 5, concludes that the architecture repository, not a document, is the single source from which that documentation is generated (169, Nordqvist, 2026). The model is the architecture part of that source.

The consequence for the architect is a change in what is reviewed. A review at design time asks whether a particular system satisfies the principles. A rule asks the same question of every system, on every change, at no marginal cost per system. The architect's judgement moves to deciding which principles deserve a rule, and which exceptions are justified, expire and are recorded.

The pull request as the unit of change

In a document-based practice the unit of architectural change is a revision of the document, reviewed at a board. In a model-based practice it is the pull request. Humble and Farley's argument for the deployment pipeline, that every change to the system goes through the same automated path to production, applies with equal force to changes in the architecture, which are changes to a controlled artefact like any other (80, Humble & Farley, 2010). A pull request carries what a review needs: the diff of the model, the result of the policy checks, the linked decision record and a named author, whether person or agent.

Three mechanisms decide who reviews what.

Policy checks decide the routine cases, as the Rego example shows. A change that satisfies every rule and touches no protected path needs no architect.

Review triggers decide which changes need a human. A change to a file that defines a boundary, a zone, a data class, a supplier element or a Mode 5 agent's identity is a review trigger, and the architect is its named reviewer. AI Platform and Security, Chapter 17, introduced the idea for the threat model: a code-ownership rule routes any change to files named in the model's review trigger to the security architect (169, Nordqvist, 2026). Code-ownership files of this kind are a feature of the major repository hosts and can require approval from the listed owners before a merge (174, GitHub, n.d.).

Decision rights decide how long the review may take and what happens when the owner is unavailable. Chapter 4 records these in the role charter. The ownership file implements them.

Worked example: the code-ownership file for Nordvik Region

Illustrative example. Nordvik Region has one security architect, which makes the ownership file as much a risk register as a routing table. The file below sits in the AI platform repository, where the pre-production security checklist already runs against the pull request that introduces an AI system. Every protected path lists a second owner, the CISO's deputy, so that the single post does not stop the pipeline.

# .github/CODEOWNERS (illustrative, Nordvik Region AI platform repository)
# Boundaries: zones, data classes and supplier elements in the model
/architecture/vocabulary/            @nordvik-region/security-architect @nordvik-region/ciso-deputy
/architecture/model/zones/           @nordvik-region/security-architect @nordvik-region/ciso-deputy
/architecture/model/suppliers/       @nordvik-region/security-architect @nordvik-region/enterprise-architect

# Policies that enforce the architect's principles
/policies/architecture/              @nordvik-region/security-architect @nordvik-region/ciso-deputy
/policies/egress/                    @nordvik-region/security-architect @nordvik-region/platform-team

# Decision records for security-relevant choices
/decisions/aidr/                     @nordvik-region/security-architect @nordvik-region/ai-architect

# Pre-production checklist and the threat model of the citizen-service assistant
/checklists/pre-production/          @nordvik-region/security-architect
/threat-models/                      @nordvik-region/security-architect @nordvik-region/ai-architect

The file records three decisions in a form that can be reviewed. The supplier directory names the enterprise architect as co-owner, because a black-box element for TriageSoft carries contractual properties as well as technical ones. The egress policies share ownership with the platform team, who operate them. And the threat-model path names the AI architect, who owns the AI Decision Records of the estate. A path with a single owner is a finding in its own right, because the pipeline cannot enforce a review that nobody is available to give.

Decision records beside the code

The model says what the architecture is. It does not say why. Nygard's short, numbered, immutable records capture the context, the decision and the consequences of an architecturally significant choice (63, Nygard, 2011), and Architecture as Code (Chapter 4) kept them beside the code so that the rationale survives the people who made it (167, Nordqvist, 2025). AI Platform and Security, Chapter 5, added the fields AI requires, validated the records against a schema and re-opened them by evidence, under the name AI Decision Records (169, Nordqvist, 2026). This book keeps both: an Architecture Decision Record for a security design choice in any system, and an AI Decision Record (AIDR, in this book's range AIDR-0500 to AIDR-0599) where the decision concerns an AI system or an AI-assisted practice.

The link between record and model is what makes the pair useful. Each record names the model elements it concerns, and a pipeline check fails when a record cites an element that no longer exists or when a model element marked as a boundary has no record that explains it. The Structurizr DSL can also attach documentation and decision records to a workspace, which gives the website or the generated board paper a path from a box on a diagram to the decision behind it (60, Structurizr, n.d.). Evidence re-opens records in this practice: a drift finding, a failed policy check that was waived, or an incident that crossed a boundary the record called sufficient each become the trigger for a superseding record.

Worked example: the record that moves Nordvik's reference architecture into the repository

Illustrative example. Nordvik Region's decision to move its 2024 security reference architecture into the AI platform repository is itself recorded as code. AIDR-0501 follows the schema of AI Platform and Security, Chapter 5, and names the model elements and policies it creates.

# decisions/aidr/AIDR-0501.yaml (illustrative, Nordvik Region)
id: AIDR-0501
title: Move the security reference architecture into the AI platform repository
status: proposed
date: 2026-11-20
deciders: [ciso, enterprise-architect]
reviewers: [security-architect, ai-architect, platform-team-lead]
relates_to: [AIDR-0002, AIDR-0500]
model_elements: [zones/platform-control, zones/regional-datacentre, suppliers/triagesoft]
context: >
  The 2024 reference architecture is a document that predates most of the AI
  estate and lives outside the repository that holds the overlay AIDR-0002.
  The pre-production security checklist is already code.
options:
  - id: keep-document
    rejected: cannot be checked against the estate or routed to review triggers
  - id: model-and-policies
    chosen: a small model of zones and suppliers plus four policies
decision: >
  Keep the reference architecture as a Structurizr workspace and four Rego
  policies in the platform repository; generate the document from them.
consequences:
  - Supplier systems appear as black boxes with contractual properties.
  - The security architect and the CISO's deputy co-own the protected paths.
review_by: 2027-05-20

The chosen option is deliberately small. Nordvik does not model its whole estate in the first pass. It models the zones, the supplier elements and the flows that the checklist already tests, and it adds to the model as new systems arrive, so that the model grows with the work instead of ahead of it.

Drift between model and estate

A model that is not compared with the estate becomes a better-looking document. AI Platform and Security, Chapter 4, concluded that the declarative model can be checked against the running estate (169, Nordqvist, 2026); the security architect owns the question of what that comparison asserts and what a difference means.

Drift runs in two directions, and the two have different meanings.

The estate contains something the model does not. A workload with no element, an identity with no owner, an egress path with no policy point. This is the dangerous direction, because the model gives false assurance about the part it omits. Hansa Mutual would treat an unmodelled agent identity as a finding for the identity domain architect on the day it is found, since a Mode 5 agent that the model does not know is a boundary that no rule tests.

The model contains something the estate does not. A planned element that was never built, or one that was retired. This is less dangerous and is mostly a hygiene finding, but it hides the first kind in the noise, so it is also cleared.

The comparison needs an inventory of what runs: the workload identities in the platform's identity provider, the deployed services from the orchestrator, the network and egress rules from their configuration repositories, and the registered tools from the tool registry of AI Platform and Security, Chapter 4. The comparison is a report, not an alarm, and each finding has an owner and an age. Three rules keep it useful. A finding becomes a pull request, either to correct the model or to remove what should not run, so that the repair goes through the same review as any change. A finding that stays open past an agreed time becomes an exception with an expiry date and a named approver, as in Architecture as Code (Chapter 9C) (167, Nordqvist, 2025). And the drift rate itself is a measure the architect reports, because a rising rate says that the model is falling behind the work and the process, not the engineers, needs attention.

DORA Article 8 asks financial entities to keep their ICT asset inventory current (9, European Union, 2022). A drift comparison between the model and the inventory is one way to show that the documentation requirement is met by operation rather than by annual review. Whether a supervisor accepts that as sufficient is a question for the entity's supervisor, not for this chapter.

What remains a document

Executable architecture does not abolish documents. It changes who writes them and when. Four kinds remain.

Generated narratives. The board paper on how agents are contained, the supplier annex that describes the required boundary, the summary for a supervisor, the architecture section of the technical documentation under AI Act Annex IV. Each is generated from the model, the policies and the decision records, carries the commit it was generated from, and is never edited by hand. A reader who finds an error corrects the model and regenerates. Chapter 19 treats the audiences and their needs. It is expected that organisations already working this way will generate most of their security architecture documentation from the model, because the cost of keeping a hand-written copy in step rises with every agent that changes the estate; this is a projection from the practice described here, not yet a documented norm.

Rationale and judgement. The decision record is a document in the plain sense: prose that explains a choice to a later reader. It stays prose because the reasoning it carries is not reducible to a property.

Policy statements that people must read. The information-security policy that staff accept, the acceptable-use rule for AI tools, the role charter itself in its human-readable parts. These are addressed to people, who read them once and act on them. They are still versioned and reviewed through the repository.

Contracts. A tender annex is a legal document that a supplier must accept. For Nordvik Region it is the main instrument through which the architect holds a boundary in a supplier's system. The annex is generated from the same model elements and requirement text, so that what the contract says and what the model asserts are the same sentences, but the contract remains a contract.

The test the architect applies to any proposed document is whether a person will read it to decide or to act. If a rule could answer the question, the rule is the artefact.

Making the move

Practical guide: moving a security reference architecture document into a model and a policy set

Purpose. Replace a security reference architecture document with a model, a small policy set and a change workflow, without a pause in the architect's other work.

Roles. The security architect (owner and author of the first policies), the enterprise architect (owner of the modelling conventions), the platform team (owner of the repository and pipeline), the CISO or the CISO's deputy (approver of the decision record).

Steps.

  1. Read the document and list every sentence that states a principle ("systems in zone A reach zone B only through X"). Mark each as testable now, testable with a new property, or not testable. Expect about half to fall in the first two groups.
  2. Choose the closed vocabularies: three to six trust zones, three to four data classes, and the usage modes. Commit them as files in the repository before drawing anything.
  3. Model only the flows that cross a zone boundary in the first pass, with the properties in the list above. Keep the first model to a size one person can review in an hour.
  4. Write one policy for each testable principle, starting with the completeness rule and the boundary rule. Test each policy against a deliberately broken copy of the model, in the pipeline, with the expected failure.
  5. Add the ownership file for the vocabulary, the zones, the supplier elements and the policies, with a second owner on every path. Record the decision as an AIDR or ADR that names the model elements it creates.
  6. Run the policies for two weeks in report-only mode. Fix the model where it is wrong and the rule where it is too strict, then switch the boundary rule to blocking on the main branch.
  7. Generate the first document from the model, compare it with the original, and mark the original as superseded with a link to the generated one. Do not maintain the two side by side.
  8. Add the drift comparison against one inventory, such as the workload identities, and set an age limit for findings. A default of 30 days for a finding to be corrected or become an expiring exception suits many organisations; adapt it to the organisation's risk appetite and the speed at which its agents change.

Definition of done. The boundary rule blocks a deliberately introduced violation on the main branch; every protected path has two owners; the superseded document points to its generated replacement; the first drift report has an owner for every finding; and the decision record is merged.

Actors, modes and the outlook

Across the usage modes

The model represents AI differently according to how the AI is deployed and whose identity it uses. The distinction between the architect's own use of AI and the agents in the estate is the one that matters most for this chapter.

Mode How it appears in the model Review path for its changes
Mode 0 Ambient AI A property of a supplier element, for example usageMode: 0, with a contractual owner Supplier directory path; contract change
Mode 1 Conversational assistants An external service element in the external-supplier zone; the user's identity is the actor Policy on data class leaving the organisation
Mode 2 Embedded workplace assistants A feature of a suite element; acts with the user's tenant permissions Supplier path plus tenant permission review
Mode 3 Agentic work tools An element acting with a person's identity; for the architect, a tool that drafts model changes as proposals Same review triggers as any author; no commit or push, merge by a named person
Mode 4 Built AI applications A software system in the platform zones with a manifest of its components Boundary rules; AIDR for the system
Mode 5 Autonomous production agents An actor with an identity, permissions and trust zone of its own; its own element Identity rule, boundary rule, review by the identity and AI domain architects

For the architect's Mode 3 tools, the control is simple and strict. A tool that drafts a pull request against the model acts with the architect's identity, and its change passes the same policy checks and review triggers as any other author's. An agent that proposes weakening a boundary rule receives no shortcut. At Nordvik Region, the Mode 3 tool of the mandate manifest MND-NR-01 may edit at Level 2 Supervised, may not commit or push, and has the policy directories among its protected paths; from 1 January 2027 the role charter's ceiling of Level 1 Assisted governs its edits, and the manifest itself was aligned with that ceiling as version 3.0.0 at its May 2027 review (Chapter 25) until the manifest is aligned. In practice it drafts model changes, the architect or the CISO's deputy commits and approves them, and the ownership file enforces this regardless of what the tool is configured to do. Chapters 12 and 13 define the mandate manifest in full.

For Mode 5 agents in the estate, the model is the first place their authority is written down. An agent without an identity property fails the Rego rule above. An agent whose relationships cross zones without a policy point fails the boundary rule. The model alone cannot say that an agent behaves; it states what the architect designed it to be allowed to reach, and Chapter 7 and Chapter 8 define the containment and identity that make the statement true.

What is observable, expected and speculation

Architecture models kept as code, Structurizr workspaces and policy as code in Open Policy Agent are observable practice, documented by the tools' own communities (60, Structurizr, n.d.) (62, Open Policy Agent, n.d.) and by the earlier volumes of this series. The pull request as the unit of architectural change, with code-ownership files routing review, is observable wherever the repository host supports it. It is expected that organisations already working this way will generate most of their security architecture documentation from the model, for the reason given above. Whether an AI system will be able to check a model for omissions that no rule anticipates is speculation: the evidence on AI-assisted review of architecture is limited, and Chapter 14 treats how an architect verifies what an AI proposes.

Nordvik Region and Hansa Mutual

Nordvik Region moves the 2024 security reference architecture into the AI platform repository as a small model and four policies, starting from the pre-production security checklist that is already code, and records the decision as AIDR-0501. Its model is small on purpose: three zones, the supplier elements and the flows the checklist already tests. The hard part is that suppliers' systems appear in the model only as black boxes with contractual properties. TriageSoft's benefits-triage system under tender NR-2026-117 is a single element whose zone is external-supplier, whose properties record what the contract promises, and whose verification is documentary until the supplier's boundary can be tested. The single post-holder remains a single point of failure, which the second owner on every protected path mitigates and does not remove.

Hansa Mutual already has a Structurizr workspace and policy as code with market overlays. Its work is to attach the security properties to the existing elements, add review triggers for its domain architects, and bring the UK and Swiss mappings, now kept by the local security officers outside the catalogue, into the same repository as overlays. Its hard part is organisational. The architecture review board still reviews documents generated beside the model, so the board's decisions and the model can disagree. Until the board reviews the pull request and the generated view of it, the fortnightly session remains in the path of changes that agents propose daily. The practical step is to reduce the board's agenda to contested items, as the decision tiers of Chapter 17 provide, and to let the policy checks decide the rest.

Summary

Security architecture becomes executable when four things are kept in one repository: the model of the estate with security properties on its elements, the policies that read the model and fail when it breaks the architect's principles, the decision records that explain the choices, and the ownership file that routes the changes that need a human to the person accountable. The pull request is the unit of change, and the drift comparison is the check that the declared architecture still describes the running one.

This chapter concerns two of the four shifts. Shift 1, from documents to code, is realised in the model, the Rego policies and the decision records, from which the documents that remain are generated rather than maintained. Shift 2, from gatekeeper to boundary designer, is realised in the division of labour the pull request creates: policy checks decide the routine case, review triggers bring the contested case to a named architect, and the architect's effort goes into the boundary and the rule that holds it rather than into reading every diagram. Mode 3 tools and Mode 5 agents are treated like any other author and actor: they act within an identity, pass the same checks and appear in the model with a zone and an owner.

Models and policy as code are observable practice; generating most security architecture documentation from the model is expected, not yet established. The model is only as good as its comparison with the estate, so the drift finding and its age are measures the architect reports. Two things stay with the architect throughout: choosing which principles deserve a rule, and judging the exceptions. Both are the accountable human judgement that the thesis of this book names as the scarce part of the role.

Chapter 6 takes the model as its input. It shows how threat models are generated from the architecture repository, assisted by AI and verified by a named reviewer, so that every threat names a control and the pipeline fails when one does not.

Sources

  1. International Organization for Standardization, International Electrotechnical Commission and Institute of Electrical and Electronics Engineers. ISO/IEC/IEEE 42010:2022 Software, systems and enterprise: Architecture description. (28, ISO/IEC, 2022)
  2. Rozanski, N. & Woods, E. Software Systems Architecture: Working with Stakeholders Using Viewpoints and Perspectives. (75, Rozanski & Woods, 2011)
  3. Brown, S. The C4 model for visualising software architecture. (59, Brown, n.d.)
  4. Structurizr. Structurizr DSL language reference. (60, Structurizr, n.d.)
  5. FINOS. Architecture as Code: What is CALM?. (61, FINOS, n.d.)
  6. Open Policy Agent Contributors. Open Policy Agent Documentation. (62, Open Policy Agent, n.d.)
  7. Conftest. Conftest: test structured configuration data with Open Policy Agent policies. (177, Conftest, n.d.)
  8. Souppaya, M., Scarfone, K. & Dodson, D. Secure Software Development Framework (SSDF) Version 1.1: Recommendations for Mitigating the Risk of Software Vulnerabilities. (34, Souppaya et al., 2022)
  9. European Parliament and Council of the European Union. Directive (EU) 2022/2555 on measures for a high common level of cybersecurity across the Union (NIS 2 Directive). (6, European Union, 2022)
  10. European Parliament and Council of the European Union. Regulation (EU) 2022/2554 on digital operational resilience for the financial sector (DORA). (9, European Union, 2022)
  11. European Parliament and Council of the European Union. Regulation (EU) 2024/1689 laying down harmonised rules on artificial intelligence (Artificial Intelligence Act). (1, European Union, 2024)
  12. Humble, J. & Farley, D. Continuous Delivery: Reliable Software Releases through Build, Test, and Deployment Automation. (80, Humble & Farley, 2010)
  13. GitHub. About code owners. (174, GitHub, n.d.)
  14. Nygard, M. Documenting Architecture Decisions. (63, Nygard, 2011)
  15. Nordqvist, G. Architecture as Code. (167, Nordqvist, 2025)
  16. Nordqvist, G. AI Platform and Security: Building and Securing AI Platforms in European Enterprises and Public Authorities. (169, Nordqvist, 2026)