Architecture is the set of decisions that are hard to reverse. When those decisions are not recorded, the company inherits architecture by accident. Every new feature pays interest on choices nobody remembers making. Coupling grows silently. Module boundaries dissolve. What was a structured system becomes a body of code nobody dares touch without fear of breaking something else.
Subcapability 01 of 05 · Software Engineering & Architecture
Evolutionary Architecture
Fitness functions, ADRs and evolutionary architecture principles that let the system absorb strategy changes without full rewrites and keep the cost of change quantifiable and within manageable limits.
What is at stake
The architecture was decided but not documented. Every new engineer interprets the pattern differently. Every exception becomes the new norm. When the company tries to scale, the system reveals that decisions that seemed local have global consequences. The cost of every change rises because coupling grew without anyone declaring that debt.
What it is, in practice
How we work
Active Architecture Decision Records
We document each significant architectural decision with context, alternatives considered, accepted trade-offs and expected review date. The ADR travels with the code in the repository and is revisited when the conditions that justified it change.
Fitness functions in the pipeline
We implement automated architectural conformance checks that run on every commit: coupling limits between modules, prohibition of circular dependencies and layer restrictions. Violations are captured before manual review, when correction cost is minimal.
Pattern selection by problem
We evaluate modular monolith, microservices and event-driven with explicit criteria per context: team volume, need for independent deployment, consistency requirements and operational capacity. The right pattern for the right problem, not adoption by conference trend.
Architectural debt mapping
We make the accumulated liability visible with an inventory of decisions that diverged from the standard, estimated remediation cost per item and impact on change lead time. Declared debt has a plan. Hidden debt grows without an address.
Continuous architectural governance
We establish an architectural review process for significant changes, with explicit criteria for what requires formal review and what follows established pattern. Governance that does not slow velocity while maintaining system coherence over time.
Measurable gains
What changes in the result when this subcapability matures.
Lead time for significant architectural change
Fitness functions that detect erosion early and ADRs that document the original reasoning reduce the time to identify the point of change and assess impact. What took weeks of analysis now has documented reference and automated validation.
Percentage of architectural violations detected before merge
Fitness functions in the pipeline move the discovery of layer violations, coupling and circular dependencies to the commit moment. Correction cost at that point is a fraction of the cost in production or in a system with coupling already established.
Onboarding time for an engineer in a new system
Active ADRs eliminate the oral tradition period where the new engineer learns what not to do by trial and error. The architectural reasoning is in the repository, accessible from day one.
Cost of replacing edge technology
Architecture with explicit boundaries and documented dependencies reduces the impact scope of each peripheral technology change. Swapping database, framework or provider affects the adapter layer, not the business rules core.
Frequently asked questions
What differentiates an ADR from a traditional architecture document?
An architecture document describes the system as it is. An ADR records why a decision was made, which alternatives were discarded and under what conditions the decision should be revisited. When the context changes, the ADR is the starting point for evaluating whether the original decision is still valid. Documents that only describe current state become stale without warning.
What is a fitness function and why does it automate architectural governance?
A fitness function is a test that verifies a desired architectural property automatically. It may be a test that fails when a module imports from the wrong module, when cyclomatic complexity exceeds a threshold or when a service introduces a synchronous dependency where the pattern requires asynchronous. What previously depended on manual review and architect attention is now verified at every commit.
When is a modular monolith preferable to microservices?
A modular monolith is preferable when the team is still discovering the correct bounded contexts, when traffic volume does not justify the operational complexity of multiple services or when the organization cannot support independent pipelines per service. Microservices carry real operational cost. Choosing them before that cost is covered by the gain in independent deployability produces the worst of both worlds: distributed complexity with monolith coupling.
How to measure architectural debt in economic terms?
Architectural debt has a cost in lead time: how much longer each change takes because of existing coupling. Tools like SonarQube, Structure101 and dependency analysis via Maven or Gradle quantify circular dependencies, layer violations and cohesion metrics. The remediation cost of each item, estimated in engineering days, makes the liability readable in board language.
How often should ADRs be reviewed?
ADRs should be reviewed when the condition that motivated them changes. Traffic volume that exceeds what the current model supports, compliance requirement change, adoption of technology that alters the original trade-off. The expected review date should be part of the ADR. An ADR without a planned review is a document that ages without awareness.
Other subcapabilities in this capability
Domain-Driven Design
Domain-Driven Design strategic layer with bounded contexts, ubiquitous language and Event Storming that eliminates the translation layer between business and code, reducing rework and containing domain change cost.
Clean Architecture & Patterns
Clean Architecture Dependency Rule with Hexagonal Architecture, CQRS and Event Sourcing applied to the right contexts, allowing vendor and technology swaps without touching the business logic that matters.
Testing Strategy
Test Pyramid with Consumer-Driven Contracts via Pact and Mutation Testing that build genuine confidence to change production code and eliminate the fear ceremony that slows every release.
Code Quality & Craft
SonarQube Quality Gates, Technical Debt Ratio and Cognitive Complexity metrics that keep delivery velocity sustainable and prevent silent technical debt accumulation from becoming the invisible bottleneck of every future release.
Want clarity on where to invest first?
A complete technology capability assessment with an evolution roadmap connected to financial result.