1.7 KiB
Diagram-type decision guide
Context
Shows the system of interest, external people/systems, and directional interactions. It deliberately hides internal implementation. Use for onboarding, scope, and ownership discussions.
Architecture / container / component
Shows stable responsibilities and dependencies at exactly one abstraction level. Use “container” for independently deployable/runnable units and “component” for meaningful internal modules only when the prose supports that distinction.
Deployment / network
Shows runtime placement, regions/zones, compute nodes, network/trust boundaries, and deployment mappings. Do not add infrastructure inferred from common practice.
Data flow
Shows sources, transformations, stores, sinks, and sensitive-boundary crossings. Label edges with data, events, or protocols. Separate control flow when it would obscure data movement.
Sequence
Shows one scenario in chronological order. Every edge needs an explicit order. Use separate diagrams for success and materially different failure paths.
Flow
Shows procedural steps and decisions. Decision labels should be questions; outgoing edges should state conditions. Avoid using a flowchart for static architecture.
State
Shows valid states, triggering events, and transition constraints. Nodes are states, not actions.
ERD
Shows entities and cardinality. Do not infer keys or cardinality from naming conventions.
Dependency
Shows structural dependencies where graph topology is the primary message. Use Graphviz-style layout and filter low-value transitive or generated dependencies.
Concept
Explains a mental model, trade-off, or mechanism without claiming implementation topology. Use generic shapes and label it clearly as conceptual.