Communitygithub.com

architecture-diagram

Architecture diagrams as text, in the reader's own words. Blackbox blocks, the interface on every seam with its operations, data types and an example of what crosses it, one state or several compared (as-is, a target, a proposal); text first, then LikeC4 when it is for others. Use when the user asks to draw, diagram or visualise how code or systems fit together, or what a change does to their structure.

What is architecture-diagram?

architecture-diagram is a Claude Code agent skill that architecture diagrams as text, in the reader's own words. Blackbox blocks, the interface on every seam with its operations, data types and an example of what crosses it, one state or several compared (as-is, a target, a proposal); text first, then LikeC4 when it is for others. Use when the user asks to draw, diagram or visualise how code or systems fit together, or what a change does to their structure.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/NG-Bullseye/architecture-diagram-skill/tree/HEAD/skills/architecture-diagram

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

Architecture Diagram

A diagram is understood when what it shows docks onto what the reader already knows. A senior developer reads it for the top-level flow and for the seams. A block is a blackbox: its design pattern, what it is responsible for, who owns it, and its inside hidden. What one block offers another across a seam is its interface: operations with parameter and return types, errors, the data types that cross with their fields, and an example of what exactly crosses and what it looks like. The transport (REST, OPC UA, a process start) is an attribute of an interface and never stands in for it.

Read EXAMPLE.md before drawing: one change, complete, in both forms.

Steps

1. The reader's words

A new term docks onto nothing. Before anything else, collect the words the reader already has: from their messages in this conversation, from the documents they wrote (project instructions, architecture pages, glossaries, nomenclature tables), and from every model the diagram is compared with. Write the word list: the thing, the reader's word for it, the word of each other party who will read the diagram, the name in the code, and the word the diagram uses.

  • Label every block and interface with the reader's word; the code name stands beside it.
  • Where two words clash, or a word is used for the wrong thing, pick one, say why in the word list, and name the other beside it once.
  • Coin nothing. An interface without a name in the code is called by its two ends, Frontend -> Backend.
  • Start from the picture the reader already has, their own diagram with its levels and names, and place what is new into it.

Done when every label on a diagram comes from the word list, and every term that is new to the reader stands in the glossary beside the known word it belongs to.

2. Questions

Write the reader's questions, one line each. They pick the views.

QuestionView
What are the parts, what is each responsible for, who owns it, who calls whom?building block view
Which interface joins two parts, and what exactly crosses it?the interface, its data types and an example on every seam
What happens, in which order, in the scenario that matters?runtime view: one sequence
Where does each part run?host: on every block; a deployment view when networks or trust boundaries are the question
What does a change do, or how do two designs differ?every state in the same form, then the differences

Done when every view has its question and the question stands above it as its caption.

3. Catalogue

Fill four lists from the sources before any drawing.

  • Blocks: the reader's word and the name in the code, stereotype, one sentence of responsibility, owner, host.
  • Interfaces, one per seam: provider, consumers, every operation as a signature name(param: Type) -> Type, errors, transport.
  • Data types: every type a signature names, with its fields, units and defaults.
  • Examples, one per interface: a message as it crosses, call and answer in their real format: a command line with its output, a JSON body, a table row. Take it from a run, a recording, a fixture or the data. An example put together from the code says so in its first line.

Every entry carries its origin: a code reference path:line, or a tag (below). A state someone else drew, a model file or a sketch, is reproduced as it stands and in its own words; what it leaves out is tagged [undefined], and what you add goes into a state of its own.

Done when every block has its sentence, every seam an interface whose signatures are copied from the code or tagged, every type in a signature its fields, every interface its example, and every entry a reference or a tag.

4. Level

The blocks of one state are peers: units that are deployed, owned or replaced on their own, five to nine of them. Files, functions and the steps inside a block are its inside. A zoom is a further diagram one level down, drawn for the one block the question is about.

Done when no block of a state sits inside another one, and every zoom names the question that pays for it.

5. Form

  • Chat form, up to 78 columns: the building block view with the interface's name and its main signature on every edge, then the catalogue as tables and the examples as code blocks. For one state or a small change.
  • Canvas form, a static HTML page of text diagrams as wide as they need: beside every edge its interface in full, the example, and the data types with their fields. For several states, or when more than three seams are shown in full. The page is built by a generator script that sits beside it; the chat answer names the file, says in a few sentences what the comparison shows and lists the open decisions.
  • C4 form, the same model drawn with LikeC4 on a page with a tab per state, boxes to click and to zoom into. The text diagrams are its prototype: settle words, blocks, interfaces and examples there first, then render. For a result other people will open. Read LIKEC4.md.

6. Draw

Draw with the three files in this folder, so that boxes align and no row is wider than its canvas. Each file's docstring is its manual, and running it prints a demo.

FileGives
grid.pyGrid (boxes with compartments, lines, arrows), sequence (a runtime view), table
canvas.pyglance (every state on one line), overview (states side by side, one row per level), panel (one state: blocks, interfaces with examples, data types)
page.pyhtml_page: the page around the diagrams, with the colours and the links between ids
likec4/for the C4 form: template.c4, build.sh, the tab page index.html with tabs.js, and clicktest.py

A page goes from the ten-second picture to the detail: at a glance, the word list, the reading guide, the overview, one panel per state, the differences per seam as a table, the open decisions, glossary, sources.

7. Check

  • Every box is a block of the catalogue, every edge an interface, every type box a data type; an entry left out of a diagram is left out on purpose.
  • Every code reference resolves: the file exists and the line shows the name.
  • The same block stands at the same place in every state. A block a state lacks is a dotted box there.
  • Screenshots of the whole page, read tile by tile: borders meet, nothing is cut, colours carry their meaning.
  • The sources name what was read, at which commit, which examples are real, and what was not read.

States

A state is the code as it is, a target someone drew, or a proposal. Compare states by position: the same block in the same column of glance and the same row of overview, so that the gaps of two states show where they complement each other.

A seam has an id of a letter for its state and a number, (I4). An interface or data type defined at one seam is referred to by that id everywhere else; its fields are written once.

The differences are a table with one row per seam and one column per state. The open decisions are a table: the question, the options, who decides.

Tags and stereotypes

TagMeaning
[code]exists in the code; the reference stands beside it
a source tag, e.g. [c4]stated by a source model; name the tag in the reading guide
[proposed]proposed here, exists nowhere yet
[new] [changed] [moved]what a change does, when there are only as-is and to-be
[undefined]the state leaves it open
[?1]an open decision, listed with its number

Stereotypes name the design pattern a block plays: <<ui>>, <<client>>, <<gateway>>, <<facade>>, <<service>>, <<port>>, <<adapter>>, <<repository>>, <<external>>. Use one where the code plays that role; a block without a stereotype is better than one with a wrong one. A port is an interface the consumer owns and the provider implements: <<port>> stands on the interface, <<adapter>> on the block that implements it. A source model's own kinds are quoted as it writes them.

Devices of explanation

Each of these earns its place by answering something the reader would otherwise have to ask. Use them sparingly.

  • Reading guide: one small diagram that shows how a panel reads, and the tags.
  • Code references: on every interface and data type, so the reader can look it up.
  • Short texts: one paragraph above a state that says the one thing to see in it; a note inside an interface box where the reader would ask why.
  • Glossary: the terms the word list does not cover, one line each.
  • Colour: only for the tags, the ids, and one or two key names that stay the same across all states. Colour marks what states share and where they differ; nothing else is coloured.

Prose is in the language of the conversation. Names from code and from source models are verbatim.

Related Skills