Choosing An Architecture - Learning Module

Loading content...

0/246

Practical Considerations: Implementation and Pitfalls

From Theory to Practice

Understanding architectural patterns conceptually is essential—but it's only half the battle. The true test comes when you begin implementation. How do you structure your folders? What naming conventions support the architecture? How do you configure dependency injection? What are the common mistakes that derail even well-intentioned teams?

This page bridges the gap between theory and practice. We'll examine the concrete decisions that bring architectural patterns to life: project organization, coding conventions, team coordination, and the pitfalls that commonly undermine architectural intentions. By the end, you'll have actionable guidance for implementing whatever architecture you've chosen.

What You Will Master

By the end of this page, you will be able to organize codebases to reflect architectural patterns, establish conventions that reinforce architectural boundaries, configure dependency injection properly, and avoid the common pitfalls that cause architectural decay in real projects.

Project Organization Strategies

Folder structure is the first visible manifestation of architecture. A well-designed structure makes architectural boundaries obvious; a poor one hides them or actively contradicts them.

Two Fundamental Approaches:

Organization by Layer — Group files by their architectural layer (Domain, Application, Infrastructure)
Organization by Feature — Group files by the feature or capability they support

Most domain-centric architectures benefit from a hybrid approach: layer-based at the top level, feature-based within layers. Let's examine concrete examples.

Clean Architecture Folder Structure

text

MyApplication/
├── src/
│   ├── Domain/                           # Enterprise Business Rules (innermost)
│   │   ├── Entities/
│   │   │   ├── Order.cs                  # Core domain entity
│   │   │   ├── Customer.cs
│   │   │   └── Product.cs
│   │   ├── ValueObjects/
│   │   │   ├── Money.cs
│   │   │   ├── Address.cs
│   │   │   └── OrderId.cs
│   │   ├── Aggregates/                   # Aggregate roots
│   │   │   ├── OrderAggregate.cs
│   │   │   └── CustomerAggregate.cs
│   │   ├── Events/                       # Domain events
│   │   │   ├── OrderPlacedEvent.cs
│   │   │   └── OrderShippedEvent.cs
│   │   ├── Interfaces/                   # Port interfaces (defined by domain)
│   │   │   ├── IOrderRepository.cs
│   │   │   ├── IPaymentService.cs
│   │   │   └── IEmailService.cs
│   │   └── Exceptions/
│   │       ├── InsufficientInventoryException.cs
│   │       └── InvalidOrderStateException.cs
│   │
│   ├── Application/                      # Application Business Rules
│   │   ├── UseCases/                     # Organized by feature
│   │   │   ├── Orders/
│   │   │   │   ├── PlaceOrder/
│   │   │   │   │   ├── PlaceOrderCommand.cs
│   │   │   │   │   ├── PlaceOrderHandler.cs
│   │   │   │   │   └── PlaceOrderValidator.cs
│   │   │   │   ├── CancelOrder/
│   │   │   │   │   ├── CancelOrderCommand.cs
│   │   │   │   │   └── CancelOrderHandler.cs
│   │   │   │   └── GetOrderDetails/
│   │   │   │       ├── GetOrderDetailsQuery.cs
│   │   │   │       ├── GetOrderDetailsHandler.cs
│   │   │   │       └── OrderDetailsDto.cs
│   │   │   └── Payments/
│   │   │       └── ProcessPayment/
│   │   │           ├── ProcessPaymentCommand.cs
│   │   │           └── ProcessPaymentHandler.cs
│   │   ├── Common/
│   │   │   ├── Behaviors/                # Cross-cutting concerns
│   │   │   │   ├── LoggingBehavior.cs
│   │   │   │   └── ValidationBehavior.cs
│   │   │   └── Interfaces/
│   │   │       ├── IDateTimeProvider.cs
│   │   │       └── ICurrentUserService.cs
│   │   └── Mappings/
│   │       └── OrderMappingProfile.cs
│   │
│   ├── Infrastructure/                   # Frameworks & Drivers (outermost)
│   │   ├── Persistence/
│   │   │   ├── Configurations/           # EF Core configs
│   │   │   │   ├── OrderConfiguration.cs
│   │   │   │   └── CustomerConfiguration.cs
│   │   │   ├── Repositories/
│   │   │   │   ├── OrderRepository.cs    # Implements IOrderRepository
│   │   │   │   └── CustomerRepository.cs
│   │   │   ├── Migrations/
│   │   │   └── AppDbContext.cs
│   │   ├── ExternalServices/
│   │   │   ├── Payment/
│   │   │   │   └── StripePaymentService.cs
│   │   │   └── Email/
│   │   │       └── SendGridEmailService.cs
│   │   ├── Identity/
│   │   │   └── CurrentUserService.cs
│   │   └── DependencyInjection.cs        # DI configuration
│   │
│   └── WebApi/                           # Interface Adapters (presentation)
│       ├── Controllers/
│       │   ├── OrdersController.cs
│       │   └── PaymentsController.cs
│       ├── Middleware/
│       │   └── ExceptionHandlingMiddleware.cs
│       ├── Filters/
│       └── Program.cs
│
├── tests/
│   ├── Domain.UnitTests/
│   ├── Application.UnitTests/
│   ├── Infrastructure.IntegrationTests/
│   └── WebApi.IntegrationTests/
│
└── README.md

Folder Structure As Documentation

A well-designed folder structure is self-documenting. A new developer should be able to look at the top-level folders and immediately understand the architectural approach. Names like 'Domain', 'Application', 'Infrastructure' signal Clean Architecture; 'Core', 'Adapters' might signal Hexagonal.

Alternative: Hexagonal Architecture Structure

Hexagonal Architecture uses different terminology, reflected in its folder structure. The concepts map directly to Clean Architecture but with port/adapter vocabulary.

Hexagonal Architecture Folder Structure

text

OrderingService/
├── src/
│   ├── Core/                             # The Hexagon (Application Core)
│   │   ├── Domain/                       # Domain model
│   │   │   ├── Order.cs
│   │   │   ├── Customer.cs
│   │   │   └── ValueObjects/
│   │   │       ├── Money.cs
│   │   │       └── OrderId.cs
│   │   ├── Ports/                        # Interfaces (inbound and outbound)
│   │   │   ├── Inbound/                  # Primary/Driving ports
│   │   │   │   ├── IOrderingService.cs   # Use cases as interface
│   │   │   │   └── IInventoryQueryService.cs
│   │   │   └── Outbound/                 # Secondary/Driven ports
│   │   │       ├── IOrderRepository.cs
│   │   │       ├── IPaymentGateway.cs
│   │   │       └── IEmailSender.cs
│   │   ├── Services/                     # Application services (implement inbound ports)
│   │   │   ├── OrderingService.cs        # Implements IOrderingService
│   │   │   └── InventoryQueryService.cs
│   │   └── Events/
│   │       └── OrderPlaced.cs
│   │
│   └── Adapters/                         # Outside the Hexagon
│       ├── Inbound/                      # Primary/Driving adapters
│       │   ├── Web/
│       │   │   ├── Controllers/
│       │   │   │   └── OrdersController.cs
│       │   │   └── DTOs/
│       │   │       └── CreateOrderRequest.cs
│       │   ├── CLI/
│       │   │   └── OrderCommands.cs
│       │   └── MessageQueue/
│       │       └── OrderEventConsumer.cs
│       │
│       └── Outbound/                     # Secondary/Driven adapters
│           ├── Persistence/
│           │   ├── SqlOrderRepository.cs  # Implements IOrderRepository
│           │   └── Configurations/
│           │       └── OrderMapping.cs
│           ├── Payment/
│           │   └── StripePaymentGateway.cs
│           └── Email/
│               └── SmtpEmailSender.cs
│
└── tests/
    ├── Core.Tests/                       # Unit tests for core
    └── Adapters.Tests/                   # Integration tests for adapters

Key Differences from Clean Architecture Structure:

Explicit Port Separation: Inbound vs Outbound ports are structurally separated
Adapter Symmetry: The same inbound/outbound distinction applies to adapters
Terms: 'Core' instead of 'Domain+Application'; 'Adapters' instead of 'Infrastructure'

Choose Consistent Vocabulary

The terminology matters less than consistency. Pick Clean Architecture vocabulary, Hexagonal vocabulary, or Onion vocabulary—and use it consistently throughout the codebase, documentation, and team communication.

Naming Conventions That Reinforce Architecture

Names are powerful tools for enforcing architecture. When names clearly signal architectural roles, violations become obvious. Let's establish conventions for each architectural element.

Naming Conventions by Architectural Element
Element	Convention	Examples
Entities	Noun, representing the object	Order, Customer, Product
Value Objects	Noun or descriptive name	Money, Address, EmailAddress
Aggregates	EntityAggregate or just Entity if obvious	OrderAggregate, CustomerAggregate
Domain Events	Past tense verb phrase	OrderPlacedEvent, PaymentProcessedEvent
Commands	Imperative verb phrase + Command	PlaceOrderCommand, CancelOrderCommand
Queries	Get/Find + noun + Query	GetOrderDetailsQuery, FindCustomersByRegionQuery
Handlers	Match command/query + Handler	PlaceOrderHandler, GetOrderDetailsHandler
Ports/Interfaces	I + noun + capability	IOrderRepository, IPaymentGateway, IEmailService
Adapters	Technology + Interface name (impl)	SqlOrderRepository, StripePaymentGateway
DTOs	Purpose + DTO or Request/Response	CreateOrderRequest, OrderDetailsDto
Controllers	Plural noun + Controller	OrdersController, PaymentsController

Namespace/Package Naming:

Namespaces should mirror the folder structure and reinforce layer boundaries:

Namespace Conventions
C#
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
// Domain Layer - Pure business logic
namespace MyApp.Domain.Entities 
{
    public class Order { }
}
 
namespace MyApp.Domain.ValueObjects
{
    public record Money(decimal Amount, string Currency);
}
 
namespace MyApp.Domain.Interfaces  // Ports defined by domain
{
    public interface IOrderRepository { }
}
 
// Application Layer - Use cases
namespace MyApp.Application.Orders.PlaceOrder
{
    public record PlaceOrderCommand(/* ... */);
    public class PlaceOrderHandler { }
}
 
// Infrastructure Layer - Adapters
namespace MyApp.Infrastructure.Persistence.Repositories
{
    public class SqlOrderRepository : IOrderRepository { }
}
 
// Presentation Layer - Controllers
namespace MyApp.WebApi.Controllers
{
    public class OrdersController : ControllerBase { }
}

Names Surface Violations

When naming conventions are consistent, violations become jarring. If you see 'SqlOrderRepository' in the Domain namespace or 'Order' (entity) being imported into a Controller, the inconsistency is immediately visible during code review.

Dependency Injection Configuration

Dependency Injection (DI) is the mechanism that makes domain-centric architectures work. The DI container wires interfaces to implementations at composition time, allowing the domain to depend on abstractions while the actual implementations are provided from the infrastructure layer.

The Composition Root:

The Composition Root is the single location where all dependencies are configured. In ASP.NET Core, this is typically Program.cs or extension methods called from it.

DI Configuration
C#
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
// Infrastructure/DependencyInjection.cs
namespace MyApp.Infrastructure;
 
public static class DependencyInjection
{
    public static IServiceCollection AddInfrastructure(
        this IServiceCollection services,
        IConfiguration configuration)
    {
        // Persistence
        services.AddDbContext<AppDbContext>(options =>
            options.UseSqlServer(configuration.GetConnectionString("Default")));
        
        // Repository implementations (adapters for ports)
        services.AddScoped<IOrderRepository, SqlOrderRepository>();
        services.AddScoped<ICustomerRepository, SqlCustomerRepository>();
        
        // External service adapters
        services.AddScoped<IPaymentGateway, StripePaymentGateway>();
        services.AddScoped<IEmailService, SendGridEmailService>();
        
        // Infrastructure services
        services.AddScoped<IDateTimeProvider, SystemDateTimeProvider>();
        
        return services;
    }
}
 
// Application/DependencyInjection.cs
namespace MyApp.Application;
 
public static class DependencyInjection
{
    public static IServiceCollection AddApplication(this IServiceCollection services)
    {
        // Register MediatR for CQRS handlers
        services.AddMediatR(cfg => {
            cfg.RegisterServicesFromAssembly(typeof(DependencyInjection).Assembly);
        });
        
        // Register validation pipeline
        services.AddScoped(typeof(IPipelineBehavior<,>), typeof(ValidationBehavior<,>));
        services.AddScoped(typeof(IPipelineBehavior<,>), typeof(LoggingBehavior<,>));
        
        // AutoMapper for DTO mapping
        services.AddAutoMapper(typeof(DependencyInjection).Assembly);
        
        return services;
    }
}
 
// WebApi/Program.cs (Composition Root)
var builder = WebApplication.CreateBuilder(args);
 
// Add layers in dependency order
builder.Services.AddApplication();        // Application layer
builder.Services.AddInfrastructure(       // Infrastructure layer
    builder.Configuration);
 
var app = builder.Build();

DI Best Practices

•One Composition Root — All wiring happens in one place. Don't scatter registration across the codebase.
•Layer-Specific Extensions — Each layer provides an extension method that registers its own types.
•Interface First — Always register interfaces, not concrete types directly.
•Appropriate Lifetimes — Use Scoped for request-bound work, Singleton for stateless services, Transient sparingly.
•Environment-Specific Configuration — Different adapters for different environments (e.g., in-memory for tests).

Common Implementation Pitfalls

Even teams that understand architectural concepts make implementation mistakes. Here are the most common pitfalls and how to avoid them:

Pitfall 1: Anemic Domain Model

•Symptom: Entities are just data containers with getters/setters. All logic lives in services.
•Problem: You've recreated procedural programming with extra steps. The domain model provides no encapsulation.
•Solution: Push behavior into entities. Orders should know how to calculate totals, validate themselves, apply discounts. Services orchestrate; entities contain logic.

Anemic vs Rich Domain Model
C#
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
// ❌ ANEMIC: Entity has no behavior
public class Order
{
    public Guid Id { get; set; }
    public List<OrderLine> Lines { get; set; }
    public decimal Total { get; set; }
    public string Status { get; set; }
}
 
public class OrderService
{
    public void PlaceOrder(Order order)
    {
        // All logic in service - entity is just a data bag
        order.Total = order.Lines.Sum(l => l.Quantity * l.UnitPrice);
        if (order.Total < 0) throw new Exception("Invalid total");
        order.Status = "Placed";
        _repository.Save(order);
    }
}
 
// ✅ RICH: Entity encapsulates behavior
public class Order
{
    private readonly List<OrderLine> _lines = new();
    public IReadOnlyList<OrderLine> Lines => _lines.AsReadOnly();
    public Money Total { get; private set; }
    public OrderStatus Status { get; private set; }
    
    public void AddLine(Product product, int quantity)
    {
        if (Status != OrderStatus.Draft)
            throw new InvalidOrderStateException("Cannot modify placed order");
        
        var line = new OrderLine(product, quantity);
        _lines.Add(line);
        RecalculateTotal();
    }
    
    public void Place()
    {
        if (!_lines.Any())
            throw new InvalidOperationException("Cannot place empty order");
        
        Status = OrderStatus.Placed;
        AddDomainEvent(new OrderPlacedEvent(this));
    }
    
    private void RecalculateTotal()
    {
        Total = _lines.Aggregate(Money.Zero, (sum, line) => sum + line.Total);
    }
}

Pitfall 2: Leaking Infrastructure Into Domain

•Symptom: Domain entities have ORM attributes, serialization attributes, or framework-specific types.
•Problem: The domain is now coupled to infrastructure choices. Changing ORMs means changing entities.
•Solution: Keep entities pure. Use separate persistence models mapped to/from domain entities.

Pitfall 3: Pass-Through Layers

•Symptom: Application service methods just call repository methods with no additional logic.
•Problem: Layers exist without providing value—just adding indirection and maintenance burden.
•Solution: Either add meaningful logic to the layer, or acknowledge this is a simple CRUD operation that doesn't need all layers. Not everything requires full architecture.

Pitfall 4: Interface Explosion

•Symptom: Every class has a corresponding interface, including trivial utilities and data mappers.
•Problem: Interfaces add cognitive overhead and maintenance burden. Not everything needs to be swappable.
•Solution: Create interfaces for dependencies that cross architectural boundaries or need to be mocked in tests. Not every class needs an interface.

Pitfall 5: Wrong Abstraction Level

•Symptom: Repository interfaces expose database concepts (like IQueryable) or adapters expose vendor-specific types.
•Problem: The abstraction is leaky—it's tightly coupled to the implementation it's supposed to abstract.
•Solution: Interfaces should be defined in terms of domain concepts. IOrderRepository.FindByCustomer(CustomerId) not IOrderRepository.Query(Expression<Func<Order,bool>>).

Team Organization and Architecture

Conway's Law states that organizations design systems mirroring their communication structures. For architecture to succeed, team organization must align with—or at least not contradict—architectural boundaries.

Team Structures That Support Architecture:

Team Structures and Architectural Fit
Team Structure	Best For	Architectural Alignment
Feature Teams	Cross-functional delivery	Teams own features across all layers; need architectural guardrails
Component/Layer Teams	Deep expertise per layer	Natural ownership of layers; risk of handoff overhead
Domain Teams	Complex domains	Align with bounded contexts; each team owns a domain's full stack
Platform Teams	Shared infrastructure	Own common adapters, shared infrastructure layer

Practical Recommendations:

Team-Architecture Alignment

•Ownership Clarity — Every file should have a clear owning team. Shared code with unclear ownership decays fastest.
•Architecture Champions — Each team should have someone responsible for architectural consistency within that team's work.
•Cross-Team Interfaces — When teams must integrate, define explicit interfaces (like ports) at the boundary. Don't share implementation details.
•Regular Syncs — Architecture-focused discussions (not just feature standups) help maintain alignment across teams.
•Shared Guidelines — Document architectural patterns and conventions. New team members and new teams need onboarding material.

Inverse Conway Maneuver

Some organizations deliberately restructure teams to drive architectural outcomes (the 'Inverse Conway Maneuver'). If you want microservices, create small autonomous teams. If you want a cohesive monolith, keep teams closely integrated. Structure follows strategy.

Testing Strategy by Architectural Layer

One of the primary benefits of domain-centric architecture is testability. Each layer can be tested appropriately, with the testing pyramid naturally emerging from the architecture.

Testing Strategy by Layer
Layer	Test Type	Dependencies	Speed	Coverage Focus
Domain	Unit Tests	None (pure code)	Very Fast	Business rules, entity behavior, value objects
Application	Unit Tests	Mocked ports	Fast	Use case orchestration, workflows
Infrastructure	Integration Tests	Real dependencies	Slow	Adapter correctness, database queries
Presentation/API	Integration Tests	In-memory application	Medium	Request/response mapping, routing
Full System	E2E Tests	All real	Very Slow	Critical paths, smoke tests

Testing Examples by Layer
C#
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
// DOMAIN LAYER: Pure unit tests - no dependencies
[Fact]
public void Order_AddLine_IncreasesTotalCorrectly()
{
    // Arrange
    var order = new Order(CustomerId.New());
    var product = new Product("Widget", Money.FromUsd(10));
    
    // Act
    order.AddLine(product, quantity: 3);
    
    // Assert
    order.Total.Should().Be(Money.FromUsd(30));
}
 
// APPLICATION LAYER: Unit tests with mocked ports
[Fact]
public async Task PlaceOrder_ValidOrder_SavesAndPublishesEvent()
{
    // Arrange
    var mockRepo = new Mock<IOrderRepository>();
    var mockPublisher = new Mock<IEventPublisher>();
    var handler = new PlaceOrderHandler(mockRepo.Object, mockPublisher.Object);
    var command = new PlaceOrderCommand(/* ... */);
    
    // Act
    await handler.Handle(command, CancellationToken.None);
    
    // Assert
    mockRepo.Verify(r => r.Add(It.IsAny<Order>()), Times.Once);
    mockPublisher.Verify(p => p.Publish(It.IsAny<OrderPlacedEvent>()), Times.Once);
}
 
// INFRASTRUCTURE LAYER: Integration tests with real DB
[Fact]
public async Task SqlOrderRepository_Add_PersistsOrder()
{
    // Arrange
    using var context = CreateTestDbContext();  // In-memory or testcontainers
    var repository = new SqlOrderRepository(context);
    var order = CreateTestOrder();
    
    // Act
    await repository.Add(order);
    await context.SaveChangesAsync();
    
    // Assert
    var loaded = await context.Orders.FindAsync(order.Id);
    loaded.Should().NotBeNull();
    loaded.Total.Should().Be(order.Total);
}
 
// API LAYER: Integration tests with WebApplicationFactory
[Fact]
public async Task POST_Orders_ValidRequest_Returns201()
{
    // Arrange
    await using var factory = new WebApplicationFactory<Program>();
    var client = factory.CreateClient();
    var request = new CreateOrderRequest { /* ... */ };
    
    // Act
    var response = await client.PostAsJsonAsync("/api/orders", request);
    
    // Assert
    response.StatusCode.Should().Be(HttpStatusCode.Created);
}

The Testing Pyramid Emerges

With proper architecture, the testing pyramid (many unit tests, fewer integration tests, few E2E tests) emerges naturally. Domain and application layers have thousands of fast unit tests. Infrastructure has hundreds of slower integration tests. A handful of E2E tests validate complete flows.

Implementation Checklist

Use this checklist when implementing domain-centric architecture. It serves as a quality gate for architectural compliance:

Domain Layer Checklist

•☐ Entities have behavior, not just data
•☐ Value objects are immutable with value equality
•☐ No references to infrastructure (ORMs, frameworks)
•☐ Interfaces (ports) for external dependencies are defined here
•☐ Domain events capture significant occurrences
•☐ Aggregates enforce invariants
•☐ Domain exceptions are specific and meaningful

Application Layer Checklist

•☐ Use cases are explicit (commands/queries)
•☐ Handlers orchestrate, don't contain business logic
•☐ DTOs for external communication; domain objects internal
•☐ Cross-cutting concerns handled via behaviors/decorators
•☐ Validation happens before domain operations
•☐ Transaction boundaries are clear

Infrastructure Layer Checklist

•☐ All adapters implement domain-defined interfaces
•☐ No domain logic in adapters (only mapping/translation)
•☐ Technology-specific code is isolated
•☐ Multiple implementations possible (e.g., SQL + in-memory)
•☐ Configuration externalized appropriately
•☐ Integration tests cover adapter behavior

Presentation Layer Checklist

•☐ Controllers are thin (delegate to application layer)
•☐ DTOs define API contract, mapped from domain
•☐ Error handling is consistent
•☐ Authentication/authorization at boundaries
•☐ No business logic in controllers

Overall Architecture Checklist

•☐ Dependencies point inward only
•☐ Folder structure reflects architecture
•☐ Naming conventions are consistent
•☐ DI configuration is centralized
•☐ Architectural fitness functions exist
•☐ ADRs document key decisions
•☐ Onboarding documentation exists

Module Summary: Choosing an Architecture

We've completed a comprehensive exploration of how to choose, implement, and maintain software architecture. Let's consolidate everything we've learned across this module:

Module Key Takeaways

•Architecture Comparison: Traditional Layered trades flexibility for simplicity; Hexagonal, Onion, and Clean share the same core principles with different terminology. The defining difference is dependency direction.
•Project Fit: Multiple dimensions influence choice—domain complexity, lifespan, team, technical requirements, and organizational context. Use frameworks to structure thinking, not replace judgment.
•Evolution: Architecture has a lifecycle. Evolution is inevitable, driven by business, scale, technology, and team changes. Manage debt proactively; prevent decay with fitness functions and governance.
•Practical Implementation: Folder structure manifests architecture. Naming conventions reinforce boundaries. DI wires dependencies. Common pitfalls include anemic models, leaky abstractions, and unnecessary complexity.

The Ultimate Insight:

Architecture is not a one-time decision but an ongoing practice. The best architects are not those who design perfect systems from the start (impossible), but those who make good initial choices and skillfully adapt as reality unfolds.

Your architecture should serve your goals—not the reverse. Be pragmatic, be thoughtful, and always remember: the goal isn't architectural purity, but building systems that work, scale, and remain maintainable over time.

Module Complete

Congratulations! You've completed the module on Choosing an Architecture. You now have a comprehensive framework for comparing, selecting, evolving, and implementing architectural patterns. You're equipped to make informed architectural decisions for any project context and to guide those architectures through their full lifecycle.

Practical Considerations: Implementation and Pitfalls

From Theory to Practice

What You Will Master

Project Organization Strategies

Folder structure is the first visible manifestation of architecture. A well-designed structure makes architectural boundaries obvious; a poor one hides them or actively contradicts them.

Two Fundamental Approaches:

Organization by Layer — Group files by their architectural layer (Domain, Application, Infrastructure)
Organization by Feature — Group files by the feature or capability they support

Most domain-centric architectures benefit from a hybrid approach: layer-based at the top level, feature-based within layers. Let's examine concrete examples.

Clean Architecture Folder Structure

text

MyApplication/
├── src/
│   ├── Domain/                           # Enterprise Business Rules (innermost)
│   │   ├── Entities/
│   │   │   ├── Order.cs                  # Core domain entity
│   │   │   ├── Customer.cs
│   │   │   └── Product.cs
│   │   ├── ValueObjects/
│   │   │   ├── Money.cs
│   │   │   ├── Address.cs
│   │   │   └── OrderId.cs
│   │   ├── Aggregates/                   # Aggregate roots
│   │   │   ├── OrderAggregate.cs
│   │   │   └── CustomerAggregate.cs
│   │   ├── Events/                       # Domain events
│   │   │   ├── OrderPlacedEvent.cs
│   │   │   └── OrderShippedEvent.cs
│   │   ├── Interfaces/                   # Port interfaces (defined by domain)
│   │   │   ├── IOrderRepository.cs
│   │   │   ├── IPaymentService.cs
│   │   │   └── IEmailService.cs
│   │   └── Exceptions/
│   │       ├── InsufficientInventoryException.cs
│   │       └── InvalidOrderStateException.cs
│   │
│   ├── Application/                      # Application Business Rules
│   │   ├── UseCases/                     # Organized by feature
│   │   │   ├── Orders/
│   │   │   │   ├── PlaceOrder/
│   │   │   │   │   ├── PlaceOrderCommand.cs
│   │   │   │   │   ├── PlaceOrderHandler.cs
│   │   │   │   │   └── PlaceOrderValidator.cs
│   │   │   │   ├── CancelOrder/
│   │   │   │   │   ├── CancelOrderCommand.cs
│   │   │   │   │   └── CancelOrderHandler.cs
│   │   │   │   └── GetOrderDetails/
│   │   │   │       ├── GetOrderDetailsQuery.cs
│   │   │   │       ├── GetOrderDetailsHandler.cs
│   │   │   │       └── OrderDetailsDto.cs
│   │   │   └── Payments/
│   │   │       └── ProcessPayment/
│   │   │           ├── ProcessPaymentCommand.cs
│   │   │           └── ProcessPaymentHandler.cs
│   │   ├── Common/
│   │   │   ├── Behaviors/                # Cross-cutting concerns
│   │   │   │   ├── LoggingBehavior.cs
│   │   │   │   └── ValidationBehavior.cs
│   │   │   └── Interfaces/
│   │   │       ├── IDateTimeProvider.cs
│   │   │       └── ICurrentUserService.cs
│   │   └── Mappings/
│   │       └── OrderMappingProfile.cs
│   │
│   ├── Infrastructure/                   # Frameworks & Drivers (outermost)
│   │   ├── Persistence/
│   │   │   ├── Configurations/           # EF Core configs
│   │   │   │   ├── OrderConfiguration.cs
│   │   │   │   └── CustomerConfiguration.cs
│   │   │   ├── Repositories/
│   │   │   │   ├── OrderRepository.cs    # Implements IOrderRepository
│   │   │   │   └── CustomerRepository.cs
│   │   │   ├── Migrations/
│   │   │   └── AppDbContext.cs
│   │   ├── ExternalServices/
│   │   │   ├── Payment/
│   │   │   │   └── StripePaymentService.cs
│   │   │   └── Email/
│   │   │       └── SendGridEmailService.cs
│   │   ├── Identity/
│   │   │   └── CurrentUserService.cs
│   │   └── DependencyInjection.cs        # DI configuration
│   │
│   └── WebApi/                           # Interface Adapters (presentation)
│       ├── Controllers/
│       │   ├── OrdersController.cs
│       │   └── PaymentsController.cs
│       ├── Middleware/
│       │   └── ExceptionHandlingMiddleware.cs
│       ├── Filters/
│       └── Program.cs
│
├── tests/
│   ├── Domain.UnitTests/
│   ├── Application.UnitTests/
│   ├── Infrastructure.IntegrationTests/
│   └── WebApi.IntegrationTests/
│
└── README.md

Folder Structure As Documentation

Alternative: Hexagonal Architecture Structure

Hexagonal Architecture uses different terminology, reflected in its folder structure. The concepts map directly to Clean Architecture but with port/adapter vocabulary.

Hexagonal Architecture Folder Structure

text

OrderingService/
├── src/
│   ├── Core/                             # The Hexagon (Application Core)
│   │   ├── Domain/                       # Domain model
│   │   │   ├── Order.cs
│   │   │   ├── Customer.cs
│   │   │   └── ValueObjects/
│   │   │       ├── Money.cs
│   │   │       └── OrderId.cs
│   │   ├── Ports/                        # Interfaces (inbound and outbound)
│   │   │   ├── Inbound/                  # Primary/Driving ports
│   │   │   │   ├── IOrderingService.cs   # Use cases as interface
│   │   │   │   └── IInventoryQueryService.cs
│   │   │   └── Outbound/                 # Secondary/Driven ports
│   │   │       ├── IOrderRepository.cs
│   │   │       ├── IPaymentGateway.cs
│   │   │       └── IEmailSender.cs
│   │   ├── Services/                     # Application services (implement inbound ports)
│   │   │   ├── OrderingService.cs        # Implements IOrderingService
│   │   │   └── InventoryQueryService.cs
│   │   └── Events/
│   │       └── OrderPlaced.cs
│   │
│   └── Adapters/                         # Outside the Hexagon
│       ├── Inbound/                      # Primary/Driving adapters
│       │   ├── Web/
│       │   │   ├── Controllers/
│       │   │   │   └── OrdersController.cs
│       │   │   └── DTOs/
│       │   │       └── CreateOrderRequest.cs
│       │   ├── CLI/
│       │   │   └── OrderCommands.cs
│       │   └── MessageQueue/
│       │       └── OrderEventConsumer.cs
│       │
│       └── Outbound/                     # Secondary/Driven adapters
│           ├── Persistence/
│           │   ├── SqlOrderRepository.cs  # Implements IOrderRepository
│           │   └── Configurations/
│           │       └── OrderMapping.cs
│           ├── Payment/
│           │   └── StripePaymentGateway.cs
│           └── Email/
│               └── SmtpEmailSender.cs
│
└── tests/
    ├── Core.Tests/                       # Unit tests for core
    └── Adapters.Tests/                   # Integration tests for adapters

Key Differences from Clean Architecture Structure:

Explicit Port Separation: Inbound vs Outbound ports are structurally separated
Adapter Symmetry: The same inbound/outbound distinction applies to adapters
Terms: 'Core' instead of 'Domain+Application'; 'Adapters' instead of 'Infrastructure'

Choose Consistent Vocabulary

Naming Conventions That Reinforce Architecture

Names are powerful tools for enforcing architecture. When names clearly signal architectural roles, violations become obvious. Let's establish conventions for each architectural element.

Naming Conventions by Architectural Element
Element	Convention	Examples
Entities	Noun, representing the object	Order, Customer, Product
Value Objects	Noun or descriptive name	Money, Address, EmailAddress
Aggregates	EntityAggregate or just Entity if obvious	OrderAggregate, CustomerAggregate
Domain Events	Past tense verb phrase	OrderPlacedEvent, PaymentProcessedEvent
Commands	Imperative verb phrase + Command	PlaceOrderCommand, CancelOrderCommand
Queries	Get/Find + noun + Query	GetOrderDetailsQuery, FindCustomersByRegionQuery
Handlers	Match command/query + Handler	PlaceOrderHandler, GetOrderDetailsHandler
Ports/Interfaces	I + noun + capability	IOrderRepository, IPaymentGateway, IEmailService
Adapters	Technology + Interface name (impl)	SqlOrderRepository, StripePaymentGateway
DTOs	Purpose + DTO or Request/Response	CreateOrderRequest, OrderDetailsDto
Controllers	Plural noun + Controller	OrdersController, PaymentsController

Namespace/Package Naming:

Namespaces should mirror the folder structure and reinforce layer boundaries:

Namespace Conventions
C#
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
// Domain Layer - Pure business logic
namespace MyApp.Domain.Entities 
{
    public class Order { }
}
 
namespace MyApp.Domain.ValueObjects
{
    public record Money(decimal Amount, string Currency);
}
 
namespace MyApp.Domain.Interfaces  // Ports defined by domain
{
    public interface IOrderRepository { }
}
 
// Application Layer - Use cases
namespace MyApp.Application.Orders.PlaceOrder
{
    public record PlaceOrderCommand(/* ... */);
    public class PlaceOrderHandler { }
}
 
// Infrastructure Layer - Adapters
namespace MyApp.Infrastructure.Persistence.Repositories
{
    public class SqlOrderRepository : IOrderRepository { }
}
 
// Presentation Layer - Controllers
namespace MyApp.WebApi.Controllers
{
    public class OrdersController : ControllerBase { }
}

Names Surface Violations

Dependency Injection Configuration

The Composition Root:

The Composition Root is the single location where all dependencies are configured. In ASP.NET Core, this is typically Program.cs or extension methods called from it.

DI Configuration
C#
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
// Infrastructure/DependencyInjection.cs
namespace MyApp.Infrastructure;
 
public static class DependencyInjection
{
    public static IServiceCollection AddInfrastructure(
        this IServiceCollection services,
        IConfiguration configuration)
    {
        // Persistence
        services.AddDbContext<AppDbContext>(options =>
            options.UseSqlServer(configuration.GetConnectionString("Default")));
        
        // Repository implementations (adapters for ports)
        services.AddScoped<IOrderRepository, SqlOrderRepository>();
        services.AddScoped<ICustomerRepository, SqlCustomerRepository>();
        
        // External service adapters
        services.AddScoped<IPaymentGateway, StripePaymentGateway>();
        services.AddScoped<IEmailService, SendGridEmailService>();
        
        // Infrastructure services
        services.AddScoped<IDateTimeProvider, SystemDateTimeProvider>();
        
        return services;
    }
}
 
// Application/DependencyInjection.cs
namespace MyApp.Application;
 
public static class DependencyInjection
{
    public static IServiceCollection AddApplication(this IServiceCollection services)
    {
        // Register MediatR for CQRS handlers
        services.AddMediatR(cfg => {
            cfg.RegisterServicesFromAssembly(typeof(DependencyInjection).Assembly);
        });
        
        // Register validation pipeline
        services.AddScoped(typeof(IPipelineBehavior<,>), typeof(ValidationBehavior<,>));
        services.AddScoped(typeof(IPipelineBehavior<,>), typeof(LoggingBehavior<,>));
        
        // AutoMapper for DTO mapping
        services.AddAutoMapper(typeof(DependencyInjection).Assembly);
        
        return services;
    }
}
 
// WebApi/Program.cs (Composition Root)
var builder = WebApplication.CreateBuilder(args);
 
// Add layers in dependency order
builder.Services.AddApplication();        // Application layer
builder.Services.AddInfrastructure(       // Infrastructure layer
    builder.Configuration);
 
var app = builder.Build();

DI Best Practices

•One Composition Root — All wiring happens in one place. Don't scatter registration across the codebase.
•Layer-Specific Extensions — Each layer provides an extension method that registers its own types.
•Interface First — Always register interfaces, not concrete types directly.
•Appropriate Lifetimes — Use Scoped for request-bound work, Singleton for stateless services, Transient sparingly.
•Environment-Specific Configuration — Different adapters for different environments (e.g., in-memory for tests).

Common Implementation Pitfalls

Even teams that understand architectural concepts make implementation mistakes. Here are the most common pitfalls and how to avoid them:

Pitfall 1: Anemic Domain Model

•Symptom: Entities are just data containers with getters/setters. All logic lives in services.
•Problem: You've recreated procedural programming with extra steps. The domain model provides no encapsulation.
•Solution: Push behavior into entities. Orders should know how to calculate totals, validate themselves, apply discounts. Services orchestrate; entities contain logic.

Anemic vs Rich Domain Model
C#
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
// ❌ ANEMIC: Entity has no behavior
public class Order
{
    public Guid Id { get; set; }
    public List<OrderLine> Lines { get; set; }
    public decimal Total { get; set; }
    public string Status { get; set; }
}
 
public class OrderService
{
    public void PlaceOrder(Order order)
    {
        // All logic in service - entity is just a data bag
        order.Total = order.Lines.Sum(l => l.Quantity * l.UnitPrice);
        if (order.Total < 0) throw new Exception("Invalid total");
        order.Status = "Placed";
        _repository.Save(order);
    }
}
 
// ✅ RICH: Entity encapsulates behavior
public class Order
{
    private readonly List<OrderLine> _lines = new();
    public IReadOnlyList<OrderLine> Lines => _lines.AsReadOnly();
    public Money Total { get; private set; }
    public OrderStatus Status { get; private set; }
    
    public void AddLine(Product product, int quantity)
    {
        if (Status != OrderStatus.Draft)
            throw new InvalidOrderStateException("Cannot modify placed order");
        
        var line = new OrderLine(product, quantity);
        _lines.Add(line);
        RecalculateTotal();
    }
    
    public void Place()
    {
        if (!_lines.Any())
            throw new InvalidOperationException("Cannot place empty order");
        
        Status = OrderStatus.Placed;
        AddDomainEvent(new OrderPlacedEvent(this));
    }
    
    private void RecalculateTotal()
    {
        Total = _lines.Aggregate(Money.Zero, (sum, line) => sum + line.Total);
    }
}

Pitfall 2: Leaking Infrastructure Into Domain

•Symptom: Domain entities have ORM attributes, serialization attributes, or framework-specific types.
•Problem: The domain is now coupled to infrastructure choices. Changing ORMs means changing entities.
•Solution: Keep entities pure. Use separate persistence models mapped to/from domain entities.

Pitfall 3: Pass-Through Layers

•Symptom: Application service methods just call repository methods with no additional logic.
•Problem: Layers exist without providing value—just adding indirection and maintenance burden.
•Solution: Either add meaningful logic to the layer, or acknowledge this is a simple CRUD operation that doesn't need all layers. Not everything requires full architecture.

Pitfall 4: Interface Explosion

•Symptom: Every class has a corresponding interface, including trivial utilities and data mappers.
•Problem: Interfaces add cognitive overhead and maintenance burden. Not everything needs to be swappable.
•Solution: Create interfaces for dependencies that cross architectural boundaries or need to be mocked in tests. Not every class needs an interface.

Pitfall 5: Wrong Abstraction Level

•Symptom: Repository interfaces expose database concepts (like IQueryable) or adapters expose vendor-specific types.
•Problem: The abstraction is leaky—it's tightly coupled to the implementation it's supposed to abstract.
•Solution: Interfaces should be defined in terms of domain concepts. IOrderRepository.FindByCustomer(CustomerId) not IOrderRepository.Query(Expression<Func<Order,bool>>).

Team Organization and Architecture

Team Structures That Support Architecture:

Team Structures and Architectural Fit
Team Structure	Best For	Architectural Alignment
Feature Teams	Cross-functional delivery	Teams own features across all layers; need architectural guardrails
Component/Layer Teams	Deep expertise per layer	Natural ownership of layers; risk of handoff overhead
Domain Teams	Complex domains	Align with bounded contexts; each team owns a domain's full stack
Platform Teams	Shared infrastructure	Own common adapters, shared infrastructure layer

Practical Recommendations:

Team-Architecture Alignment

•Ownership Clarity — Every file should have a clear owning team. Shared code with unclear ownership decays fastest.
•Architecture Champions — Each team should have someone responsible for architectural consistency within that team's work.
•Cross-Team Interfaces — When teams must integrate, define explicit interfaces (like ports) at the boundary. Don't share implementation details.
•Regular Syncs — Architecture-focused discussions (not just feature standups) help maintain alignment across teams.
•Shared Guidelines — Document architectural patterns and conventions. New team members and new teams need onboarding material.

Inverse Conway Maneuver

Testing Strategy by Architectural Layer

One of the primary benefits of domain-centric architecture is testability. Each layer can be tested appropriately, with the testing pyramid naturally emerging from the architecture.

Testing Strategy by Layer
Layer	Test Type	Dependencies	Speed	Coverage Focus
Domain	Unit Tests	None (pure code)	Very Fast	Business rules, entity behavior, value objects
Application	Unit Tests	Mocked ports	Fast	Use case orchestration, workflows
Infrastructure	Integration Tests	Real dependencies	Slow	Adapter correctness, database queries
Presentation/API	Integration Tests	In-memory application	Medium	Request/response mapping, routing
Full System	E2E Tests	All real	Very Slow	Critical paths, smoke tests

Testing Examples by Layer
C#
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
// DOMAIN LAYER: Pure unit tests - no dependencies
[Fact]
public void Order_AddLine_IncreasesTotalCorrectly()
{
    // Arrange
    var order = new Order(CustomerId.New());
    var product = new Product("Widget", Money.FromUsd(10));
    
    // Act
    order.AddLine(product, quantity: 3);
    
    // Assert
    order.Total.Should().Be(Money.FromUsd(30));
}
 
// APPLICATION LAYER: Unit tests with mocked ports
[Fact]
public async Task PlaceOrder_ValidOrder_SavesAndPublishesEvent()
{
    // Arrange
    var mockRepo = new Mock<IOrderRepository>();
    var mockPublisher = new Mock<IEventPublisher>();
    var handler = new PlaceOrderHandler(mockRepo.Object, mockPublisher.Object);
    var command = new PlaceOrderCommand(/* ... */);
    
    // Act
    await handler.Handle(command, CancellationToken.None);
    
    // Assert
    mockRepo.Verify(r => r.Add(It.IsAny<Order>()), Times.Once);
    mockPublisher.Verify(p => p.Publish(It.IsAny<OrderPlacedEvent>()), Times.Once);
}
 
// INFRASTRUCTURE LAYER: Integration tests with real DB
[Fact]
public async Task SqlOrderRepository_Add_PersistsOrder()
{
    // Arrange
    using var context = CreateTestDbContext();  // In-memory or testcontainers
    var repository = new SqlOrderRepository(context);
    var order = CreateTestOrder();
    
    // Act
    await repository.Add(order);
    await context.SaveChangesAsync();
    
    // Assert
    var loaded = await context.Orders.FindAsync(order.Id);
    loaded.Should().NotBeNull();
    loaded.Total.Should().Be(order.Total);
}
 
// API LAYER: Integration tests with WebApplicationFactory
[Fact]
public async Task POST_Orders_ValidRequest_Returns201()
{
    // Arrange
    await using var factory = new WebApplicationFactory<Program>();
    var client = factory.CreateClient();
    var request = new CreateOrderRequest { /* ... */ };
    
    // Act
    var response = await client.PostAsJsonAsync("/api/orders", request);
    
    // Assert
    response.StatusCode.Should().Be(HttpStatusCode.Created);
}

The Testing Pyramid Emerges

Implementation Checklist

Use this checklist when implementing domain-centric architecture. It serves as a quality gate for architectural compliance:

Domain Layer Checklist

•☐ Entities have behavior, not just data
•☐ Value objects are immutable with value equality
•☐ No references to infrastructure (ORMs, frameworks)
•☐ Interfaces (ports) for external dependencies are defined here
•☐ Domain events capture significant occurrences
•☐ Aggregates enforce invariants
•☐ Domain exceptions are specific and meaningful

Application Layer Checklist

•☐ Use cases are explicit (commands/queries)
•☐ Handlers orchestrate, don't contain business logic
•☐ DTOs for external communication; domain objects internal
•☐ Cross-cutting concerns handled via behaviors/decorators
•☐ Validation happens before domain operations
•☐ Transaction boundaries are clear

Infrastructure Layer Checklist

•☐ All adapters implement domain-defined interfaces
•☐ No domain logic in adapters (only mapping/translation)
•☐ Technology-specific code is isolated
•☐ Multiple implementations possible (e.g., SQL + in-memory)
•☐ Configuration externalized appropriately
•☐ Integration tests cover adapter behavior

Presentation Layer Checklist

•☐ Controllers are thin (delegate to application layer)
•☐ DTOs define API contract, mapped from domain
•☐ Error handling is consistent
•☐ Authentication/authorization at boundaries
•☐ No business logic in controllers

Overall Architecture Checklist

•☐ Dependencies point inward only
•☐ Folder structure reflects architecture
•☐ Naming conventions are consistent
•☐ DI configuration is centralized
•☐ Architectural fitness functions exist
•☐ ADRs document key decisions
•☐ Onboarding documentation exists

Module Summary: Choosing an Architecture

We've completed a comprehensive exploration of how to choose, implement, and maintain software architecture. Let's consolidate everything we've learned across this module:

Module Key Takeaways

•Architecture Comparison: Traditional Layered trades flexibility for simplicity; Hexagonal, Onion, and Clean share the same core principles with different terminology. The defining difference is dependency direction.
•Project Fit: Multiple dimensions influence choice—domain complexity, lifespan, team, technical requirements, and organizational context. Use frameworks to structure thinking, not replace judgment.
•Evolution: Architecture has a lifecycle. Evolution is inevitable, driven by business, scale, technology, and team changes. Manage debt proactively; prevent decay with fitness functions and governance.
•Practical Implementation: Folder structure manifests architecture. Naming conventions reinforce boundaries. DI wires dependencies. Common pitfalls include anemic models, leaky abstractions, and unnecessary complexity.

The Ultimate Insight:

Module Complete