learning-it by example

#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.

1. What is the advantage of keeping a C4 architecture model as text or data instead of drawing it by hand?
2. How many elements, relationships and problems did the check find in the AI shop assistant model, and how many problems after the repairs?
3. Which of the checks in the C4-model-as-code script is the author's own rule and not part of C4?
4. In the C4 example, which relationship was reported as reaching an external system without the gateway?
5. In the Python C4-model-as-code example, what can a checked model still get wrong, and was the Mermaid text rendered?

Practice only: nothing is saved and no score counts towards anything. Each answer comes with the reason.

  1. 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.

  2. 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.

  3. 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.

  4. 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

All Enterprise architecture and AI agents videos

Related videos