https://www.bencode.io/categories/architecture/ Recent content in Architecture on Benny Simmonds Hugo -- 0.149.1 en-us Sun, 26 Oct 2025 13:13:01 +1000 https://www.bencode.io/posts/cleanarch/ Thu, 29 May 2025 20:14:01 +1000 https://www.bencode.io/posts/cleanarch/ <p>Domain centric architectures, like clean architecture, have inner architectural cores that model the domain. Dependency inversion is king, with inner layers defining abstractions and interfaces and outer layers implementing them. Clean architecture is a good fit when aligning to Domain Driven Design (DDD), dealing with complex business logic, high testability is desirable and/or working in a large team, as the architecture can enforce design policies.</p> <ul> <li><a href="#guiding-principles">Guiding Principles</a></li> <li><a href="#clean-architecture-layers">Clean Architecture Layers</a> <ul> <li><a href="#domain-layer">Domain layer</a> <ul> <li><a href="#entities">Entities</a></li> <li><a href="#value-objects">Value Objects</a></li> <li><a href="#domain-events">Domain Events</a></li> <li><a href="#domain-services">Domain Services</a></li> <li><a href="#interfaces">Interfaces</a></li> <li><a href="#results-and-exceptions">Results and Exceptions</a></li> </ul> </li> <li><a href="#application-layer-the-use-case-orchestrator">Application layer: The Use Case Orchestrator</a> <ul> <li><a href="#application-layer-key-responsibilities">Application Layer Key Responsibilities</a> <ul> <li><a href="#use-case-orchestration">Use Case Orchestration</a></li> <li><a href="#higher-order-business-logic">Higher Order Business Logic</a></li> <li><a href="#cross-cutting-concerns">Cross Cutting Concerns</a></li> <li><a href="#exception-translation--handling">Exception Translation &amp; Handling</a></li> <li><a href="#dependency-injection-hub">Dependency Injection Hub</a></li> </ul> </li> <li><a href="#what-the-application-layer-does-not-do">What the Application Layer Does NOT Do</a></li> <li><a href="#example-application-service">Example Application Service</a></li> <li><a href="#dependency-injection-and-mediatr-bootstrapping">Dependency Injection and MediatR Bootstrapping</a></li> <li><a href="#cqrs-abstractions">CQRS Abstractions</a></li> <li><a href="#handling-domain-events">Handling Domain Events</a></li> <li><a href="#cross-cutting-concerns-with-mediatr-pipelines">Cross Cutting Concerns with MediatR Pipelines</a> <ul> <li><a href="#logging-pipeline">Logging Pipeline</a></li> <li><a href="#validation-pipeline-with-fluentvalidation">Validation Pipeline with FluentValidation</a></li> </ul> </li> </ul> </li> <li><a href="#infrastructure-layer">Infrastructure layer</a> <ul> <li><a href="#infrastructure-layer-key-responsibilities">Infrastructure Layer Key Responsibilities</a> <ul> <li><a href="#data-persistence-and-access">Data Persistence and Access</a></li> <li><a href="#external-service-integration">External Service Integration</a></li> <li><a href="#cross-cutting-concerns-implementation">Cross Cutting Concerns Implementation</a></li> <li><a href="#event-handling-infrastructure">Event Handling Infrastructure</a></li> </ul> </li> <li><a href="#what-the-infrastructure-layer-does-not-do">What the Infrastructure Layer Does NOT Do</a></li> <li><a href="#example-concrete-provider-for-idatetimeprovider">Example Concrete Provider for IDateTimeProvider</a></li> <li><a href="#ef-core-setup">EF Core Setup</a></li> <li><a href="#integrating-domain-entities-with-ef-core">Integrating Domain Entities with EF Core</a></li> <li><a href="#publishing-domain-events-in-the-unit-of-work">Publishing Domain Events in the Unit of Work</a></li> <li><a href="#handling-race-conditions-with-optimistic-concurrency">Handling Race Conditions with Optimistic Concurrency</a></li> <li><a href="#distributed-cache-service">Distributed Cache Service</a></li> </ul> </li> <li><a href="#presentation-layer">Presentation layer</a> <ul> <li><a href="#presentation-layer-key-responsibilities">Presentation Layer Key Responsibilities</a></li> <li><a href="#what-the-presentation-layer-does-not-do">What the Presentation Layer Does NOT Do</a></li> <li><a href="#api-controllers-and-endpoints">API Controllers and Endpoints</a></li> <li><a href="#seed-data-and-ef-migrations">Seed Data and EF Migrations</a></li> <li><a href="#authentication-authn-with-keycloak">Authentication (authn) with Keycloak</a></li> <li><a href="#authorization-authz">Authorization (authz)</a> <ul> <li><a href="#role-based-authorization">Role-based Authorization</a></li> <li><a href="#permission-based-policy-authorization">Permission-based (Policy) Authorization</a></li> <li><a href="#resource-based-authorization">Resource-based Authorization</a></li> </ul> </li> <li><a href="#structured-logging">Structured Logging</a></li> <li><a href="#health-checks">Health Checks</a></li> </ul> </li> </ul> </li> <li><a href="#net-implementation-tips">.NET Implementation Tips</a> <ul> <li><a href="#general-net-tips">General .NET Tips</a></li> <li><a href="#domain-layer-net-tips">Domain Layer .NET Tips</a></li> <li><a href="#application-layer-net-tips">Application Layer .NET Tips</a></li> <li><a href="#infrastructure-layer-net-tips">Infrastructure Layer .NET Tips</a></li> <li><a href="#presentation-layer-net-tips">Presentation Layer .NET Tips</a></li> </ul> </li> <li><a href="#structured-logging-1">Structured Logging</a> <ul> <li><a href="#serilog">Serilog</a> <ul> <li><a href="#serilog-and-seq-setup-guide">Serilog and Seq Setup Guide</a></li> </ul> </li> </ul> </li> <li><a href="#outbox-pattern">Outbox Pattern</a> <ul> <li><a href="#the-problem">The Problem</a></li> <li><a href="#the-solution">The Solution</a></li> <li><a href="#key-benefits">Key Benefits</a></li> <li><a href="#outbox-net-implementation">Outbox .NET Implementation</a> <ul> <li><a href="#outbox-message-definition">Outbox Message Definition</a></li> <li><a href="#transactionally-publish-domain-events-as-outbox-messages">Transactionally Publish Domain Events as Outbox Messages</a></li> <li><a href="#background-worker-job-with-quartznet">Background Worker Job with Quartz.NET</a></li> <li><a href="#hookup-dependency-injection">Hookup Dependency Injection</a></li> </ul> </li> </ul> </li> <li><a href="#aspnet-core-minimal-apis">ASP.NET Core Minimal APIs</a> <ul> <li><a href="#controller-to-minimal-api-conversion-cookbook">Controller to Minimal API Conversion Cookbook</a></li> <li><a href="#centralising-route-opinions-with-route-groups">Centralising Route Opinions with Route Groups</a></li> </ul> </li> <li><a href="#testing">Testing</a> <ul> <li><a href="#domain-layer-unit-testing">Domain Layer Unit Testing</a></li> <li><a href="#application-layer-unit-testing">Application Layer Unit Testing</a> <ul> <li><a href="#mocking-with-nsubstitute">Mocking with NSubstitute</a></li> </ul> </li> <li><a href="#application-layer-integration-testing-with-testcontainers">Application Layer Integration Testing with TestContainers</a> <ul> <li><a href="#troubleshooting">Troubleshooting</a></li> <li><a href="#accessing-internal-symbols">Accessing Internal Symbols</a></li> </ul> </li> </ul> </li> <li><a href="#bonus-contemporary-net-gems">Bonus: Contemporary .NET gems</a> <ul> <li><a href="#primary-constructors">Primary Constructors</a></li> <li><a href="#switch-expressions">Switch Expressions</a></li> <li><a href="#records">Records</a></li> <li><a href="#async-tips">Async Tips</a></li> <li><a href="#mediatr">MediatR</a> <ul> <li><a href="#irequest-and-irequesthandler---requestresponse">IRequest and IRequestHandler - Request/Response</a> <ul> <li><a href="#publishing">Publishing</a></li> </ul> </li> <li><a href="#inotification-and-inotificationhandler---pubsub">INotification and INotificationHandler - Pub/Sub</a> <ul> <li><a href="#publishing-1">Publishing</a></li> </ul> </li> <li><a href="#mediatrcontracts-package">MediatR.Contracts Package</a></li> </ul> </li> <li><a href="#visual-studio-and-roslyn-code-quality-level-ups">Visual Studio and Roslyn Code Quality Level Ups</a></li> <li><a href="#dotnet-cli-tips">dotnet CLI Tips</a></li> </ul> </li> </ul> <h2 id="guiding-principles">Guiding Principles</h2> <p>High level qualities that a good software architecture should (and enforce) strive for; maintainability, testability and loose coupling.</p>