Architecture and Decision Tools · Tools: the course

All courses / Tools / Module 2 / Chapter 4

Learning objectives

After the lesson the participant can:

Compare the C4 model in the Structurizr DSL with CALM as a model language that pipelines can check.
Draft an Architecture Decision Record with status, review dates and deciders in the template of Architecture as Code.
Annotate model elements with the security properties that a zone-crossing rule needs.
Determine which decision record a usage mode requires and at what threshold.

Key concepts

Diagram decay: The drift between a diagram drawn in a graphical tool and the system it shows, because updating the diagram is a separate manual act. Architecture as Code answers it with one text model under version control from which diagrams are generated.
Declarative reference architecture model: An artefact of AI Platform and Security, Chapter 4, that declares the layers, patterns and control plane as code with a pinned version. A team records deviations in an AI Decision Record but does not remove the gateway, registry, evaluation service or control plane.
Workspace with trust-zone properties: A Structurizr workspace from The Transformed Security Architect, Chapter 5, in which trust zone, data class, usage mode, identity, owner and policy point are element and relationship properties, so a pipeline rule can fail a pull request that creates an unprotected crossing.
Architecture Decision Record: A short text document, after Nygard, that captures one decision with its context and consequences in a numbered file under version control. The number ADR-NNNN is permanent even if the record is later deprecated or superseded.
Market overlay: An artefact of AI Platform and Security that applies jurisdiction-specific constraints on top of the pinned reference model. Nordvik Region runs its reduced variant as an overlay on a pinned base, recorded in AIDR-0002.

Interactive exercises

Do them here and get feedback at once. Choose a card and then where it belongs, or drag it.

Interactive exercise 1 · Sort

Architecture and decision tools by kind

Sort each tool of Chapter 4 into the kind that its entry or family table gives it.

Interactive exercise 2 · Scenario

Extending the decision record template

Choose how the team should adopt the Architecture Decision Record template, following the chapter's entry.

Teaching plan

15 min	Present Figure 4.1, from model to decision record, and the three model languages. Note that Structurizr Lite, the standalone CLI and the cloud service have reached end of life.
15 min	Read the excerpt of the Hansa Mutual workspace: the claims-triage agent with its trust zone, data class, usage mode and identity. Ask what the missing direct relationship to the core claims system proves.
10 min	Walk through the ADR template and what validate_adrs.py requires. Present the table of decisions recorded per usage mode.
25 min	Exercise: participants write one ADR and annotate three elements of their own architecture with security properties.
10 min	Pairs review each other's record: is the review date set, are the deciders named, could a script read every added field?

Discussion

The chapter says CALM's adoption is observable but its standing in regulated sectors is expected, not established. How should that label affect a choice of model language today?
A reader adopting the ADR template should add only fields a script will read. Which fields in your own decision records does nothing read, and what do they cost?
For Modes 0 to 3 the series asks only for a short record and an inventory entry. Where does that lighter requirement become a risk in practice?

Written exercise

Exercise · 25 minutes

One decision record and three annotated elements

Take one recent architecture choice in your own organisation, or Hansa Mutual's choice that the claims-triage agent has no direct write path to the core claims system. Write it as an Architecture Decision Record in the template of Architecture as Code: identifier, title, status, date, last reviewed, next review due, deciders, context, decision and consequences. Then list three elements of the architecture the decision touches and give each the properties of the trust-zone workspace: trust zone, data class, usage mode, identity, owner and, for each crossing between zones, the named policy point. Mark any property you cannot fill in.

Deliverable: One completed ADR and a table of three elements with their security properties and any missing values flagged.

Your work

Self-test

Choose an answer to see whether it is right, or open the answer below each question.

Which rule holds for every adaptation of the declarative reference architecture model, according to AI Platform and Security, Chapter 4?
Show the answer
C. A team records deviations in an AI Decision Record but keeps the gateway, the registry, the evaluation service and the control plane
The file is a template for the form, not a prescription of the contents, with one fixed rule: deviations are recorded, but the gateway, registry, evaluation service and control plane stay because later controls depend on them.
What does the validator validate_adrs.py of Architecture as Code check?
Show the answer
A. That each ADR front matter is complete and its status is one of the four lifecycle statuses
The validator requires the scalar fields such as adr_id, title, status, date, last_reviewed and next_review_due, and accepts only the four lifecycle statuses. It is the one ADR script of four that a chapter describes.
For which usage modes does the chapter's table require the full AI Decision Record always, for each system or agent?
Show the answer
D. Mode 4 Built AI applications and Mode 5 Autonomous production agents
Modes 0 to 3 need a short record and an inventory entry. Modes 4 and 5 need the full record always, and for Mode 5 again whenever permissions widen, because the organisation operates all the layers.