Evolutionary Architecture by Example: A Story-Based Guide to .NET Architecture Decisions

What This Repository Actually Solves

The problem is not a lack of .NET architecture examples. It is an oversupply of one-size-fits-all tutorials. Each repository tends to push a single approach: Clean Architecture, Onion, Hexagonal, tactical DDD, modular monolith, or microservices. The authors, Maciej Jedrzejewski and Kamil Baczek, argue that this misses the real challenge: knowing when and how to combine these elements. The repository is a decision map, organized as a story across four chapters. It uses a Fitness domain as the running example. The intended reader is a .NET developer who has seen the patterns in isolation but needs help deciding which to apply, and when. The authors explicitly reject the idea that any one architecture is universally correct. Instead, they present an evolutionary path that starts simple and grows with domain understanding.

The Project Paradox and the Evolutionary Approach

The core concept is the Project Paradox: at project start, you must make the most important architectural decisions at the exact moment you understand the domain least. This leads to two failure modes. The first is overengineering, adopting microservices, NoSQL, or caching before you know you need them. The second is underengineering, a monolith that grows into a big ball of mud. The repository's solution is to evolve the architecture in step with your understanding. Chapter 1 starts with a single project called Fitnet, organized by vertical slices. Each business process, like SignContract, gets its own namespace. This keeps related code together and makes future removal or relocation trivial. The modules communicate through a simple in-memory queue, enough infrastructure to work without overcomplicating. The approach is deliberately minimal. The authors want you to spend time building features, not debating folder structures.

How the Chapters Build on Each Other

The repository is structured as four chapters, each with its own README and code. Chapter 1 focuses on simplicity, laying the foundation with a single project and vertical slices. Chapter 2 shifts to maintainability by separating modules. The README is truncated at that point, so the exact contents of Chapters 3 and 4 are not fully visible in the provided material. However, the overall description indicates that later chapters introduce architectural pattern selection and evolution, leading to a hybrid architecture combining modular monolith and microservices. The narrative is meant to be read sequentially. Each chapter builds on the previous one, showing how the architecture changes as the domain becomes clearer. This is not a reference manual. It is a guided journey, and the interactive diagram link in Chapter 1 suggests a visual component to support the story.

Getting It Running: Commands and Configuration

The README does not list explicit installation commands or configuration keys. That is a limitation. To work with the repository, you would clone it and open the solution in a .NET environment. The primary language is C#, and the backend uses minimal APIs. The repository includes a solution file, but the exact project names and build steps are not described in the provided material. You would need to inspect the repository layout after cloning. The README does mention that modules communicate through an in-memory queue, which implies some configuration for that queue, but no specific keys are given. For a developer familiar with .NET, the path is straightforward: clone, restore, build. But the lack of a quick-start guide is a gap. The authors assume you know how to run a .NET solution, which is reasonable for the target audience but still a barrier for beginners.

What This Repository Is Not: A Template or Framework

This is not a template you can copy and adapt. It is a learning resource. The code is a vehicle for the narrative, not a reusable starting point. The authors deliberately leave some choices to you: frontend technology, logging implementation, and contract testing. They recommend Serilog for logging and Pact Net for contract testing, but they do not include them. This is a design choice. It keeps the repository focused on architecture, not infrastructure. But it also means you cannot use this as a drop-in foundation. The vertical slice structure in Chapter 1 is a pattern you can imitate, but the in-memory queue is explicitly described as 'just enough infrastructure.' For a real production system, you would need to replace it with a proper messaging solution. The repository is honest about this, which is refreshing, but it means the value is in the lessons, not the code.

Limitations and Potential Failure Modes

The most obvious limitation is the truncated README. The provided material cuts off mid-sentence in Chapter 2, so the full scope of Chapters 3 and 4 is not visible. You would need to clone the repository to see the complete content. That is a minor inconvenience. A more substantive limitation is the Fitness domain. It is a representative example, but it may not map to your domain's complexity. Fitness has clear bounded contexts, such as memberships and contracts. If your domain has more tangled dependencies, the evolutionary path may be harder to follow. The authors acknowledge the cliché of 'it depends,' but they do not provide a formal decision framework. They offer heuristics, not a checklist. This is a strength for learning, but a weakness if you need a prescriptive guide. The repository also assumes you are comfortable with .NET and minimal APIs. If you are not, the code examples will be a distraction.

Comparing with Alternatives: The Difference in Approach

A common alternative is a reference architecture like the eShopOnContainers or the Modular Monolith with DDD repository from Microsoft. Those projects provide a complete, production-oriented sample with a full set of patterns. The difference here is the narrative structure. Instead of showing a final architecture, this repository shows the evolution from simple to complex. It is a story, not a blueprint. Another alternative is a book like 'Clean Architecture' by Robert Martin, which is conceptual and technology-agnostic. This repository is concrete and .NET-specific. It bridges the gap between theory and practice. The key difference is that the authors do not present a target architecture. They present a process. That is rare in sample code. Most samples are static. This one is dynamic, and that is its main selling point.

Maintenance, Licensing, and Upgrade Cost

The repository is under the MIT license, which means you can use the code freely in your own projects, with attribution. The project is not archived, and the last push was in May 2025, with a release v1.2.0 on the same date. This suggests active maintenance, but the release cadence is irregular: v1.0.0 in September 2023, v1.1.0 in December 2023, and then a long gap to v1.2.0. The upgrade cost for a reader is low. You are reading and learning, not depending on a library. The code is a learning artifact, so you would not typically upgrade it. However, if you fork it and use the code in your own project, you inherit the maintenance burden. The authors recommend external tools like Serilog and Pact Net, which have their own release cycles. For a learning resource, the maintenance cost is minimal. For a production fork, it is a different story.

Editorial conclusion

Adopt this repository if you are a .NET developer or architect who wants to see how modular monolith and microservices decisions unfold in a realistic domain, with a clear narrative and code examples. Do not adopt it if you need a prescriptive template or a production-ready framework; this is a learning resource, not a starter kit. Before diving in, verify that the Fitness domain and the specific patterns (minimal APIs, in-memory queue) align with your context, and check the chapter README files for any prerequisites. The repository is actively maintained, with a release as recent as May 2025, but the value lies in the journey, not in any single artifact. Start with Chapter 1 to see the initial vertical-slice structure, then decide if the evolutionary path matches your own project's constraints.

Official sources

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