Real-World Use Cases

Who: Engineering leads or senior developers preparing for a new team member's first week. When: Before the new hire starts, or during their first day. Why: New engineers routinely cite "understanding the system architecture" as their biggest challenge during onboarding. A high-level architecture diagram that shows service boundaries, data stores, and communication patterns reduces the time-to-productivity from weeks to days.

The goal is not to document every detail, but to provide a mental map that the new hire can reference as they explore the codebase. Focus on the services they will interact with most frequently, the databases they will query, and the key integrations with external systems.

Who: The engineer proposing a new feature or system change, presenting to the team during a design review. When: Before implementation begins, typically as part of an RFC or ADR (Architecture Decision Record) document. Why: Words alone are ambiguous when describing system interactions. A sequence diagram attached to a design document makes the proposed behavior explicit, reducing the number of "what about this edge case?" questions during the review.

The diagram should illustrate the proposed change in context, showing how new components interact with existing ones. Include the happy path and at least one error path to demonstrate you have considered failure scenarios.

Who: The incident commander or on-call engineer writing the post-mortem report after a production incident. When: Within 48 hours of an incident, as part of the blameless post-mortem process. Why: A timeline diagram makes the sequence of events unambiguous. It shows exactly when each system failed, when alerts fired, and when remediation steps were taken. This clarity is essential for identifying the root cause and preventing recurrence.

Who: The engineering manager, scrum master, or tech lead facilitating the sprint planning ceremony. When: At the start of each sprint, after stories have been estimated and prioritized. Why: A Gantt chart makes task dependencies and parallel workstreams visible at a glance. It helps the team identify bottlenecks before the sprint starts, balance work across team members, and communicate the plan to stakeholders who want to know when specific features will be ready for testing.

Who: Backend engineers or technical writers creating API documentation for internal or external consumers. When: When publishing a new API version, or when onboarding partners who will integrate with your API. Why: API consumers need to understand the order of calls, required headers, and expected responses. A sequence diagram in the API docs is far more effective than a wall of curl examples because it shows the full interaction flow including authentication, pagination, and error handling.

Who: Security engineers, AppSec team members, or senior developers conducting threat modeling during the design phase of a new feature. When: During the design review, before code is written, or during a periodic security assessment. Why: Threat models identify attack surfaces and potential vulnerabilities before they reach production. A visual threat model makes it easy to communicate risks to non-security stakeholders and creates a traceable artifact for compliance audits (SOC 2, ISO 27001, PCI DSS).

The diagram should show data flows, trust boundaries, and identified threats mapped to specific components. Pair it with a STRIDE analysis table for a complete threat model document.