{"id":79903,"date":"2026-06-19T11:40:18","date_gmt":"2026-06-19T06:10:18","guid":{"rendered":"https:\/\/www.tothenew.com\/blog\/?p=79903"},"modified":"2026-06-19T12:05:27","modified_gmt":"2026-06-19T06:35:27","slug":"learn-onion-architecture-as-a-complete-beginner-and-implement-as-an-architect","status":"publish","type":"post","link":"https:\/\/www.tothenew.com\/blog\/learn-onion-architecture-as-a-complete-beginner-and-implement-as-an-architect\/","title":{"rendered":"Learn Onion Architecture as a Complete Beginner and Implement as an Architect"},"content":{"rendered":"

The Problem Story<\/h2>\n

Picture this. It is a Tuesday afternoon. Your product manager says: “We just need to add an email field. Should be quick, right?”<\/em><\/p>\n

You open the codebase. The User<\/code> entity imports SqlConnection<\/code>. Business logic calls the database in the same method. No interfaces. No tests. Everything wired to everything else.<\/p>\n

You add the field. The ORM breaks. You fix the ORM, and three unrelated features stop working. Four hours for a twenty-minute task.<\/p>\n

“What if your business logic never had to care what database you used, what UI framework you picked, or what cloud you deployed to?”<\/strong><\/p><\/blockquote>\n

That is Onion Architecture \u2014 your business rules at the centre, infrastructure as swappable details at the edge.<\/p>\n

Why Traditional Layered Architecture Fails<\/h2>\n

Most developers start with the classic three-tier model: UI \u2192 Business Logic \u2192 Data Layer<\/strong>. On small projects, it works. On large ones, it becomes a trap in four specific ways:<\/p>\n

    \n
  • Tight Coupling<\/strong> \u2014 Business logic directly instantiates database classes. Swap the ORM, and every service class needs surgery.<\/li>\n
  • Difficult Testing<\/strong> \u2014 To test one business rule, you need a real database running. Not because the rule touches it, but because the class containing it does.<\/li>\n
  • Slow Feature Changes<\/strong> \u2014 Adding a feature in the business layer requires understanding the data layer. Teams constantly step on each other.<\/li>\n
  • High Maintenance Cost<\/strong> \u2014 After 18 months, no one wants to touch the code. This is the layered architecture death spiral.<\/li>\n<\/ul>\n
    \/\/ The classic anti-pattern: business logic importing infrastructure\r\npublic class OrderService\r\n{\r\n    public void PlaceOrder(Order order)\r\n    {\r\n        using var connection = new SqlConnection(\"Server=...\");\r\n        \/\/ business rules mixed with database calls\r\n    }\r\n}<\/pre>\n
    <\/p>\n
    \"Fig<\/p>\n
    <\/h2>\n
    The Core Insight: Inward Dependency Rule<\/h2>\n
    Jeffrey Palermo introduced Onion Architecture in 2008. The single governing rule: dependencies always point inward.<\/strong><\/p>\n
    Inner layers know nothing about outer layers. Outer layers adapt to inner layers \u2014 never the reverse.<\/p>\n
    Think of a company. The CEO (Domain) sets the rules. Management (Application) executes them. Operations (Infrastructure) handles the tools. Front-of-house (Presentation) faces the world. When a new CRM is adopted, the CEO’s strategy does not change.<\/p>\n
    \"Fig
    Fig 2<\/p><\/div>\n
    <\/p>\n
    This works via the Dependency Inversion Principle<\/strong>: the Application layer defines an interface (IOrderRepository<\/code>), and Infrastructure implements it. The interface lives in the inner layer. The implementation lives in the outer layer.<\/p>\n
     <\/p>\n
    The Four Layers Explained for Everyone<\/h2>\n
    Using a restaurant analogy: Domain = recipe book, Application = kitchen manager, Infrastructure = ingredients supplier, Presentation = waiter.<\/p>\n
    Domain Layer (Innermost)<\/h3>\n
    The heart of your application: entities, value objects, domain events, pure business rules. No NuGet packages. No framework references.<\/p>\n
      \n
    • Lives here:<\/strong> Entities, Value Objects, Domain Events, Business Rules<\/li>\n
    • Never here:<\/strong> Entity Framework, HttpClient, SqlConnection<\/li>\n<\/ul>\n
      Application Layer<\/h3>\n
      The use-case layer. Orchestrates the domain. Contains use cases, service interfaces, and DTOs.<\/p>\n
        \n
      • Lives here:<\/strong> Use Cases, IRepository interfaces, DTOs, Application Services<\/li>\n
      • Never here:<\/strong> EF DbContext, HTTP Controllers<\/li>\n<\/ul>\n
        Infrastructure Layer<\/h3>\n
        The plumbing. Implements the interfaces defined in Application. Databases, email, file system, APIs. Completely swappable.<\/p>\n
          \n
        • Lives here:<\/strong> SqlOrderRepository, AppDbContext, SmtpEmailService, S3FileStorage<\/li>\n
        • Never here:<\/strong> Business rules<\/li>\n<\/ul>\n
          Presentation Layer (Outermost)<\/h3>\n
          The entry point. Controllers, Minimal API, gRPC, Worker Services. Takes the order, passes it in, returns results. Never contains business logic.<\/p>\n
          The 7 Key Principles Beyond the Definition<\/h2>\n
            \n
          1. Domain-Centric Design<\/strong> \u2014 Business rules first. Database shaped to match the domain, not vice versa.<\/li>\n
          2. Dependency Inward Rule<\/strong> \u2014 A using<\/code> statement in Domain pointing to Infrastructure is a violation.<\/li>\n
          3. Separation of Concerns<\/strong> \u2014 Each layer, one job. Application orchestrates; it does not calculate.<\/li>\n
          4. Infrastructure as External Detail<\/strong> \u2014 Application defines IOrderRepository<\/code>; Infrastructure delivers SqlOrderRepository<\/code>.<\/li>\n
          5. Testability<\/strong> \u2014 Use cases testable with nothing but mocks. No database, no HTTP, no test containers.<\/li>\n
          6. Maintainability<\/strong> \u2014 Swapping ORM from EF Core to Dapper: one-project change. Application and Domain untouched.<\/li>\n
          7. Independent Domain Layer<\/strong> \u2014 Open your domain entity. Any [Key]<\/code> or EF attribute? Remove them.<\/li>\n<\/ol>\n
            Self-Assessment Checklist<\/h3>\n
              \n
            • Domain entities have zero infrastructure using statements<\/li>\n
            • All interfaces live in the Application layer<\/li>\n
            • Infrastructure references Application \u2014 not the reverse<\/li>\n
            • Domain has no third-party NuGet dependencies<\/li>\n
            • Business rules testable without a database<\/li>\n
            • Swapping the ORM only affects Infrastructure<\/li>\n
            • Presentation calls Application services, never Infrastructure directly<\/li>\n<\/ul>\n
              Visualising Onion Architecture<\/h2>\n
              Fig 3: The Onion rings annotated with real class examples \u2014 Domain at centre, through Application, Infrastructure, to Presentation.<\/p>\n
              <\/p>\n
              \"Fig
              Fig 3<\/p><\/div>\n
              <\/p>\n
              Fig 4: A single HTTP POST flowing through all four layers: Controller \u2192 UseCase \u2192 Domain \u2192 Repository \u2192 SQL Server \u2192 201 response.<\/em><\/p>\n
              <\/p>\n
              \"Fig
              Fig 4<\/p><\/div>\n
              Fig 5: Recommended .NET solution structure \u2014 each layer as a separate project for enforced dependency rules.<\/em><\/p>\n
              \"Fig
              Fig 5<\/p><\/div>\n
              Implementing It: From Concept to Code<\/h2>\n
              Step 1 \u2014 Domain Entity<\/h3>\n
              public class Order\r\n{\r\n    public Guid Id { get; private set; }\r\n    public decimal TotalAmount { get; private set; }\r\n\r\n    private Order() { }\r\n\r\n    public static Order Create(Guid customerId, decimal amount)\r\n    {\r\n        if (amount <= 0) throw new DomainException(\"Amount must be positive.\");\r\n        return new Order { Id = Guid.NewGuid(), TotalAmount = amount };\r\n    }\r\n}<\/pre>\n
              Step 2 \u2014 Use Case in Application Layer<\/h3>\n
              public class PlaceOrderUseCase\r\n{\r\n    private readonly IOrderRepository _orders;\r\n    private readonly IEmailService _email;\r\n   public async Task<Guid> ExecuteAsync(CreateOrderDto dto)\r\n    {\r\n        var order = Order.Create(dto.CustomerId, dto.Amount);\r\n        await _orders.AddAsync(order);\r\n        await _orders.SaveChangesAsync();\r\n        await _email.SendOrderConfirmationAsync(dto.CustomerEmail, order.Id);\r\n        return order.Id;\r\n    }\r\n}<\/pre>\n
              Step 3 \u2014 Controller in Presentation<\/h3>\n
              [HttpPost]\r\npublic async Task<IActionResult> Create(CreateOrderDto dto)\r\n{\r\n    var orderId = await _placeOrder.ExecuteAsync(dto);\r\n    return CreatedAtAction(nameof(Create), new { id = orderId }, orderId);\r\n}<\/pre>\n
              Step 4 \u2014 DI Wiring (Program.cs)<\/h3>\n
              builder.Services.AddScoped<IOrderRepository, SqlOrderRepository>();\r\nbuilder.Services.AddScoped<IEmailService, SmtpEmailService>();\r\nbuilder.Services.AddScoped<PlaceOrderUseCase>();<\/pre>\n
              Real-World Use Cases<\/h2>\n
              “Your business logic should outlive your framework. Onion Architecture is the insurance policy.”<\/strong><\/p><\/blockquote>\n
              E-Commerce<\/h3>\n
              Discount rules, inventory, order lifecycle independent of storefront or database. Migrate from SQL Server to Cosmos DB \u2014 Domain and Application untouched.<\/p>\n
              Banking \/ FinTech<\/h3>\n
              Compliance rules testable, auditable, independent of vendor SDKs. Business rules live once in the domain \u2014 regardless of web, mobile, API, or batch delivery.<\/p>\n
              Multi-Channel Delivery<\/h3>\n
              <\/p>\n
              Same Domain and Application layers powering Web API, background worker, CLI tool, and gRPC service. Only Presentation changes per channel.<\/p>\n
              \"Fig
              Fig 6<\/p><\/div>\n
              Legacy Migration<\/h3>\n
              Use the strangler fig pattern \u2014 wrap legacy code with clean interfaces, replace internals gradually. No big-bang rewrite required.<\/p>\n
              Onion vs Clean Architecture: The Honest Comparison<\/h2>\n
              Clean Architecture<\/strong> (Uncle Bob, 2012): conceptual principles \u2014 Entities, Use Cases, Interface Adapters, Frameworks.<\/p>\n
              Onion Architecture<\/strong> (Palermo, 2008): structural implementation \u2014 Domain, Application, Infrastructure, Presentation with inward dependency rule.<\/p>\n\n\n\n\n\n\n\n\n
              Dimension<\/th>\nOnion Architecture<\/th>\nClean Architecture<\/th>\n<\/tr>\n
              Nature<\/td>\nStructural<\/td>\nConceptual<\/td>\n<\/tr>\n
              Focus<\/td>\nDomain-centric<\/td>\nUse-case-driven<\/td>\n<\/tr>\n
              Dependency Rule<\/td>\nInward<\/td>\nInward (same)<\/td>\n<\/tr>\n
              Flexibility<\/td>\nFlexible naming<\/td>\nPrescriptive naming<\/td>\n<\/tr>\n
              Coexist?<\/td>\nYes \u2014 many teams blend both successfully<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
              Myth-buster:<\/strong> They are not the same thing. Onion is structural; Clean is philosophical. A well-implemented Onion Architecture satisfies most Clean Architecture principles automatically.<\/p>\n
              Things I Wish I Knew Before Implementing Onion Architecture<\/h2>\n
              Anti-Pattern 1 \u2014 Infrastructure Leaking into Domain<\/h3>\n
              [Table]<\/code>, [Column]<\/code>, or EF navigation properties on domain entities. Technically compiles. Architecturally fatal.<\/p>\n
              \/\/ WRONG\r\n[Table(\"orders\")] public class Order { [Key] public Guid Id { get; set; } }\r\n\r\n\/\/ RIGHT \u2014 EF mapping in Infrastructure, domain stays clean\r\npublic class Order { public Guid Id { get; private set; } }<\/pre>\n
              Anti-Pattern 2 \u2014 Anemic Domain Model<\/h3>\n
              Entities with only getters and setters. Business rules pushed into services. Domain is hollow. Onion without a rich domain is just folder organisation.<\/p>\n
              Anti-Pattern 3 \u2014 Service Layer Overload<\/h3>\n
              Use cases should be small: PlaceOrderUseCase<\/code>, CancelOrderUseCase<\/code>. An 800-line OrderService<\/code> has too many jobs.<\/p>\n
              Anti-Pattern 4 \u2014 Interface for Everything<\/h3>\n
              Interfaces earn their place when they enable mocking or multiple implementations. If a class will only ever have one implementation, the interface is noise.<\/p>\n
              Anti-Pattern 5 \u2014 Onion in Name Only<\/h3>\n
              Check your .csproj<\/code> files: Domain \u2192 nothing, Application \u2192 Domain only, Infrastructure \u2192 Application, API \u2192 Infrastructure + Application. Any other reference is a violation.<\/p>\n
              Testing Strategy in Onion Architecture<\/h2>\n
              \"Fig
              Fig 7<\/p><\/div>\n
              <\/p>\n
                \n
              • Domain layer:<\/strong> Pure unit tests \u2014 no mocks needed, business rules in complete isolation<\/li>\n
              • Application layer:<\/strong> Unit tests with mocked repositories \u2014 no database, no HTTP<\/li>\n
              • Infrastructure layer:<\/strong> Integration tests with real DB (test containers)<\/li>\n
              • Presentation layer:<\/strong> End-to-end \/ contract tests<\/li>\n<\/ul>\n
                \/\/ No SQL Server started. Pure business logic test.\r\n[Fact]\r\npublic async Task Execute_NegativeAmount_ThrowsDomainException()\r\n{\r\n    var useCase = new PlaceOrderUseCase(_orderRepo.Object, _email.Object);\r\n    var dto = new CreateOrderDto { Amount = -50m };\r\n    await Assert.ThrowsAsync<DomainException>(() => useCase.ExecuteAsync(dto));\r\n}<\/pre>\n
                Architecture Tests<\/h3>\n
                [Fact]\r\npublic void Domain_Should_Not_Reference_Infrastructure()\r\n{\r\n    var result = Types.InAssembly(typeof(Order).Assembly)\r\n        .ShouldNot().HaveDependencyOn(\"YourApp.Infrastructure\").GetResult();\r\n    result.IsSuccessful.Should().BeTrue();\r\n}<\/pre>\n
                The Architect’s Mental Model<\/h2>\n
                We traced the full journey: tight coupling pain \u2192 inward dependency insight \u2192 four layers \u2192 seven principles \u2192 implementation \u2192 use cases \u2192 comparison \u2192 anti-patterns \u2192 testing.<\/p>\n
                “Your domain should be able to run its tests with zero infrastructure. If it cannot, your architecture has a leak.”<\/strong><\/p><\/blockquote>\n
                Further Reading<\/h3>\n
                  \n
                • Jeffrey Palermo’s original 2008 blog post on Onion Architecture<\/li>\n
                • Clean Architecture<\/em> \u2014 Robert C. Martin (2017)<\/li>\n
                • Domain-Driven Design<\/em> \u2014 Eric Evans<\/li>\n
                • Patterns of Enterprise Application Architecture<\/em> \u2014 Martin Fowler<\/li>\n<\/ul>\n
                  \n
                  Which layer do you think most teams get wrong first, and why?<\/strong> Share your experience in the comments.<\/p>\n","protected":false},"excerpt":{"rendered":"
                  The Problem Story Picture this. It is a Tuesday afternoon. Your product manager says: “We just need to add an email field. Should be quick, right?” You open the codebase. The User entity imports SqlConnection. Business logic calls the database in the same method. No interfaces. No tests. Everything wired to everything else. You add […]<\/p>\n","protected":false},"author":2282,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"iawp_total_views":101,"footnotes":""},"categories":[5867],"tags":[2930,6490,6734,8604,7248,8603],"class_list":["post-79903","post","type-post","status-publish","format-standard","hentry","category-net","tag-architecture","tag-ddd","tag-dotnet","tag-onionarchitecture","tag-softwaredesign","tag-solid"],"aioseo_notices":[],"aioseo_head":"\n\t\t\n\t\n\t\n\t\n\t\n\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t