There has been a lot of confusion over the years around the terms design and architecture. What is software design? What is software architecture? Where’s the line between the two — and does it even exist? Some developers say there is; others see no difference at all. Ultimately, it’s up to you how you interpret it. My goal here is simply to clarify the concepts for you😅.

Recognizing the different scales of architecture can help you make smarter decisions. That’s why it’s important to understand the distinctions between:

• design principles
• design patterns
• software design
• software architecture
• architecture patterns
• architectural styles
• software architecture

Each has its place — once you see how they relate, everything becomes much clearer 😉.

🎯 Design Principles

This is a bit out of scope of this article, but let's quickly mention design principles.

They help you make smarter decisions long before code becomes a tangled mess.

Design principles provide guidelines on how to write clean, maintainable, and scalable code

Examples:

• Divide and Conquer — split the problem into smaller parts, solve each part, and combine the results
• Separation of Concerns — divide a program into distinct sections, each addressing a separate concern
• SOLID — five principles that promote maintainable object-oriented design
• KISS (Keep It Simple, Stupid) — avoid unnecessary complexity
• DRY (Don’t Repeat Yourself)— reduce code duplication
• YAGNI (You Aren’t Gonna Need It)— don’t add features until they’re actually needed

🧱 Design Patterns

Every program has to start somewhere. Usually from spaghetti code😅. And don't lie to me. Everybody was there at some point.

Some parts of the code become unsupportable, so you have to structure those in a better way.

This is the point where developers start a journey to architecture and learn about design patterns.

Design patterns are well-known, proven solutions to common problems encountered in object-oriented design. They operate at the class or object level

Examples:

• singleton — ensures only one instance of a class exists
• observer — notifies multiple objects about state changes in another object
• decorator — adds new behavior to objects dynamically
• state — allows an object to alter its behavior when its internal state changes
• proxy — controls access to another object, adding a layer like lazy loading, access control, cache, or logging
• adapter —converts one interface to another expected by the client
• facade — provides a simplified interface to a complex subsystem

🧩 Software Design

Once you’ve established communication between certain classes, you may begin extracting code into a separate project.

Often, the internal structure of these modules doesn’t follow a specific architecture — the main goal is simply to maintain low coupling and high cohesion.

However, that’s not always sufficient. Sometimes, the entire module must be deliberately designed in a particular way.

Software design (code architecture) refers to low-level structure of a single module

Examples:

• organizing a command-handler pattern inside the Application module to separate concerns
• using a rich domain model to enforce consistency and encapsulate business logic within the Domain project
• applying screaming architecture to make the component’s intent and purpose clearly reflected in its structure and naming
• designing a state machine to manage transitions in a workflow engine
• implementing the bridge pattern to enforce a common structure in reporting jobs

🧠 Architecture Patterns

One project is great. But do you know what is even better? Many projects😅.

Similar to what we had before, we need to organize and structure those modules somehow.

Architecture patterns provide guidance on how to organize many projects within a single application

Examples:

• MVC/MVP/MVVM — divides an application into Model, View, and Controller layers to separate business logic, user interface, and control logic
• Monolith Architecture — a traditional architectural style where the entire application is built, deployed, and run as a single, unified unit
• N-layered — divides the application into multiple layers with distinct responsibilities
• DDD Layers — focuses on aligning software design with the business domain
• Hexagonal Architecture (Ports and Adapters) — isolates business logic from external dependencies
• Onion Architecture — enforces dependency flow toward the domain
• Vertical Slice Architecture — structures the system around features or use cases, keeping all related layers (UI, Domain, Infrastructure) within a single, independent slice
• Multitenant Architecture — an architectural approach that enables a single instance of software to serve multiple independent user groups (tenants)
• CQRS — separates read and write models for scalability and clarity
• Event Sourcing — stores state as a sequence of events rather than a single snapshot

🗺️ Architectural Styles

One application is great. But do you know what is even better? 😂 Many applications.

Systems grow. Now they consist of multiple applications, and they all need to interact with each other.

Architectural styles define the overall structure and interaction of multiple applications

Examples:

• Client-Server — separates consumers (clients) from providers (servers)
• Modular Monolith — organizes the system into well-defined, independently developed modules within a single deployable unit
• Microservices — compose the system of small, independent services
• REST — defines a resource-oriented interaction style over a uniform interface
• Event-Driven Architecture — components interact through events rather than direct calls
• Serverless — abstracts server management by running functions or services on demand in a cloud environment

🏛️ Software Architecture

For the final, we have software architecture. It dictates the shape of the entire system.

It is also the most ambiguous term — often used to refer to any of the concepts above, depending on the scale you’re working at.

After all, architecture can be described in ways that apply across different contexts.

Software architecture describe components of a system and the relation between them

What’s fascinating is how very basic design patterns reappear at higher levels of abstraction, seamlessly blending into architectural styles 😅:

• a distributed cache acts like a singleton inside a cluster
• a facade pattern morphs into a gateway
• an anti-corruption layer is nothing more than the adapter
• the mediator becomes an event bus, while the observer is similar to queue (you can also argue that the observer is the webhook approach)
• concepts like saga represent state machines

I could go on — proxies, decorators, sidecars — but you get the idea. The concept remains the same; only the scale changes. That’s why mastering the fundamentals is so essential — it helps you recognize familiar patterns, no matter how big the system gets 🙃.

This recursive nature of software concepts — repeating at different levels of scale — is what makes architecture both challenging and beautiful 😌.

Summary

Let me quickly sum it up for you, so can easily compare those terms without scrolling 😁:

• Design Principles provide guidelines on how to write clean code
• Design Patterns address common, low-level problems within classes
• Software Design focuses on the internal structure of one module
• Architecture Patterns guide the organization of multiple modules in an application
• Architectural Styles describe the interaction between many applications
• Software Architecture shapes the whole system layout

👏 Give this article a clap if you liked it

☕️ You can also support me using the link below

✅ Follow to see more

🙃 And keep coding

If you’ve been around long enough, you probably started building applications the “classic” way: create a single API, define a few endpoints, and deploy everything onto a server.

As systems grew, we split that monolith into multiple smaller APIs — microservices — each deployed independently, often across many servers.

But the idea doesn’t stop there.

Take it one step further, and you can break an application down into even smaller units — sometimes as small as a single endpoint — and deploy each piece independently.

Writing less code sounds nice, but you can easily end up spending more time deploying each piece than actually building the functionality.

Because of that, many cloud providers (like Azure) simplify DevOps for us by handling provisioning, scaling, execution, and resource cleanup on our behalf.

At this point, something interesting happens: you’re no longer thinking about servers at all. Not because they disappeared, but because you no longer have to care about them. This results in a serverless architecture.

Serverless architecture is a cloud computing model where developers build and run applications without managing servers.

So, How Exactly Does It Work?🤔

At the core of serverless is a simple idea: you write small pieces of code (a function), and something else decides when and where to run it.

The Function is a small, stateless unit of work. Each function is focused on doing one thing well, not hosting an entire application.

public class MyFunction
{
    [FunctionName("MyFunction")]
    public async Task Run(
        [HttpTrigger(AuthorizationLevel.Function, "post")] // 👈 trigger
        HttpRequest req) 
    {
         . . .
    }
}

From there, the flow is straightforward:

• An event occurs (HTTP request, queue message, file upload, a scheduled job, or even a database change)
• The cloud platform invokes the corresponding function
• The function runs in an isolated environment
• Resources are allocated automatically for execution
• Once the function completes, everything is cleaned up

You don’t manage servers, scaling rules, or infrastructure. The platform handles it in real time.

Snap Back to Reality

I can already see some of you, inspired by “no servers at all” idea, but don’t rush up.

Functions work great for internal tools, background jobs, startups validating ideas, and event-driven systems. They let you move fast, focus on business logic, and avoid heavy DevOps work.

But they fall short when you need long-running processes, low-latency responses, or complex business logic.

Serverless is a great building block, but not always a great entire foundation.

Therefore, it is usually a bad idea to build an entire project on functions. Most real systems are a mix — a traditional monolith API with some serverless parts. Trying to force everything into serverless usually ends in messy code, painful debugging and tracing, hidden costs, and other problems we will discuss below.

Long-Running Execution Limits in Serverless

One of the most important constraints in serverless architecture is execution time. Even though you would like to move the background work to a function, serverless platforms are built for short-lived, event-driven workloads — not processes that run for minutes or hours. Usually, cloud platforms enforce a maximum execution duration, like up to 5–10 minutes (depending on plan).

Once this limit is reached, the function is terminated, leading the application to an inconsistent state and risking data integrity.

Because of these limits, long-running workflows must be redesigned:

• break work into small steps
• persist progress externally (database, queue, storage)
• make each step idempotent, and safe to retry

This isn’t just a technical limitation — it’s a shift in thinking. Serverless doesn’t support long-running execution. It forces you to model long-running workflows as a series of short tasks.

The Complexity Trap of Serverless

Serverless works best when the logic is simple, event-driven, loosely coupled, and short-lived.

At first glance, it may seem that serverless makes complex logic easier by breaking it into smaller pieces. That’s only partially true. Serverless doesn’t eliminate complexity — it redistributes it.

As business logic is split across multiple functions, it often becomes more fragmented and harder to read, reason about, and maintain. On top of that, serverless introduces additional challenges: coordinating between functions, managing state externally, and handling the overhead of distributed workflows.

— out-of-process by design

One important shift: your application is no longer stateful by default. Functions are ephemeral, so any state or in-memory data must be stored externally.

Therefore, you need to rely more on supporting services — databases, authentication providers, storage, and messaging systems — to persist and manage that state.

Of course, some cloud providers support durable functions, adding orchestration, state persistence, and automatic retries for long-running workflows in a way that’s transparent to the developer, but that does not completely eliminate the need for careful design.

The in-process mechanisms that worked for a single instance are no longer sufficient. Everything needs to be out-of-process now:

• to share cache between multiple nodes, it should be distributed
• threads synchronization can be achieved using the distributed lock
• configuration settings need to be consistent across instances
• task scheduling must ensure coordination across multiple nodes
• idempotent request coordination is a must

This result is a system with more moving parts — and, inevitably, more potential failure points.

— communication between components

In a monolith handling long-running processes, you can simply call one method after another within the same execution context. In serverless, that model breaks down — each step lives in a separate function, and you must explicitly pass context between them.

Serverless components don’t communicate directly. Instead, they rely on event-based communication, where context is passed along with events from one function to the next.

If the context becomes too large to include in event payloads and you want to avoid document events, a common approach is to persist state in a database and use events only to signal that a step has completed and the next one should start.

While sharing storage is often considered an anti-pattern in microservices — where each service should own its data — in serverless architectures this is more acceptable. Functions are smaller, more transient units, and using shared storage as a coordination mechanism is often the most practical solution.

— transactions

In a monolith or a traditional service, complex operations often rely on a single transactional boundary. Multiple steps can be executed atomically — either everything succeeds, or everything is rolled back.

In serverless, that model no longer applies. There is no built-in way to wrap multiple steps in a single, atomic transaction.

To maintain consistency across steps, you end up implementing:

• compensating actions — manually undoing previously completed steps
• eventual consistency — accepting that the system may be temporarily inconsistent
• retry logic — handling partial failures and duplicate executions

What used to be straightforward transactional logic becomes real complexity.

Overall, if your domain logic is rich and tightly connected, a more traditional service (or even a modular monolith) is often the simpler, more maintainable choice.

Cold Start Problem in Lambdas

One of the most common downsides of serverless is the cold start.

A cold start happens when your function hasn’t been used for a while, so the platform has to deploy it before running. This does not happen instantly but requires time.

Although functions are mostly used for asynchronous execution when you don’t expect an immediate response, there are cases when it is not acceptable.

There are a few practical ways to reduce cold starts:

• keep functions small — less code, fewer dependencies, and simpler initialization = faster startup
• pay for pre-warmed instances — most providers let you keep some instances always ready (at an extra cost)
• deploy as a web app — a bit of a cheat 😅, but running as an app service removes cold starts entirely
• use warm-up strategies — trigger your function periodically (e.g., every few minutes) to keep it “warm”
• accept it where it doesn’t matter — background jobs, queues, async processing — cold starts are often irrelevant there. Don’t optimize what users never notice

Cold starts aren’t a dealbreaker — but ignoring them is a mistake. If you’re building anything user-facing, you need to account for them early, not after users start noticing delays.

Vendor lock-in

The last problem we're going to discuss is vendor lock-in.

Applications typically rely on standard protocols like HTTP to stay portable. This makes it possible to swap components, move them to different servers, or even rewrite parts of the system without having to rebuild everything from scratch.

Serverless is different.

Once you adopt it, you inevitably start depending on the Cloud platform itself. As you need to adapt to your cloud provider and how it handles:

• function runtime
• bindings (like Azure Functions input/output bindings)
• configuration and deployment style
• built-in integrations (storage, auth, messaging)
• etc

All of this is tightly coupled. Your function isn’t just “code” anymore — it’s code + platform.

Vendor lock-in is a problem developers try to deal with. The good news is, it is not a problem😅.

In practice, you will never change cloud providers. Aiming for a fully independent solution will make you lose most of the benefits and platform features, and you’ll spend a lot of time fighting the platform instead of using it.

That said, it doesn’t mean you should fall into the trap of putting everything inside a function. You still need to follow clean code principles to avoid ending up with messy, unmanageable code, like below, where you mix concerns:

public static class PlaceOrderFunction
{
    [FunctionName("PlaceOrder")]
    public static async Task Run(
        [HttpTrigger(AuthorizationLevel.Function, "post")]
        HttpRequest req,
        
        // ⚠️ application logic mixed with infrastructure concerns
        [ServiceBus(queueName: "orders-queue", Connection = "ServiceBusConnection")]
        IAsyncCollector<OrderPlacedEvent> output)
    {
        // ⚠️ application logic mixed with infrastructure concerns
        var userId = new UserId(Guid.Parse(req.HttpContext.User.Value)); // ⚠️

        var order = new Order(OrderId.New(), userId);
        dbContext.Orders.Add(order);

        await dbContext.SaveChangesAsync();
        await output.AddAsync(new OrderPlacedEvent(order.Id, userId)); // ⚠️
    }
}

Keep your business logic clean.

Isolate platform-dependent parts at the edges of your system, define application-level abstractions, and let the infrastructure layer handle cloud integration.

Don’t try to eliminate vendor lock-in entirely — manage it instead.

// Presentation Layer
public class PlaceOrderFunction
{
    private readonly PlaceOrderUseCase _useCase;

    public PlaceOrderFunction(PlaceOrderUseCase useCase)
    {
        _useCase = useCase;
    }
    
    [FunctionName("PlaceOrder")]
    public async Task Run(
        [HttpTrigger(AuthorizationLevel.Function, "post")] 
        HttpRequest req

        // ✅ do not rely on Azure Functions–specific bindings in your core logic
        /*IAsyncCollector<OrderPlacedEvent> output*/) 
    {
        await _useCase.ExecuteAsync();
    }
}

------------------------------------------------------------------------------------

// Application Layer
public class PlaceOrderUseCase
{
    private readonly ICurrentUserService _currentUserService;
    private readonly IDbContext _dbContext;
    private readonly IMessageBus _messageBus;

    public PlaceOrderUseCase(
        ICurrentUserService currentUserService
        IDbContext dbContext,
        IMessageBus messageBus)
    {
        _currentUserService = currentUserService;
        _dbContext = dbContext;
        _messageBus = messageBus;
    }

    public async Task ExecuteAsync()
    {
        // ✅ application logic uses abstractions
        var userId = _currentUserService.GetCurrentUserId(); // ✅

        var order = new Order(OrderId.New(), userId);
        _dbContext.Orders.Add(order);

        await _dbContext.SaveChangesAsync();
        await _messageBus.AddAsync(new OrderPlacedEvent(order.Id, userId)); // ✅
    }
}

From an architectural perspective, cloud-specific SDKs, configurations, and service integrations belong to the infrastructure layer and should be kept behind clear boundaries.

Treating the cloud as infrastructure preserves portability, keeps business logic clean, and prevents cloud providers from leaking into the core of your system. That way, even if you ever need to move, you’re not rewriting the whole system — just the parts that actually depend on the cloud.

Conclusion

• Serverless breaks applications into small, independently executed functions managed by the cloud.
• It works best for simple, event-driven, short-lived tasks — not complex or long-running processes.
• It excels at scalability, speed, and operational simplicity, but requires thoughtful design to avoid hidden complexity.
• Serverless does not eliminate the complexity of business logic — it forces you to split it into a smaller series of manageable steps.
• Additionally, you have to deal with orchestration, state management, communication, transactions, and consistency handling.
• Core limitations of serverless are timeouts, cold starts, and vendor lock-in.
• In practice, serverless is a powerful building block, but most real systems work best as a hybrid with traditional architectures.
• Used in the right context, serverless can significantly accelerate development and reduce costs.

That’s all folks 🐷 I hope you learned something new here 🤓 Give this article a clap 👏 Support me with coffee ☕️ And do not forget to follow to receive more ✅

Picture a common scenario with two microservices: one handling Orders and another managing Users. The Orders microservice needs to verify if a user is eligible to place an order based on their age.

Since the data is decentralized, the user’s information resides in the Users microservice.

The most straightforward and obvious solution that comes to mind is simply querying the missing information.

While simple, it adds latency because of the network overhead; the communication is synchronous, blocking the client until a response is received; services become dependent on each other’s functionality, resulting in tight coupling (if you move some behavior to another microservice, you need to rewrite all dependent clients), and so on and so forth.

An alternative approach would be to use events and solve the original problem this way:

• OrdersAPI creates its own projection of [User] table (but only with the columns it needs)
• then OrdersAPI subscribes for changes in UsersAPI
• when the user’s age changes, OrdersAPI updates the corresponding records in its own [User] table

Yes, it means data duplication; however, this time, OrdersAPI is self-sufficient. It has all the data needed to execute an action without making additional requests, without relying on the client microservice to be up and running, and without introducing coupling between services.

The approach where the system is designed to communicate by emitting and reacting to events, instead of calling each other directly, is called Event-Driven Architecture.

Nothing stops you from applying Event-Driven Architecture with CRUD applications, but it is usually a bad fit if strong consistency is a must.

On the other hand, it works great in distributed systems that require high scalability, loose coupling, and asynchronous workflows.

Let’s explore the core components that make up an event-driven architecture, examine the key characteristics of each one, and discuss the patterns that can be applied in practice. This will help build a solid understanding of how EDA works and how to design reliable, scalable systems with it 😜.

Overview

At its core, event-driven architecture models systems around the occurrence of events rather than direct method calls or requests.

Something happens → An event is published → Listeners react to events.

In this architecture, you can highlight the following components:

• event— a fact that something happened (UserRegisteredEvent, etc)
• event source (producer/publisher/emitter) — someone who produces an event
• event listener (consumer/subscriber/sink)— someone who reacts to the event
• event broker (message channel)— a tool through which the source and the listener exchange events

While it may look simple, let’s take a closer look at each of these concepts, as they are quite different from what we are used to in REST.

Events

In Event-Driven Architecture (EDA), events are facts that describe something that has already happened in the system.

Despite the name, an event is just a plain DTO class used as a data container.

class UserCreatedEvent : IEvent
{
    // metadata
    public Guid EventId { get; }

    // payload
    public int UserId { get; }
    public string UserName { get; }
    public string UserSurname { get; }
}

You can also inherit the marker interface to categorize messages or to apply cross-cutting behavior consistently.

Event Immutability

One of the most important characteristics is that events are immutable types. It derives from their nature, as an event represents something that happened in the past.

But there is also a practical reason for it. It is critical that no one can modify the contents of an event after it has been published; otherwise, it becomes impossible to know what was sent originally.

Event Types

In Event-Driven Architecture, messages can be classified by different types:

• Message — a generic term for any piece of information sent between components

• Event / Notification— something happened (UserCreatedEvent)
• Command — do something (CreateUserCommand)
• Document — here is the data (UserInfoDocument)

An event represents something that happened (UserCreatedEvent). They usually broadcast to multiple consumers. The publisher does not care who consumes it, what actions they take, and does not wait for a response from them.

A command instructs the receiver to take a specific action (CreateUserCommand). It is sent to a single receiver — similarly to a REST request, but without exposing the receiver’s API or coupling the sender to its implementation. The publisher may or may not expect a response through the same channel.

Messages are usually poorly suited for the request-response model, since you need to serialize the message, store it, retrieve and deserialize it back. However, it allows you to shift a heavy task to asynchronous background processing.

A document message conveys the entire snapshot of the state.

It allows the publisher to ignore how the data is used, what information is needed, or how many consumers will process it. Consumers can process, store, or forward the data without affecting the publisher or needing to coordinate with it.

As you might guess, in the Event-Driven Architecture, the most popular and used type is events 😅 . However, commands and document messages also play important roles.

⚠️ By the way ⚠️

Some projects may adopt different naming conventions or even assign their own terms to existing concepts — for example, some teams call an Event a Message. Therefore it is important to make sure, you understand their language, to avoid confusion and keep communication clear.

Event Semantic

Events can be categorized by their usage:

• domain events — are used to communicate changes and trigger reactions inside the application within the current bounded context
• integration events — are used to communicate changes and trigger reactions outside the application across different bounded contexts

Domain events are usually easy to work with since:

• they operate in-process and are primarily used to reduce coupling between components
• they can be published at any moment, as they are part of local transaction boundaries that respect ACID principles
• they typically contain smaller payloads, since event listeners are located within the same service, and their data requirements are clearly defined
• their structure is simpler to change, as versioning is often unnecessary
• they are usually exchanged through an in-memory bus and are not persisted; it is fine to lose them when the application crashes

Integration events require more careful design because:

• they are out-of-process and are used to notify external systems about the changes in state
• should be published only after the local transaction completes, when the local state has become stable, as they coordinate distributed transactions
• they carry more complex payloads with additional attributes, as different listeners may require different information
• their structure is more robust to evolve, as they need to be backward compatible, often requiring versioning
• they must be persisted in a durable out-of-process event bus, as they play a critical role in maintaining data consistency across the entire system

It is common to model the same business fact as both a domain event (such as UserAgeChangedDomainEvent) and an integration event (for example UserAgeChangedIntegrationEvent), with the integration event being mapped from the domain event for external communication.

Event Structure

An event typically consists of three parts:

• name — identifies the event and often reflects what happened
• metadata — contains technical information about the event
• payload — the actual data describing what happened

The event structure should be consistent and applied across all events, allowing consumers to handle them in a predictable way.

— name

In Event-Driven Architecture, the event name is not just a label — it’s a contract. It tells consumers what exactly happened in the system (UserAgeChanged).

By convention, event classes are usually named:

• in the past tense (UserCreated, OrderPaid)
• with an Event suffix (UserCreatedEvent)

This convention is widely used because it makes the intent obvious, but it’s not strictly required.

The event name also influences what must be included in the payload.

Generic names require richer payloads. An event like UserUpdatedEvent is vague. To make it useful, you typically need to include the previous and new states of an entity, so consumers can understand what actually changed.

Specific names can minimize payload. An event like UserDeletedEvent may need no payload at all. The name itself already fully describes what happened.

Additionaly, the name may include metadata, such as a version (UserCreatedEventV2). This can be useful for evolution and backward compatibility, but it should be applied to all events when.

— metadata

It is recommended, but not required, for every event to include metadata — technical information that makes events reliable, traceable, and safe to process.

Medatada typically includes the following properties:

• eventId — a unique event identifier (usually based on a GUID). Its primary purpose is audit and idempotency: ensuring that the same event is not processed more than once
• entityId (subjectId) — the identifier of the entity associated with this event (for example, an order or a user). It can be numeric, but in practice, a string is often chosen as a more generic and implementation-agnostic option
• version — indicates the schema version of the event. It allows events to evolve over time (adding or changing fields) without breaking consumers
• type — the event type that uniquely describes what happened (e.g., PaymentSuccess)

You may be wondering why the hell we need a type in metadata, if the event’s name should be sufficient 😅. Yes, event names are useful, but having a type in the metadata allows us to ease the refactoring (event renaming does not require changes in all consumers).

Similarly to eventId, it is also recommended to use a string instead of an enum for type. As it would allow for avoiding frequent changes to shared libraries, and reduce coupling between services.

You can also include other fields in metadata, like publishedBy, createdAt, correlationId, tenantId, and so on.

Metadata makes events self-describing. It allows consumers to process messages safely, trace their origin, avoid duplicates, and remain independent.

— payload

The payload is an optional part of an event that contains business data specific to that event.

There is no universal rule for what must be inside it. A common question is: what data should be included? How can a publishing service know in advance what data other consumers might need?

In theory, the publisher and consumers could agree on the exact data structure. And this is often an acceptable option if you have control over the producer and the consumer.

However, this creates tight coupling, which is especially undesirable in large systems or when events are exposed for external consumption.

Therefore, it is better when the publisher does not know how the data will be used, so publishers and consumers remain isolated and decoupled.

Choosing the right level of data granularity is crucial, so we’ll explore this in the next section.

Event Granularity

In EDA, it is important to choose how detailed or coarse your events are — how much information each event contains and how frequently they are emitted. Selecting the right granularity is crucial for clarity, performance, and maintainability.

For some events, no additional data is needed — their name or type is self-explanatory, so only the entity identifier is provided. The approach is called Event Notification.

While it may work for some events, others like UserAgeChanged, will cause consumers to fetch additional missing data explicitly via an API.

Small messages are lightweight, faster to process, minimize bandwidth, and easier for consumers to subscribe to. However, it is less scalable, slower due to additional queries, and creates coupling.

An alternative would be the Event-Carried State Transfer pattern, where the event carries all relevant state information related to the entity.

This method decreases coupling, scales more efficiently because consumers can handle the event without sending additional requests or putting extra load on the source.

However, larger messages increase network load, make serialization slower, can lead to data inconsistencies (as you have multiple sources of truth), and potentially can lead to data structure coupling.

The final choice is to use a document message and convey the entire snapshot of the entity state.

Document events are more challenging to listen to for specific changes, often requiring consumers to calculate deltas manually, and are less efficient in terms of memory and network bandwidth. However, they are easier to publish and eliminate the need for data fetching.

So, which option to choose?

The choice between those approaches depends on factors such as performance, memory usage, data ownership and consistency, consumer flexibility, coupling, and other requirements.

Publishing too many small events can overload the system and make the overall flow hard to understand — especially when you need to roll back changes. On the other hand, grouping too much into a single event can trigger unnecessary processing by consumers.

First and foremost, events exist because they are important for your domain. You should avoid modeling technical changes; focus on business-relevant transitions. An event should describe something that matters to a business stakeholder or domain expert.

Aim for balance by thinking about the impact of each event and whether consumers must dig into the payload just to decide how to react.

Event Versioning

Your application’s business logic changes over time. You may add fields, rename concepts, split/merge entities, etc.

However, old events that are already serialized, published, and stored in the broker still exist and will be consumed with outdated structures.

Therefore, you would have to manage event changes somehow.

First, keep in mind that some changes are backward-compatible — for example, adding a new property. If consumers don’t need this new property, they can simply ignore it.

However, if the change is significant (for example, renaming a property or removing important data), consumers will need to adapt. In such cases, you will likely introduce a version, either in the event name (e.g., UserNameChangedV1, UserNameChangedV2) or in its metadata. Consumers can support multiple versions in parallel and migrate safely as the event contract changes.

It’s also important to continue publishing older event versions until all consumers have migrated.

Event Reuse

When you have a publisher and subscribers sharing events, the first instinct is often to reduce code duplication by placing event definitions in some shared location.

You generally have a few options:

• Shared library (or a NuGet package) — this works well, but only if both producers and consumers are written in the same programming language
• Interface definition language (IDL) — you define an event schema, and each team uses tooling to generate event classes in their own language (similar to how Swagger/OpenAPI generates code from an API specification)

struct UserEvent {
    1: i32 userId,
    2: string name,
}

• Event duplication — sometimes duplicating code is perfectly fine 🙃. If events are pure DTOs with no logic, duplication avoids stamp coupling and allows consumers to have different schemas, deserializing only the fields they actually need

Event Source (Producer/Publisher/Emitter)

The next component we are going to discuss is an event source.

It is responsible for creating and publishing events when something meaningful happens in the system.

public class UserService : IUserService
{
    private readonly IEventProducer _eventProducer;

    public UserService(IEventProducer eventProducer)
    {
        _eventProducer = eventProducer;
    }

    public async Task CreateUser(User user)
    {
        // business logic
                  
                            . . .

        
        // publish events
        var event = new UserCreatedEvent(user.Id, user.Name);
        await _eventProducer.Publish(@event);
    }
}

The emitter does not care who will handle the event or what will happen next — it simply reports a fact and moves on.

This keeps the producer loosely coupled from consumers and helps the system evolve independently.

Let’s see how an event producer differs from the traditional REST approach.

Uncertainty in Event Delivery

With REST APIs, we send a request and can determine how successful it was based on the response. In the Event Driven Architecture, things become more complicated.

When we publish an event, there is no guarantee that it will not be lost.

For example, the event may be delivered to the message broker but not yet consumed. If the message broker fails, the message could be lost. From the service’s perspective, the delivery operation appears successful.

Even if the event is successfully delivered, we still have no way of knowing whether a consumer successfully processed it or if the order was right.

There could be no subscriber at all.

Moreover, we cannot know in advance when the event will be consumed.

This significantly complicates the overall application logic. If, for any reason, the consumer fails to receive or process this event, the system may end up in an inconsistent state. This responsibility is usually delegated to the message broker, which we’ll cover in the next sections.

Outbox Pattern

Ideally, all parts of your infrastructure (databases, message brokers, and other dependencies) should always be up and running. In practice, this is hard to achieve, and therefore, you should always try making your code robust and prepared for failure.

Consider a typical scenario where the message broker is unavailable. Your service successfully persists data in the database, but fails to publish the corresponding event.

As a result, an inconsistency appears between the event publisher and its consumers: the state has changed, but no event was emitted to notify other services.

This problem is commonly addressed using the Outbox pattern. Instead of publishing events after an operation has completed, the service stores them in the database during the transaction.

Later, a background process reads these stored events and publishes them to the message broker, ensuring reliable event delivery.

Batching Events

Sending (or persisting) messages one by one is highly inefficient. Moreover, since we do not expect an immediate response and communication is asynchronous, there is no real need to process each message individually.

To address this, the Message Sequence pattern is used. Messages are typically grouped into sequences (batches) and sent together, which improves throughput and reduces the overhead associated with message delivery.

Event Sourcing

When applying the Outbox pattern, an application performs two operations: persisting state and publishing events. These operations must stay in sync because they represent the same state transition. But what if you could rely only on events and compute the current application state from them? That is the idea of Event Sourcing.

Event-Driven Architecture and Event Sourcing are frequently used together because they complement each other naturally.

In EDA, events represent facts about what has already happened and are used to notify other parts of the system.

Event Sourcing takes this idea further by making those same events the source of truth for application state. Instead of storing only the current state, the system persists a sequence of domain events and rebuilds the state by replaying them.

This aligns perfectly with EDA, where events are already being produced and consumed.

⚠️ By the way ⚠️
When using a broker like Kafka to store events instead of a traditional database, it can effectively serve as both a data store and a message broker.

CQRS

If you opted in for Event Sourcing, it’s also a good idea to consider CQRS, especially when your service is frequently queried.

Implementing CQRS can help by improving query performance and reducing the need to constantly recalculate state from events.

Event Broker

After the event is created and published, it is sent to the event broker, a component through which the source and the listener exchange events

Sometimes developers wonder why we even need this component instead of directly sending events to each listener. This would result in tight coupling, making the system harder to maintain and scale.

Additionaly, handling failures or retries would become the producer’s responsibility, but as we are following the Single Responsibility principle, it's better to delegate the work to someone else 😅.

Technically, you could implement your own broker by storing events in a database and sending them to consumers, similar to a webhook mechanism. However, event-driven systems often have complex architectures and require advanced algorithms for efficient processing, routing, and delivery of events. Instead of building this from scratch, it is common practice to use existing, battle-tested solutions or proven architectural patterns.

Canonical Data Model

After the event is published, it is likely to be stored. However, which format should we use?

Technically, it’s possible to use one format for writing and another for reading, but this makes the system harder to understand and integrate.

The Canonical Data Model pattern addresses this by proposing a single, standardized data format for all participants in the message exchange.

Think of how we handle REST APIs: we usually pick a popular format like JSON and use HTTP as the transport protocol. This works well because almost every programming language has an HTTP client and libraries for creating and parsing JSON documents. It allows new microservices to be written in any language and run on any platform.

While being widely understood, JSON is not the most compact or performance-efficient format. There are others, like Protobuf or others. Just ensure it is platform-independent.

Topologies

In the Broker topology (Choreography), components publish events to a shared event broker, and other components decide independently whether to react to them or ignore them.

This approach works well when the event flow is relatively simple, but the lack of coordination makes multi-step business processes harder to manage.

Alternatively to this approach, we have the Mediator topology (Orchestration). Instead of broadcasting events, components publish events as commands to a specific mediator component.

The mediator manages process state, error handling, and retries, providing better control and consistency across distributed operations.

The trade-off is tighter coupling and the risk of the mediator becoming a bottleneck or single point of failure if poorly designed.

⚠️ By the way ⚠️

Typically, each domain has its own mediator, which helps reduce the risk of a single point of failure.

Communication Patterns

With the Event Bus pattern, participants are completely decoupled from each other. Services don’t need to know about each other, only about the bus. Consumers can act upon or filter out unwanted events, join or leave at any time.

If a message must have exactly one recipient, the Point-to-Point pattern is recommended, where both parties know about the channel. Even if multiple consumers are connected to the same message channel, only one of them will receive a given message. This pattern is usually implemented using queues and is more suitable for commands.

If a message should be delivered to all consumers, the Publish/Subscribe pattern should be used. This is typically implemented using topics and is ideal for events, where multiple consumers may need to react to the same events.

Datatype Channel

The Datatype Channel pattern promotes the idea of using one channel per event type.

In this approach, both the sender and the receiver know the channel name in advance and, based on it, understand what kind of data is published there and in which format (e.g UserCreatedEvent is published in UserCreatedEventChannel).

As a result, messages do not need to include extra metadata describing their structure or having additional logic to filter, transform or deserialize to correct types when processing the events.

Message Consumption Models

Messages can be delivered in two ways: push-based, where consumers receive messages automatically, and pull-based, where consumers read stored messages when ready.

In the publish/subscribe model, the messaging infrastructure manages subscriptions. When an event is published, it is pushed to all registered subscribers. It is simple, provides low latency, and is good for real-time reactions, but you cannot replay events, or you can even miss some if subscribed later.

In the event streaming model, events are appended to the list. Consumers read events from this stream. It is harder to implement, requires more storage space, but you can make sure events will be handled even when the consumer disconnects, you can easily reply to events, and handle them at your own pace.

Broker Reliability

A message broker can handle events in different ways: it may persist them temporarily in memory (for example, RedisMQ) or store them in durable storage, ensuring that messages remain in the system even after broker restarts or shutdowns.

The choice depends on balancing these factors:

• durability: Do I need a history of incoming messages (pull model), or messages are deleted after they are processed (push model)?
• scalability: Is the incoming message processed by another application? By multiple consumers?
• latency: How crucial is the time it takes to store and retrieve the message?
• resilience: Can I afford to lose all persisted inbox messages when the application goes down?

Often, in a large distributed system, it’s important that messages are not lost— even if the broker was temporarily down. Therefore, this requires the messaging system to have reliable storage for messages.

The Guaranteed Delivery pattern ensures that a message is stored in the system and not removed until all consumers have processed it.

Additionaly, it is also necessary to track the state of each consumer — what messages they have already read and which are still pending. This prevents missed messages if a consumer becomes overloaded or temporarily unavailable.

The Durable Subscriber pattern addresses this, requiring each consumer to have a unique identifier so it can be distinguished from others.

Message-Delivery Semantics

Depending on what matters more to your business — guaranteed delivery or single processing — different message delivery semantics can be applied.

Notice, exactly-once seems like an ideal option, but achieving it is nearly impossible because a message may be processed multiple times — especially after failures — so consumers must be designed to handle reprocessing safely using the Idempotent Receiver pattern to prevent duplicate side effects.

Dead Letter Channel

If an error occurs while processing a message due to its invalid content, the Dead Letter Channel pattern suggests routing the “poisoned” message to a special channel for further analysis and troubleshooting.

Note, this pattern applies both to push-based topics and pull-based channels, where messages can be skipped or deferred during processing.

Event Listener

The final component we are going to discuss is event listeners. They are responsible for receiving events from the event broker and reacting to them by executing some business logic.

An event consumer subscribes to one or more event types and is triggered whenever a relevant event occurs.

public class UserCreatedEventHandler : IEventHandler<UserCreatedEvent>
{
    public async Task Handle(UserCreatedEvent @event)
    {
        // react to the event
        // for example: send email, update local record in DB, etc...
    }
}

The consumer focuses only on what to do when the event happens, not on who produced the event.

Multiple consumers can react to the same event independently, each implementing its own behavior.

This loose coupling is one of the key strengths of Event-Driven Architecture and is a major difference compared to traditional REST-based communication, where services must explicitly call each other and coordinate execution.

Message Consumption Models

We already discussed this from the broker’s perspective, but let’s revisit the same terminology from the consumer’s.

When the consumer subscribes to messages and provides an asynchronous callback method that is automatically invoked whenever a message arrives, it is the Event-Driven Consumer pattern.

If a consumer is ready to receive messages and synchronously waits for new messages, it is known as the Polling Consumer pattern.

Asynchronous Processing

In an event-driven architecture, producers and consumers are decoupled, allowing them to work independently of each other’s performance.

This is especially useful when consumers are slower than producers, as messages can be buffered and processed at their own pace without blocking the producer.

From a performance and scalability perspective, asynchronous event processing is a major advantage. However, it also introduces additional complexity in managing cross-service communication, including logging, distributed tracing, error handling, and distributed transactions.

Competing Consumers Pattern

Processing messages one by one is simple, but it is not the fastest approach. And what do we do to improve throughput? We scale, vertically or horizontally.

Let’s say we add more instances of the same server. It means messages can be processed in parallel. However, when multiple consumers compete for messages in the same message channel, multiple challenges arise, like handling messages only once, proper message ordering, load balancing, fault tolerance, etc.

⚠️ By the way ⚠️

Although multiple consumers are involved, this is not the same as the Publish-Subscribe pattern. With Competing Consumers, each message is handled once, whereas in Pub/Sub, every consumer receives a message.

Eventual Consistency

As components are decoupled and communicate asynchronously, it is quite hard to achieve strong consistency.

When data is distributed across components and updated via events, changes don’t propagate instantly — they require time to reach all parts of the system. Users may see outdated data. This results in eventual consistency. It means that data will be updated… eventually 😁. But not immediately.

Of course, if both the publisher and the consumer are part of the same process, they can be grouped under a single transactional scope, ensuring atomic execution. However, this effectively collapses the system back into a tightly coupled, synchronous design and defeats the core purpose of EDA.

As a result, most EDA systems typically favor eventual consistency, accepting temporary inconsistencies in exchange for scalability, resilience, and loose coupling.

Client Acknowledgement Mode

A message can be acknowledged as soon as it is received or processed, but this approach can lead to serious issues.

One common problem is consumer failure — either software or hardware — during message processing. If the message is marked as acknowledged in the broker before processing completes, the message is effectively lost and will never be handled.

To avoid this, consumers can use manual acknowledgements, confirming message consumption only after successful processing.

Idempotency

Idempotency is a property of an operation, which guarantees that performing the operation multiple times will yield the same result as if it was executed only once

Or in plain English: if an event consumer, due to a system bug, receives the same “charge money” event ten times, the payment will be processed only once.

Idempotency is a critical concept in event-driven architectures because message delivery is not guaranteed to happen exactly once.

Picture this: a consumer starts processing an event, updates the database, but fails before acknowledging it; the message broker retries delivering the same event. As a result, a consumer receives duplicate messages.

To prevent this, consumers should be designed so that processing the same event multiple times produces the same outcome as processing it once. This is commonly achieved by tracking processed event identifiers, using idempotency keys, or relying on database constraints.

Without idempotent handling, retries can lead to inconsistent state, duplicated side effects, or corrupted data.

Compensating Transactions

Error handling becomes especially challenging in distributed systems due to the lack of atomicity. The more services that participate in a single business transaction, the harder it is to guarantee that all steps either succeed or fail together.

For instance, a service executes an action successfully, but later the system discovers that the next consumer fails. In such cases, it must reverse the operation by publishing a compensating event that undoes the previous action.

The difficulty is that these steps occur asynchronously. Compensating transactions are rarely a simple rollback of the original operation. By the time compensation runs, the system state may have already changed due to other transactions, which makes reliable recovery even more complex.

CQRS

CQRS is not limited to the producer side and can be effectively applied to consumers, too.

Since CQRS operates in an asynchronous world, commands can be delivered to consumers via a queue, processed independently, and the resulting outcomes can be published back to the event bus.

Summary

As you see, compared to REST, Event Driven Architecture does not have well-established conventions.

Which event (or events) should be emitted? How should event classes be named, and what data should they contain? How can we be sure that the provided information is sufficient for other services to handle the event correctly?

Fortunately, we can rely on multiple practices and patterns 🙃.

• The core idea of Event-Driven Architecture (EDA) is to produce an event on every state change. Something happens → an event is created
• Despite its conceptual simplicity, this architecture works regardless of your scale: with classes, modules, or distributed microservices
• Many projects combine Event-Driven Architecture with others like microservices, modular monoliths, etc
• EDA does not mean microservices, but often complete them
• Use this architecture when multiple subsystems need to handle the same events, and you want to decouple producers from consumers to scale and evolve them independently
• The clear benefits are that it decouples producers and consumers, improves scalability, resilience, and performance through asynchronous processing and horizontal scaling
• The challenges it brings are increased infrastructure costs and operational complexity, complex error handling, data inconsistency, event ordering, idempotency, and data loss

Pick the approach that best suits the complexity and requirements of your domain 😉

Give this article a clap or a few if you like it 👏
You can support me with the link below ☕️
Don’t forget to follow to receive more ✅
Out the door, dinosaur 🦖

Imagine you are sitting in a room waiting for the phone to ring. You don’t constantly check the phone every second, asking: “Did someone call? Did someone call now?”. You're just doing your work. And when the phone rings, you react.

It turns out many real-life processes work exactly this way. Moreover, this is how many applications work, too. This way of writing programs can even lead to a completely different programming style: instead of constantly checking whether something happened, a program can simply wait for events and react when they occur.

This concept is known as Event-Driven Programming. In this article, we will explore what this paradigm is all about: the different ways components communicate — such as Observer, Mediator, and Event Bus — and common techniques for handling events, including debouncing vs throttling, buffering, batch processing, and event aggregation.

In case you are interested in other programming paradigms, look here:

• Structured Programming
• Object-Oriented Programming
• Aspect-Oriented Programming
• Functional Programming
• Event-Driven Programming
• Reactive Programming

Are you ready?😃 Let us begin.

Event-Driven Programming

The popularity of event-driven architectures comes from a simple fact: the imperative paradigm (executing commands step by step) doesn’t reflect how the real world works.

While most programs execute code in a linear flow, each step is explicitly invoked after the next one:

var order = CreateOrder();

SendNotification(order);
ChargePayment(order);
LogOrder(order);

In the real world (and in many systems too), actions are triggered as a result of other actions.

var onEvent = _eventBroker.When<OrderCreated>();

onEvent.Execute((o) => SendNotification(o));
onEvent.Execute((o) => ChargePayment(o));
onEvent.Execute((o) => LogOrder(o));

The simple concept of publishing events and responding with callbacks can serve as the foundation for an entire programming paradigm:

Event-Driven Programming (EDP) is a programming paradigm in which operations are triggered by changes in state of other objects.

Many things can trigger events: a user clicking a button, a payment succeeding, an object being added to a collection — essentially, anything that changes the system’s state.

Once you start noticing it, event-driven programming appears everywhere 😁.

However, applying an event-driven approach can also make the program harder to reason about. Instead of a clear sequence of function calls, behavior is spread across many event handlers, which can complicate debugging, make it harder to trace the flow of execution, and increase the cognitive load for developers.

Let’s take a closer look and see what it means in practice.

Core Concepts

At its core, event-driven programming models systems around the occurrence of events rather than direct method calls.

Something happens → An event is published → Callbacks are triggered.

In this paradigm, you can highlight the following components:

• event — a fact that something happened (UserRegisteredEvent, etc)
• event source (producer/publisher/emitter) — someone who produces an event
• event listener (consumer/subscriber/sink) — someone who reacts to the event
• event broker (event loop) — a tool through which the source and the listener exchange events

Event Communication Patterns

In event-driven systems, components need a way to produce and react to events. Several patterns organize this communication, each providing a different level of decoupling and control.

Let’s look at some common approaches.

Observer

Imagine you build a system that sends notifications when an order is created. Multiple parts of the system may be interested in this event — one component may send an email, another update the cache, and a third one writes logs.

A naive approach would be to call all these components directly from the order service.

public class OrderService
{
                .  .  .
    public void CreateOrder(string orderId)
    {
        var order = new Order();

        _emailService.SendEmail(order);
        _cacheService.UpdateCache(order);
        _logger.AutidLog(order);
    }
}

But this tightly couples the order creation logic with every feature that needs to react to it. As the system grows, the code becomes harder to maintain.

To solve this, we can apply the Observer pattern. Publishes an event so anyone can subscribe to it and react when it happens.

public class OrderService
{
    public event Action<Order> OrderCreated;

    public void CreateOrder(string orderId)
    {
        var order = new Order();
        OrderCreated?.Invoke(order);
    }
}

public class EmailNotifier
{
    public void OnOrderCreated(Order order)
    {
                .  .  .
    }
}

------------------------------------------------------------------------

orderService.OrderCreated += _emailNotifier.OnOrderCreated;
orderService.OrderCreated += _cacheService.OnOrderCreated;
orderService.OrderCreated += _logger.OnOrderCreated;

This way, the event producer does not need to know who is listening. New functionality can be added by simply creating a new event handler without modifying the existing code.

This pattern is widely used in UI frameworks like WinForms, HTML + JavaScript, or any MVP model, where the UI control and its event handler are naturally tied together. However, in the backend API server, where component state is renewed per request, maintaining persistent subscriptions across requests is difficult.

Mediator

Imagine you have multiple services in a system that need to communicate with each other in both directions. If each service directly triggers the others, you’d have multiple subscriptions and dependencies everywhere, and the system quickly becomes tangled and hard to maintain.

To address this, we can use the Mediator pattern. With it, all communication is centralized — services interact with each other indirectly through the mediator.

public interface IEventMediator
{
    event Action<Order> OrderCreated;
    void PublishOrderCreatedEvent(Order order);

    event Action<Order> OrderUpdated;
    void PublishOrderUpdatedEvent(Order order);
}

public class OrderService(IEventMediator _mediator)
{
    public void CreateOrder(string orderId)
    {
        var order = new Order(orderId);
        _mediator.PublishOrderCreatedEvent(order);
    }
}

________________________________________________________________________

_mediator.OrderCreated += _emailNotifier.OnOrderCreated;
_mediator.OrderCreated += _cacheService.OnOrderCreated;
_mediator.OrderCreated += _logger.OnOrderCreated;

Here, email, cache, or logging services do not know about the OrderService . The mediator handles all communication.

The always-on Mediator works well in backend systems, where components are often short-lived or stateless, because it is durable, centralizes interactions, and avoids the problem of maintaining persistent subscriptions.

Bus

If you want to take decoupling one step further, just like the mediator, you can implement an Event Bus to coordinate communication between components.

With a mediator, there is a central object that knows how components interact. But an event bus removes even that knowledge. Components simply publish events, and any component that is interested can subscribe to them.

interface IEvent { }

class OrderCreatedEvent : IEvent { . . . }
class OrderUpdatedEvent : IEvent { . . . }

public interface IEventBus
{
    void Subscribe<TEvent>(Action<TEvent> handler);
    void Publish(IEvent e);
}

----------------------------------------------------------------------

// a component can publish an event:
_eventBus.Publish(new OrderCreatedEvent());

// and other components can subscribe to it:
_eventBus.Subscribe<OrderCreatedEvent>(e =>
{
    // send email
});

_eventBus.Subscribe<OrderCreatedEvent>(e =>
{
    // update metrics
});

However, this flexibility comes with a trade-off. With an event bus, it becomes harder to track navigation in the codebase. Since there are no direct references between components, IDE tools cannot easily show the full flow of events. Understanding who publishes and who handles an event often requires additional investigation and clean code conventions.

Event Processing Patterns

With these core concepts in place, we can look at common patterns used in event-driven systems. These patterns solve recurring problems such as how events are delivered, how event flow is managed, and how event frequency is controlled.

Debouncing

Imagine you implement a typical search bar. Every time a user types a character, an event fires.

If we send a request to the API on every keystroke and rerender the results immediately, it becomes wasteful and can overload the system.

To optimize this, we can apply debouncing. It will trigger one event only when the user has stopped typing in the search bar for at least 500 milliseconds.

There are many similar scenarios where events fire very frequently, but the work they trigger is expensive — typing in an input field, resizing a window (where you could have thousand events per second), applying many filters, etc.

In such cases, debouncing delays execution of an event handler until a certain amount of time has passed without new events.

Throttling

Imagine you design a fighting game. Each time a user presses a button, it triggers an event.

Usually, players press buttons very rapidly to perform an attack. For example, 10 times within a second, while the character in the game is only able to perform one attack.

In such cases, it makes sense to throttle the events. Throttling ensures that the event is triggered once within a certain period.

There are many other scenarios where this technique is useful — such as rapid mouse clicks, users clicking a button multiple times instead of once, continuous scrolling, or rate limiting.

Buffering

Both debouncing and throttling reject excessive events to execute an operation once in a certain period.

However, sometimes you need to handle all the events. For example, your system processes images uploaded by users. Each time a user uploads an image, an event is generated to start processing it.

The thing is that processing an image takes time, and multiple users may upload images faster than the system can handle them.

In such cases, it makes sense to buffer the events. Instead of processing each event immediately, the system places events in a queue, allowing consumers to handle them at their own pace.

This approach ensures that consumers can handle the workload at a sustainable rate. Buffering is commonly used in systems where the event producer is faster than the consumer, such as video processing, order processing, or background task execution.

Batch Processing

Let’s say your component writes logs from all the events. Every time something happens, a log event is generated and persisted in a database.

If the system writes every log entry to the storage immediately, it may perform many small and expensive operations.

In such cases, it makes sense to apply batch processing. Instead of processing each event right away, the system handles a group of them.

For example, the application may collect log events for a few seconds, buffer them to a queue, and then write them to the database in a one batch.

This approach is useful to reduce the large number of operations and improve performance when many events occur within a short period of time.

Event Aggregation / Coalescing

It is common for a website analytics system to track how many users are viewing a page in real time. Every user action — like loading a page or clicking a link — generates an event.

If thousands of users interact at once, processing each event individually could overload the system.

In such cases, it makes sense to aggregate events. Instead of updating the dashboard for every single event, the system collects events over a short time window — say 1 second — combines them into one event, and then updates the total number of active users at once.

This approach reduces the number of events, improves performance, and still provides accurate data.

Personal Opinion🤔

Event-Driven Programming is a powerful paradigm that describes how code inside an application is structured; however, it is rarely used in isolation and is typically combined with other programming approaches when applied, if applied at all 😬.

Developers are generally more familiar with imperative programming, and most frameworks are designed to encourage that style. Even though, in C#, events exist as a language feature, they are somewhat obscure and rarely used, except in Windows Forms, while modern UI frameworks tend to rely on data binding instead.

Beign said that EDP still shines in user interfaces, games, monitoring, and other event-driven systems, where it keeps the UI responsive and prevents the application from freezing when actions are triggered.

It can also be applied in backend systems, particularly in Domain-Driven Design (DDD) or microservices architectures, to improve loose coupling, scalability, and performance.

Moreover, this simple code style inspired an entire architecture style, Event-Driven Architectures (EDA), where events coordinate actions across services.

Conclusion

Event-Driven Programming is a paradigm that focuses on reacting to events rather than executing instructions sequentially.

It promotes loose coupling and responsiveness. EDP helps manage complexity by decoupling components, enabling asynchronous processing, improving modularity and reusability, and allowing the system to react and scale more easily.

Here are some of the main advantages:

• loose coupling. components don’t need to know about each other. They only communicate through events.
• modularity: separating event generation from event handling allows components to be developed, tested, and maintained independently
• scalability
   — producers don’t wait for consumers to finish, they emit an event and continue their work.
   — multiple consumers can process the same event in parallel.
• extensibility. you can add new features without changing existing components.

💬 Let me know in the comments how often you face the Event-Driven Paradigm?

👏 Clap if you find something new here

☕️ Support me if you want

✅ Follow

😉 And stay awesome

Every developer at least once experienced tangled code where responsibilities are mixed, and even a small change feels risky and painful to make.

What should be a simple modification turns into a chain reaction. You touch one class, three others break. The kind of complexity comes from uncontrolled dependencies pointing in every direction.

Uncontrolled dependencies often don’t stay linear — they quietly turn into circles. At first, everything seems fine, but if you start tracing who depends on whom, you suddenly find yourself back where you started. That’s usually a sign the design has drifted, and boundaries are no longer clear.

Circular dependencies are a problem because they tightly couple components, making them hard to understand, test, reuse, or change independently. They break modularity, increase cognitive load, and most importantly, they signal unclear responsibilities and weak architectural boundaries — and that pain only grows as the system scales.

Therefore, according to The Acyclic Dependencies Principle, the dependency graph must have no cycles. It is preferable for dependencies to be pointed out in the form of an acyclic graph or even a tree (ideally, but unlikely)

The rule applies regardless of scale — whether you’re dealing with individual classes, projects within a monolith, or even microservices.

A circular dependency between two small classes is a design smell that can cause runtime issues (especially with DI containers); the same anti-pattern between projects can block builds; and between microservices, it can create tight coupling at the system level. The size changes, but the architectural damage follows the same pattern.

There is also some good news 🙃. Both the problem and the solution have been known for a long time. For example, traditional N-layered architecture was designed specifically to enforce clear, one-directional dependencies between components.

However, as time goes on, the structure becomes unstable and starts to sprawl. A few messy dependencies, and you have cycles. Once they appear, you can’t ignore them. Cycles must be broken to restore clarity and stability. Fortunately, no matter the situation, there are always ways to deal with them 😉.

Cycle-Breaking Techniques

When you face cycles in a system across multiple components, it may look overwhelming at first.

However, you don’t need to solve everything at once. Just pick any dependency, and eliminate a cycle there.

All cycle-breaking strategies come down to one of these moves:

• change direction of dependency (Dependency Inversion)
• restructure logic
• decouple the system with events

Each of them changes how responsibilities and dependencies are arranged in the system, so the dependency graph becomes acyclic again.

Let’s see it in practice, with the simplest case: a cycle formed by two components that directly reference each other.

In this example, OrderService depends on PaymentService, and PaymentService depends on OrderService. Each service calls the other to complete its work, which creates a circular dependency.

public class OrderService(PaymentService _paymentService)
{
    public void CreateOrder(Order order)
    {
        _paymentService.ProcessPayment(order.Id);
    }

    public void MarkAsPaid(Guid orderId)
    {
        Console.WriteLine("Order marked as paid");
    }
}

public class PaymentService(OrderService _orderService)
{
    public void ProcessPayment(Guid orderId)
    {
        Console.WriteLine("Payment processed");

        _orderService.MarkAsPaid(orderId);
    }
}

This is the smallest possible cycle, but if you learn how to break the dependency here, the same techniques can be applied to much larger dependency graphs.

In practice, complex cycles are usually just combinations of many small cycles like this.

— Dependency Inversion

One way to break a cycle is to revert a dependency on an interface rather than on an implementation, by applying the Dependency Inversion principle.

Instead of PaymentService depending on concrete OrderService, it depends on an abstraction (IOrderUpdater). This way, all the dependencies crossing the boundaries are pointing in the same direction.

The interface represents the behavior PaymentService actually needs. Instead of referencing the entire OrderService, the dependency is narrowed to just the operation required to update the order state.

public class OrderService(PaymentService _paymentService) 
  : IOrderUpdater // 👈 
{
    public void CreateOrder(Order order)
    {
        _paymentService.ProcessPayment(order.Id);
    }

    public void MarkAsPaid(Guid orderId)
    {
        Console.WriteLine("Order marked as paid");
    }
}

------------------------------------------------------------------------

public interface IOrderUpdater
{
    void MarkAsPaid(Guid orderId);
}

public class PaymentService(IOrderUpdater _orderUpdater) // 👈
{
    public void ProcessPayment(Guid orderId)
    {
        Console.WriteLine("Payment processed");

        _orderUpdater.MarkAsPaid(orderId);
    }
}

After this change, PaymentService no longer knows about OrderService directly. It only interacts with the IOrderUpdater abstraction. OrderService provides the implementation, but the dependency is now inverted, which removes the direct cycle between the two components.

— Restructure Logic

Circular dependencies are almost always a red flag. It is often a signal that responsibilities are misplaced.

In that case, the solution is often to reorganize the code in one of the following ways.

• merge responsibilities into a single component

If two components constantly call each other, they may actually represent one cohesive responsibility that was artificially split. Instead of forcing them to collaborate through a back-and-forth dependency, it can be simpler to combine them into a single component.

This approach works well when the logic naturally belongs to one use case. By merging components, the control flow becomes explicit and easier to reason about.

public class CheckoutService
{
                      .  .  .

    public async Task Checkout(CreateOrderRequest request)
    {
        var order = Order.Create(request.Items);

        var paymentResult = await _paymentGateway.Charge(request.PaymentDetails, order.Total);

        order.MarkAsPaid();

        await _orderRepository.Save(order);
    }
}

• consolidating responsibility in one of the components

In case the services are truly independent and cannot be merged, but you still have a cycle, this can mean that their responsibilities were chosen poorly.

In such cases, the simplest solution is to move the relevant logic into a single component and make it responsible for the entire operation.

Here, the responsibility for the process is consolidated in OrderService. It creates the order, triggers the payment, and completes the workflow by marking the order as paid.

PaymentService only performs its core task—processing the payment—without knowing anything about orders.

public class OrderService(PaymentService _paymentService)
{
    public void CreateOrder(Order order)
    {
        _paymentService.ProcessPayment(order.Id);
     
         MarkAsPaid();
    }
}

public class PaymentService
{
    public void ProcessPayment(Guid orderId)
    {
        Console.WriteLine("Payment processed");
    }
}

By clarifying ownership of the workflow, the dependency becomes one-directional, and the cycle disappears.

• introducing a new shared component

You may find that the functionality doesn’t naturally belong to either service.

It would be a good idea to extract the shared logic into a separate component. Both services can then use this new component independently, removing the direct dependency between them.

The shared component handles the cross-cutting functionality (MarkAsPaid), so OrderService and PaymentService no longer depend directly on each other:

public class OrderService(
  PaymentService _paymentService, 
  OrderStateManager _orderStateManager)
{
    public void CreateOrder(Order order)
    {
        _paymentService.ProcessPayment(order.Id);
        _orderStateManager.MarkAsPaid(order.Id);
    }
}

public class PaymentService
{
    public void ProcessPayment(Guid orderId)
    {
        Console.WriteLine("Payment processed");
    }
}

// Shared component handling Order state logic
public class OrderStateManager(IOrderRepository _orderRepository)
{
    public void MarkAsPaid(Guid orderId)
    {
        var order = _orderRepository.Get(orderId);
        order.MarkAsPaid();
        _orderRepository.Save(order);
    }
}

• introduce the coordinator component

Sometimes a cycle appears because the domain logic is anemic, and services at the same layer end up coordinating behavior between themselves.

Instead of services calling each other, you can introduce an orchestrator above them, usually in an upper layer, such as the Application layer.

This component becomes responsible for sequencing the operations while the lower-level services focus only on their specific tasks.

public class OrderApplicationService(
    OrderService _orderService,
    PaymentService _paymentService)
{
    public void Handle(CreateOrderRequest request)
    {
        _orderService.CreateOrder(request.Order);
        _paymentService.ProcessPayment(request.Order.Id);
        _orderService.MarkAsPaid(request.Order.Id);
    }
}

• push the behavior to a deeper layer

Rather than introducing a component above them, some of the work can be pushed down to deeper layers, such as the domain model or infrastructure utilities.

When the domain object owns the rule, services no longer need to coordinate back and forth, and the cycle disappears.

public class OrderService(PaymentService _paymentService)
{
    public void CreateOrder(Order order)
    {
        _paymentService.ProcessPayment(order);
    }
}

public class PaymentService
{
    public void ProcessPayment(Order order)
    {
        Console.WriteLine("Payment processed");

        order.MarkAsPaid();
    }
}

class Order
{
                  .  .  .
 
    public bool IsPaid { get; private set; }

    public void MarkAsPaid()
    {
        IsPaid = true;
    }
}

— decouple the system with events

Another strong solution to reduce coupling and break direct dependencies between components is to communicate through events.

Instead of calling each other directly, services publish events describing what happened, and other components react to those events. This removes the need for services to reference each other.

In this approach, components depend only on an event bus and the event contracts, not on each other’s implementations.

public record OrderCreatedEvent(Guid OrderId);
public record PaymentProcessedEvent(Guid OrderId);

public class OrderService(IEventBus _eventBus): IEventHandler<PaymentProcessedEvent>
{
    public void CreateOrder(Order order)
    {
        Console.WriteLine("Create order");

        _eventBus.Publish(new OrderCreatedEvent(orderId));
    }

    public void Handle(PaymentProcessedEvent e)
    {
        Console.WriteLine("Order marked as paid");
    }
}

public class PaymentService(IEventBus _eventBus) : IEventHandler<OrderCreatedEvent>
{
    public void Handle(OrderCreatedEvent e)
    {
        Console.WriteLine("Payment processed");

        _eventBus.Publish(new PaymentProcessedEvent(orderId));
    }
}

Notice that the services no longer depend on each other. However, it is important to remember that logical cycles can still exist in event-driven systems. One event may trigger another, which eventually leads back to the original component, creating an infinite loop of publishes and handlers.

Summary

In a system with many components, it is inevitable for one to depend on another. Managing those dependencies helps to shape the structure of the system and determine how easy it is to maintain the code.

• Uncontrolled references between components gradually turn a system into a tangled structure where dependencies point in every direction.
• Mixed responsibilities often create cycles, where a change in one component triggers a cascade of changes in another.
• Cycles tightly couple components, making systems harder to understand, test, and change.
• The core goal is to restore one-directional dependencies so the architecture forms an acyclic graph.
• Most solutions fall into three categories: dependency inversion, restructuring responsibilities, or decoupling with events.
• Large cycles can often be fixed simply by resolving a single misplaced dependency.

Give this article a clap or a few if you like it 👏
You can support me with a link below ☕️
And don’t forget to follow ✅

It is common to build backend architectures around horizontal layers. We separate systems into familiar tiers like presentation, infrastructure, application, and domain, each responsible for a specific technical concern.

However, there is an alternative approach: vertical architecture. Instead of organizing code around technical concerns, the system is structured around features, with each vertical slice containing everything it needs — from API to persistence.

Let’s explore what vertical architecture is, the challenges you may face when adopting it, how to share code effectively, where to draw boundaries, and how features communicate with each other.

Problem with Traditional Layered Architecture

In a well-known layered architecture, when adding or modifying a feature, the change rarely stays in one place. Even a small functionality typically forces you to touch multiple layers at once:

• you start by updating the Domain, changing entities, introducing new rules and constraints
• then you add new tables, repositories, or DB objects, corresponding mappers in the Infrastructure layer
• after that, you modify or create a use case, adjust validation logic, add DTOs, and more mapping code in the Application layer
• finally, you expose everything through a controller or API endpoint in the Presentation layer

Instead of focusing on the feature itself, you end up coordinating changes across technical boundaries. This increases cognitive load and raises the risk of breaking unrelated parts of the system.

Layers are about managing coupling in a clear way, not cohesion.

What Vertical Slice Architecture Is

Vertical slice architecture takes a different approach.

Slices are about maximizing cohesion within a slice and minimizing coupling between them.

It builds on ideas from Screaming Architecture, but puts it further. Slices organized the code by feature, not by technical concern. This means that each slice contains everything it needs (API, use case, validation, business logic, persistence, infrastructure, etc).

So if you need to update functionality, all the changes will be concentrated within a single slice.

The benefits are:

• changes are localized within a single slice
• code navigation becomes simpler
• folders remain small and focused, making them easier to manage and maintain
• the risk of breaking unrelated functionality is reduced
• features evolve independently
• teams work in parallel
• developers better understand the system's business capability
• it’s easier to understand a module, its available use cases, the used infrastructure, etc
• adding a new feature is easier, as you can identify similar behavior and replicate the structure
• removing a feature is straightforward because you can simply delete the entire folder without affecting unrelated code
• refactoring becomes easier; it is simpler to move, reorganize, or restructure functionality without impacting other parts of the system
• extracting functionality from a folder into a separate project becomes easier, since related code is already grouped and self-contained
• and so on and so forth…

You may be thinking: “Sounds like some kind of magic. So why isn’t everyone applying it everywhere? 🤔”.

Don’t push the horses. There are reasons 😅. The most common problems are:

• slice granularity
• code sharing
• slices communication

Let’s address each problem one by one.

Slice Granularity

You might think, in theory, that you know where one slice ends and another begins. Buuuut… in practice, you’ll encounter many pitfalls before getting it right 😒.

While, for most people, grouping code by categories such as business logic or API endpoints is relatively simple to comprehend, organizing code within slices is more complex.

Defining boundaries is hard. Should you group around an entity or an aggregate? Around an action or a use case? Around a feature?

There is no one good solution.

Some claim that slicing by actions is wise, as you can use different tools for each action, but this is rarely practical and results in too thin slices.

You can also group by entities, as it feels more intuitive. This way, you can combine all operations over a single entity into one slice. But business concepts often span multiple entities. Therefore, it’s usually better to organize code around aggregate boundaries.

Finally, and the way I recommend, is to design each slice around the entire feature. It is the broadest but also the most isolated concept.

But what is even a feature 🤔?

A feature is a complete business capability that enables a user to achieve a specific goal. It represents a meaningful outcome, delivers measurable value, and can be understood, discussed, prioritized and used independently.

Such features could be course offering, student management, enrollment workflow, etc.

A feature may span multiple aggregates, or it may be contained within just one endpoint, depending on the scope of the business capability it represents. You should define a slice around functionality that is meaningful to your business stakeholders, and not by the number of entities it includes. The key is that each slice fully encapsulates the feature it serves, keeping it cohesive, understandable, and easy to evolve.

Long story short, if your slices are too thin, you’ll likely end up with more shared code and duplication. On the other hand, slices that are too chunky risk turning into spaghetti code. This architecture demands stronger discipline, thorough code reviews, and constant boundary re-evaluation.

Code Sharing

In vertical slice architecture, your goal is to have independent, self-contained slices. Buuuut… it is easier said than done 😒.

Sometimes you need to share business invariants, rules, or even entities across multiple slices; other times, what needs to be shared is infrastructure, such as caching, persistence, or logging.

Therefore, you typically introduce layers above and/or below the slices. A common approach is to add the following supporting layers:

• Core — define a foundation for your slices, containing part of the framework (composition root, UI pages layout, middlewares, etc)
• Shared — shared infrastructure code, such as persistence, caching, logging, message bus, reused across multiple slices

Notice that even here we have dependency rules: references should flow from top to bottom, not the other way around, and never horizontally between slices.

For example, your Core module references each slice to execute an action triggered by the UI:

[ApiController]
[Route("api/course")]
public class CourseController : ControllerBase
{
    [HttpPost("create")]
    public IActionResult CreateCourse([FromServices] ICourseSliceApi sliceApi)
    {
        var result = sliceApi.CreateCourse();

        return Ok(result);
    }
}

On the other side, your slice can define the interface:

public interface ICourseDbContext
{
    DbSet<Course> Courses { get; }
    DbSet<Lesson> Modules { get; }
    DbSet<Lesson> Lessons { get; }

    Task<int> SaveChangesAsync(CancellationToken cancellationToken = default);
}

Where the implementation will be provided in the underneath shared layer:

public class AppDbContext : DbContext, 
  ICourseDbContext,  // 👈 course slice 
  IStudentDbContext, // 👈 students slice
  ...
{
    public DbSet<Course> Courses { get; set; }
    public DbSet<Module> Modules { get; set; }
    public DbSet<Lesson> Lessons { get; set; }

    public DbSet<Student> Students { get; set; }

    public DbSet<Enrollment> Enrollments { get; set; }
    
    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.ApplyConfigurationsFromAssembly(typeof(AppDbContext));
    }
}

This approach allows each interface to expose only the functionality a slice actually needs, which significantly reduces cognitive load.

The trade-off is that the shared layer ends up depending on all slices. This can become problematic: a change in one slice might propagate to the shared layer, potentially impacting other slices indirectly. To mitigate this, you can split the shared layer to limit the ripple effect and to avoid referencing unnecessary classes.

In practice, many teams keep all slices in a single project and separate them by folders; this keeps things simple and flexible. Moving each slice into its own project gives you stronger, compiler-enforced boundaries, but it also adds overhead and can be harder to maintain as the number of slices grows.

However, some people go even further, and keep all three layers (Core, Slices, Shared) in a single project😅.

This can work for small projects, but within a team quickly results in a mess. Nothing prevents breaking a dependency rule. There are no clear boundaries — no compilation errors or project reference restrictions — to enforce separation.

As a result, people coming from other architectures, like Hexagon, where the Core layer has a different meaning, tend to put domain rules, value objects, services, current user context, and basically anything that represents core concepts of the system there, making the code harder to maintain for everyone😒.

Your team should switch mindset and understand that this isn’t layered architecture: a slice’s business logic and infrastructure should remain within that slice, and shared functionality should go into the shared layer. However, it usually takes a long review cycle — some gentle scolding included — before the team fully gets it 😁.

Slices Communication

If you properly pick boundaries between slices, they would barely need to communicate. Buuuut… sometimes they do 😒.

If you’re familiar with similar architectures — where systems are organized around bounded contexts, like in a Modular Monolith or Microservices — you might feel confident and be tempted to implement a solution the same way, with slices interacting exclusively through a public API 🤓.

But those are slices, not modules. We don't need to overcomplicate stuff. To fetch data from another slice, you can rely on shared infrastructure and use the database tables you need.

public interface IStudentDbContext
{
    // 👇 Access data owned by another slice in a read-only manner
    IQueryable<Course> Courses { get; } 
    
    DbSet<Lesson> Students { get; }

    Task<int> SaveChangesAsync(CancellationToken cancellationToken = default);
}

If you not only need to fetch data, but also to perform an operation in another slice, instead of triggering an action, it’s better to take the reverse approach: publish an event via a mediator or an in-memory message bus (see github example), allowing the other slice to react to it.

For example, one slice publishes an event:

// Event definition
public record CoursePublishedEvent(Guid CourseId) : IEvent;

// Course slice publishes the event
public class CourseService(IEventBus _eventBus)
{
    public void PublishCourse(Guid courseId)
    {
                  .  .  .
        
        // Notify other slices
        _eventBus.Publish(new CoursePublishedEvent(courseId));
    }
}

And another slice performs the callbacks.

// Students slice reacts to the event
public class NotifyStudentsHandler : IEventHandler<CoursePublishedEvent>
{
    public void Handle(CoursePublishedEvent @event)
    {
        var students = _dbContext.Students.ToList();

        foreach (var student in students) 
        {
            _emailService.SendEmail(student, $"New Course is available: {@event.Course.Name}")
        }
    }
}

With the event-driven paradigm, you don’t have direct method calls, and this keeps slices decoupled while still enabling cross-feature reactions.

Summary

This architectural style goes by several names: Vertical Architecture, Slice Architecture, or Feature-Based Architecture.

Vertical Slice Architecture isn’t just about having neatly organized folders; it also defines the purpose of the Core and Shared layers and clarifies the dependencies between them, slices granularity, and how they communicate.

It’s a luck to see Vertical Slice applied in backend systems, though some projects — like IdentityService — adopt it successfully. It is more commonly used in frontend frameworks such as Angular or React, where concerns like tight coupling to the UI framework are less of an issue. In these environments, features don’t have complex domain logic and don't depend on external infrastructure dependencies, making slices easier to implement.

While Slices offer clear benefits, they come with trade-offs that are important to understand:

• it is designed to optimize for change rather than reuse
• it emphasizes cohesion within a feature rather than minimizing coupling between components
• this approach makes it harder to define feature boundaries
• intentional code duplication is common, and reusing “shared” becomes more difficult
• if a lot of code must be shared between slices, that’s usually a sign that the boundaries have been drawn incorrectly
• core and shared layers have references across slices, making them harder to replace, as they are stable components
• without high discipline in a team and physical boundaries, a project can turn into a “big ball of mud”, where responsibilities overlap, logic is duplicated, and features unnecessarily reference one another

That said, let’s hope I haven’t scared you too much, and have encouraged you just enough to give it a try 🙃. For those who get that far, as always a small joke:

Don’t forget to give the article a rating if you liked it 👏
Let me know if you have faced this architecture in practice💬
You can support me using the link below ☕️
Share with friends 🗣 Slice, by slice 🤫
Check out my other articles ⬇️
And don’t forget to follow ✅
See Ya😉

Yeap, another article about PR reviews 😅. This one’s going to be a big one — however, it’s not for you guys, it’s for me. It’s a personal reminder on how to conduct reviews and document new projects. If you find it useful, great 😁! If not, that’s unfortunate 😔.

There are some general topics I would like to discuss:

• What Is a Code Review?
• Motivation
• Knowledge Sharing
• Who Should Review Your Code?
• How Many Reviewers Should Be Assigned?

And give advice to each party:

• Rules for the Team
• Rules for Code Review Creators
• Rules for Reviewers

Still, I hope you will like it. Let’s see 🙃.

What Is a Code Review?

A code review is the process of examining someone’s code before it’s merged into the main branch.

Motivation

Code reviews motivate developers to write high-quality code, knowing it will be examined by their peers:

• Code reuse: Encourages leveraging existing functionality instead of reinventing the wheel.
• Code style consistency: Reviewers ensure new code follows established style guides before it reaches the main branch.
• Error detection: Reviewers help catch typos, legacy fragments, redundant comments, or stray console logs.
• Bug reduction: Early feedback lowers the number of issues reaching production.
• Less refactoring: Developers can address concerns before merging, reducing the need for later fixes.

Notice ⚠️:

Many teams choose to skip code reviews, believing they’re time-consuming and rarely catch significant bugs. They usually limit reviews to newcomers or less experienced developers. That approach can work. I’ve tried it myself, and it was actually refreshing, especially in a toxic environment where reviews focused more on blank lines than real issues. However, in a healthy, well-structured team, code reviews often prove their worth.

Knowledge Sharing

Code reviews foster continuous learning and team growth.

They create an environment where knowledge flows freely, encouraging everyone to become both a teacher and a learner:

• Learn from Others: Reviewers discover new algorithms, patterns, and techniques by exploring different coding styles.
• Reasoning Skills: Explaining and defending decisions helps developers think critically about their code and understand why one solution is better than another.
• Gain Feedback: Authors receive valuable input and suggestions that can improve their skills and solution design.
• Fresh Perspective: A new set of eyes can spot alternative approaches or potential improvements.
• System Awareness: All participants become more familiar with the system’s new or modified components.

Who Should Review Your Code?

Ideally, every developer should regularly participate in the review process.

However, some teammates may have deeper expertise. It is recommended to assign:

• A senior developer or architect capable of spotting structural and architectural issues.
• Someone familiar with the functionality you’re modifying.
• A responsible teammate you trust 🙃.

Do not overload the same reviewers with every pull request. Let’s let those people rest, for God’s sake 😭. Code reviews work best when everyone shares the load (and the blame) evenly across the team.

How Many Reviewers Should Be Assigned?

The optimal number of reviewers depends on the complexity and impact of the change.

For small fixes or minor updates, one reviewer is usually enough to ensure code quality and consistency.

For larger features, architectural updates, or critical modules, it’s best to have two reviewers, based on research.

Avoid overloading the process with too many reviewers, as it can slow down development and dilute responsibility. The goal is to maintain quality while keeping the feedback loop fast and focused.

Rules for the Team

As a team, you should establish your PR review process.

Ensure your PR review process is clearly documented and agreed upon by everybody. Meet with your team to define:

📏 PR Size & Structure

• Maximum PR Size: Define the largest pull request each team member is comfortable reviewing. Smaller, frequent PRs are easier to review thoroughly.
• Handling Large or Complex Features: Agree on splitting large features into multiple PRs and using intermediate reviews.

⏰ Review Timing

• Review Turnaround Time: Set expectations for how quickly reviews should be completed.
• Maximum Time Before Review: Agree on how long a PR can remain unreviewed.

I don’t even remember what I had for lunch today; if you ask me a week later why I wrote the code this way, I’d be explaining it to myself 😒!

👥 Roles & Assignments

• Reviewer Assignment: Decide whether PRs are assigned to specific reviewers or rotated across the team.

🧾 Process & Standards

• PR Template: Agree on mandatory checklist items for all PRs to ensure consistency in quality and style. Configure PR template for your repository:

✅ My code follows the style guidelines of this project
✅ I have performed a self-review of my own code
[] I have commented my code, particularly in hard-to-understand areas
[] My changes generate no new warnings
[] I have added tests that prove my fix is effective or that my feature works

                               . . .

• Code Review Pyramid: Agree on a code review pyramid to focus on those parts that matter the most during a code review.

💬 Communication & Feedback

• Commenting Guidelines: Standardize how to provide constructive feedback, including templates, tone, and when to escalate issues.
• Conflict Resolution: Establish a clear process for disagreements between reviewers and authors.

⚙️ Automation & Quality Gates

• Automated Checks: Determine which tasks (linters, formatters, tests, security checks) should be automated before human review.
• Approval Criteria: Define what conditions must be met before a PR can be approved and merged.

Rules for Code Review Creators

A well-prepared author makes the review process smoother and more productive for everyone involved.

The author of a code review should follow these key rules to keep the process efficient and professional.

💡 Preparation

• Prepare Before Submitting. Make sure your code compiles, there are no merge conflicts, it passes all tests, and follows the team’s style guide. Don’t submit half-done work.
• Self-Review. Review your code first — check clarity, complexity, formatting, and tests. Fix what you can before submission. Seeing the full picture often helps you catch things you initially missed.

🤝 Collaboration

• Resolving Comments. All reviewer comments must be addressed. It’s not acceptable to close the comments without discussion.
• Communicate Clearly. If you disagree with feedback, discuss it respectfully and provide reasoning. The goal is collaboration, not debate.

🧠 Mindset

• You Are Not Your Code. The purpose of a review is to improve the code, not to judge the developer. Expect feedback and remember — comments target the code, not you.
• Learn from Feedback. Each review is an opportunity to improve. Pay attention to recurring comments — they often reveal areas where you can grow as a developer.

Rules for Reviewers

I found it more entertaining to review someone’s code than being reviewed. Creating a PR is easy; reviewing one is where the real challenge lies — and the real skill shows.

Where else would you be able to compare others to garbage to feel smarter yourself 😅. Therefore, let’s see a list of practices on how to do it professionally.

⚡ The Right Tone in Reviews

This may surprise you — especially if you’re the people-type — but sometimes a little tension is healthy.

A good code review isn’t a tea party; it’s a constructive clash of ideas. When people like you too much, they may avoid challenging your decisions to keep the peace. But if they respect you — even if they occasionally dislike you — they’ll speak up. That’s where real technical growth happens.

The secret here is to be toxic just enough not to get fired.

Diamonds form under pressure; so does great code.

🤖 Automate Code Review

Before even starting a review, you should make sure it passes all automated checks.

I’ve worked with developers who’d spend hours pointing out in review formatting and syntax rules. What a waste of time and the customer’s money 😒. We’re developers, after all 😤. Spend five days to automate your five-minute routine 😁!

Here are some tasks worth automating:

• This one is kind of obvious, but still, builds and unit tests should always be automated to catch errors early.
• Branch, commit, PR name validation to keep naming consistent
• Linters to enforce coding style rules.
• Code formatters (beautifiers) to standardize formatting automatically.
• Architecture and convention checks to ensure the code follows project structure rules, layer boundaries, and established naming or conventions.
• Use automated code review tools that generate comments using code analysis or AI, like Codacy, SonarQube, etc
• Find extensions that will help your project — for example, tools that automatically create work items when a TODO is detected in the code, etc.

Automated checks should be run at different stages to catch issues early and ensure code quality.

• On-save actions: Automatically run linting, formatting, or basic static checks when the file is saved in the IDE.
• Pre-commit or pre-push Git hooks: Perfect for repository-level rules (branch or commit name).
• CI pipeline: Triggered when a pull request is created. Ideal for running builds, executing tests, and performing deeper analysis.

This lets the reviewer focus on what truly matters — logic, design, and architecture — instead of formatting or syntax.

🎯Understand the Purpose Before Reviewing

Code becomes far easier to understand when you know why it was written.

Begin by reading the ticket thoroughly and identifying the code that addresses the stated requirements.

Then, run the code to verify it actually works. You don’t need to act as QA or test every edge case — just make sure the main “happy path” functions as expected. Otherwise, you may approve good-looking code that doesn’t even work. What was even the point of doing the review?

🧐 What Should Be Reviewed

Focus on what truly matters — logic, redundant code to remove, design, convention, and architecture. The goal of a review isn’t to argue over spaces, bracket placement, or be nitpicky, but to ensure the code makes sense.

A good reviewer looks for clear logic, maintainable structure, and alignment with architectural standards.

✅ Have a Code Review Checklist

It’s easy to overlook important details during a code review, which is why having a checklist is crucial. A checklist ensures consistency, helps reviewers cover all key points, and makes the review process more thorough and effective.

It defines what must be verified in every pull request:

Git:
✅ Branch name is correct
️✅️️ Commits names are correct
️✅ PR name is correct
️✅ Work item is linked
✅️ Is the pull request merged into the correct branch

Code:
✅️ Folders / Files structure is reasonable
❌ Code is covered with tests
✅ Functions and variables are well-named 
️✅ No duplicated code 
️✅ Proper error handling 
[] Code is properly formatted
[] Input validation implemented 
[] Performance considerations addressed

Performances:
[] Are introduced changes scalable?
[] Will it cause performances issues?

Maintenance:
[] Do we have enough logging do debug on production?
[] Do logs contain enough details (entity ID, email, names, trace ID)?

DB:
[] Is the database structure (if any changes) correct?
[] Does it contain the correct constraints?
[] Is the naming for new tables/columns correct?

Security:
️✅️️️ Permissions are managed properly
[] No exposed secrets or API keys

Docs:
️✅ Documentation is created/updated if needed

The exact content depends on your team’s priorities, but it should cover everything you consider critical for stability, security, and readability.

And if you think some of the items can be automated, do it 🙃.

💻 Review Code in an IDE

Sure, reviewing code in a browser is faster, but try checking out the branch in your IDE instead.

Comparing branches lets you explore the file structure, navigate to references, and see where functions are declared.

Trust me — reviewing in an IDE is far more efficient than in a browser.

💬 When to Leave a Comment — and When Not

Learn to work in a team and accept non-ideal solutions. Only comment when one of the items in your checklist fails, the code affects functionality, readability, maintainability, performance, or security, or you found a bug.

Look for potential enhancements: new abstractions, reusable code, libraries, or better organization. Watch for overly complex logic, long methods, or code that relies on too many comments to explain itself.
Find a method full of nested conditionals, and suggest breaking it into smaller, well-named helper methods to make it cleaner and easier to follow.

Don’t demand a complete rewrite. First, understand why the current approach was chosen. If you genuinely have a better solution, discuss it with the team — but keep time management and priorities in mind.

Avoid commenting on minor stylistic preferences — automation already handles that.

🔥How to tell people their code is bad

Other people’s code will often seem worse — simply because it wasn’t written by you.

However, you can’t just tell someone their code is “bad”. For some reason, people tend to get upset (and this is a pure mystery to me) when you call their work pathetic 😒. You need to have good reasons for that. The key is to learn how to give feedback constructively.

Avoid vague or condescending comments. These phrases do more harm than good:

• “Can you make it clearer?” assumes the code is unclear without explaining what is confusing.
• “Why didn’t you write it this way?” implies the developer was wrong, careless, or lacked skills or knowledge.
• “Do it differently/clearer/etc” gives no direction and leads to endless back-and-forth.

Be specific. Explain what’s wrong, why it’s a problem, and how it can be improved. Do not assume your solution is automatically better. Prove it.

Use a clear comment template:

Priority:
- Suggestions (consider improving)
- Warnings (should fix)
- Critical issues (must fix)

What is wrong: ***
Why it's wrong: ***
Suggested improvement: ***

This format helps the developer understand exactly what needs to be improved and why, and it helps the reviewer to improve reasoning skills.

Code can always be written differently — there’s more than one way to solve the same problem. Learn to clearly explain and justify your reasoning. If your proposed change adds little real value, it’s probably not worth leaving a comment. If you feel that something is wrong, but do not have any suggestions, maybe it is not worth writing a comment at all.

Of course, you can skip the template for obvious issues like types, formatting, or minor typos.

Make your comments easy to read to minimize misunderstandings.

❓ How to ask questions

If something in the code isn’t clear, ask. Questions reveal hidden issues, clarify intent, and often spark discussions that lead to better design and shared understanding.

However, asking questions feels bad sometimes because it can be interpreted as criticism — especially if phrased bluntly (“Why did you do it this way?” sounds like “You did it wrong”). Developers often tie their identity to their code, so even neutral questions can feel personal.

The key is how you ask. Prefer curiosity over accusation — e.g., “Can you help me understand why this approach was chosen?” assume positive intent — the author likely had a reason.

You might uncover the reasoning behind the decision — maybe it was based on outdated information, time pressure, limited experience, or constraints you weren’t aware of. Avoid assuming your approach is better unless you have solid evidence to support it.

🤝 Discuss Code Together with the Author

Even with a clear comment template, there is always a risk of miscommunication.

Written comments take time, and explanations lead to long threads. Just call the person, review together, and discuss. The author can clarify why a particular solution was chosen, avoiding weeks of back-and-forth.

💎 Learn from Bad Reviews

It’s often easier to learn from bad reviews than from good ones. Notice what irritates you when someone reviews your code — vague comments, harsh tone, or nitpicking. Remember how that feels, and make sure you don’t repeat the same mistakes when reviewing others’ work. Bad experiences can teach you how to give better, more respectful feedback.

Summary

Code reviews in pull requests aren’t just about catching obvious bugs — that’s what tests are for. A solid review uncovers design issues that could become serious problems later. Additionally, they strengthen collaboration and communication among developers while ensuring consistent quality across the project.

If you want to conduct a professional code review, switch to the branch and open the PR in your IDE, use a review template, avoid nitpicking, focus your comments on meaningful issues, have a good argument for each point, and discuss each comment to prevent misunderstandings.

💬 Let me know what pisses you off during PR

👏 Clap for this article if you enjoyed

☕️ You can also buy me a coffee with the link below

✅ Follow to not miss out on more

😉 But most importantly, keep going

Have you ever wondered what the difference is between a folder and a project? While it may seem minor at first, a simple decision can save you from future headaches, make dependencies clearer, and make your system much easier to maintain.

In today’s article, we’ll talk about what a component really is, how to separate components properly, and why those boundaries matter. We’ll look at the difference between organizing code with folders, enforcing structure with projects, and isolating systems at the application level.

Without any further ado, let’s begin.

What Is a Component?

Regardless of the scale of your architecture, it is always the same: you have components, and a relation between them.

A component can depend on, collaborate with, contain, expose, or hide other components.

But what is even a component?

It can be a class, a folder, a project, a module, or even a microservice. It is something that owns its data, exposes behavior, hides implementation details, and can evolve independently (ideally).

Therefore, let’s have a clear definition:

A component is a cohesive part of a system that does one thing well and interacts with the rest of the system through explicit contracts.

However, a folder is not automatically a component. A project is not automatically a component. A boundary is what makes it one.

Where Should You Draw the Boundary?

The moment you draw a boundary between components, you create an internal structure, a public interface to interact (API), and a direction of dependencies. And that’s where architecture begins.

There are different reasons why you can create a boundary.

You can separate by technical concerns — business logic, infrastructure, UI. That’s the classic layered approach.

You can draw boundaries around business capabilities (Orders, Payments, etc), as encouraged in Domain-Driven Design.

You can also separate by rate of change, following the Single Responsibility Principle. If the parts change for different reasons, they deserve a boundary.

There’s a well-known trilemma in architecture: releases, responsibility, or code reuse. As with other trilemmas, you have to choose two principles and sacrifice the third one 😒.

Place your fingers on two nodes, and the line between them shows what you had to deal with.

There are other valid reasons to create a boundary. You might split based on team organization, scalability requirements, or deployment needs.

The difficulty isn’t writing the code. The difficulty is deciding where the boundaries truly belong.

The real problem with architectural boundaries is that almost any decision can be justified if you argue well enough.

See yourself, even with simple classes like the ones below, it’s not always obvious how they should be structured.

Should you keep the interface and its implementation in the same module (N-Layered)? Is it worth splitting abstractions from implementations (Ports and Adapters)?

Would it be better if everything related to a feature lived together (Vertical Slices)? Or could you isolate each module completely to avoid unnecessary references between components (Divine Architecture).

The key is this: boundaries should solve a real problem — organizational, technical, or business — not exist just because you can have them.

Define a boundary whenever you need to separate responsibility, ownership, and concerns. If boundaries are well designed, the system can evolve safely and predictably. If they’re wrong, everything becomes tightly coupled and hard to change.

In any case, you probably won’t get boundaries right from the first try 😅. That’s normal. Architecture is iterative. You refine it by better understanding the domain, noticing where friction shows up, and refactoring when the pain becomes real.

How Do You Define a Boundary?

If you’ve decided to split your system into components instead of building one big monolith, that’s already a good sign 😅. But the moment you break a system into modules, you also need to introduce dependencies between them — and that’s where the real challenge begins. Every dependency is a form of coupling. And coupling is what determines how painful change will be.

You can try to keep dependencies manageable, enforce rules, and define clear contracts — but it’s still possible to mess things up. A few careless references, shared abstractions in the wrong place, or circular dependencies, and your “component” starts behaving like a tangled monolith again.

That’s why it’s not enough to just split components. It’s equally important to understand the different ways to separate them properly, so boundaries stay real — and change stays cheap.

— folder boundary

The simplest and lightest way to organize a system is by grouping components logically with folders.

It gives you a clean structure with no overhead and is simple to refactor. For small systems and prototypes, this approach can work well because it keeps things fast and flexible.

But let’s be honest about the downsides 😒. There is no real enforcement — only convention. Dependencies are easy to violate, and the structure can be broken in seconds. With folders, you may not even notice when one component starts using functionality from another. Over time, this often turns into spaghetti code.

— project boundary

Physical separation with projects is a different thing.

The difference between a folder and a separate project is major. A folder is just an organization. A project actually gives you real boundaries.

With separate projects, you get compile-time enforcement, clear dependency direction, explicit contracts, and better ownership.

They let you control dependencies between components, avoid cyclic dependencies, move to a deployable NuGet library, and boundaries can be easily enforced with architectural tests.

Additionally, you can make use of access modifiers like public and internal that allows you to control visibility and encapsulation inside an assembly. However, it only works between modules, but not within, and does not fully protect you from architectural drift.

The problem with projects is that they introduce more setup, more coordination between teams, and refactoring across projects becomes heavier. If your application grows too complex, you can still organize projects further using folders or even separate solutions. Just remember that going too far with project separation can make the codebase fragile and harder to maintain.

There are no strict rules to it. Try it yourself and see what suits you best. As always, it is a trade-off between reliability and complexity. My advice here is not to create too many projects unless you really need them.

This approach fits best for medium-to-large systems where architecture starts becoming real.

— application boundary

An application boundary — such as microservices or N-tier — means running in a separate runtime process.

This provides true isolation, scalability, and even technology freedom. With separate processes, you can not even allow references to the wrong component.

Boundaries are enforced strictly through API communication — either inside the same machine (for example, calling another module through its public interface, IPC, CLI) or over the network via HTTP, gRPC, or events.

While strong internal APIs alone can dramatically reduce chaos, it is still possible to violate rules by affecting application outputs such as a database, cache, queue, and so on. If components bypass those entry points and access internals directly, the boundary is meaningless.

As always, there is a cost to this level of separation, like performance degradation, serialization overhead, network complexity, distributed system challenges, versioning headaches, and operational complexity.

This level of separation should be used only when the business genuinely justifies it — not because microservices are fashionable.

Summary

Architecture is the art of drawing boundaries between components — and living with their consequences.

• A component is a cohesive part of a system that does one thing well and interacts with the rest of the system through explicit contracts.
• A component can be a function, class, folder, module, project, or microservice.
• There is no universally correct structure. You can separate components by: technical layers, business capabilities, rate of change, team ownership, deployment, or scalability needs. Every choice is a trade-off.
• You can define boundaries logically with folders, or physically with a project or even a separate application.
• Every boundary adds protection — but it also adds complexity.
• Even when boundaries exist, they can still be violated. Shared databases, shared files, shared caches, or careless references can silently destroy isolation.
• Boundaries are not just about structure. They require discipline within the team, clear conventions, and architectural tests.
• The higher the boundary, the more expensive the mistake.
   — at the folder level, the cost of bad boundaries is inconvenience.
   — at the project level, it is a refactoring effort.
   — at the service level, it becomes deployment coordination and team friction.
• Separating too early can be just as harmful as not separating at all.
• You won’t get boundaries perfect on the first try. Architecture is iterative. You refine it as the domain becomes clearer and friction reveals where separation truly belongs.
• Sometimes poorly chosen boundaries can be more damaging than having no boundaries at all.

Let me know in the comment section how often you organize your system 💬 Clap if you like the article👋 Support me with a coffee ☕ Follow to receive more ✅ And see you next time! 😜

Previously, I wrote an article about a handy ‘weird’ method that prevents empty collections.

var empty = Enumerable.Empty<int>();
var result = empty.DefaultIfEmpty(42); // [42]

This is especially useful in aggregations to avoid exceptions or empty results.

var maxNumber = empty
    .Where(n => n > 25)
    .DefaultIfEmpty()
    .Max(); // no longer throw InvalidOperationException("Sequence contains no elements")

You seem to like it 🙃.

Therefore, let’s explore a few more weird LINQ method overloads.

Extension methods

Let’s start with something simple, and something you already know😅.

LINQ is not magic, but just a bunch of extension methods for IEnumerable<T>:

static class Enumerable
{
                    .  .  .
    public static T First<TSource>(this IEnumerable<T> source);
    public static float? Max(this IEnumerable<float?> source);
    public static double? Sum(this IEnumerable<double?> source);
                    .  .  .
}

It means two things:

• to make LINQ work with your own class, you need to inherit IEnumerable
• while it is common to chain them, you can just call them as static methods:

var maxValue1 = new int[] { 1, 2, 3 }.Max();  // chaining
var maxValue2 = Enumerable.Max([1, 2, 3]);    // use a static method

Static LINQ Methods

LINQ provides several handy static methods in the Enumerable class to generate sequences on the fly, without needing to manually create or fill collections.

IEnumerable<int> empty  = Enumerable.Empty<int>();                  // []
IEnumerable<int> range  = Enumerable.Range(start: 2, count: 3);     // [2, 3, 4]
IEnumerable<int> repeat = Enumerable.Repeat(element: 27, count: 2); // [27, 27]

And don’t forget — LINQ also offers a simple way to compare collections element-by-element 😉:

var array1 = new[] { 1, 2, 3 };
var array2 = new[] { 1, 2, 4 };

var areEqual1 = Enumerable.SequenceEqual(array1, array2);
var areEqual2 = array1.SequenceEqual(array2);

.Where((value, index) => predicate)

Many developers know popular LINQ methods — such as Select, Where, or SkipWhile. However, only a few are aware that they have overloads that accept two arguments: the current item and its index.

var result = numbers.Where((currentItem, index) => index % 2 == 0);

Here, x is the current element, and i is its index in the sequence.

.FirstOrDefault()

In all those, .FirstOrDefault(), .LastOrDefault(), .SingleOrDefault(), or .SomethingSomethingOrDefault() you can specify a default value.

var result = numbers.FirstOrDefault(42); // returns 42 instead of default(T)

This makes it much clearer and safer when you want a custom fallback value instead of relying on the type’s default.

.SelectMany()

As you know .SelectMany() allows you to flatten multidimensional collections into a single sequence.

var people = new[]
{
    new { Name = "Alice", Pets = new[] { "Dog", "Cat" } },
    new { Name = "Bob",   Pets = new[] { "Fish" } }
};

// ["Dog", "Cat", "Fish"]
var allPets = people.SelectMany(p => p.Pets); 

But, did you know that it also has a second parameter that lets you project both the outer and inner elements into a custom shape? 🤔

// [ { Alice - Dog }, { Alice - Cat }, { Bob - Fish } ]
var petOwners = people
  .SelectMany(
      p => p.Pets,                                             // collectionSelector
      (person, pet) => new { Owner = person.Name, Pet = pet }  // resultSelector
  ); 

.Cast()

.Cast() is useful for explicit casting, especially when working with non-generic sequences.

List<object> list = new List<object> { 1, 2, 3 };

List<int> numbers = list.Cast<int>().ToList();

Now, let’s say you have a base class and a derived class:

class Animal(string Name) { }
class Dog(string Name, string Breed) : Animal(Name) { }

And then work with collections of the derived type:

IEnumerable<Dog> dogs = new List<Dog>
{
    new Dog("Buddy", "Golden Retriever"),
    new Dog("Rex", "German Shepherd")
};

If you want to create a collection of base entities, you can use .Cast(), but you can also convert directly to the list with .ToList<BaseType>():

var animals1 = dogs.Cast<Animal>().ToList();
var animals2 = dogs.ToList<Animal>();
var animals3 = dogs.AsEnumerable<Animal>();

.GroupBy()

.GroupBy() groups elements by a specified key.

var people = new[]
{
    new { Name = "Alice", City = "London" },
    new { Name = "Bob",   City = "Paris" },
    new { Name = "Carol", City = "London" },
};

// London → [{ Alice }, { Carol }]
// Paris  → [{ Bob }]
var groups = people.GroupBy(p => p.City);

You can also specify what each group should contain using an element selector:

// London → ["Alice", "Carol"]
// Paris  → ["Bob"]
var namesByCity = people.GroupBy(p => p.City, p => p.Name);

But did you know, you can go even further, and you can project each group into a custom result using a result selector:

// London → { City = London, Count = 2 }
// Paris  → { City = Paris, Count = 1 }
var cityStats = people.GroupBy(
    p => p.City,
    p => p.Name,
    (string city, IEnumerable<string> names) => new 
    { 
        City = city, 
        Count = names.Count(), 
    }
);

This form is especially useful when you want an aggregated result right away — like counts, averages, or summaries — without iterating over groups later.

.Concat(), .Union(), .Zip()

LINQ has methods that allow you to combine collections into one, let’s see the difference between those:

.Concat() allows you to combine multiple sequences into one. It simply appends the second sequence after the first:

var numbers1 = new List<int> { 1, 2 };
var numbers2 = new List<int> { 3, 4, 5 };

var result = numbers1.Concat(numbers2).ToList(); // [1, 2, 3, 4, 5]

.Union() is similar to .Concat(), but it removes duplicates, returning only distinct elements:

var numbers1 = new List<int> { 1, 2, 3, 4, 5 };
var numbers2 = new List<int> { 3, 4, 5 };

var result = numbers1.Union(numbers2).ToList(); // [1, 2, 3, 4, 5]

.Zip() is the one everybody forgot😁. It combines two sequences element by element, producing a new sequence based on a selector function:

var numbers1 = new List<int> { 1, 2 };
var numbers2 = new List<int> { 3, 4, 5 };

var result = numbers1.Zip(numbers2).ToList(); // [(1, 3), (2, 4)]
var result = numbers1.Zip(numbers2, (n1, n2) => n1 * n2).ToList(); // [3, 8]

Note: .Zip() stops when the shorter sequence ends.

.Aggregate()

.Aggregate() is one of the most powerful and sometimes confusing LINQ methods. Anyone who has used it knows they’ve been through some wild times 😅.

It can be used to generalize all sorts of accumulation operations (like Sum, Max, etc).

var numbers = new[] { 1, 2, 3, 4 };

// 10
var sum = numbers.Aggregate((result, currentItem) => result + currentItem);

But it goes beyond that. Only a few know that one of its overloads allows you to set an initial value:

// 20
var sum = numbers.Aggregate(
    10,                                             // seed
    (result, currentItem) => result + currentItem); // accumulation function

And, only developers from Microsoft know (but maybe even they forget) that there is an overload that lets you transform the final accumulator before returning it:

var words = new[] { "Hello", "World" };

var sentence = words.Aggregate(
    "",                                     // seed
    (result, word) => result + word + " ",  // accumulation function
    result => result.Trim()                 // final transformation
);

Console.WriteLine(sentence); // "Hello World"

Summary

LINQ is full of surprises that few developers ever notice. So next time you write a .Where(), .Select(), or .Aggregate(), remember: there’s probably a secret overload or quirky behavior waiting to make your code a little more expressive (and maybe a little weirder 😄).

Let me know in the comment section is there's anything else I forgot about LINQ💬 Clap if you like the article👋 Support me with a coffee ☕ Follow to receive more ✅ See U! 😜

In today’s article, we’ll take a deep dive into the Infrastructure Layer — what it really is, why it exists, and why it’s often misunderstood. We’ll walk through how infrastructure evolved from classic N-layered systems to Hexagonal, Onion, and Clean Architecture, clarify where interfaces actually belong, and explore common traps like smart repositories, domain-leaking utilities, and framework-driven design.

Stick with me — this article is written to unblock juniors, challenge seniors, and hopefully save everyone a few future refactors 🙃.

The Infrastructure Layer Explained

The infrastructure layer is the part of an application that deals with technical and external concerns.

It is often considered the most boring layer, yet many developers — including myself — actually enjoy building technical utilities 🙃.

The responsibility of this layer is to implement interactions with the outside world: databases, message brokers, file systems, external services, caching, logging, and other frameworks or tools the system depends on.

By isolating these details, the infrastructure layer keeps the core of the system clean, testable, and independent from specific technologies, allowing implementations to be replaced or evolved with minimal impact on business logic.

Where should you put Repository Interfaces?

It took a long time for developers to understand how to properly define the infrastructure layer.

The question of where to place infrastructure interfaces and their implementations is not limited to repositories — it applies to all infrastructure concerns. But the database is the simplest concern to understand, therefore it will be used as an example😅.

Let’s briefly review the history to see how we got here, where these elements belong, and why we define them the way we do.

— N-Layered

When the N-layered architecture was introduced, the infrastructure layer was very last in the line.

This made sense at the time: applications were mostly simple CRUD systems with little business logic, so allowing the business layer to directly access and operate on database objects was quite typical.

Additionally, infrastructure was simple back then. Typically, it was only a data access layer.

Let’s have a closer look at the relationship between Business Logic and Data Access layers.

In N-layered architecture, both interfaces and implementations reside in the Infrastructure Layer.

While straightforward, trying to adapt this approach to modern tech will quickly lead to the following issues:

• reduced modularity — business logic can’t stand alone without infrastructure assemblies
• infrastructure leakage— infrastructure concepts (DB models, ORM details, HTTP clients) bleed into higher layers
• implementation-driven interfaces — when an interface has only one implementation, it tends to mirror that implementation, leaking implementation details
• fragile clients — replacing an implementation requires modifying/updating the NuGet’s version/redeploying all layers that depend on it, and not just the composition root
• uncontrolled dependencies — since interfaces are public, other layers can use them, bypassing intended architectural boundaries

— Hexagon (Ports and Adapters)

Ports and Adapters architecture applies the Dependency Inversion Principle, reversing the dependency flow so infrastructure depends on business logic, not the other way around.

This becomes quite handy as applications become more complex and we start using more infrastructure like email services, file storage, and so on.

In the Ports and Adapters architecture, infrastructure interfaces are defined alongside the Business Logic, while their implementations live in the Infrastructure Layer.

This makes stuff better and fixes issues from above, as Domain is now a central component of the system that does not have any dependencies on the Infrastructure.

However, in this architecture, the business layer often ends up containing interfaces it doesn’t really need. Ideally, the business layer should only include concepts that are meaningful to domain experts. Exposing abstractions like ICache, IMessageQueue, or IHttpClient introduces foreign infrastructure concerns, cluttering the layer.

Another problem is that your infrastructure may reference business-logic services and use them in unintended ways.

Let’s see what we have in the next architecture.

— Onion

Onion Architecture introduces a new layer — the Application Layer — responsible for orchestrating use cases, managing application behaviour like thread coordination, sessions, transaction boundaries, etc

For our infrastructure, this means that interfaces can be moved into the Business or Application layers, while their implementations stay in the Infrastructure layer.

Repository interfaces remain in the domain layer, since domain services frequently need to access data from the database.

— Clean Architecture

Clean Architecture implies that you don’t have domain services and anemic models, but rich entities with both data and behaviour.

Since we don't have services in our domain layer, all infrastructure interfaces are moved to the Application layer.

Even if you define services in the business layer, data should be fetched in the application layer and all required records passed to the domain service, emphasizing the combination of purity and encapsulation.

class UserService : IUserService 
{
    public void IsEmailFree(
        IReadOnlyList<User> users, // no DB dependency
        string email)
    {
        var isValid = email.Contains("@");
        if (!isValid) throw new InvalidArgumentException();

        var isAlreadyInUse = users.Any(u => u.Email == email);
        return !isAlreadyInUse;
    }
}

Writing Infrastructure Code

Here are a few guidelines that can help you write better infrastructure code:

Dependency Rules

From the section above, you should take away the following dependency rule: Infrastructure should depend on Application/Domain, never the other way around.

High-level modules (Domain) should not depend on low-level modules (Infrastructure); instead, both depend on abstractions, ensuring that business logic remains unaware of concrete implementations.

This separation preserves inversion of control, prevents dependency cycles, and allows infrastructure components to be replaced or evolved without impacting the core of the system.

Should You Split Infrastructure?

As already discussed, interfaces should live in the application or domain layer, while infrastructure stays in its own project.

Additionally, infrastructure is often grouped into cohesive folders— persistence, messaging, integrations — each following screaming architecture, where the structure reflects the separate technologies it uses.

However, when infrastructure grows significantly, it can be practical to separate each implementation into its own project. The same applies to the interfaces.

Quite often, the data access layer is the first to be extracted into a separate project, as it is usually the largest and most complex part of the system.

In fact, you can extract each infrastructure per project. Having multiple small modules is what low coupling and high cohesion are about:

Low Coupling — refers to the degree of dependency between different components in a software system.

It is desirable to avoid dependencies for independent modules with minimal interactions.

High Cohesion — refers to the degree to which the elements within a module or component are related to each other.

Classes that share the same responsibilities should belong to one module.

Of course, it is up to you whether to keep all infrastructure in one project or to split it. The benefits of this setup are:

• smaller, focused projects are easier to understand, refactor, and update independently
• project boundaries are stronger than folder organization. While folders cannot prevent one infrastructure module from accessing another, separate projects make these dependencies explicit and easier to control
• higher-level layers never depend on concrete implementations
• you can replace a concrete implementation without modifying all dependent packages (open/closed principle) — only the composition root needs to change (the host responsible for composing dependencies)
• if your code lives in a separate NuGet, when split, implementations may be packaged separately to support multiple implementations (such as AzureMessageBus or LoopbackMessageBus) while still keeping the interface in the Domain
• if parts of infrastructure evolve at different rates (e.g., database vs messaging), separate projects allow independent versioning and deployment
• you are less likely to use infrastructure that you don’t need if they live in separate projects

As you can see, it largely depends on the complexity of your domain, your specific needs, preferences, and future plans.

Think about your code as if you are writing a Third-Party Library

As your infrastructure depends on the Domain, it is natural to pass domain types across that boundary. You may feel tempted to simplify your infrastructure code and start using entities or domain terminology more freely.

// Infrastructure layer
public class CacheService : ICacheService
{
    // ⚠️ knows about domain entities
    public User? GetUserById(UserId userId) { . . . }
    public void SetUser(User user) { . . . }
}

While it is inevitable for stuff like repositories, but try designing your code as if you are writing a third-party library.

// Infrastructure layer
public class CacheService : ICacheService
{
    // ✅ сan be packaged and reused anywhere
    public Task<T?> GetAsync<T>(string key) { . . . }
    public Task SetAsync<T>(string key, T value, TimeSpan ttl) { . . . }
}

By doing so, your utilities (e.g. EmailService, EventBus, Cache) become independent, loosely coupled, reusable, domain-agnostic components, ideally packaged in a separate library.

Make your Infrastructure Domain Agnostic

Even with clear layering, mistakes can still happen — such as injecting domain services, rules, or constraints into infrastructure utilities.

Even though, these issues are usually junior-level mistakes and are easy to spot and fix during pull request reviews, the project references technically allow this.

However, this should be clear that infrastructure should remain domain-agnostic.

Avoid Making Infrastructure “Smart”

You may not inject domain rules into the Infrastructure directly, but another common mistake is giving infrastructure components responsibilities they don’t belong to — such as embedding business logic in repositories or making infrastructure “smart.”

interface IOrderRepository
{
    OrderStatistic CalculateOrderStatistic(int orderId); // implement business layer calculation at the SQL level
    void UpdateStatus(int id, OrderStatus newStatus);    // update record directly, bypassing business invariants
}

Repositories, message handlers, and other technical implementations should only perform technical tasks: fetching, saving, sending, or logging data.

Adding business rules or decision-making to these layers breaks the separation of concerns, creates hidden dependencies, and makes the system harder to test and maintain.

Keep infrastructure simple, predictable, and focused on how to do things, not what the system should do.

Persistence Ignorance Principle

The persistence ignorance principle implies that domain models should not know or care about how data is stored, retrieved, or persisted.

This aligns with how references are meant to work: the domain defines the rules, and infrastructure follows them.

In practice, however, this principle does not always work 😅.

Persistence, as one of the most crucial concerns in a system, will indirectly affect your domain entities. The choice of ORM — EF, Dapper, Hibernate — shapes how you think and define your entities and relationships between them. This is usually not a problem as long as the influence is minimal and controlled.

// Domain model 
public class Order
{
    public Guid Id { get; private set; }
    // ⚠️ EF navigation properties
    // ⚠️ virtual used for EF
    public virtual ICollection<OrderItem> Items { get; set; } = new List<OrderItem>();

    // ⚠️ EF parameterless constructor
    protected Order() { }
    public Order(Guid id)
    {
        Id = id;
    }

    public decimal Total => Items.Sum(i => i.Price * i.Quantity);
}

Your goal is to design your domain entities first, based on business meaning, rather than shaping them to make infrastructure easier to implement.

Try also applying this principle beyond persistence to other infrastructure concerns.

Avoid Direct Infrastructure Calls From the UI

In case your infrastructure’s interfaces are not internal and defined outside the Domain project, or you simply define layers in a different order, it becomes possible to call your infrastructure from the UI.

This is an issue because it breaks the intended dependency direction. The Presentation should only interact with the Application layer, never with the Infrastructure directly.

Similarly to the previous issues, it can be fixed in a few ways:

• establishing clear conventions and documenting allowed practices helps developers understand how layers should interact
• perform code reviews to enforce architecture in practice
• enforce dependency rules, public/internal boundaries, and layer separation with architecture tests
• split components and define dependency in a way that your supreme architecture does not allow wrong usage
• prevent reference propagations with project configuration

<!-- Application Layer -->
<Project Sdk="Microsoft.NET.Sdk">

  <ItemGroup>
    <ProjectReference Include="Infrastructure.Interfaces.csproj">
      <!-- Prevent Infrastructure from being implicitly accessed by other layers  -->
      <ExcludeAssets>compile</ExcludeAssets>
    </ProjectReference>
  </ItemGroup>

</Project>

• make interfaces internal and explicitly select trusted projects with [InternalsVisibleTo] attribute

// Infrastructure.Interfaces project

// Allow only the Application layer (or specific test projects) to access internal members
[assembly: InternalsVisibleTo("Application")]
[assembly: InternalsVisibleTo("Infrastructure.Tests")]

                          .  .  .

// Infrastructure.Implementation project
[assembly: InternalsVisibleTo("Presentation")] // Composition Root

Ultimately, clean architecture is not enforced by structure alone; it requires discipline, reviews, and deliberate boundary protection.

Testing Infrastructure Code

Of course, you can mock infrastructure in unit tests to isolate specific behaviors and focus on verifying domain rules.

However, if your goal is to test Infrastructure code, you should primarily rely on integration tests, since they verify interactions with external systems like databases, message brokers, or APIs.

Dockerize Your Infrastructure

Installing and configuring infrastructure components (SQL Server, Redis instance, etc) manually can be time-consuming, error-prone, and inconsistent across machines.

When developing locally, it’s better to run them in Docker containers rather than installing them directly on your machine to mirror production, avoid polluting your system with multiple versions, and make it easy to reset or reproduce issues.

What Else do You Count as Infrastructure?

For the final, let’s discuss what else counts as Infrastructure, as with some components, teams often struggle to decide where they truly belong.

Let’s briefly review common elements that are considered infrastructure details.

— Database

While it becomes more obvious over time that the database is nothing more than a tool, many developers still reject this and treat it as the main component of their system.

Even though it was like that in the past, technologies and requirements have shifted, but some developers’ brains have not 😬.

When the database is in the center, business logic, use cases, and sometimes even the UI become tightly coupled to a relational schema, allowing the database to dictate application behavior.

The database may be large and dominant, but it remains just a tool — used indirectly by business rules and isolated from the core logic.

Business logic doesn’t need to know about schemas, query languages, or storage details — they only need a set of methods to load data at the beginning of a use case, and to persist it at the end for future use.

— Frameworks

Your architecture should be framework-independent. That framework you use should not shape your system. That means frameworks are also nothing more than just an infrastructure tool.

Frameworks commonly promote inheriting from their base classes, embedding framework functionality into business objects, and maximizing coupling to the framework.

// Domain
public class User : IdentityUser<Guid> // ⚠️ framework dependent
{
    public string Name { get; set; }
}

Heavy frameworks should be wrapped to limit their impact; otherwise, when a newer, better framework emerges, you won’t be able to adopt it without rewriting the entire system.

// Infrastructure (ASP.NET)
public sealed class AspHostCurrentUser : ICurrentUser
{
                  .  .  .

    public UserId GetCurrentUserId()
    {
         return _httpContextAccessor
            .HttpContext
            .User
            .FindFirst(ClaimTypes.NameIdentifier);
    }
}

The only exception I would make is Entity Framework 😅 . However, avoid attribute-based configuration. Keep database mapping in the infrastructure layer with use of the Fluent API.

— Host / UI

The user interface, as the most volatile component, should be changed without affecting the rest of the system. It should be possible to expose the same system as a console, web app, desktop, or even pure API in a library.

How? To achieve that, you should treat your WebHost as another tool. And where do we place tools 😅? Yeap, your UI is just another infrastructure.

If so, given a diagram with Presentation and Infrastructure layers, which one should contain the code?

My advice is as follows:

• infrastructure code related to the UI, host configuration, presenters, and so on, can live in the Presentation layer (you can even create an Infrastructure folder in the host, as Microsoft did)
• if you need to reuse middlewares, ActionResult or other host settings, add that to the Infrastructure layer

— Cloud

Cloud platforms like Azure, AWS, and Google Cloud provide many useful tools — message brokers, databases, blob storages, and more. It’s common to hide these behind interfaces, keeping business logic abstracted while placing the concrete behavior in the infrastructure layer.

However, a cloud provider can also play the role of the presentation layer. For example, Azure Functions can act as the host that starts and triggers your application. In this case, the cloud runtime is just another delivery mechanism.

At the same time, you must prevent cloud-specific details from leaking into the core of your system — for example, using cloud specific classes to send messages directly to a cloud queue from business logic.

public static class PlaceOrderFunction
{
    [FunctionName("PlaceOrder")]
    public static async Task Run(
        [HttpTrigger(AuthorizationLevel.Function, "post")]
        HttpRequest req,
        
        [ServiceBus(queueName: "orders-queue", Connection = "ServiceBusConnection")]
        IAsyncCollector<OrderPlacedEvent> output)
    {
        // ⚠️ application logic mixed with infrastructure concerns
        var userId = new UserId(Guid.Parse(req.HttpContext.User.Value)); // ⚠️

        var order = new Order(OrderId.New(), userId);
        dbContext.Orders.Add(order);

        await dbContext.SaveChangesAsync();
        await output.AddAsync(new OrderPlacedEvent(order.Id, userId)); // ⚠️
    }
}

Instead, define application-level abstractions and let infrastructure handle the cloud integration.

// Presentation Layer
public class PlaceOrderFunction
{
    private readonly PlaceOrderUseCase _useCase;

    public PlaceOrderFunction(PlaceOrderUseCase useCase)
    {
        _useCase = useCase;
    }
    
    [FunctionName("PlaceOrder")]
    public async Task Run(
        [HttpTrigger(AuthorizationLevel.Function, "post")] 
        HttpRequest req

        // ✅ do not rely on Azure Functions–specific bindings in your core logic
        /*IAsyncCollector<OrderPlacedEvent> output*/) 
    {
        await _useCase.ExecuteAsync();
    }
}

------------------------------------------------------------------------------------

// Application Layer
public class PlaceOrderUseCase
{
    private readonly ICurrentUserService _currentUserService;
    private readonly IDbContext _dbContext;
    private readonly IMessageBus _messageBus;

    public PlaceOrderUseCase(
        ICurrentUserService currentUserService
        IDbContext dbContext,
        IMessageBus messageBus)
    {
        _currentUserService = currentUserService;
        _dbContext = dbContext;
        _messageBus = messageBus;
    }

    public async Task ExecuteAsync()
    {
        // ✅ application logic uses abstractions
        var userId = _currentUserService.GetCurrentUserId(); // ✅

        var order = new Order(OrderId.New(), userId);
        _dbContext.Orders.Add(order);

        await _dbContext.SaveChangesAsync();
        await _messageBus.AddAsync(new OrderPlacedEvent(order.Id, userId)); // ✅
    }
}

From an architectural perspective, cloud-specific SDKs, configurations, and service integrations belong to the infrastructure layer and should be kept behind clear boundaries.

Treating the cloud as infrastructure preserves portability, keeps business logic clean, and prevents cloud providers from leaking into the core of your system.

— Utilities

Sometimes you write code that extends your runtime or platform like extension methods, missing data structures, or helper utilities.

Although it may seem natural to place such code in the infrastructure layer, a better choice is a Utilities layer (as long as this code is completely domain-agnostic and merely enhances your programming language capabilities):

namespace Utilities
{
    public static class DictionaryExtensions
    {
        public static TValue GetOrDefault<TKey, TValue>(this IDictionary<TKey, Value> source, TKey key, TValue defaultValue = default!)
        {
            return source.TryGetValue(key, out var value)
                ? value
                : defaultValue;
        }
    }
}

This layer can sit deeper in the stack and be reused across all other layers — domain, application, and host — without introducing unwanted dependencies.

Summary

The Infrastructure Layer provides concrete implementations of interfaces defined in the application or domain layers, focusing purely on technical execution, dealing with databases, external services, messaging systems, and frameworks.

Keep this code concrete, replaceable, and cohesive: implement well-defined technical behavior, avoid embedding or influencing business rules, minimize assumptions about use cases, and keep related responsibilities together.

Well-written infrastructure code is predictable, isolated, and easy to swap when technology inevitably changes.

Let me know in the comment section where do you put your infrastructure interfaces? Do you split infrastructure and implementation or keep them in the same module? What insights do you get from building utils ?💬 Clap if you like the article 👋 Support me with a coffee ☕ And follow to receive more ✅