Sequence Diagrams

You should know and love sequence diagrams in the Year of Our Lord 2026.

Thinking in Systems

The journey to becoming a Staff+ Engineer is marked as much by a growth in Systems Thinking as it is the development of deep technical skills and leadership sense.

Systems thinking is the ability to take a step back out of the weeds, to a higher plateau. An elevated vantage point gives you the perspective needed to make higher impact decisions that affect entire teams and streams of work.

To think in systems, you need to see in systems. Sometimes that’s really hard.

It’s incredible that you can now summon legions of agents to investigate and summarize on your behalf, but you must still read and understand mountains of LLM output¹ that come back to you. I believe reading is an increasingly essential discipline in software development. I recommend you learn to love it.

But sometimes, reading is inefficient.

After all,

A picture is worth a thousand tokens

Seeing in Systems

Sequence diagrams are that picture.

They are a visual representation of the interactions made within a system.

I was formally introduced to sequence diagrams by the venerable Sandi Metz, and they’ve been an indispensable tool in my engineering toolbox ever since.

Here’s a simple example for the uninitiated:

sequenceDiagram
    Client->>API Gateway: Request
    API Gateway->>Target: Proxy request
    Target-->>API Gateway: Response
    API Gateway-->>Client: Response

They can also represent control-flow and concurrency, and you can write them in markdown using Mermaid.

Here is a more complex one:

sequenceDiagram
    autonumber
    participant C as Client
    participant GW as AgentCore Gateway
    participant ID as AgentCore Identity
    participant V as Token Vault
    participant IdP as OAuth Provider
    participant T as Target MCP Server

    C->>GW: POST /mcp tools/call<br/>Authorization: Bearer inbound JWT
    GW->>GW: Validate JWT against discovery URL<br/>(signature, aud/client_id, scopes)
    Note over GW: Gateway looks up the target's<br/>credentialProviderConfigurations<br/>(OAUTH, CLIENT_CREDENTIALS)

    GW->>ID: GetWorkloadAccessToken
    ID-->>GW: Workload access token (gateway's own identity)

    GW->>ID: GetResourceOauth2Token<br/>(provider, scopes, M2M, workload token)
    ID->>V: Look up cached token for provider + scopes
    alt Cached token still valid
        V-->>ID: Access token
    else Cache miss or expired
        V-->>ID: Miss (client secret read from Secrets Manager)
        ID->>IdP: POST /token (client_credentials)
        IdP-->>ID: Access token
        ID->>V: Store token
    end
    ID-->>GW: Outbound access token

    GW->>T: tools/call<br/>Authorization: Bearer outbound token
    T-->>GW: Tool result
    GW-->>C: Tool result

Follow that diagram until you grasp the system it is describing.

Now imagine how many words you would need to read to gain the level of understanding equivalent to what you just got from that diagram. Thousands. Perhaps tens of thousands.

With a well-drawn sequence diagram, imagine how much faster you could discover that Galactus, the all-knowing user service provider aggregator, doesn’t have knowledge of past user info providers!

The examples I showed are at a component level, but you can zoom in or out as far as you’d like. From company department processes down to the syscalls made by a single function.

A Beautiful Twist of Fate

Agents are actually quite good at generating sequence diagrams (Claude Code w/Sonnet 5 generated both the above). Use this to your advantage!

Have them show you the way the things are, and the way they could be.

See the system, understand it, refine it, and build it.