There are many repositories that describe software and solution architecture in .NET. As there is no single definition of software architecture, they combine several topics:

• Deployment strategies like Modular Monolith and Microservices

• Domain-Driven Design

• Clean, Onion, Hexagonal Architecture

• Infrastructure

as if each of the above were the only possible solution. And that is the problem - it is very rare that any single material shows you a concrete decision path or mix of the above approaches.

Often the examples you find are either too trivial or too complex. Sometimes they are harmful because they misunderstand different concepts. As a result, it is very difficult to take just one and follow some patterns for your own application.

It depends - one of the most overused phrases. Well, it always depends on something, but there are always heuristics to help you decide.

In summary, if you are looking for a journey - not just a single article describing a solution - look no further. It starts here, in this repo.

Our solution should be read like a story and is divided into 4 chapters:

Chapter 1: Initial Architecture: Focus On Simplicity

Chapter 2: Modules Separation: Focus On Maintainability

Chapter 3: Microservice Extraction: Focus On Growth

Chapter 4: Applying Tactical Domain-Driven Design: Focus On Complexity

In each chapter we describe the evolution of the architecture of a selected domain:

• Starting with a simple solution architecture that meets early production needs, where business processes are separated in namespaces and communication is handled by an in-memory queue

• Moving to module separation with the structure of multiple projects associated with each module (including CQRS)

• Continue with the single module extraction to a microservice and add the message queue component

• Tackling the complexity of one of the modules using tactical Domain-Driven Design

We apply everything we have learned over many years of software development - our aim is to help you avoid making the same mistakes we have. This way you can be sure that your architecture will not be too trivial for too long, or too complex from the start. Treat it as a guide, something you can refer to at any time.

What we focus on:

• Selected business domain analysis

• Split the domain into subdomains (Core and Supportive)

• Choice of architectural pattern

• Evolution from monolithic to modular

• Evolution to a mix of modular monolith and microservices

• Applying Domain-Driven Design to a Core module

• Backend (.NET) with minimal API

• Loose coupling

• Architecture decision log

• Good coding practices

What we do not focus on:

• Frontend (you can use React, Vue, Angular, Svelte or anything else)

• Logging (you can use Serilog)

• Contract testing (you can use Pact Net)

so that you get the gist of what we have to share with you. Additionally, static code analysis is enabled in all chapters to help us to keep the code base as clean as possible. It is strongly suggested to use it as well in your production code.

The chosen domain for analysis and implementation is a Fitness Studio. It is an area that most of people have an idea of how it works. You can:

• Get an offer

• Request for a contract

• Sign the contract

• Receive a pass (to be able to enter the fitness studio)

• Attend to fitness classes

and many more.

However, in order to identify the above processes, you usually need to analyse the domain with Domain Experts and break it down into smaller pieces called Subdomains. Otherwise, there is a high risk of falling into a big ball of mud (or distributed mud) where everything is tightly coupled.

At first glance, the domain seems small and problems of oversimplification of initial assumptions usually arise from this interpretation. There are dozens of processes related to expired passes and renewals, discount policies, VIP access, negative cases (e.g. rejection of the access). We often tend to underestimate the problem.

Now that you understand which business domain we are focusing on, it is time to break it down into smaller pieces called Subdomains.

There are many ways to do this. Our 3 favourites are:

• Domain Storytelling

• Event Storming

• Story Storming

In general, the idea is to find processes by discovering the flow. Based on different heuristics you are able to define the smaller blocks.

After a round of analysis, we decided to choose the following areas for implementation to show you the idea of Evolutionary Architecture:

As you can imagine, each subdomain covers a lot of different processes. Again, due to time constraints, we cannot focus on every single aspect. Therefore, we have chosen the following actions for each subdomain:

There are 6 different processes in 4 different subdomains. There is a problem here - these subdomains do not communicate with each other and this is one of the most common problems we have in our applications. So we decided to complicate things a bit and add some communication:

There are 2 triggers:

• when the contract is signed by you (a customer), then the new pass is registered to allow you to enter the fitness studio

• when the pass expires, then the new offer is prepared (which will be sent to you as a customer)

This way we are almost ready to start the implementation.

One more thing to mention - in our example, each subdomain is a separate Bounded Context.

Before you decide to start coding, it is worth to look at your analysis and division one more time and check the complexity of each (it will be mainly defined by the amount of processes and its business rules/policies). Let’s take a look at below examples.

In this chapter we will show you how to start your solution architecture. We start with modularisation from day one of the application, but modules are only separated by namespaces (there is only one project for the production code called Fitnet). Each process that occurs in each module is sliced vertically - all the code is covered in each process namespace. This gives us several advantages:

• better productivity - when we start a new design, we are not distracted by creating namespaces, renaming, moving things around

• all the code for each process is in just one namespace, so there is no need to look around in folders like Controllers, Entities, Commands, Queries etc. Everything is just in e.g. SignContract

• deleting or extracting the process is simple - you just drop or extract a namespace

Modules communicate with the in-memory queue.

This chapter focuses on the second step you can take in your application. After some time, you will find that your assumptions about modules were wrong - they grow fast, the business logic becomes more complex. You may have to decide to use a different type of database (e.g. key-value). Or the other way around - something you thought was going to be complex is actually quite simple and there is not a lot of business logic involved. Also, the team has grown and it is quite difficult to work on one project - lots of conflict and merging hell.

With this in mind, you can now start thinking to split your single Fitnet project into several ones:

• for one module it will be just Fitnet.Reports - there is only a transaction script, no business logic

• for another, it will be Fitnet.Passes.Api, Fitnet.Passes.DataAccess to build around the active record

• for the complex one it will be Fitnet.Contracts.Api, Fitnet.Contracts.Application, Fitnet.Contracts.Core, Fitnet.Contracts.Infrastructure

and so on. The modules still communicate with the in-memory queue (alternatives described in the chapter’s own README).

Over time, you may need to extract a microservice from one of your application modules. In this chapter, you will identify the most common disintegrators (decision drivers for extracting a microservice).

We will also add a message queue component to replace the in-memory queue. This way, we will improve the exchange of messages between the modules themselves and the microservice.

Here you will learn about various concepts that are important from a microservices architecture perspective.

At the end of the story, we want to show you that it is possible to evolve to a domain model for one of your modules at some point.

You do not have to start from scratch if you do not know your business domain. And you do not need to apply all the concepts of Domain-Driven Design to get good results.

Interesting fact - if you have done a proper analysis of your business domain in the beginning and have already broken it down into different subdomains (and combined them into e.g. a module), then you are almost done from a strategic Domain-Driven Design perspective. Now you just need to make some adjustments and do some tactical DDD. Cool? Absolutely cool!

Here we focus mainly on tactical DDD and describe

• value objects

• entities

• aggregates

You will also find some tips for the next steps.

We are trying to keep this repository as simple as possible, so that you can read it like a book. It contains chapters, where each chapter is an extension of the previous one, read like a story.

In the root folder of this repository you will find only this README, the assets (images & diagrams) used in it, and 4 folders containing the content for each chapter.

In each folder you will find the same root solution, but expanded:

1. Chapter 1 - Initial state of the application

2. Chapter 2 - Extraction into separate projects

3. Chapter 3 - Extracting a module to a microservice and using the message queue

4. Chapter 4 - Applying Tactical Domain-Driven Design to one of the modules

Another important thing to note is that the detailed description of each chapter is in its own README folder. There you will find the information on how to run the solution, what solution structure is used, and other important things that are only relevant to that particular chapter.

We are not repeating the information covered in the previous chapter, we are just extending it with the decision we have made.

In this webinar, Maciej "MJ" Jedrzejewski gives a detailed talk on Evolutionary Architecture. You can watch the recorded webinar here.

This is a recorded presentation from the Programistok 2023 Conference, where Evolutionary Architecture was extensively explained. You can watch it on YouTube here.

Explore Evolutionary Architecture visualized through NDepend, featuring comprehensive dependency and code analysis in the form of an interview led by Ferry de Boer with Kamil. Watch it on YouTube here.

Really appreciate the repository and the content you are sharing. I think it is really valuable to see the evolutionary approach in practice, and focus on simplicity and pragmatic reasoning and making decisions in software design.

Your work has been super helpful as I dive deeper into this field. Evolutionary Architecture, in particular, is incredible and has really clicked for me thanks to your examples and insights.

I was always concerned about what architecture to use on a project. Sometimes, spending time on researching what’s right affects my motivation. Your approach which focuses on creating a project with an architecture that evolves resonates perfectly with me. Your efforts in creating such a wonderful resource is greatly appreciated.