Hey friends 👋 Welcome to the first newsletter issue of December 2024. Coincidentally, this will also be the last issue of December 2024, because the entire Frontend at Scale team is taking a break until the new year.

The team has a ton of reading to catch up on and many neglected side-projects that need the team's attention. Also, the team's wife has a massive list of things the team needs to do around the house during the Holiday break, and the team doesn't want to get in trouble.

I wish you a fantastic Holiday season and a great start to the New Year, and I hope to continue seeing you around in 2025. I have some very exciting things planned for Frontend at Scale next year, and I can't wait to tell you all about them.

Today we'll talk about one of the most useful tools in the software architect's toolkit, how React may or may not be a legacy technology, and my upcoming proposal for replacing JSON with Morse code.

Let's dive in.

SOFTWARE DESIGN

Your Architecture's Journal

If you think about it, software architecture is nothing more than never-ending decision-making:

Which JavaScript framework should we use? Should we use microservices or a monolith? Should we use a monorepo? SQL or NoSQL? Should I take a shower today? Should I eat something healthy for dinner tonight or is it pizza for the sixth night in a row?

Ok, some non-architectural decisions may have slipped into that list, but I think you get my point.

Now, the thing is, making a decision is only one part of the equation. The other part is articulating why we made the decision in the first place and documenting it so it can be referenced in the future.

Luckily for us, there’s a tool for that, and it’s as easy as A-B-C, or… should I say, A-D-R.

A Brief Intro to ADRs

Architectural Decision Records, or ADRs, are short documents that describe architecturally significant decisions and their consequences. If you’re wondering what I mean exactly by “architecturally significant”, hang with me for a minute. We’ll come back to that soon.

There’s a lot of great advice out there for how to write ADRs, but to me, the key to writing a good ADR boils down to two characteristics.

The first one is that an ADR should describe not just what the decision is, but also why it was made. Decision records will be referenced a lot in the future, so the context that you provide in them will be key to understanding the reason behind a particular decision years from now.

The second characteristic of a good ADR—and this is one that’s very often overlooked—is that they should be as short and concise as possible. Chances are that you’ve done a ton of research before making the decision, and you might be tempted to include it all in your document. But ADRs are only useful if people actually read them, and the longer your document is, the lower its chances of being read.

Michael Nygard wrote a seminal article about ADRs in the agile era, which has resonated with a lot of people, particularly because of his emphasis on keeping ADRs brief. “Nobody ever reads large documents,” Michael says—and he’s certainly not wrong.

To help us keep our ADRs short, Michael suggests using a simple template consisting of only five sections:

1. Title: A summary of what the decision is, typically including some sort of numeric ID as well. For example: “ADR-001: Using Morse code to communicate between micro-frontends.” (Hey, I never said the decisions had to be good.)
2. Status: In review, accepted, rejected, deprecated, etc.
3. Context: What is the issue or situation that is forcing you to make this decision? Include any information that could be useful to better understand why the decision had to be made.
4. Decision: What the decision is. E.g., “We will use Morse code to communicate across micro-frontends because it’s a performant and widely supported protocol that has been battle-tested for over 200 years.”
5. Consequences: What will happen as a result of making this decision? Since architecture is all about tradeoffs, there is a big chance that you’ll have both positive and negative consequences to talk about.

If you’d like to see an example of an ADR using this template, here's the one we covered in the Fundamentals course.

Over time, your collection of ADRs will form an architectural decision log, which you can think of as your architecture’s personal journal.

In fact, reading a decision long is very much like reading an actual journal—it’ll give you an insight into the decisions that made your architecture what it is today, and it’ll answer the question “What the heck were they thinking about?” whenever you find about an unconventional decision in your codebase. You know, like that time you discovered that your micro-frontends were talking to each other in morse code.

Understanding why a decision was made is the only way to know whether it’s worth re-evaluating it. Otherwise, your options would be to blindly accept the decision or blindly try to change it, and these are both equally risky calls to make.

Is This Architectural Enough For You?

ADRs are not exactly a shiny new tool. They’ve been around for a long time and many tech companies have adopted them in some shape or form over the last few years. But even if you’ve been using ADRs for a while, it can still be hard to determine whether a decision is “architectural enough” to justify its own decision record.

We talked earlier about how ADRs are reserved for architecturally significant decisions, which Michael Nygard describes as “those that affect the structure, non-functional characteristics, dependencies, interfaces, or construction techniques.” This is a useful description, but if I’m being completely honest, it’s a bit too abstract for my monkey brain to understand.

So what I like to do instead to determine if a decision is architecturally significant or not, is finding where it fits in the Architecture <-> Design spectrum.

​

Every decision we make when building software fits on this spectrum. On the Architecture side, we have decisions that are more about the structure of the system, while on the Design side, we have decisions that are more about the code.

To find where a particular decision falls in the spectrum, it helps to analyze it through a few different lenses:

• How hard or how easy is it to change? The harder it is to change, the more architectural in nature a decision is. Sometimes, a decision might be absolutely irreversible, which puts it a the very end of the spectrum on the architecture side.
• How strategic or tactical is it? Architectural decisions tend to have longer-term implications and involve larger groups of people, requiring us to think more strategically about them.
• How high or low level it is? Architectural decisions are higher level because they require more context and more information about how the decision will impact other projects and codebases.

Choosing a framework or database technology, for example, clearly falls on the architecture end of the spectrum because it pretty much checks all of our boxes—it's a decision that is hard to change, has long-term implications, and can potentially involve multiple teams and projects.

On the other hand, deciding how to name a function or whether to use the Factory design pattern for a feature in your building falls closer to the design end of the spectrum.

The closer a decision falls to the architecture end of the spectrum, the more seriously we should consider its consequences and the more important it is that we document it with an ADR. And if you’re not entirely sure, evaluate the decision through each lens individually, and then see where it fits “overall.” I know that might not make a lot of sense, so check out this video from the Fundamentals course to see an example.

It helps to think of an ADR as a long-term investment and even as an act of kindness for future maintainers of the codebase. Put yourself in the shoes of someone dealing with the consequences of your decisions 2 or 3 years from now. This person might not like you very much (especially if you actually decided to use Morse code as a communication protocol), but they will like you a lot better if you took the time to document your thinking with an ADR.

ARCHITECTURE SNACKS

Links Worth Checking Out

1. Addy Osmani gave a great talk about the AI-Assisted Developer Workflow. Addy has been doing a ton of research on how AI agents can help us be more productive, and he put it all together in his presentation at JS Nation last month. If you've been looking to catch up on the coolest AI coding tools these days, give this one a watch.
2. Legendary software architect Grady Booch was on the latest episode of The Pragmatic Engineer podcast, talking with Gergely about everything from how we invented UML and its impact on software engineering, to the future of LLMs and how it feels to hold the very cool title of "Chief Scientist." Grady is truly a living legend (with an emphasis on living, as he would say) and a great speaker, and it's always a pleasure to learn about the history of our industry from someone who was there while it was being made.
3. Alex Rusell wrote an article titled "If not React, then what?", answering the question he's always asked when he tells people they should stop using React for new development. According to Alex, frameworks like React and Angular should be considered legacy technology and we'd be doing all Internet users a favor by steering away from them. Even if you don't agree with his premise (I personally don't), Alex does have some very compelling points, so I'd recommend giving his article a read.
4. Speaking of React, version 19 was finally made stable this week (so I guess it's not that legacy, huh?), complete with all new hooks, new APIs, and everyone's favorite new feature: refs as a prop. Astro 5.0 and Vite 6.0 were also released over the past couple of weeks, and I like to think that they all got together and threw a massive party to celebrate the major releases. My invitation probably got lost in the mail, btw.
5. Spotify Wrapped felt a bit underwhelming this year? Worry not. CSS Wrapped 2024 is out now, highlighting 17 new and super cool features that were added to the web platform this year.
6. Abenezer Belachew wrote about Hyrum's Law in Golang. Hyrum's Law is more of a universal truth of programming, though, so I'd recommend checking it out even if you have no interest in learning Go.
7. One of my favorite principles from the book A Philosophy of Software Design is Define Errors Out of Existence, which is a much cooler way to say, "avoid throwing exceptions everywhere." Alex Kondow wrote a great article explaining how we can apply this principle in JavaScript.
8. Yes, it is possible to write modern JavaScript without a bundler like Vite or Webpack, and Corbin Crutchley tells us how in his latest article.

That’s all for today, friends! Thank you for making it all the way to the end. If you enjoyed the newsletter, it would mean the world to me if you’d share it with your friends and coworkers. (And if you didn't enjoy it, why not share it with an enemy?)

Did someone forward this to you? First of all, tell them how awesome they are, and then consider subscribing to the newsletter to get the next issue right in your inbox.

I read and reply to all of your comments. Feel free to reach out on Twitter, LinkedIn, or reply to this email directly with any feedback or questions.

Have a great week 👋

– Maxi