Jacob Barrieault

Sequence Diagrams

jacob.barrieault@gmail.com (Jacob Barrieault) — Sun, 20 Sep 2026 00:00:00 +0000

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.

I don’t know about you, but I’m reading more words per day than I ever have, exclusively thanks to LLMs. ↩︎

Why now?

jacob.barrieault@gmail.com (Jacob Barrieault) — Mon, 07 Sep 2026 00:00:00 +0000

Here I am, a dozen years deep into my career in software, and I’ve decided to start a blog.

But why? Why start a software engineering blog in 2026?

The truth is, I’m asking myself that question too.

I feel internally compelled to, without having the ability to fully articulate all my motivations. This being the inaugural post of the blog, I’m going to reflect and process what I can sense.

Reflection has led me to multiple factors converging at once:

1. Stage of Life

Simply put, I’m in a season of life with margin to spend time and energy writing.

My kids have gotten older and more self-sufficient, which is freeing up a non-trivial amount of my time. No more sleepless nights, feeding them each bite by hand, changing diapers, dressing them, keeping a constant eye on them, etc. Now they sleep like rocks, pour their own cereal, use toilets, play together, and put on their own shoes! Don’t get me wrong, our household has a busy schedule! Besides school the kids are in soccer, basketball, ballet, swimming, summer camps–the works. My wife and I also tend to maximize family time on the weekends (the ability to do that is an incredible luxury I often take for granted).

Although our household schedule is not wanting, it’s generally structured, making free time predictable. I love predictable schedules. They’re fertile ground for designing consistent habits that create rewarding results over time.

2. Stage of Career

This is going to sound like gloating, and I hope it can be read more charitably, but here it goes:

I have achieved an aspirational level of success in my software career, and I believe there are people who would benefit from my thoughts and experience.

Blogging is a pretty common practice among developers of all experience levels, and I do believe you can deliver value in a blog even as a junior level engineer. But a harsh reality is that a lot of these blogs are trash. This was true even before AI-generated slop cannons began to fire.

My old boss, Scott Meves, once said:

There are millions of bad software developers out there, and they all have blogs!

After more than a dozen years of dedication to the craft, I’ve gathered enough hubris to believe my skill, knowledge, and experience are worth sharing.

3. Moment in History

In November of 2025 Anthropic released Opus 4.5. I had previously tried Claude Code and enjoyed it, but its quality and overall ability to accomplish non-trivial tasks were limited. That December, I tried Opus 4.5 with Claude Code and it felt different. This combination of model and harness was a clear inflection point in the history of software. It’s been a hell of a ride since then and it’s a truly exciting time to be in software.

At the risk of overly aggrandizing this change in the technology landscape, and the position of experienced developers like myself:

Experienced engineers who understand the fundamentals of software and computing, and have experience building and maintaining systems pre-Opus 4.5, should share their perspective as we all discover the possibilities that lie ahead.

4. Personal Artifacts

Another motivation for blogging is that 99% of my work is committed in repositories. I’m proud of the things I’ve built (some Planning Center features I’ve made are used by millions of people), but they aren’t mine. Only paying customers can see the end results, and only co-workers can see the code (…sometimes I’m grateful for that 😄).

Writing is a way I can share my work with the world.

5. Personal Growth

Lastly, I want to get better at writing. I believe the skill of writing will become more (not less) important in the Agentic AI era (or whatever we’re calling it). My own personal growth and trajectory towards excellence is an intrinsic motivation as well. And the only way I’m going to get better at writing is by doing it consistently.

So here we go.