What is evolutionary architecture, and how do you design a .NET system so its architecture can change safely over time?

1. Origin

Building Evolutionary Architectures (Neal Ford, Rebecca Parsons, Patrick Kua; 2nd edition with Pramod Sadalage) defines it as architecture that "supports guided, incremental change across multiple dimensions". It borrows fitness functions from evolutionary computing: an objective measure of how close a solution is to its goals.

2. Kinds of fitness functions

Start with a few that protect what matters most; too many noisy checks get ignored.

3. Modular monolith mechanics in .NET

src/
  Modules/
    Ordering/
      Ordering.Contracts      (public: commands, events, DTOs)
      Ordering                (internal implementation, OrderingDbContext → schema 'ordering')
    Catalogue/
      Catalogue.Contracts
      Catalogue               (CatalogueDbContext → schema 'catalogue')
  Host/                       (composition root; references modules)
tests/
  ArchitectureTests/          (NetArchTest rules)

• Modules reference only other modules' *.Contracts.
• Implementation types are internal; InternalsVisibleTo only for the module's tests.
• Each module owns its schema; no cross-module joins.
• Cross-module reactions use in-process events (later replaceable by a broker with an outbox).

4. Extraction checklist

5. Last responsible moment and reversibility

Deciding too early locks in choices with little information; deciding too late lets options disappear (e.g. data model already shared). The trick is to make the expensive decisions reversible where possible (ports in front of vendors, owned data, versioned contracts) so fewer decisions need to be made early at all.

6. Conway's law and stakeholders

• Systems mirror the communication structure of the organisation that builds them. If two teams share one module, expect coupling; if one team owns five services, expect them to merge in practice.
• The inverse Conway manoeuvre shapes teams to match the desired architecture.
• Architecture changes need product and leadership alignment: explain the trade-offs (cost, delivery speed, risk) and decide together; ADRs make those decisions visible.

7. ADRs

# ADR-0012: Extract Catalogue into a separate service
Status: Accepted (2026-05-10)
Context: Search load grew 8x; catalogue scaling forced scaling the whole monolith.
Decision: Extract Catalogue behind Catalogue.Contracts; keep events via outbox.
Consequences: +1 deployable, +network hop for product lookups; independent scaling; team X owns it.
Revisit if: search load drops or cross-module latency exceeds the SLO.

8. Try it yourself

1. Write an architecture test forbidding your domain project from referencing EF Core; add it to CI.
2. Add a rule that modules may only reference other modules' *.Contracts assemblies.
3. Define one SLO-based fitness function (e.g. p95 latency) and an alert for it.
4. Add an OpenAPI diff step to the pipeline that fails on breaking changes.
5. Write an ADR for your current module boundaries, including "revisit if" criteria.

// Fitness functions as xUnit tests with NetArchTest.Rules.
using NetArchTest.Rules;
using Xunit;

public class ArchitectureFitnessTests
{
    private static readonly System.Reflection.Assembly OrderingAssembly = typeof(Ordering.PlaceOrder).Assembly;

    [Fact]
    public void Ordering_domain_does_not_depend_on_infrastructure()
    {
        var result = Types.InAssembly(OrderingAssembly)
            .That().ResideInNamespace("Ordering.Domain")
            .ShouldNot().HaveDependencyOnAny("Microsoft.EntityFrameworkCore", "Ordering.Infrastructure")
            .GetResult();

        Assert.True(result.IsSuccessful, string.Join(", ", result.FailingTypeNames ?? []));
    }

    [Fact]
    public void Ordering_only_uses_other_modules_through_their_contracts()
    {
        var result = Types.InAssembly(OrderingAssembly)
            .ShouldNot().HaveDependencyOnAny("Catalogue.Internal", "Billing.Internal")
            .GetResult();

        Assert.True(result.IsSuccessful, string.Join(", ", result.FailingTypeNames ?? []));
    }

    [Fact]
    public void Module_implementation_types_are_not_public()
    {
        var result = Types.InAssembly(OrderingAssembly)
            .That().ResideInNamespace("Ordering.Internal")
            .ShouldNot().BePublic()
            .GetResult();

        Assert.True(result.IsSuccessful, string.Join(", ", result.FailingTypeNames ?? []));
    }
}

namespace Ordering
{
    public sealed class PlaceOrder { }
}

Requires xunit and NetArchTest.Rules. In a real solution the test project references the module assemblies; the PlaceOrder stub only gives typeof an anchor type.