Engineering Notes
Short, focused notes on the systems I build and maintain. Each one captures a design decision, the reasoning behind it, and the rules that survived contact with production.
An API is a promise to every client that will ever call it, and clients outlive engineers. The design work is deciding the shape of that promise, and making the shape so boring tha
Read the noteAuth is the one subsystem where a quiet mistake is expensive: it fails at 2 a.m., at scale, in a way that violates user trust and looks indistinguishable from a feature bug. The de
Read the noteCaching is the only correctness problem that's also a performance feature. The systems that do it safely treat cache invalidation not as a tactic but as two explicit rules, written
Read the noteA CLI has no dashboard to hide behind. Every decision is visible in the first five seconds a user spends with it: the help output, the error message, the exit code. Those five seco
Read the noteConfiguration is the part every user touches and the last thing they understand. The design principle that survived every change: configuration is a *decision process*, not a data
Read the noteFlutter's strength on desktop is the same thing that makes it dangerous: one codebase for every platform. The discipline that makes it work is deciding, up front, where the codebas
Read the noteObservability is not a dashboard. It's the ability to answer questions about a running system you didn't know you'd need to ask, and to answer them from production data, not from i
Read the noteThe test pyramid is usually drawn as a diagram and skipped as a policy. The point isn't the shape of the pyramid; it's the *cost structure*. Unit tests are cheap and instant, integ
Read the note