SOLID & architecture

#S: single responsibility and cohesion

If changing an email layout requires touching invoice calculations, responsibilities are mixed. SRP groups code that changes for the same reason and separates code that changes for different reasons; it does not require one method per class. Cohesion measures how closely a module's responsibilities belong together; coupling concerns its dependencies on other modules. Aim for cohesive responsibilities and few explicit dependencies.

public sealed class InvoiceService
{
    public string BuildEmail(decimal subtotal) =>
        $"<p>Total: {subtotal * 1.14m}</p>";
}

public sealed class InvoiceTotals(decimal taxRate)
{
    public decimal Calculate(decimal subtotal) => subtotal * (1 + taxRate); // (1)
}
public sealed class InvoiceEmail
{
    public string Format(decimal total) => $"Total: {total:0.00}";          // (2)
}

Rules can now be tested without an email server. Do not split every line into a class: responsibilities that always change together may become harder to follow when fragmented.

#O: open/closed at a real variation point

If every discount type adds another branch to the same large switch, you have a recurring variation point. OCP lets new variants implement a stable contract. It does not prohibit editing existing code: bugs and contract changes still require changes and tests.

decimal Discount(decimal total, string kind) => kind switch
{
    "percent" => total * 0.1m,
    "fixed" => Math.Min(total, 50m),
    _ => throw new ArgumentException("Unknown discount")
};

public interface IDiscountRule { decimal Calculate(decimal total); } // (1)
public sealed class PercentDiscount(decimal rate) : IDiscountRule
{
    public decimal Calculate(decimal total) => total * rate;
}
public sealed class DiscountCalculator(IDiscountRule rule)
{
    public decimal Calculate(decimal total) => rule.Calculate(total); // (2)
}

Strategy and DI are implementation tools. A small switch over a stable closed set may be clearer than many interfaces. Avoid extension points for speculative requirements.

#L: Liskov and rectangle/square

Inheritance is a behavioral promise: a subtype must work wherever its base is expected without breaking the client's contract. It must not strengthen preconditions or weaken promised postconditions. A square is mathematically a rectangle, but not a mutable rectangle whose width and height can change independently.

public class Rectangle
{
    public virtual int Width { get; set; }
    public virtual int Height { get; set; }
}
public sealed class Square : Rectangle
{
    public override int Width
    {
        get => base.Width;
        set { base.Width = value; base.Height = value; }
    }
    public override int Height
    {
        get => base.Height;
        set { base.Width = value; base.Height = value; }
    }
}
// For a Rectangle, the client expects 5 * 10 = 50.
Rectangle shape = new Square();
shape.Width = 5;
shape.Height = 10;                     // Width also becomes 10; area = 100

public interface IShape { int Area { get; } }                  // (1)
public sealed record Rectangle(int Width, int Height) : IShape
{
    public int Area => Width * Height;
}
public sealed record Square(int Side) : IShape
{
    public int Area => Side * Side;                            // (2)
}

These are independent alternatives, not definitions to combine in one file. An exception alone does not prove an LSP violation; ask whether it violates the advertised contract.

#I: interface segregation through capabilities

An interface is a small contract describing what a caller may ask an object to do. If the payment contract promises every provider can refund, it makes a false promise for a cash provider that cannot reverse an electronic transaction. ISP splits contracts around the capability a caller actually needs, not an arbitrary method count.

public interface IPaymentProvider
{
    Task ChargeAsync(decimal amount);
    Task RefundAsync(string paymentId);
}
public sealed class CashProvider : IPaymentProvider
{
    public Task ChargeAsync(decimal amount) => Task.CompletedTask;
    public Task RefundAsync(string paymentId) => throw new NotSupportedException();
}

public interface IChargeProvider
{
    Task ChargeAsync(decimal amount, CancellationToken ct);
}
public interface IRefundProvider
{
    Task RefundAsync(string paymentId, CancellationToken ct);        // (1)
}
public sealed class RefundPayment(IRefundProvider refunds)
{
    public Task Run(string paymentId, CancellationToken ct) =>
        refunds.RefundAsync(paymentId, ct);                         // (2)
}

The bad example is a behavioral sketch, not a real payment implementation. One provider can implement both contracts without becoming two objects. Splitting contracts that always change together and serve the same clients can add noise.

#D: dependency inversion is more than injection

In order confirmation, the policy is the application rule: what should happen after confirmation? Infrastructure is how the work is carried out, such as writing a file or calling an external SDK. If checkout chooses that mechanism itself, changing storage also changes business code. An abstraction here is a small contract describing checkout’s need without choosing the mechanism. DIP makes the business rule depend on that contract, which the mechanism implements. Dependency injection (DI) is how the implementation is supplied from outside; directly injecting a concrete class alone is not DIP.

public sealed class ConfirmOrder
{
    public void Run(int id) =>
        File.AppendAllText("orders.log", $"Confirmed {id}\n");
}

// Application project
public interface IOrderNotifications { void Confirmed(int orderId); } // (1)
public sealed class ConfirmOrder(IOrderNotifications notifications)
{
    public void Run(int id) => notifications.Confirmed(id);
}
// Infrastructure project references Application.
public sealed class FileOrderNotifications(string path) : IOrderNotifications
{
    public void Confirmed(int id) =>
        File.AppendAllText(path, $"Confirmed {id}\n");                // (2)
}
// Composition root supplies path and implementation.                 // (3)

This illustrates dependency direction, not durable notification delivery. Do not create an interface for every pure utility; isolate boundaries with real reasons to vary or be substituted.

#Layered, Clean, Hexagonal, Onion and vertical slices

Does a feature require visiting ten folders, or are domain rules tied to HTTP? Choose organization to solve the actual problem. These styles overlap; they are not mutually exclusive frameworks.

Clean source references:
Shop.Application → Shop.Domain                          (1)
Shop.Infrastructure → Shop.Application, Shop.Domain
Shop.Api → Shop.Application, Shop.Infrastructure         (2)

Inside Application, organized by feature:
Features/Orders/PlaceOrder/Handler.cs                     (3)
Features/Orders/GetSummary/Handler.cs

Changing databases is not necessarily a one-file change: transaction and SQL semantics can leak. The main benefit is clear dependencies. Small CRUD applications may need only simple slices. Microsoft architecture guide.

#Strategic DDD: boundaries of meaning

Catalog treats Product as descriptions and images; Inventory treats it as quantities and storage locations. Forcing both into one giant model creates coupling. A bounded context defines a model's meaning, and a ubiquitous language aligns code with domain experts' vocabulary.

A context map records relationships: upstream and downstream roles, contract ownership, published language, and anti-corruption layers used for translation. A context is not necessarily a microservice, table or exact team boundary.

Catalog [upstream] -- ProductSnapshot v1 --> Sales [downstream]   (1)
Payment provider -- external status --> ACL --> Sales.PaymentState (2)
Inventory owns availability; Catalog owns descriptions.          (3)

Start with conversations and concrete examples from domain experts. DDD is not a class-naming exercise; a simple stable domain may not justify many tactical patterns.

#Tactical DDD: protecting invariants

If every controller decides independently whether paid orders can change, the rule will drift. An entity has persistent identity; a value object is defined by its values. An aggregate is a consistency boundary whose root controls changes, not an object graph containing everything connected by a foreign key.

public sealed record OrderLine(Guid ProductId, int Quantity);
public sealed record OrderConfirmed(Guid OrderId);
public sealed class Order
{
    private readonly List<OrderLine> _lines = [];
    private readonly List<OrderConfirmed> _events = [];
    public Guid Id { get; } = Guid.CreateVersion7();
    public bool IsConfirmed { get; private set; }
    public IReadOnlyList<OrderLine> Lines => _lines.AsReadOnly(); // (1)
    public IReadOnlyList<OrderConfirmed> Events => _events.AsReadOnly();
    public void AddLine(Guid productId, int quantity)
    {
        if (IsConfirmed) throw new InvalidOperationException("Order locked");
        ArgumentOutOfRangeException.ThrowIfNegativeOrZero(quantity);
        _lines.Add(new(productId, quantity));                    // (2)
    }
    public void Confirm()
    {
        if (IsConfirmed) return;
        if (_lines.Count == 0) throw new InvalidOperationException("Empty order");
        IsConfirmed = true;
        _events.Add(new(Id));                                    // (3)
    }
}

This is a small model; translate expected failures to meaningful application results and protect database concurrency. Encapsulation alone does not prevent concurrent updates. Avoid aggregates containing millions of children: choose boundaries from invariants.

#Modular monolith: boundaries without a network

When teams need feature ownership without independent deployment, a modular monolith is a practical option: one deployable, modules with explicit contracts and hidden implementations. Separate folders do not create modularity if everyone directly queries everyone else's tables.

Shop.Catalog.Contracts     ICatalogPrices, ProductPriceDto       (1)
Shop.Catalog               internal entities and persistence
Shop.Sales.Contracts       PlaceOrderRequest, OrderSummary
Shop.Sales                 references Catalog.Contracts only     (2)
Shop.Host                  registers module implementations      (3)

A shared database can use schemas with clear ownership. Cross-module transactions deliberately increase coupling and are not automatic across separate DbContexts. Deployment and scaling usually apply to the whole application. Good boundaries help later extraction, but data migration and network failure handling remain real work.

#Microservices: independence has a cost

A separate service may pay off when independent scaling, release cadence or ownership is needed. A network call is not a method call: latency, partial failures, timeouts and versioning are design concerns.

An API gateway provides routing and shared policies; a BFF serves a particular client's needs, such as mobile. Neither should become the home of all domain logic. Service discovery resolves logical names to instances through DNS, a registry or platform routing.

Mobile → Mobile BFF → Sales API → Sales-owned database         (1)
                              → outbox → broker → Inventory   (2)
Old application → routing boundary → extracted Catalog API     (3)

Not every bounded context needs a service, and asynchronous communication is not limited to brokers. Start with the least deployment complexity meeting requirements and examine transaction boundaries before splitting.

#CQRS: separate read and write needs

Confirming an order needs invariants; displaying a summary needs a small projection. CQRS separates command and query models and paths. Here “light” means one database and “full” is shorthand for a separate read store; these are common labels, not formal maturity levels. Event sourcing is optional.

// Application fragments; db exposes EF-mapped Orders.
public sealed record ConfirmOrder(int Id);
public sealed record OrderSummary(int Id, string Status);

// Command handler: load, enforce domain behavior, persist.
var order = await db.Orders.SingleAsync(o => o.Id == command.Id, ct);
order.Confirm();
await db.SaveChangesAsync(ct);                               // (1)

// Query handler: project directly, without loading the aggregate.
var summary = await db.Orders.AsNoTracking()
    .Where(o => o.Id == id)
    .Select(o => new OrderSummary(o.Id, o.Status))
    .SingleOrDefaultAsync(ct);                               // (2)

MediatR is an implementation choice, not CQRS itself; check licensing before adoption. Purely ceremonial handler separation may add little to a small CRUD application.

#ADRs and architecture tests

Boundaries drift when their rationale is forgotten and nothing checks them. An ADR records one decision: context, alternatives, decision, consequences and status. Record costs and revisit triggers instead of describing every choice as ideal.

ADR 004: Keep checkout in the modular monolith              (1)
Status: Accepted
Context: Stock reservation and order creation need one local commit.
Alternatives: Shared transaction; service split with saga.
Decision: Shared transaction with explicit module participation.
Consequence: More coupling; simpler atomic persistence.
Revisit: Inventory requires independent ownership or deployment.

// Test project: NetArchTest.Rules and the chosen xUnit package.
using NetArchTest.Rules;
using Xunit;

public sealed class BoundaryTests
{
    [Fact]
    public void Domain_does_not_depend_on_infrastructure()
    {
        var assembly = typeof(Shop.Domain.Order).Assembly;          // (2)
        var result = Types.InAssembly(assembly)
            .ShouldNot().HaveDependencyOn("Shop.Infrastructure")
            .GetResult();
        Assert.True(result.IsSuccessful);                          // (3)
    }
}

NetArchTest and ArchUnitNET express dependency rules; they do not prove domain correctness or stop raw SQL from bypassing ownership. If Catalog.Contracts is allowed, avoid a forbidden namespace prefix that accidentally includes it; separate implementation namespaces or define precise groups.