AURELIA Architecture Notes #2 Why do most software projects become harder to understand over time?
When I started building AURELIA, I thought complexity came from writing more code.
Now I think it comes from something else.
Every time we add a new feature, we also add a new decision.
After months (or years), those decisions become scattered across files, databases, APIs, and people’s memory.
Eventually, the problem isn’t the code anymore.
It’s that nobody can explain why the system looks the way it does.
That’s why I’ve been trying to organize everything around a simple execution model:
Origin → Decision → Action → Result → Impact
Not because it’s perfect.
But because every change should answer five questions:
* Where did it come from?
* Why was the decision made?
* What action happened?
* What was the result?
* What impact did it create?
The more I build, the more I believe that architecture is not about adding layers.
It’s about making every decision understandable years later.
So I’m curious:
How do you stop your projects from becoming too complex over time?
I’d genuinely like to learn how other builders think about this.
Replies
This is a really interesting way to think about complexity. I agree that the problem often isn't simply the amount of code, but the loss of context behind the decisions.
The “Origin → Decision → Action → Result → Impact” model is a simple way to preserve that context. I especially like the focus on “why,” because that's often the first thing that disappears as a project grows.
I work in Online Reputation Management, and I see a similar pattern with businesses. Over time, their online presence becomes fragmented across reviews, directories, social platforms, and customer conversations. Without understanding the context behind those signals, it can be difficult to know what action will actually improve the bigger picture.
For software projects, I think documenting decisions as they happen—rather than trying to reconstruct them months later—is probably one of the most effective ways to keep complexity manageable.
Curious: do you plan for AURELIA to automatically track this execution chain, or is it mainly a framework for how developers should think about system changes?