#241 Enterprise architecture and AI agents 5.8 min
C4 Diagrams for AI Systems, Written and Checked as Code
A diagram can hide a shortcut your own rules do not allow. Check the model before you draw it.
Find the four planted problems
Copy the code folder first. Open model.py and look for the four mistakes before you run anything: a missing description, a missing label, a link to something that does not exist, and a route to an external system that skips the gateway. Write down the line of each, then run python compare.py and check your list against the four problems it prints.
A hint
Look at the model server, and at the two relationships that start at agent.
Remove a technology
In model.py, change the Gateway container's technology from "FastAPI" to an empty string "". Predict the new problem line, then run python compare.py. When I ran it the problem count went from 4 to 5, with the new line container Gateway has no technology, and after the repairs it stayed at 1 problem. Then change the technology back to "FastAPI" before the next task.
A hint
The repairs in compare.py fix only the model server and the two agent relationships.
Add a second shortcut
In model.py, add the relationship ("web", "orders", "Reads orders directly", "REST") to the end of RELATIONS. Predict the problem count and the line count of the diagram text, then run python compare.py. When I ran it there were 10 relationships and 5 problems, and the new line said web -> orders reaches an external system without the gateway, and the diagram text had 18 lines. Then remove the added relationship before the next task.
A hint
The rule reports any link to an external system whose start is not the gateway.
Add an unconnected element
In model.py, add a container to ELEMENTS: ("container", "cache", "Cache", "Redis", "Keeps recent answers"). Do not add any relationship for it. Predict the problem it causes, then run python compare.py. When I ran it there were 9 elements and 5 problems, and the new line said Cache is not connected to anything.
A hint
One of the checks looks for elements that no relationship touches.
These tasks are for you to try on your own machine. Nothing is checked or saved.
What this does not show
A toy model at one C4 level with four planted mistakes; the Mermaid text is not rendered in the video; Structurizr and LikeC4 were not run; the script prints problems and exits 0, so it needs a non-zero exit before it can fail a build; the gateway rule is mine, not C4; a checked model can still differ from the real system.
Up next in Enterprise architecture and AI agents
More in Enterprise architecture and AI agents
- #229 A Reference Architecture for Enterprise AI Agents, as Code
- #230 Agent Gateway: One Front Door for Models, Tools, Agents
- #231 MCP Gateway: Per-Tool Policy for Agent Tools (Python)
- #232 Give Every AI Agent Its Own Identity
- #233 Delegated Authority: Let an AI Agent Act for a User, Safely
- #234 Authorisation for AI Agents With Policy as Code (Cedar)
Related videos
- #229 A Reference Architecture for Enterprise AI Agents, as Code Enterprise architecture and AI agents
- #242 Architecture Decision Records for AI Choices, With a Lint Enterprise architecture and AI agents
- #248 TOGAF and ArchiMate: Where an AI Agent Fits, as Code Enterprise architecture and AI agents
- #230 Agent Gateway: One Front Door for Models, Tools, Agents Enterprise architecture and AI agents
