Building software in C#: part 2 - code architecture

In my previous post, I described how historical trends shaped our (or at least my) perception of software architecture.

However, with experience and seniority, you learn that code architecture always depends on a variety of context-dependent factors. This is something AI cannot help you with. A human must always establish the direction, depending on human factors such as company culture, team dynamics, formalization of work, responsibilities, and the software life cycle.

The best code architecture I have encountered so far doesn't have a name yet. It is a mix of various concepts taken from different architectural patterns.

Domain as a Flat List of Functions

When you use the mediator pattern, you are basically using a service locator. Writing CreateUserCommand and CreateUserCommandHandler is fundamentally the same thing as writing ICreateUserService and/or CreateUserService with a single CreateUser method.

Ultimately, the specific approach doesn't matter. The important thing is to always write your domain as a flat list of functions, each having a single responsibility and handling a single process. Time and again, this has proven to be the best strategy to guarantee long-term stability and, all else being equal, the avoidance of technical debt.

In this article, I will use the term function, but what I mean is a mediator command/handler or a service with a single public method; the specific shape is secondary.

CQRS, But Read is Part of the Domain

Originally, CQRS was meant to separate reads and writes at the infrastructure level because, for most business applications, 90% of operations are reads and 10% are writes. Domain writes are focused on one system, and changes eventually become visible eventually in a separate system optimized for reading.

However, I have never worked in an environment where traffic was high enough to justify such infrastructure-level optimizations. One reason is that the Czech Republic is a relatively small country with a population of around 10.5 million, and not everyone works at a high-traffic site like seznam.cz.

From a code architecture perspective, accounting for a separate read-only database is difficult. You need to produce and capture events, and you must maintain a manual or automated synchronization mechanism in case event delivery fails. Chances are, you don't need to do this at all—I certainly haven't.

BUT: Separating your domain functions into writing and reading functions is still an excellent idea.

Why?

If your users interact with a UI that displays data, then reading data is part of your domain. The DDD purists who believe the domain is strictly for writing are mistaken. The domain is supposed to represent what the business needs. If the business needs to read and display data, a function that reads and returns that data belongs in the domain.

Higher-Order Functions

Once you start writing your domain as a list of read or write functions, if the domain is complex enough, you will inevitably need a higher-order function: a function that calls (reuses) other functions in your domain. This is a saga pattern of sorts. Your first higher-order function will be a second-level function reusing your foundational, flat list of functions.

The critical architectural constraint here is that any higher-order function must strictly read from or write to the domain using the functions directly below them. A second-level function can use the first-level (bottom) list of functions. A third-level function can only use second-level functions, and so on.

Another constraint is that functions on the same level must NEVER invoke each other.

I have never needed anything higher than a second-level function, even in highly complex financial domains. However, in my first job, I worked on a monolithic application for travel agencies, which was probably the most complex domain I have ever seen. If that domain were written using this architecture, it would definitely require third- or even fourth-level functions.

Monolithic Domain

The domain is a monolith that should not be modularized within the scope of a single application or API. You should never spread domain functions across different .csproj files. The only justification for moving functions elsewhere is a deliberate decision to extract a new application that takes over specific responsibilities from the original one.

Validation, Transformation, Dependency

These are the only three actions allowed inside your domain functions, executed in any order:

• Validation: Verify whether, at any point inside the function, your in-memory data is valid.
• Transformation: Transform or manipulate data in memory.
• Dependency: Invoke a request to an external service (including your repository) to pass data, request data, or both.

Direct Use of EF Core

Most applications I have written in my career use MSSQL as their primary data source, or at least some relational database.

Time for a hard-to-swallow pill: switching from one RDBMS to another never happens. Unless the database schema is cleanly architected from the beginning, moving from MSSQL to PostgreSQL or MySQL (or vice versa) requires an immense amount of work that is rarely justified.

For those reasons, I don't see a point in abstracting the DbContext. It already is the abstraction I need. The argument that you must abstract DbContext into a repository interface just for testing is outdated; the ability to mock or substitute it has been solved for years. If you think EF Core is inherently slow, you probably haven't heard of .AsNoTracking().

This is also my critique of the Unit of Work pattern in Clean Architecture—it is often completely useless. There is no point in abstracting DbSet<User>.Add into IUserRepository.Add only to invoke IUnitOfWork.Commit instead of DbContext.SaveChanges(). YAGNI!

Dependencies as Modules & Maturity Levels

The domain needs to handle operations other than just reading and writing to the database. You invoke external APIs, write PDFs to file systems, or open sockets using legacy, third-party binary protocols.

Some operations are simple enough to write directly inside the function. However, complex operations should be abstracted away into an interface (like IInvoicePdfWriter) with the actual implementation moved elsewhere.

Where exactly? It depends on how much architectural overhead you are willing to accept:

• Maturity Level 5: InvoicePdfWriter is packaged inside a NuGet package, making it completely reusable across other projects.
• Maturity Level 4B: InvoicePdfWriter resides in a dedicated .csproj file created solely for this specific functionality.
• Maturity Level 4A: InvoicePdfWriter resides in a shared .csproj for all external dependencies, organized in a dedicated folder. A custom analyzer is configured to allow or forbid dependencies the same way you would use project references.
• Maturity Level 3: InvoicePdfWriter is in the same .csproj as the domain functions, but the functions inject the IInvoicePdfWriter interface.
• Maturity Level 2: You skip the interface entirely and inject the concrete InvoicePdfWriter class directly.
• Maturity level 1: The dependency speficic code is written directly inside of your function. You should at least move all of that to an internal service (maturity level 2).

The difference between 4A and 4B is practical: with 4B, you can easily end up with hundreds of .csproj files even for a relatively small project. This slows down your Visual Studio instance considerably and is rarely worth the overhead.