Architecture on Jesse Builds Software

Disambiguating Scalability

Fri, 09 May 2025 19:33:22 -0700

Although it was years ago, I still remember the conversation vividly. I was having my regular check-in with the CTO. It was also sunny outside, and the view from his office was particularly nice that day.

He asked me, “Is our app scalable?” After a moment of thought, I answered, “Yes.”

I spent the next few years remembering that conversation, wondering what would have happened if I had asked what he meant by scalable.

Architectural Decision: Using Obsidian For Work Notes - 2025-01

Sun, 02 Mar 2025 13:59:08 -0800

I have been feeling frustrated with my personal organization of late. I had a bit of time before starting a new project, so I put some time into improving my process. The post below is a simplified version of the notes I took while I looked for alternatives. I’m sharing this as an example of how I do research, and as a more realistic example of the architectural report structure I typically use, which I’ve written about before.

Case of the Premature Power Outage

Mon, 03 Feb 2025 19:40:52 -0800

Many years ago I worked on a large system with a number of interconnected services that had grown organically over the years. As new services were added, they became dependent on each other in ways that nobody on the team fully understood. When our hosting provider announced a planned outage, we had to figure out how to safely shut the system off, and more importantly, how to safely and quickly start it back up again afterward. We had never done either of these things before, so we put a lot of effort in to make sure it would go smoothly.

The Pragmatic Potato Tech Stack

Mon, 24 Jun 2024 12:02:43 -0700

I recently launched my new company, Pragmatic Potato Software Inc. The creation of a company itself is pretty easy, but setting up everything you need to do business can become overwhelming quickly. There are a lot of compelling options available, each promising the moon. It’s not that simple though.

I’m going to be writing about the technology stack I’m using to run my company, and why I made the choices I did. There is a lot more to a company than its technology, but I’m not an expert in setting those up.

Cross-Cutting Concerns - Ten Approaches

Mon, 27 May 2024 13:18:08 -0700

One often (and ironically) repeated rule in programming is: don’t repeat yourself. We repeat it so much we even have an abbreviation: DRY. There are good reasons for this advice. Duplicating and modifying code can be a quick and easy way to get a feature done, but it can also lead to problems over time. It’s harder to understand code when the valuable logic is mixed with reams of low-value boilerplate. Subtle differences can also sneak in, leading to inconsistent behaviour across the application. Things get even more difficult if you want to make a change.

The True Cost of Dependencies

Wed, 27 Mar 2024 15:35:10 -0700

I used to use Getform for a contact form on my consulting company website. I recently received an email from them announcing that their free tier was dropping from 50 submissions per month to a lifetime limit of 25. This makes it useless for anything more than a trial, and their lowest tier is a more expensive than other similar options.

I’m not here to complain about companies taking back free offerings. I don’t like the change, and I wish they’d given me more than three days of notice, but they are a businesses, and businesses need to make money. It is a good reminder though: even if something is free to use, it still takes time and effort to integrate, to maintain, and you may occasionally need to throw it out and find a replacement.

Using Architectural Decision Records

Tue, 21 Nov 2023 17:51:51 -0800

Architectural Decision Records are a simple technique that promotes good architectural thinking and better collaboration. They don’t need to be big or complicated to be effective, but they do take some time, and are yet another step between setting goals and delivering value. If you use them in the right circumstances they can be a big help.

What is an Architectural Decision Record?

An Architectural Decision Record (often abbreviated ADR) is just as the name implies: a document that describes an architectural decision. It can include various details, but should at a minimum describe the problem being solved and the solution that was chosen. It can be a simple text document with a page or two of text, or it can be longer with specific sections that are important to the team.

This Blog: Hexo-generated static site hosted on GitHub Pages

Wed, 01 Nov 2023 10:34:32 -0700

A couple of years ago I switched this blog from a WordPress site hosted on GoDaddy to a statically generated site. The new setup is faster, more secure, and cheaper to operate. And it was easy to do!

Static vs Dynamic websites

WordPress is a very popular blogging platform. You can use it hosted on WordPress.com, or any number of other web providers that offer it. Because it’s open source, you can also host it yourself easily. In my case, I had a virtual server running in GoDaddy where I maintained the installation myself.

Regarding Test Coverage Targets

Mon, 21 Aug 2023 11:28:52 -0700

Unit tests are undeniably a good thing, but you only realize the full benefits of them when you have enough tests that you can make changes with confidence. If you can make a change, run your tests, and be comfortable enough to ship your changes, then you and your team can get work done much faster. More drastic changes to the shared code become feasible. Life gets better.

It makes sense then that teams want to ensure that code is sufficiently covered with tests. Nobody wants to count tests every time they review a PR, so tools are added that check it automatically. It’s then a small step to set a coverage target, and suddenly you have a machine checking every PR for tests. This all makes sense to me, and it was my first instinct too. I don’t recommend this approach any more.

My Architectural Report Template

Tue, 08 Aug 2023 12:45:13 -0700

As an architect I’ve been asked to answer a lot of hard questions. I used to waste time figuring out how to structure my answers, preventing me from getting into a good flow sooner. Now I have a simple template that is easy to use, easy to read, and saves me that wasted time up front.

This template works for simple reports that are only a couple of pages, but can easily be adjusted or expanded for more complicated or much larger documents.

Horizontal One-on-Ones and Talking Practice

Tue, 18 Jul 2023 15:35:11 -0700

When I was promoted to the role of architect it was a new role in the organization. The stakeholders I had to work with were not used to talking to an architect, and weren’t sure what I did or when I should be involved in a conversation. I started using recurring one-on-one meetings with each stakeholder separately. It worked great. It’s also made me a much better communicator.

One of the first and most important lessons I learned as an architect is that you can’t design a good architecture without a good understanding of its requirements. You can design a system in a vacuum, it’s also much easier to do it this way, but it’s far less likely to serve the organization. Gathering, validating, and documenting technical requirements is tough work, but an essential part of being an architect.