Software Architecture Decisions That Determine Whether You Rewrite

Most software rewrites aren't engineering failures. They're the delayed consequence of decisions made in the first few months of a project — before the requirements were clear, before the team fully understood the problem, before the pressure to ship was balanced against the cost of getting the foundation wrong.

The rewrite itself is rarely the problem. It's a symptom. The problem is a set of architecture decisions that made sense at the time, compounded quietly, and eventually made growth expensive enough that starting over looked cheaper than continuing.

Understanding which decisions those are — and why they go wrong — is the difference between building something that lasts and building something you'll be explaining to the next team in two years.

Architecture Sets the Ceiling, Not the Floor

When companies evaluate software quality, they tend to focus on what the system does. Does it work? Is it fast enough? Does it pass the tests? These are floor-level questions. They tell you whether the system is functional, not whether it can grow.

Architecture sets the ceiling — the maximum complexity the system can absorb before change becomes dangerous or prohibitively expensive. A well-architected system can be extended, refactored, and handed to new engineers without catastrophic risk. A poorly architected one extracts a tax on every change: more time, more breakage, more risk that touching one thing breaks three others.

That ceiling is set early. Most of the decisions that determine it are made in the first sprint, the first month, sometimes even in the initial technical conversation before a line of code is written. By the time the consequences are visible, they're already structural.

The Decisions That Actually Matter

Not all architecture decisions carry the same weight. Some are expensive to change; some are nearly impossible to reverse. The ones that determine whether you rewrite tend to cluster around four areas.

The data model. This is the hardest decision to reverse. Every layer above the data model — the business logic, the API, the front end — is shaped by it. A data model designed around the current feature set rather than the underlying domain creates constraints that propagate upward. When the business model evolves (and it will), the data model becomes a bottleneck. The cost of changing it grows with every layer built on top.

Coupling decisions. Coupling isn't inherently bad — every system has it. The question is whether it's intentional. Unmanaged coupling means that changing one component requires understanding and touching several others. It slows development, raises the risk of regression, and makes the system progressively harder to reason about. Systems that accumulate tight coupling over time don't fail suddenly; they become increasingly expensive to change until the team stops changing things they should be changing.

Abstraction choices. Good abstractions hide complexity and reflect the domain. Bad abstractions hide the wrong things, or reflect the implementation rather than the problem being solved. An abstraction built around how the code works rather than what it represents makes future developers dependent on understanding the internals to use it correctly. Wrong abstractions are harder to live with than no abstractions — they mislead. They make the system look simpler than it is until someone tries to do something the abstraction didn't anticipate.

Integration boundaries. Where your system ends and another begins is a design decision, not just a technical detail. Integration points that aren't deliberately defined become organic — they expand informally as convenience wins over principle. By the time you need to change the integration, you discover it's not one well-defined boundary but a dozen points of contact distributed across the codebase.

Why These Decisions Get Made Wrong

This isn't a story about incompetent engineers. These decisions go wrong for structural reasons that competent engineers are still subject to.

Timeline pressure compresses design time. The sprint starts before the architecture conversation ends. In practice, that conversation often doesn't happen at all — the team starts building and designs emerge from the code rather than informing it. Emergent design under pressure produces systems that reflect the urgency of the moment, not the shape of the problem.

Requirements are incomplete by definition. At the start of any meaningful software project, the requirements are not fully known. Not because the stakeholders haven't thought hard enough — because the act of building reveals things that couldn't be anticipated from a specification. A good architecture accommodates this uncertainty. A brittle one treats the first version of the requirements as permanent.

The people making the decisions aren't close enough to the problem. Architecture decisions are business decisions expressed in code. The right data model for a billing system depends on how the business models revenue — not just what fields the current invoices have. An engineer who doesn't understand that context will model the current state, not the underlying domain. The gap between those two things is where technical debt lives.

Prototypes get promoted. A prototype exists to test an idea. Its architecture is deliberately expedient — the point is to learn something quickly. The mistake is treating a validated prototype as a foundation. Prototypes answer "does this idea work?" They don't answer "can this architecture support what this idea becomes?" Those are different questions. Systems built on promoted prototypes inherit all the shortcuts that were appropriate for exploration and none of the structure needed for production.

What "Built Right" Actually Looks Like

"Built right" doesn't mean no shortcuts. It means the right shortcuts in the right places, with a clear understanding of what's been deferred and why.

A data model designed around the domain rather than the current feature set, with explicit decisions about what will change and what won't. Coupling placed deliberately — some components tightly coupled because they change together, others loosely coupled because they change independently. Abstractions that reflect how engineers think about the problem, not how the first implementation happened to solve it. Integration points defined as contracts rather than discovered as side effects.

It also looks like a team that asks uncomfortable questions early. What will the data model need to accommodate in two years that it doesn't today? Where are the integration points and who controls them? What decisions are being deferred, and is that documented? Are the engineers making these calls close enough to the business to understand the implications?

A system built this way doesn't need to be perfect — it needs to be honest about where it's made tradeoffs. The dangerous systems aren't the ones with known technical debt. They're the ones where the debt is invisible because nobody mapped it.

The Rewrite-or-Refactor Decision

When a system reaches the point where change is visibly expensive, the question becomes: rewrite or refactor? Most teams frame this as a binary. It isn't.

Refactoring works when the architecture's skeleton is sound. If the right things are separated, if the data model reflects the domain, if the integration boundaries are defensible — then the work is cleaning up the flesh around a good skeleton. Painful, sometimes, but tractable.

Rewriting is the right call when the skeleton itself is wrong. A data model built on incorrect assumptions about the domain can't be refactored into correctness — every table, every query, every piece of business logic built on top of it carries the wrong assumption. Coupling that's architectural rather than incidental can't be incrementally loosened; the system has to be restructured. When the problems are structural, refactoring is an exercise in symptom treatment.

The challenge is that most arguments for rewriting are actually arguments for refactoring, made by teams who've lost confidence in the existing codebase. Rewrites carry their own risk — the same conditions that produced a poor architecture the first time will produce another poor architecture unless the conditions change. A rewrite without addressing the root cause is a two-year detour back to the same problem.

The decision isn't really "rewrite or refactor." It's "do we understand the architecture well enough to know which problems are structural?"

If you can't answer that question, you can't make the call confidently. The first step is always a clear-eyed diagnosis of what's actually wrong — not just where things are slow or buggy, but whether the underlying structure can support where the product needs to go.

The Missing Conversation

The decisions described here are most consequential when they're made implicitly — when they emerge from code rather than conversation, when they're shaped by whoever happened to start the project rather than deliberate design.

Good engineering teams treat architecture as an ongoing conversation, not a document filed after the kickoff. They revisit the data model when the business model changes. They map coupling explicitly and decide what to do about it. They document the abstractions and why they were chosen. They keep the people making technical decisions close to the business problems those decisions express.

None of this needs a formal process. It needs someone in the room who understands both the technical constraints and the business context well enough to translate between them. That's a proximity problem — and it's the same one at the root of most offshore development failures.

The systems that hold up aren't the ones built by the most technically skilled teams. They're the ones built by teams who understood the problem well enough to make good decisions under uncertainty — and who kept revisiting those decisions as the problem became clearer.

If your current system is expensive to change, the question worth sitting with isn't "how do we fix the code?" It's "when were the decisions made that got us here, and what would have to be different for the next version to age better?"

Armin Marxer writes at zeroclue.dev.