Architect Craft: Diagrams and the ADR Index
Explore how to build and use system context, container, data-flow, and trust-boundary diagrams alongside architecture decision records (ADRs) to make AI platform decisions auditable and repeatable. Understand the role of these artifacts in security reviews, incident investigations, and design governance to ensure clear ownership, traceable controls, and compliance with enterprise requirements.
Diagrams and architecture decision records (ADRs) are the mechanism that makes control placement and decision trade-offs auditable and repeatable across teams. The platform reference architecture and golden paths become reviewable once a minimal, consistent diagram set shows a boundary and a flow, and an ADR index ties every consequential decision to evidence and to the controls that must hold during an audit or an incident investigation.
The minimum diagram set and what each must prove
Build four diagrams for an enterprise GenAI and agent platform, each answering a different review question.
The system context diagram proves scope and accountability. Name the human and system actors, the external dependencies, and the interaction surface where policy must get enforced. Also state what’s out of scope, so a review doesn’t drift into a deferred area like model training from scratch or platform administration details.
The container diagram proves a responsibility boundary. Show the major runtime components and the seams where ownership, change control, and operational on-call rotate. This is where the reference architecture and golden paths become concrete: express the application, the AI gateway, the retrieval service, the model access layer, and the tool integration boundary as separate containers, so security and operations can assign an owner and reason about failure isolation.
The data-flow diagram proves where sensitive data moves and what transformation occurs. It is the artifact that links most directly to the threat model, the evaluation spec, and the observability plan, without re-teaching them. The threat model needs the data-flow to locate a control point. The evaluation spec needs it to define where a citation, a provenance claim, and a policy outcome can get tested. The observability plan needs it to define a trace boundary and what must get logged or redacted at every hop.
The trust-boundary view proves where a control must exist and what ...