The reference agent's subject, cloud solution architecture, as an agent in the operating model agent's pattern: the Execution engine (from orchestration_engine) and one Workflow in app/solution_architecture, built for the settings and provider bundle by assembly.workflow_for. Copied from gcp_solution_architecture_agent at 8b397cd without its own engine: its role files, Skills, provider bundle, ADRs, vocabulary, scripts and evaluation datasets. The image takes the engine from a named build context and installs Terraform. It is called through the Orchestration engine, and its files are what the operating model agent digests. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
357 lines
12 KiB
Python
357 lines
12 KiB
Python
"""The Target architecture: one explicit graph, established before code (ADR-0005).
|
|
|
|
Elements every component and the resource that realises it
|
|
Relationships how Elements connect
|
|
Checks the numbered, verifiable conditions each must meet, each traced
|
|
to the requirement or design recommendation it comes from
|
|
|
|
This module is pure: it parses the graph, states what is wrong with it, renders it as
|
|
a diagram and as tables a person can review, and says whether the Requirements chain
|
|
through it is complete.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import json
|
|
import re
|
|
from collections.abc import Iterable, Mapping, Sequence
|
|
from dataclasses import dataclass
|
|
from typing import Any
|
|
|
|
GRAPH_ATTACHMENT = "target-architecture.json"
|
|
DIAGRAM_ATTACHMENT = "architecture.mmd"
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class Element:
|
|
id: str
|
|
name: str
|
|
product: str
|
|
resource_type: str
|
|
component: str | None = None # None for a supporting Element, e.g. an identity
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class Relationship:
|
|
id: str
|
|
source: str # "from" in the data
|
|
target: str # "to" in the data
|
|
kind: str
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class Check:
|
|
id: str
|
|
applies_to: str # an Element or Relationship id
|
|
statement: str
|
|
source: str # a requirement or design recommendation id
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class NotApplicable:
|
|
recommendation: str
|
|
reason: str
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class TargetArchitecture:
|
|
elements: tuple[Element, ...]
|
|
relationships: tuple[Relationship, ...]
|
|
checks: tuple[Check, ...]
|
|
not_applicable: tuple[NotApplicable, ...] = ()
|
|
|
|
@property
|
|
def check_ids(self) -> tuple[str, ...]:
|
|
return tuple(check.id for check in self.checks)
|
|
|
|
def summary(self) -> dict[str, Any]:
|
|
"""What a user approving the design is told about the graph."""
|
|
return {
|
|
"elements": len(self.elements),
|
|
"relationships": len(self.relationships),
|
|
"checks": len(self.checks),
|
|
"not_applicable": [
|
|
{"recommendation": item.recommendation, "reason": item.reason}
|
|
for item in self.not_applicable
|
|
],
|
|
}
|
|
|
|
|
|
class GraphError(ValueError):
|
|
"""The graph is not well-formed; `problems` says how, one entry per fault."""
|
|
|
|
def __init__(self, problems: Sequence[str]) -> None:
|
|
super().__init__("; ".join(problems))
|
|
self.problems = tuple(problems)
|
|
|
|
|
|
def parse_graph(text: str) -> TargetArchitecture:
|
|
"""Parse target-architecture.json, or raise GraphError naming every fault."""
|
|
name = GRAPH_ATTACHMENT
|
|
try:
|
|
data = json.loads(text)
|
|
except ValueError as exc:
|
|
raise GraphError([f"{name}: not valid JSON ({exc})"]) from exc
|
|
if not isinstance(data, dict):
|
|
raise GraphError(
|
|
[f"{name}: must be an object with elements, relationships and checks"]
|
|
)
|
|
|
|
problems: list[str] = []
|
|
|
|
def items(key: str, required: Sequence[str]) -> list[dict[str, str]]:
|
|
raw = data.get(key, [])
|
|
if not isinstance(raw, list):
|
|
problems.append(f"{name}.{key}: must be a list")
|
|
return []
|
|
accepted = []
|
|
for index, item in enumerate(raw):
|
|
where = f"{name}.{key}[{index}]"
|
|
if not isinstance(item, dict):
|
|
problems.append(f"{where}: must be an object")
|
|
continue
|
|
missing = [
|
|
field
|
|
for field in required
|
|
if not isinstance(item.get(field), str) or not item[field].strip()
|
|
]
|
|
if missing:
|
|
problems.append(f"{where}: needs a non-empty {', '.join(missing)}")
|
|
continue
|
|
accepted.append(item)
|
|
return accepted
|
|
|
|
elements = tuple(
|
|
Element(
|
|
id=item["id"],
|
|
name=item["name"],
|
|
product=item["product"],
|
|
resource_type=item["resource_type"],
|
|
component=item.get("component") or None,
|
|
)
|
|
for item in items("elements", ("id", "name", "product", "resource_type"))
|
|
)
|
|
relationships = tuple(
|
|
Relationship(item["id"], item["from"], item["to"], item["kind"])
|
|
for item in items("relationships", ("id", "from", "to", "kind"))
|
|
)
|
|
checks = tuple(
|
|
Check(item["id"], item["applies_to"], item["statement"], item["source"])
|
|
for item in items("checks", ("id", "applies_to", "statement", "source"))
|
|
)
|
|
not_applicable = tuple(
|
|
NotApplicable(item["recommendation"], item["reason"])
|
|
for item in items("not_applicable", ("recommendation", "reason"))
|
|
)
|
|
|
|
if not elements and not problems:
|
|
problems.append(f"{name}.elements: the graph has no Elements")
|
|
|
|
seen: set[str] = set()
|
|
ids = [thing.id for group in (elements, relationships, checks) for thing in group]
|
|
for identifier in ids:
|
|
if identifier in seen:
|
|
problems.append(f"{name}: id {identifier} is used more than once")
|
|
seen.add(identifier)
|
|
|
|
element_ids = {element.id for element in elements}
|
|
for relationship in relationships:
|
|
for end, value in (("from", relationship.source), ("to", relationship.target)):
|
|
if value not in element_ids:
|
|
problems.append(
|
|
f"{name}: Relationship {relationship.id} {end} {value}, "
|
|
"which is not an Element"
|
|
)
|
|
targets = element_ids | {relationship.id for relationship in relationships}
|
|
for check in checks:
|
|
if check.applies_to not in targets:
|
|
problems.append(
|
|
f"{name}: Check {check.id} applies to {check.applies_to}, "
|
|
"which is not an Element or Relationship"
|
|
)
|
|
checked = {check.applies_to for check in checks}
|
|
for element in elements:
|
|
if element.id not in checked:
|
|
problems.append(f"{name}: Element {element.id} has no Check")
|
|
|
|
if problems:
|
|
raise GraphError(problems)
|
|
return TargetArchitecture(elements, relationships, checks, not_applicable)
|
|
|
|
|
|
# --- the Requirements chain through the graph ----------------------------------------
|
|
|
|
|
|
def chain_gaps(
|
|
graph: TargetArchitecture,
|
|
*,
|
|
requirements: Sequence[Mapping[str, Any]],
|
|
components: Sequence[Mapping[str, Any]],
|
|
products: Sequence[Mapping[str, Any]],
|
|
recommendations: Sequence[Mapping[str, Any]],
|
|
) -> tuple[str, ...]:
|
|
"""Every place the Requirements chain stops before reaching a Check.
|
|
|
|
A functional requirement is carried by a component that has an Element, or by a
|
|
Check of its own. A non-functional requirement and a design recommendation are
|
|
each a constraint, so each must be the source of a Check (a recommendation may
|
|
instead be marked not applicable, with a reason). A constraint that lists
|
|
nothing infrastructure code can show, only what lies outside it, needs none.
|
|
"""
|
|
gaps: list[str] = []
|
|
requirement_ids = {item["id"] for item in requirements}
|
|
recommendation_ids = {item["id"] for item in recommendations}
|
|
sources = {check.source for check in graph.checks}
|
|
realised = {element.component for element in graph.elements if element.component}
|
|
|
|
for check in graph.checks:
|
|
if check.source not in requirement_ids | recommendation_ids:
|
|
gaps.append(
|
|
f"Check {check.id} has source {check.source}, which is not a "
|
|
"requirement or design recommendation"
|
|
)
|
|
for element in graph.elements:
|
|
if element.component and element.component not in {c["id"] for c in components}:
|
|
gaps.append(
|
|
f"Element {element.id} realises {element.component}, "
|
|
"which is not a component"
|
|
)
|
|
|
|
for component in components:
|
|
if component["id"] not in realised:
|
|
gaps.append(f"Component {component['id']} has no Element")
|
|
for requirement in requirements:
|
|
if requirement["id"] in sources:
|
|
continue
|
|
served = any(
|
|
requirement["id"] in component.get("requirements", ())
|
|
and component["id"] in realised
|
|
for component in components
|
|
)
|
|
if requirement.get("kind") == "functional" and served:
|
|
continue
|
|
if _only_outside_code(requirement):
|
|
continue
|
|
gaps.append(f"Requirement {requirement['id']} has no Check")
|
|
for selection in products:
|
|
used = any(
|
|
element.component == selection["component"]
|
|
and element.product == selection["product"]
|
|
for element in graph.elements
|
|
)
|
|
if not used:
|
|
gaps.append(
|
|
f"Product {selection['product']} selected for "
|
|
f"{selection['component']} appears on no Element"
|
|
)
|
|
excused = {item.recommendation for item in graph.not_applicable}
|
|
for item in graph.not_applicable:
|
|
if item.recommendation not in recommendation_ids:
|
|
gaps.append(
|
|
f"not_applicable names {item.recommendation}, "
|
|
"which is not a design recommendation"
|
|
)
|
|
for recommendation in recommendations:
|
|
if recommendation["id"] not in sources | excused and not _only_outside_code(
|
|
recommendation
|
|
):
|
|
gaps.append(f"Recommendation {recommendation['id']} has no Check")
|
|
return tuple(gaps)
|
|
|
|
|
|
def _only_outside_code(item: Mapping[str, Any]) -> bool:
|
|
"""Whether a constraint says, explicitly, that nothing it asks for can be shown
|
|
by infrastructure code."""
|
|
return item.get("conditions") == [] and bool(item.get("outside_code"))
|
|
|
|
|
|
# --- the diagram is a view of the graph ----------------------------------------------
|
|
|
|
_UNSAFE = re.compile(r'["\[\]{}()<>|`#;]')
|
|
|
|
|
|
def _label(*parts: str) -> str:
|
|
return "<br/>".join(_UNSAFE.sub(" ", part).strip() for part in parts if part)
|
|
|
|
|
|
def _node_ids(ids: Iterable[str]) -> dict[str, str]:
|
|
"""Mermaid-safe node ids; the graph's own ids may hold characters Mermaid rejects."""
|
|
return {identifier: f"n{index}" for index, identifier in enumerate(ids)}
|
|
|
|
|
|
def render_mermaid(graph: TargetArchitecture) -> str:
|
|
"""The architecture diagram: every Element and Relationship, exactly once."""
|
|
nodes = _node_ids(element.id for element in graph.elements)
|
|
lines = ["flowchart LR"]
|
|
for element in graph.elements:
|
|
lines.append(
|
|
f' {nodes[element.id]}["{_label(element.name, element.product)}"]'
|
|
)
|
|
for relationship in graph.relationships:
|
|
lines.append(
|
|
f" {nodes[relationship.source]} -->|{_label(relationship.kind)}| "
|
|
f"{nodes[relationship.target]}"
|
|
)
|
|
return "\n".join(lines) + "\n"
|
|
|
|
|
|
# --- so are the tables a person reviews ----------------------------------------------
|
|
|
|
|
|
def _cell(text: str | None) -> str:
|
|
return " ".join((text or "").replace("|", "\\|").split())
|
|
|
|
|
|
def _table(
|
|
heading: str, columns: Sequence[str], rows: Iterable[Sequence[str | None]]
|
|
) -> str:
|
|
lines = [
|
|
f"## {heading}",
|
|
"",
|
|
"| " + " | ".join(columns) + " |",
|
|
"|" + "|".join(" --- " for _ in columns) + "|",
|
|
]
|
|
lines += ["| " + " | ".join(_cell(value) for value in row) + " |" for row in rows]
|
|
return "\n".join(lines)
|
|
|
|
|
|
def render_tables(graph: TargetArchitecture) -> str:
|
|
"""The graph as markdown tables: what a person approving the design reads.
|
|
|
|
Written by code, so the tables cannot disagree with the graph and no model spends
|
|
output repeating it.
|
|
"""
|
|
names = {element.id: element.name for element in graph.elements}
|
|
parts = [
|
|
_table(
|
|
"Elements",
|
|
("Id", "Name", "Product", "Resource type", "Component"),
|
|
(
|
|
(e.id, e.name, e.product, e.resource_type, e.component)
|
|
for e in graph.elements
|
|
),
|
|
),
|
|
_table(
|
|
"Relationships",
|
|
("Id", "From", "Kind", "To"),
|
|
(
|
|
(r.id, names[r.source], r.kind, names[r.target])
|
|
for r in graph.relationships
|
|
),
|
|
),
|
|
_table(
|
|
"Checks",
|
|
("Id", "Applies to", "Statement", "Source"),
|
|
((c.id, c.applies_to, c.statement, c.source) for c in graph.checks),
|
|
),
|
|
]
|
|
if graph.not_applicable:
|
|
parts.append(
|
|
_table(
|
|
"Not applicable",
|
|
("Recommendation", "Reason"),
|
|
((n.recommendation, n.reason) for n in graph.not_applicable),
|
|
)
|
|
)
|
|
return "\n\n".join(parts) + "\n"
|