Evolutionary Architecture by Example: a four-chapter .NET guide from modular monolith to microservices

The problem: architecture advice that assumes one answer

The README states the problem plainly. Search for .NET architecture guidance and you find repositories that each push a single approach: Clean, Onion or Hexagonal architecture, tactical Domain-Driven Design, modular monolith, or microservices. Each presents itself as the universal solution. The authors argue this misses the day-to-day reality, and that what is missing is a decision map for when and how to combine these elements.

The second complaint is about the sample code itself. Existing examples sit at two extremes: oversimplified demos that do not reflect real complexity, or enterprise-scale applications that are hard to learn from. The repository positions itself between those poles.

The intended reader is a .NET developer or architect who already knows the vocabulary and wants to see tradeoffs evaluated in order. The README names a concept it calls The Project Paradox: at the start of a project you must make architectural decisions precisely when you understand the domain least. The stated failure modes are preemptive adoption (microservices before understanding scaling needs, orchestration systems, data streaming, NoSQL, caching "just in case") and its opposite, a monolith that grows unchecked into what the README calls a "big ball of mud".

Four chapters, one Fitness domain, and a vertical slice starting point

The repository is organized as four directories, each a chapter: Chapter-1-initial-architecture, Chapter-2-modules-separation, Chapter-3-microservice-extraction, and Chapter-4-applying-tactical-domain-driven-design. The README describes the approach as a story that builds chapter on chapter.

Chapter 1 begins with a single project named Fitnet. The organizing principle is a vertical slice: each business process gets its own namespace, so everything for a process such as SignContract lives in one place instead of being spread across Controllers, Entities and Services folders. The README's justification is practical: spend time building features instead of debating project structures, and when a feature must be removed or relocated, grab its namespace.

Communication between modules in Chapter 1 is through an in-memory queue, which the README describes as just enough infrastructure to get the job done. That is a deliberate ceiling. An in-memory queue does not survive a process restart and does not cross a network boundary, so it works only while everything runs in one process. Chapter 2 then addresses module separation, framed around maintainability, and Chapter 3 extracts a microservice. Chapter 4 applies tactical Domain-Driven Design.

The README lists what the repository covers: analysis of a Fitness domain, strategic and tactical DDD, architectural pattern selection and evolution, a hybrid of modular monolith and microservices, loose coupling, a .NET backend implemented with minimal API, an architecture decision log, and clean coding practices. It also lists what is left to the reader: frontend technology choice and logging implementation, with Serilog recommended, plus contract testing, for which Pact Net is suggested.

Getting the repository and reading Chapter 1

There is no NuGet package here. The README does not give install instructions, so the entry point is the repository itself. Clone it and inspect the chapter directories, since each chapter is a separate solution rather than a single build target.

git clone https://github.com/evolutionary-architecture/evolutionary-architecture-by-example.git
cd evolutionary-architecture-by-example
ls

The listing should show the four chapter directories plus Assets, LICENSE and README.adoc. The README is written in AsciiDoc, not Markdown, which matters if your editor or internal wiki expects .md.

To follow Chapter 1, open its directory and build the Fitnet project with the .NET SDK. The README does not state a required SDK version, so check the project files before building.

cd Chapter-1-initial-architecture
dotnet build

A successful build produces the Fitnet assembly. From there, the useful reading is the chapter README, which the top-level README links as Chapter-1-initial-architecture/README.adoc, alongside an interactive diagram hosted on IcePanel. The code to read first is the namespace that holds a single business process, because the whole argument of the chapter is that a process's controller, model and handler sit together rather than in technical folders.

Where the repository stops being useful

The README is explicit about two things it does not provide: frontend technology and logging implementation. It recommends Serilog and suggests Pact Net for contract testing, which means neither is wired into the sample. If you want a full-stack reference, this is not it.

The in-memory queue in Chapter 1 is the sharpest limitation. It is deliberately minimal, and the README says so, but a reader who copies the pattern into a system that must survive restarts or run on more than one node will find the boundary quickly. The queue is a teaching device for the first chapter, not a messaging strategy.

There is also a versioning and maintenance consideration. The repository is not archived, but the last push was on 2025-05-24, which is the same date as the v1.2.0 release. The two prior releases were v1.1.0 on 2023-12-01 and v1.0.0 on 2023-09-12. That cadence, roughly one release per year with the most recent more than a year before the current date, means you should treat the code as a stable reference rather than a moving target. A .NET codebase that is not being pushed to will drift from current SDK and package versions; check the target framework before assuming a chapter builds on your machine.

Finally, the repository is a narrative. If you want a library that enforces module boundaries at compile time, or a template that scaffolds a solution, this is the wrong tool. It shows decisions; it does not automate them.

How it differs from Clean Architecture samples and DDD/CQRS examples

The related searches around this project cluster on Clean Architecture examples and DDD with CQRS. The difference is structural. A typical Clean Architecture sample fixes a layering once: domain at the center, application, infrastructure and presentation around it, with dependency rules pointing inward. You learn the shape, and the shape does not change.

This repository changes the shape on purpose. Chapter 1 is one project organized by vertical slice. Chapter 2 separates modules. Chapter 3 extracts a microservice. Chapter 4 applies tactical DDD. The reader sees the same Fitness domain under four different structural regimes, which is the point the README makes about combining approaches rather than picking one.

A DDD/CQRS example usually goes deep on a single bounded context: aggregates, commands, queries, event handlers, and the persistence choices around them. This repository spreads its attention across strategic concerns (how the domain is divided) and architectural evolution (when to split), and only reaches tactical DDD in the final chapter. If your immediate need is a worked aggregate-and-repository implementation, a focused DDD sample will get you there faster. If your need is deciding whether to split a module into a service at all, the sequence here is the more relevant material.

Licence, cost, and what upgrading involves

The repository is MIT licensed, per the LICENSE file and the badge in the README. MIT permits use, modification and redistribution with the licence and copyright notice retained. That is permissive enough to lift patterns into commercial work, though the repository is a teaching artifact and the authors' names remain attached to the text; nothing here is legal advice, and if you plan to reuse substantial portions of the narrative in your own documentation, read the licence text yourself.

The upgrade cost is not a dependency management problem, because there is nothing to depend on. It is a reading and porting problem. There are three releases: v1.0.0 on 2023-09-12, v1.1.0 on 2023-12-01, and v1.2.0 on 2025-05-24. If you adopt a chapter as a starting point for a real solution, you inherit its target framework and its package references, and you will be the one moving them forward. The release notes for v1.2.0 are titled "Evolutionary Architecture By Example v1.2" and the repository does not describe a migration path between versions, so treat each release as a snapshot to read rather than a version to upgrade along.

Editorial conclusion

Adopt it if you are a .NET engineer or tech lead who wants to see architectural decisions made in sequence rather than asserted in a slide deck, and you are willing to read the chapter READMEs alongside the solution. Skip it if you need a production framework, a frontend, or a library to install; the repository is a teaching artifact with no NuGet package. Before committing time, verify that the .NET SDK version used in the solution matches your toolchain, and read Chapter 3's README to confirm how the microservice extraction is wired, since the top-level README truncates before that detail.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes