Diagrams

Diagram is a general-purpose document type that uses nodes, connections, and groups to visualize relationships and structures. It can represent workflows, information architecture, system and service architecture, concepts, states, calls, and organizational relationships.

What you can create

Examples include:

• Flowcharts and business processes
• User and service flows
• Information architecture, sitemaps, and navigation
• System, service, and module structures
• Software architecture
• Cloud, infrastructure, and network architecture
• Data architecture and data flow
• Security architecture and trust boundaries
• Organization and role relationships
• Concept maps and mind maps
• Decision structures
• States and transitions
• Class and object relationships
• Call order and sequences
• Users and feature use cases
• Activity and processing flows
• Components and deployment structures
• Other visual explanations of project relationships and structure

The list does not limit the format. If nodes, connections, and groups can express the required information, create the diagram for the project purpose. Database tables, columns, and foreign keys are better managed as an ERD when they need a structured data model.

Before creating one

Define the purpose, audience, subject and scope, required expression, relationships or flows that must be visible, and level of detail. If a notation or convention matters, state it explicitly.

Create with an Agent

Read the source-of-truth document and related materials in [project name], then create a Diagram that explains [purpose].

When form matters, describe what the reader must see.

Show the main domain entities, their attributes, and relationships.

Show the participants and call order from the user request to the returned result.

You can also specify layout, groups, colors, and emphasis.

Building blocks

• Node — entity, step, state, role, system, or concept
• Connection — direction, relationship, call, movement, or dependency
• Group — an area or hierarchy that contains related elements
• Shape — a rectangle, circle, diamond, cylinder, or another visual distinction
• Labels and color — explanations of relationships and importance

An Agent can create, update, and remove nodes, connections, and groups. Apply related changes as one coherent operation when possible, then inspect the resulting structure.

Large diagrams

Use groups to separate areas and link related diagrams when one view becomes too dense. Split detail by purpose and audience instead of forcing everything onto one canvas.

Layout helps understanding but should not be the only carrier of meaning. Use clear names and connections, not position or color alone.

Review

Check the subject and scope, meaning of nodes and connections, direction and labels, project terminology, missing or incorrect relationships, notation consistency, appropriate complexity, and alignment with Markdown and specialized deliverables.

If a formal convention is used, apply it consistently. For a free-form diagram, decide whether a legend or explanation is needed.

Connect it to the project standard

A Diagram helps people understand and review information. Record new decisions or questions in the Markdown source of truth and create executable follow-up work in Kanban.

When you need a structured API contract, continue to OpenAPI Specifications.