Software Architecture Guide (2019) | Hacker News Reader

Software Architecture Guide (2019)

martinfowler.com

95 pointslaxmena38 comments

The problem is that bad architecture can be carried forward for a very long time at increasing cost.

The ability to differentiate good and bad architectures seems to be a lost art because to build this ability you need to have enough experience (e.g. the discussion in "The Mythical Man-Month"). Most software developers today have had no experience designing even a single system and many systems are often a random assortment of stuff thrown together by people without enough experience. What I call the "sort of works" architecture. It has big gaps but it sort of works and so there is continuous investment in trying to make it good, which is often a waste of time. You've lumped a bunch of stuff together to build something and now you're stuck with it.

AI as it is right now is probably a driver to make this worse because it makes it so much easier to throw random stuff together.

So what would be a good architecture? How would I recognize it if I stumbled against it?

My own inclinations here are that it would be good to have as few different technologies as possible. To run things on as few different machines as possible and to have automated tests for everything. The thing is that as soon as there are multiple technologies you get to have different people specializing in them and it is always the communications between those that becomes painful. The automated tests are there to prevent fear of change setting in. I think I am kind of advocating what is called a 'big ball of mud' but that I want it to be a transparent ball of mud because of automated testing. I guess what I am saying is that I distrust most developments in so-called application architecture of the last few decades except automated tests. In particular, I think frameworks and microservices are mostly just bad.

In an existing system some combination of these attributes:

- High quality (e.g. low number of issues hit by customers, resilient to failures, efficient, secure etc.)

- Easy to maintain (well organized, broken down in a sensible way into components or layers)

- Easy to extend/adapt to future requirements (i.e. the designer was able to anticipate the likely direction of the system and account for that in the design)

Automated testing feels a bit orthogonal to me but a system that is easy to test is likely one with a better architecture. It's not strictly part of what I'd call architecture.

Less different technologies - YES!

Runs on fewer machines is a sign of an efficient/performant design. Less well designed systems exhibit bloat that is often made up for by running on more machines.

We sometimes point to ISO25010 [0] if management or not so experienced devs are asking. It contains a good deal of the relevant "qualities" you keep an eye on for quality.

[0] https://iso25000.com/index.php/en/iso-25000-standards/iso-25...

That looks like a whole lot of dimensions to measure without providing any clear way of actually doing so. Which I guess is the point? But what do management or less experienced devs actually do with the information in the standard after they’ve read it?

You put all as cards on the table and have management pick their top three or five and their order. Can be extended to a full day workshop with your stakeholders, if useful. It gives you a relatively complete taxonomy and you can speak about it with the same vocabulary which is a benefit on its own also.

Hopefully, they ask more experienced devs "what do we do to accomplish this" and hopefully the devs on their team actually are experienced enough to have good answers

I've been doing this stuff for about 15 years now. Longer than many, not as long as some.

In my opinion, good architecture should be easy to extend, easy to scale (up and down), easy to reproduce. Microservice architectures are easy to scale, but usually hard to reproduce (any amount of config per service adds up a lot) and can be very hard to extend too (any changes to one service might ripple to many others, with knock-on effects)

One of my biggest red flags for a bad architecture is if you cannot easily create a (preferably localhost) development environment for it. I think this is where a lot of microservice based projects stumble. It leads to a lot of brittleness and a very siloed development team in my experience. Replacing what should be a library call or DB query with a network request to another service (which then has to query the DB for you) is a certain kind of lunacy.

Frameworks that are very opinionated are also very bad in my opinion. Depending how strict they are if you're doing anything even remotely unexpected you will butt up against the limitations of the framework often. That's annoying to me, I prefer to build my own stuff.

Good architecture reduces cost, while still achieving business goals.

(E.g. If you have problems hiring for a weird stack, it increases hiring cost; you have problems with dependency zoo maintenance it increases costs; if it took a year to build a framework that could've been a bash script, it increased the cost)

Every other architecture “metric” should be useful/convenient proxy towards reducing overall cost.

I completely agree but cost conversations are difficult to have in most orgs especially when some of the costs are hard to measure (e.g. hiring, future time investments etc.). The goal of every (commercial anyways) software is to deliver maximum value at minimum cost.

I like to ask this question: "Can I make this system do what I need it to do while being able to stay with the existing architecture or do I need to become a special case?"

There is a lot buried in this question but it can help sus out if the rules in place allow the challenges the system faces today or if it is antiquated in how it views the world it operates in. Good and bad can be related to time and context but like many things in software, it needs to be able to change and sometimes that change requires the willingness to start from scratch with new assumptions.

Attributes like mix of languages, system/task ownership, specialization are symptoms that an architecture may want to enable or discourage but are symptoms, not measures of quality. Automated testing and how much that influences your software design is more aligned with the culture of the organization and how it treats code than it is the arrangement of subsystems it is built on.

Well it can go in both directions I guess. How to design a system well for the long term is definitely in the training data, and I‘m regularly very content with the suggestions that SOTA coding agents make when asked for it.

> AI as it is right now is probably a driver to make this worse because it makes it so much easier to throw random stuff together.

My experience has been the opposite: affordable slop makes me way more conscious about architecture because bad patterns become useless exponentially quicker.

In my 30+ years of SWE/SWA career this is the first time I can harvest the benefits of a well defined and exactly implemented architecture.

Thanks to LLMs.

Before LLMs even if the architecture principles were simple and clear, distilled into templates + codegens added for boilerplate / skeleton generation ... It was impossible to follow them on the long run. Devs tried their best, but on the long run everything eroded and there were no resources for refactoring.

Now, with coding agents, I was able to create a production grade app following a similar architecture to Presentation Domain Data Layering, from this article.

Now the codebase is 100% uniform both in content (code) and structure (files and folders). It's like being written by a single person. Finding a specific file takes a second with no cognitive load. Editing a file is straightforward since every file follows a specific template.

LLMs have benefits and drawbacks, and in this case their help is enormous.

Something I recently realized is that the fastest and easiest way to use coding agents is if you apply them to problems where there is just one, obvious solution.

This absolutely relates to architecture. If your system is designed such that any given feature fits in an obvious place, using obvious patterns, with obvious ways to test it... 90% of the time a coding agent will be able to do exactly the right thing from a single, short prompt.

This also makes code review so much less taxing - if the solution is obvious, reviewing and checking that the agent followed that obvious path takes much less time than if you're trying to untangle something a lot more complicated.

Exactly! What I use is a main workflow document where I embed at every step pointers to architecture and templates.

My prompt is ... "We are implementing the X feature. We are at step 6. Plan first"

Then the agent spits out identical plans then identical code for every feature.

I am so curious as to how you make this happen.

1. How do you organize your architecture files so that agents know where to find and update architectural info? E.g. everything in one big file, or sharded per module/subsystem with an AGENTS.md for discoverability, or something else?

2. What gets templated? What do your template files contain or look like?

3. How do you get the LLMs to actually slot something into the right place? E.g. a problem I repeatedly run into is the LLM weakening abstraction boundaries. I have to explicitly tell it things such as "No, this is obviously a UI-specific endpoint that belongs on the BFF rather than on the business logic focused backend API." Of course it gets better as I add more examples and rules each time I catch something dumb, but it sounds like you're avoiding this problem altogether with good architecture. How are you doing that?

4. It sounds like you have some sort of workflow that is standardized yet still generalizable enough to cover the generic case of new feature development on the system. How is that possible? What can you share about this flow?

You can use a well known template like ARC42 and insist on the maintenance of suitable indexes for agent access and review for coherence on a regular basis.

Ultimately any useful documentation needs active curation.

Getting devs to do this well is hard. Agents can be driven to do a fair job through suitable prompt frameworks and repetition eg as PR reviewers.

I’ve had reasonable success with a combination of space dimensions structured requirements and component based indexes and time dimensions of decision records and commits.

Also a strong design model to give common structure - hex arch with ports and adapters and pure business logic.

YMMV

Take his advice with a grain... or perhaps a quarry's worth of salt. This guy has written plenty of books and articles about the "agile" dogma, but most crucially, nothing about any of the software that he wrote. These days, it's even more obvious as the contents of this page feel like something an LLM could've generated.

If you want a "software architecture guide", you'd be better off examining software written by the likes of Linus Torvalds, Richard Stallman, Brian Kernighan, Dennis Ritchie, etc.

It depends on the scale of the architecture. If you're after kernel architecture or OS architecture, then yes, Torvalds, K&R, etc.

But for enterprise software architecture, that's a different level and has a very different approach, because it is most about business processes, not the actual construction of software.

It's about designing a framework for those processes that adapts to a business as it changes or expands or has to integrate new infrastructure, it's about isolation of customer data, ensuring regulatory compliance etc.

Those are all constraints on the design of the software, not so much actual computing and other infrastructure.

"how to talk non stop for thirty minutes without saying anything"

"We create products and services that we are proud of"

This was one of the 3 core values in the best company I ever worked for. One I would never leave, if the region was not heading for a disaster.

Good architecture transcends the software: enables people to be their best, evolve the software to better match the reality of its reason for existence.

In an effective organization, people constantly exceed their own expectations. They debate alternatives, understanding the reality of momentum, but aiming for an infinitely long living product.

They identify the "main problem", find ways to best solve that.

A good architecture does not do much more than what's needed, but avoid unnecessary assumptions that would block future development.

It is vague, philosophical, pragmatic, challenging, rewarding.

What was the region?

I'm Iranian

Ahh yeah. I'm so sorry about my government. :(

It's really complex. This attack was bad for the Iranian Government, their proxy war allies, and for the American people. In the region, however, it disrupted a rapidly escalating disaster. What comes after this is hard to predict, but what would come from the existing situation was hard to avoid. Second and higher order consequences might eventually be good for the people living in that region.

The most powerful thing you can do in 2026: lint your architecture in a pre-commit check.

Agents & humans can’t commit, or stop work, unless they’ve passed all lint checks. Passing the linter requires complying with the architecture. Now architecture violations can’t creep in and entrench themselves - they have to be fixed upfront. Code review is free from worries about architecture too.

Start by having your agent install some import-linter rules. When you hit its limits, have your agent write a custom AST-based checker (a short python script will do) that can look for imports that violate your rules. Resist its attempts to add a `# noqa: imports` escape hatch, because future agents will gleefully abuse that and you’ll be back to human in the loop (ask me how I know!)

For python projects I created pytest-archon[1], initially for humans, but now I'm using it for agents, too.

[1]: https://github.com/jwbargsten/pytest-archon

Thanks, lots to love in here! You’re clearly a convert :)

The goal is codification.

Writing down knowledge as verifiable invariants. The more that is codified, the less context you need. And that means you can be fearless.

This aligns very closely with my own views on software architecture. I've often wondered if I should be a software architect, but I often get the impression that architects sit in their ivory tower producing documents rather than code. I believe architects should build the thing they design. Or maybe engineers should design the thing they build. They go hand in hand.

I design systems, and then I build them. Sometimes I revise parts of the design while we're working on it, because of changing circumstances or new insights. The whole idea of an upfront design that only lives on paper is somewhat alien to me.

> This is what happens with poor internal quality. Progress is rapid initially, but as time goes on it gets harder to add new features. Even small changes require programmers to understand large areas of code, code that's difficult to understand. When they make changes, unexpected breakages occur, leading to long test times and defects that need to be fixed.

Seems familiar!

> Concentrating on high internal quality... is a rarer case, as it requires a skilled and disciplined team to make it happen. But we do occasionally see it.

Vibecoding vs. agentic coding. Same tools used different ways. Very different outcomes.

I’m with Ralph. I think in terms of design. Which is why I’m interested to hear the architecture argument. But if they’re both aspects of the same thing, isn’t this a fruitless conversation?

I want to suggest good design solves the problems you know. In which case can we say good architecture ensures good software.

I say this as a user of and developer of small businesses solutions. I expect SaaS products to make my job easier. And I’m greatly disappointed when I learn they don’t understand my job and fixes are impossible/forever on the horizon.

While these somewhat fuzzy definitions are hugely important (well, it says: "the important stuff, whatever that is", so by definition...), I have a hard time calling them "software architecture".

I'd like to suggest that at least some of the problems associated with the term, for example the pomposity, are rooted in the "separation from programming" that is not just a suggestion, but an unfortunate fact of architecture today.

And I would further suggest that we could improve the situation if we could actually express our architectures in our programs, in our programming languages. Then software architecture wouldn't just be "deeply intertwined with programming", as it must be, but actually be part of programming and part of the program.

And once the architecture becomes part of the program, it becomes part of our feedback loops. My experience is that feedback loops are a good antidote to pomposity and great for building/evolving systems.

To do that, though, we have to retreat from this idea that software architecture must be fuzzy, an idea that IMNSHO is just a cope for the current sad state of affairs. We have pretty good definitions of architecture (connectors and components, systems, architectural styles, etc.), let's start using them in earnest and in our programs.

If writing code is tactics and the end goal is strategy.

Is architecture operations?

If writing code is tactics, architecture is strategy. The end goal is just the desired outcome.

Not in the Clausewitz definitions I think.

Strategy would be the use software to achieve business goals.

Essentially why are we doing this at all.

Needs the [2019] suffix.

Yes, please.

Reply on news.ycombinator.com