Guide
Technical diagrams, typed
A technical diagram is not decoration — it's a claim about how a system works, drawn precisely enough to be wrong. That precision is the point: pick the diagram type that answers your reader's actual question, and define it in a form that a machine can check.
Which diagram answers which question
| Diagram | The question it answers |
|---|---|
| Architecture diagrams | What is the system made of, and what does it talk to? |
| C4 diagrams | The same system at four zoom levels, one per audience |
| Sequence diagrams | What calls what, in what order, and what can fail? |
| ER diagrams | What are the entities, and how do they relate? |
| State machines | Which states exist, and what triggers each transition? |
| Data-flow diagrams | Where does data enter, get processed, and get stored? |
| Swimlanes & user journeys | Who is responsible for each step of the process? |
| Gantt charts & timelines | What happens when, and what blocks what? |
All of these — 25+ diagram types among Every typed block — shares one YAML grammar in Chiltepin, so learning one is learning them all. Every type renders live in the block catalog.
Technical diagram software: canvas vs. code
Canvas tools (draw.io, Lucidchart, Excalidraw) are unbeatable for whiteboard-day sketches, and that's where their output should stay. Diagrams that live in engineering documentation have different requirements: they need review, versioning, and a way to detect staleness. Text-based formats give you all three — and typed, schema-validated blocks go one step further than free-form DSLs like Mermaid, because chiltepin check can prove a diagram structurally correct and fail CI when it isn't. The full comparison is on the Mermaid alternative page.
Written by your agent, checked like code
Typed diagrams are also what make AI generation trustworthy: your agent writes the block, the schema validates it, you review a diff. That workflow — and why it beats image generation — is covered on the AI diagram generator page; the philosophy behind keeping diagrams in the repository is the docs-as-code guide.
Frequently asked questions
- What is a technical diagram?
- A technical diagram is a precise visual representation of how a system is structured or behaves — architecture diagrams, sequence diagrams, ER diagrams, state machines, data-flow diagrams. Unlike an illustration, a technical diagram has semantics: boxes and arrows mean specific things, which is also what makes it possible to validate one.
- Which technical diagram should I use?
- Match the diagram to the question. Structure: an architecture or C4 diagram. Behavior over time: a sequence diagram. Data shape: an ER diagram. Lifecycle: a state machine. Movement of data: a data-flow diagram. Responsibility across teams: a swimlane. Schedule: a Gantt. A diagram that tries to answer two questions usually answers neither.
- What software is best for technical diagrams?
- Canvas tools (draw.io, Lucidchart, Excalidraw) are best for one-off sketches. For diagrams that live in engineering documentation, text-based tools win: Mermaid renders DSL strings, and Chiltepin goes further by typing each diagram as schema-validated YAML in Markdown — so CI can verify diagrams, git can diff them, and an AI agent can write them reliably.
- How do teams keep technical diagrams up to date?
- The only approach that survives contact with deadlines is making the diagram part of the code change: diagram source lives in the repository, changes in the same pull request as the system change, and a CI check fails when it is invalid. If updating the diagram requires opening a separate tool, it will not happen.