System Design (LLD)Onion Architecture

Onion Architecture: Domain-Centric System Design

LevelIntermediate

Duration60 mins

TopicOnion Architecture

4 / 4

Onion Architecture in Practice

From Theory to Production

Understanding Onion Architecture's principles is one thing; applying them to real codebases is another. The gap between architectural diagrams and working code is where many projects falter. Teams draw beautiful layer diagrams, then write code that violates those boundaries within weeks.

This page bridges that gap. We'll examine practical implementation patterns, common pitfalls that trip up teams, testing strategies that leverage Onion's structure, and migration approaches for introducing Onion Architecture to brownfield projects. By the end, you'll have the practical knowledge to implement Onion Architecture effectively.

What You Will Learn

By the end of this page, you will understand how to structure a real Onion Architecture project, implement common patterns correctly, avoid typical mistakes, leverage the architecture for effective testing, and introduce Onion principles to existing code.

Structuring an Onion Architecture Project

A well-organized project structure makes architectural boundaries visible and enforceable. Here's a production-ready structure that reflects Onion Architecture layers clearly:

Production Onion Architecture Structure

Directory

src/
│
├── Domain/                           # INNERMOST LAYER - Pure business logic
│   │
│   ├── Model/                        # Domain Model
│   │   ├── Entities/                 # Identity-based objects
│   │   │   ├── Order.ts
│   │   │   ├── Customer.ts
│   │   │   └── Product.ts
│   │   │
│   │   ├── ValueObjects/             # Immutable value types
│   │   │   ├── Money.ts
│   │   │   ├── OrderId.ts
│   │   │   ├── Address.ts
│   │   │   └── EmailAddress.ts
│   │   │
│   │   ├── Aggregates/               # Aggregate roots and boundaries
│   │   │   ├── Order/
│   │   │   │   ├── OrderAggregate.ts
│   │   │   │   └── OrderItem.ts
│   │   │   └── Customer/
│   │   │       └── CustomerAggregate.ts
│   │   │
│   │   ├── Events/                   # Domain events
│   │   │   ├── OrderPlacedEvent.ts
│   │   │   ├── OrderShippedEvent.ts
│   │   │   └── PaymentReceivedEvent.ts
│   │   │
│   │   └── Exceptions/               # Domain-specific exceptions
│   │       ├── InsufficientInventoryError.ts
│   │       └── OrderNotModifiableError.ts
│   │
│   ├── Services/                     # Domain Services
│   │   ├── PricingService.ts
│   │   ├── InventoryAllocationService.ts
│   │   └── ShippingCostCalculator.ts
│   │
│   └── Ports/                        # Interfaces for external needs
│       ├── Repositories/
│       │   ├── IOrderRepository.ts
│       │   ├── ICustomerRepository.ts
│       │   └── IProductRepository.ts
│       │
│       └── Services/
│           ├── IPaymentGateway.ts
│           └── INotificationService.ts
│
├── Application/                      # APPLICATION SERVICES LAYER
│   │
│   ├── Commands/                     # Write operations
│   │   ├── PlaceOrder/
│   │   │   ├── PlaceOrderCommand.ts
│   │   │   ├── PlaceOrderHandler.ts
│   │   │   └── PlaceOrderResult.ts
│   │   │
│   │   └── ShipOrder/
│   │       ├── ShipOrderCommand.ts
│   │       └── ShipOrderHandler.ts
│   │
│   ├── Queries/                      # Read operations
│   │   ├── GetOrderDetails/
│   │   │   ├── GetOrderDetailsQuery.ts
│   │   │   ├── GetOrderDetailsHandler.ts
│   │   │   └── OrderDetailsDto.ts
│   │   │
│   │   └── ListCustomerOrders/
│   │       ├── ListCustomerOrdersQuery.ts
│   │       └── CustomerOrdersDto.ts
│   │
│   ├── Common/                       # Shared application concerns
│   │   ├── ITransactionManager.ts
│   │   ├── IEventPublisher.ts
│   │   └── BaseHandler.ts
│   │
│   └── Behaviors/                    # Cross-cutting behaviors
│       ├── LoggingBehavior.ts
│       └── ValidationBehavior.ts
│
└── Infrastructure/                   # OUTERMOST LAYER
    │
    ├── Persistence/                  # Database implementations
    │   ├── Repositories/
    │   │   ├── PostgresOrderRepository.ts
    │   │   └── PostgresCustomerRepository.ts
    │   │
    │   ├── Mappers/                  # Domain <-> Persistence
    │   │   ├── OrderMapper.ts
    │   │   └── CustomerMapper.ts
    │   │
    │   └── Config/
    │       └── DatabaseConfig.ts
    │
    ├── Web/                          # HTTP API
    │   ├── Controllers/
    │   │   ├── OrderController.ts
    │   │   └── CustomerController.ts
    │   │
    │   ├── Middleware/
    │   │   ├── AuthMiddleware.ts
    │   │   └── ErrorHandlerMiddleware.ts
    │   │
    │   └── Mappers/                  # Request/Response <-> DTOs
    │       └── OrderRequestMapper.ts
    │
    ├── Messaging/                    # Message queue integration
    │   ├── Publishers/
    │   │   └── RabbitMQEventPublisher.ts
    │   │
    │   └── Consumers/
    │       └── PaymentEventConsumer.ts
    │
    ├── External/                     # Third-party integrations
    │   ├── StripePaymentGateway.ts
    │   └── SendGridNotificationService.ts
    │
    └── DependencyInjection/          # IoC configuration
        └── ServiceRegistration.ts

Enforce Boundaries with Build Tools

In TypeScript, use path aliases and ESLint rules to enforce layer dependencies. In Java/C#, use separate modules/projects per layer. Physical separation makes accidental violations compile errors, not code review findings.

Essential Implementation Patterns

Certain patterns appear repeatedly in well-implemented Onion Architecture projects. Mastering these patterns enables you to build maintainable, testable systems.

Command Query Responsibility Segregation (CQRS) fits naturally with Onion Architecture. Commands modify state through the domain; queries read optimized views directly.

Key insight: Commands go through the full onion (validation → domain logic → persistence). Queries can bypass the domain and read directly from optimized views.

TypeScript
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
// Command: Goes through domain layer
interface PlaceOrderCommand {
    customerId: string;
    items: { productId: string; quantity: number }[];
}
 
class PlaceOrderHandler {
    constructor(
        private readonly orderRepository: IOrderRepository,
        private readonly customerRepository: ICustomerRepository,
        private readonly inventoryService: InventoryAllocationService
    ) {}
 
    async handle(command: PlaceOrderCommand): Promise<PlaceOrderResult> {
        const customer = await this.customerRepository.findById(
            new CustomerId(command.customerId)
        );
        
        // Domain model creates order with business rules
        const order = customer.placeOrder(command.items);
        
        // Domain service validates inventory
        await this.inventoryService.allocate(order);
        
        // Persist through domain repository
        await this.orderRepository.save(order);
        
        return { orderId: order.id.value };
    }
}
 
// Query: Bypasses domain, reads optimized views
interface GetOrderDetailsQuery {
    orderId: string;
}
 
class GetOrderDetailsHandler {
    constructor(
        private readonly readDb: IReadDatabase  // Optimized read model
    ) {}
 
    async handle(query: GetOrderDetailsQuery): Promise<OrderDetailsDto | null> {
        // Direct read from denormalized view - no domain traversal
        return this.readDb.query(
            `SELECT o.*, c.name as customer_name, 
                    json_agg(i.*) as items
             FROM orders_view o
             JOIN customers c ON o.customer_id = c.id
             JOIN order_items_view i ON o.id = i.order_id
             WHERE o.id = $1
             GROUP BY o.id, c.name`,
            [query.orderId]
        );
    }
}

Common Pitfalls and How to Avoid Them

Even teams that understand Onion Architecture make mistakes. Here are the most common pitfalls and how to avoid them:

Pitfall 1: Anemic Domain Model

•Symptom: Domain entities are just data containers with getters/setters. All logic lives in application services.
•Problem: You've built traditional layered architecture with extra indirection. Business rules are scattered and duplicated.
•Fix: Push behavior into entities. Ask 'what can this entity DO?' not 'what data does it HAVE?'. Methods like order.submit() and account.withdraw(amount) should contain business logic.

Anemic vs Rich Domain Model
TypeScript
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
// ❌ ANEMIC: Entity is just data, logic is external
class Order {
    id: string;
    status: string;
    items: { productId: string; quantity: number }[];
    total: number;
}
 
class OrderService {
    submitOrder(order: Order): void {
        if (order.items.length === 0) throw new Error("Empty order");
        if (order.status !== 'PENDING') throw new Error("Cannot submit");
        order.status = 'SUBMITTED';
        // Calculate total, validate items, etc.
    }
}
 
// ✅ RICH: Entity contains behavior
class Order {
    private readonly id: OrderId;
    private status: OrderStatus;
    private items: OrderItem[];
 
    submit(): void {
        if (this.items.length === 0) {
            throw new EmptyOrderError(this.id);
        }
        if (this.status !== OrderStatus.PENDING) {
            throw new InvalidStateTransitionError(this.status, OrderStatus.SUBMITTED);
        }
        this.status = OrderStatus.SUBMITTED;
    }
 
    addItem(productId: ProductId, quantity: Quantity, price: Money): void {
        if (this.status !== OrderStatus.PENDING) {
            throw new OrderNotModifiableError(this.id);
        }
        this.items.push(new OrderItem(productId, quantity, price));
    }
 
    getTotal(): Money {
        return this.items.reduce((sum, item) => sum.add(item.subtotal), Money.zero());
    }
}

Pitfall 2: Infrastructure Leaking Into Domain

•Symptom: Domain entities have @Entity, @Column, @JsonProperty annotations. Value objects know about SQL or JSON.
•Problem: Domain is coupled to persistence/serialization technology. Testing requires real infrastructure or complex mocks.
•Fix: Keep domain objects pure. Use mappers in infrastructure layer to transform between domain objects and persistence/transport formats.

Pitfall 3: Repositories Returning DTOs

•Symptom: Repository methods return DTOs, database row types, or primitive collections instead of domain aggregates.
•Problem: Domain logic can't operate on these types. Business rules end up in application services or worse, in controllers.
•Fix: Repositories return domain aggregates. Create separate read models for queries that don't need domain logic (CQRS pattern).

Pitfall 4: Application Layer Doing Domain Work

•Symptom: Application services are huge, containing hundreds of lines of business logic. Domain entities have minimal behavior.
•Problem: Application layer has become a 'God class'. Testing requires mocking everything. Business rules are hidden in orchestration code.
•Fix: Application services should orchestrate, not calculate. Push decisions into domain. If you're writing 'if/else' for business rules in application services, those rules belong in the domain.

The '10 Lines' Heuristic

A well-designed application service method should be roughly 10-15 lines: load aggregates, call domain methods, save changes, publish events. If your methods are 50+ lines, domain logic is likely misplaced. Extract it to domain entities or services.

Testing Strategy for Onion Architecture

Onion Architecture's layered structure enables an exceptionally effective testing strategy. Each layer has appropriate testing approaches, and the architecture's dependency rules make tests naturally isolated.

Testing Strategy by Layer
Layer	Test Type	Dependencies	Speed	Coverage Focus
Domain Model	Unit Tests	None (pure logic)	Milliseconds	Business rules, invariants, state transitions
Domain Services	Unit Tests	Domain model (real)	Milliseconds	Cross-entity logic, calculations
Application Services	Integration Tests	Domain (real) + Ports (mocked)	Seconds	Orchestration, workflows, use cases
Infrastructure Adapters	Integration Tests	Real infrastructure	Seconds-Minutes	Data mapping, API contracts, persistence
Full System	E2E Tests	Everything real	Minutes	Critical paths, smoke tests

Testing Each Layer
TypeScript
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
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
// ============================================
// TESTING STRATEGY BY LAYER
// ============================================
 
// ✅ DOMAIN MODEL: Pure unit tests - no mocks needed
describe('Order', () => {
    it('should transition to submitted when items present', () => {
        const order = new Order(OrderId.generate(), customerId);
        order.addItem(productId, Quantity.of(2), Money.of(50, 'USD'));
        
        order.submit();
        
        expect(order.getStatus()).toBe(OrderStatus.SUBMITTED);
    });
 
    it('should reject submission of empty orders', () => {
        const order = new Order(OrderId.generate(), customerId);
        
        expect(() => order.submit()).toThrow(EmptyOrderError);
    });
 
    it('should calculate total correctly', () => {
        const order = new Order(OrderId.generate(), customerId);
        order.addItem(productA, Quantity.of(2), Money.of(10, 'USD'));
        order.addItem(productB, Quantity.of(1), Money.of(25, 'USD'));
        
        expect(order.getTotal()).toEqual(Money.of(45, 'USD'));
    });
});
 
// ✅ DOMAIN SERVICE: Unit tests with real domain objects
describe('InventoryAllocationService', () => {
    it('should allocate inventory for order items', () => {
        const inventory = new Inventory([
            new InventoryItem(productA, Quantity.of(100)),
            new InventoryItem(productB, Quantity.of(50))
        ]);
        const service = new InventoryAllocationService();
        const order = createOrderWithItems([
            { product: productA, quantity: 5 },
            { product: productB, quantity: 10 }
        ]);
 
        const result = service.allocate(order, inventory);
 
        expect(result.isSuccess()).toBe(true);
        expect(inventory.getAvailable(productA)).toEqual(Quantity.of(95));
        expect(inventory.getAvailable(productB)).toEqual(Quantity.of(40));
    });
});
 
// ✅ APPLICATION SERVICE: Integration test with mocked ports
describe('PlaceOrderHandler', () => {
    let handler: PlaceOrderHandler;
    let orderRepository: MockOrderRepository;
    let customerRepository: MockCustomerRepository;
    let eventPublisher: MockEventPublisher;
 
    beforeEach(() => {
        orderRepository = new MockOrderRepository();
        customerRepository = new MockCustomerRepository();
        eventPublisher = new MockEventPublisher();
        
        handler = new PlaceOrderHandler(
            orderRepository,
            customerRepository,
            new InventoryAllocationService(),  // Real domain service
            eventPublisher
        );
    });
 
    it('should create and persist order', async () => {
        customerRepository.add(new Customer(customerId, 'Test Customer'));
        
        const result = await handler.handle({
            customerId: customerId.value,
            items: [{ productId: 'prod-1', quantity: 2 }]
        });
 
        expect(result.success).toBe(true);
        expect(orderRepository.getAll()).toHaveLength(1);
        expect(eventPublisher.getPublishedEvents()).toContainEqual(
            expect.objectContaining({ type: 'OrderPlaced' })
        );
    });
});
 
// ✅ INFRASTRUCTURE ADAPTER: Integration test with real database
describe('PostgresOrderRepository', () => {
    let repository: PostgresOrderRepository;
    let connection: DatabaseConnection;
 
    beforeAll(async () => {
        connection = await createTestConnection();
        repository = new PostgresOrderRepository(connection, new OrderMapper());
    });
 
    afterEach(async () => {
        await connection.query('TRUNCATE orders, order_items CASCADE');
    });
 
    it('should persist and retrieve order correctly', async () => {
        const order = new Order(OrderId.generate(), customerId);
        order.addItem(productId, Quantity.of(3), Money.of(25, 'USD'));
        order.submit();
 
        await repository.save(order);
        const retrieved = await repository.findById(order.id);
 
        expect(retrieved).not.toBeNull();
        expect(retrieved!.id).toEqual(order.id);
        expect(retrieved!.getStatus()).toBe(OrderStatus.SUBMITTED);
        expect(retrieved!.getTotal()).toEqual(Money.of(75, 'USD'));
    });
});

The Testing Pyramid Emerges Naturally

Onion Architecture naturally produces a healthy testing pyramid. Domain tests are numerous and fast (base). Application tests are moderate (middle). Infrastructure and E2E tests are few and thorough (top). The architecture's structure makes this the path of least resistance.

Dependency Injection Configuration

Dependency Injection is the runtime mechanism that wires Onion Architecture together. The infrastructure layer configures the IoC container, registering concrete implementations for domain-defined interfaces.

Complete DI Configuration
TypeScript
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
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
// ============================================
// INFRASTRUCTURE: Dependency Injection Setup
// ============================================
 
// This file lives in Infrastructure layer - it knows about all layers
// and wires them together at application startup
 
import { Container } from 'inversify';
import { DataSource } from 'typeorm';
 
// Types for DI tokens
const TYPES = {
    // Domain Ports
    OrderRepository: Symbol('OrderRepository'),
    CustomerRepository: Symbol('CustomerRepository'),
    PaymentGateway: Symbol('PaymentGateway'),
    NotificationService: Symbol('NotificationService'),
    
    // Application Services
    PlaceOrderHandler: Symbol('PlaceOrderHandler'),
    ShipOrderHandler: Symbol('ShipOrderHandler'),
    GetOrderDetailsHandler: Symbol('GetOrderDetailsHandler'),
    
    // Domain Services
    InventoryAllocationService: Symbol('InventoryAllocationService'),
    ShippingCostCalculator: Symbol('ShippingCostCalculator'),
    
    // Infrastructure
    EventPublisher: Symbol('EventPublisher'),
    TransactionManager: Symbol('TransactionManager'),
    DataSource: Symbol('DataSource'),
};
 
function configureContainer(dataSource: DataSource): Container {
    const container = new Container();
 
    // === INFRASTRUCTURE BINDINGS ===
    container.bind(TYPES.DataSource).toConstantValue(dataSource);
    
    // Repository implementations
    container.bind<IOrderRepository>(TYPES.OrderRepository)
        .toDynamicValue((ctx) => new PostgresOrderRepository(
            ctx.container.get(TYPES.DataSource),
            new OrderMapper()
        ))
        .inRequestScope();
 
    container.bind<ICustomerRepository>(TYPES.CustomerRepository)
        .toDynamicValue((ctx) => new PostgresCustomerRepository(
            ctx.container.get(TYPES.DataSource),
            new CustomerMapper()
        ))
        .inRequestScope();
 
    // External service adapters
    container.bind<IPaymentGateway>(TYPES.PaymentGateway)
        .to(StripePaymentGateway)
        .inSingletonScope();
 
    container.bind<INotificationService>(TYPES.NotificationService)
        .to(SendGridNotificationService)
        .inSingletonScope();
 
    container.bind<IEventPublisher>(TYPES.EventPublisher)
        .to(RabbitMQEventPublisher)
        .inSingletonScope();
 
    container.bind<ITransactionManager>(TYPES.TransactionManager)
        .toDynamicValue((ctx) => new TypeORMTransactionManager(
            ctx.container.get(TYPES.DataSource)
        ))
        .inRequestScope();
 
    // === DOMAIN SERVICE BINDINGS ===
    container.bind(TYPES.InventoryAllocationService)
        .to(InventoryAllocationService)
        .inTransientScope();
 
    container.bind(TYPES.ShippingCostCalculator)
        .to(ShippingCostCalculator)
        .inTransientScope();
 
    // === APPLICATION SERVICE BINDINGS ===
    container.bind(TYPES.PlaceOrderHandler)
        .toDynamicValue((ctx) => new PlaceOrderHandler(
            ctx.container.get(TYPES.OrderRepository),
            ctx.container.get(TYPES.CustomerRepository),
            ctx.container.get(TYPES.InventoryAllocationService),
            ctx.container.get(TYPES.EventPublisher),
            ctx.container.get(TYPES.TransactionManager)
        ))
        .inRequestScope();
 
    container.bind(TYPES.ShipOrderHandler)
        .toDynamicValue((ctx) => new ShipOrderHandler(
            ctx.container.get(TYPES.OrderRepository),
            ctx.container.get(TYPES.EventPublisher),
            ctx.container.get(TYPES.TransactionManager)
        ))
        .inRequestScope();
 
    return container;
}
 
// Environment-specific configuration
function configureForProduction(): Container {
    const dataSource = new DataSource({
        type: 'postgres',
        url: process.env.DATABASE_URL,
        // ... production config
    });
    return configureContainer(dataSource);
}
 
function configureForTesting(): Container {
    // Use in-memory implementations for testing
    const container = new Container();
    
    container.bind<IOrderRepository>(TYPES.OrderRepository)
        .to(InMemoryOrderRepository)
        .inSingletonScope();
    
    container.bind<IPaymentGateway>(TYPES.PaymentGateway)
        .to(MockPaymentGateway)
        .inSingletonScope();
    
    // ... other test bindings
    
    return container;
}

DI Lives in Infrastructure

The DI configuration is infrastructure code—it references all layers and external libraries. It's the 'composition root' where the application is assembled. Neither the domain nor application layers know how they're wired together.

Migrating to Onion Architecture

Most teams don't start greenfield—they inherit existing codebases. Migrating to Onion Architecture requires a phased approach that delivers value incrementally while avoiding a risky 'big bang' rewrite.

Migration Phases

•Phase 1: Introduce Interfaces — Create interfaces for infrastructure dependencies (repositories, external services). Existing implementations implement these interfaces. No behavior changes.
•Phase 2: Extract Domain Model — Identify core entities and value objects. Extract them from ORM entities or DTOs into pure domain classes. Create mappers to translate between domain and persistence.
•Phase 3: Create Application Services — Wrap existing business logic in application services. These become the entry points for use cases. Controllers call application services, not repositories directly.
•Phase 4: Refactor Domain Logic — Move business rules from application services into domain entities. Introduce domain services for cross-entity logic. This is the most ongoing phase.
•Phase 5: Enforce Boundaries — Add build-time checks (module dependencies, lint rules) to prevent layer violations. Make correct structure the path of least resistance.

Phased Migration Example
TypeScript
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
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
// ============================================
// BEFORE: Traditional layered architecture
// ============================================
 
// Controller directly uses repository with ORM entities
class OrderController {
    async submitOrder(req: Request, res: Response) {
        const orderEntity = await this.orderRepo.findOne(req.params.id);
        
        // Business logic in controller
        if (orderEntity.items.length === 0) {
            return res.status(400).json({ error: 'Empty order' });
        }
        if (orderEntity.status !== 'PENDING') {
            return res.status(400).json({ error: 'Cannot submit' });
        }
        
        orderEntity.status = 'SUBMITTED';
        orderEntity.submittedAt = new Date();
        
        await this.orderRepo.save(orderEntity);
        await this.emailService.sendOrderConfirmation(orderEntity);
        
        return res.json(orderEntity);
    }
}
 
// ============================================
// PHASE 1: Introduce Interfaces
// ============================================
 
// Define interface for repository
interface IOrderRepository {
    findById(id: string): Promise<OrderEntity | null>;
    save(order: OrderEntity): Promise<void>;
}
 
// Existing implementation now implements interface
class TypeORMOrderRepository implements IOrderRepository { /* ... */ }
 
// ============================================
// PHASE 2: Extract Domain Model
// ============================================
 
// Pure domain entity (no ORM annotations)
class Order {
    constructor(
        readonly id: OrderId,
        private status: OrderStatus,
        private items: OrderItem[]
    ) {}
 
    submit(): void {
        if (this.items.length === 0) throw new EmptyOrderError(this.id);
        if (this.status !== OrderStatus.PENDING) {
            throw new InvalidStateTransitionError(this.status, OrderStatus.SUBMITTED);
        }
        this.status = OrderStatus.SUBMITTED;
    }
}
 
// Mapper between domain and persistence
class OrderMapper {
    toDomain(entity: OrderEntity): Order { /* ... */ }
    toPersistence(order: Order): OrderEntity { /* ... */ }
}
 
// Repository now returns domain objects
class TypeORMOrderRepository implements IOrderRepository {
    async findById(id: OrderId): Promise<Order | null> {
        const entity = await this.repo.findOne(id.value);
        return entity ? this.mapper.toDomain(entity) : null;
    }
}
 
// ============================================
// PHASE 3: Create Application Services
// ============================================
 
class SubmitOrderService {
    constructor(
        private readonly orderRepo: IOrderRepository,
        private readonly notificationService: INotificationService
    ) {}
 
    async execute(orderId: string): Promise<SubmitOrderResult> {
        const order = await this.orderRepo.findById(new OrderId(orderId));
        if (!order) throw new OrderNotFoundError(orderId);
 
        order.submit();  // Domain logic now in entity
 
        await this.orderRepo.save(order);
        await this.notificationService.sendOrderConfirmation(order);
 
        return { orderId: order.id.value, status: 'SUBMITTED' };
    }
}
 
// Controller becomes thin
class OrderController {
    constructor(private readonly submitOrderService: SubmitOrderService) {}
 
    async submitOrder(req: Request, res: Response) {
        try {
            const result = await this.submitOrderService.execute(req.params.id);
            return res.json(result);
        } catch (e) {
            if (e instanceof DomainException) {
                return res.status(400).json({ error: e.message });
            }
            throw e;
        }
    }
}

Strangler Fig Pattern

Apply the Strangler Fig pattern: new features use Onion Architecture, existing features are migrated incrementally. The old architecture is gradually 'strangled' by the new. This reduces risk and allows teams to learn the new patterns before tackling complex migrations.

Production Considerations

Deploying Onion Architecture in production environments requires attention to cross-cutting concerns that span layers. Here's how to handle common production requirements:

Logging and Monitoring

•Domain layer: No logging (pure logic). Domain events serve as audit trail.
•Application layer: Log use case execution, timing, outcomes. Use structured logging.
•Infrastructure layer: Log external interactions (API calls, DB queries). Include correlation IDs.

Error Handling

•Domain layer: Throw domain-specific exceptions (business rule violations).
•Application layer: Catch domain exceptions, translate to results. Let infrastructure exceptions propagate.
•Infrastructure layer: Handle transport-specific errors. Map domain exceptions to HTTP/error codes.

Cross-Cutting Concerns by Layer
Concern	Domain	Application	Infrastructure
Validation	Business invariants	Input validation	Request/schema validation
Transactions	Aggregate boundaries	Transaction scope	Transaction implementation
Caching	N/A	Cache interface usage	Cache implementation
Security	Ownership rules	Authorization checks	Authentication
Metrics	N/A	Business metrics	Technical metrics

Aspect-Oriented Programming

Cross-cutting concerns like logging, metrics, and authorization can be implemented using AOP patterns (decorators, middleware, interceptors) in the infrastructure layer. This keeps the domain and application layers clean while ensuring consistent behavior.

Summary: Onion Architecture in Practice

We've covered the practical aspects of implementing Onion Architecture in real-world projects. Let's consolidate the key insights:

Key Takeaways

•Project structure matters — Organize folders by layer. Use build tools to enforce boundaries. Make correct structure the path of least resistance.
•Master the patterns — CQRS, Factory, Specification, Domain Events—these patterns appear repeatedly in well-designed Onion projects.
•Avoid common pitfalls — Anemic domain, infrastructure leakage, repositories returning DTOs, fat application services. Know the symptoms and fixes.
•Leverage the testing architecture — Domain unit tests (fast, many), application integration tests (focused), infrastructure tests (real resources).
•Wire with DI — The infrastructure layer configures dependency injection. Domain and application layers don't know how they're connected.
•Migrate incrementally — Introduce interfaces, extract domain, create application services, refactor behavior, enforce boundaries. No big bang.
•Handle cross-cutting concerns appropriately — Each layer has its role. Use AOP patterns to maintain clean core code.

Module complete!

You now have both the theoretical understanding and practical skills to implement Onion Architecture effectively. You understand the core principles, the layer structure, how Onion compares to Hexagonal Architecture, and the patterns and practices that make implementations successful.

As you apply these concepts, remember: the goal isn't architectural purity—it's building systems that are testable, maintainable, and resilient to change. Onion Architecture is a means to that end, not an end in itself.

Module Complete

Congratulations! You've mastered Onion Architecture—from its philosophical foundations to practical implementation patterns. You're now equipped to design and build domain-centric systems that protect business logic from infrastructure volatility, enable comprehensive testing, and adapt gracefully to technological change.

4 / 4

Loading learning content...

System Design (LLD)Onion Architecture

Onion Architecture: Domain-Centric System Design

LevelIntermediate

Duration60 mins

TopicOnion Architecture

4 / 4

Onion Architecture in Practice

From Theory to Production

What You Will Learn

Structuring an Onion Architecture Project

A well-organized project structure makes architectural boundaries visible and enforceable. Here's a production-ready structure that reflects Onion Architecture layers clearly:

Production Onion Architecture Structure

Directory

src/
│
├── Domain/                           # INNERMOST LAYER - Pure business logic
│   │
│   ├── Model/                        # Domain Model
│   │   ├── Entities/                 # Identity-based objects
│   │   │   ├── Order.ts
│   │   │   ├── Customer.ts
│   │   │   └── Product.ts
│   │   │
│   │   ├── ValueObjects/             # Immutable value types
│   │   │   ├── Money.ts
│   │   │   ├── OrderId.ts
│   │   │   ├── Address.ts
│   │   │   └── EmailAddress.ts
│   │   │
│   │   ├── Aggregates/               # Aggregate roots and boundaries
│   │   │   ├── Order/
│   │   │   │   ├── OrderAggregate.ts
│   │   │   │   └── OrderItem.ts
│   │   │   └── Customer/
│   │   │       └── CustomerAggregate.ts
│   │   │
│   │   ├── Events/                   # Domain events
│   │   │   ├── OrderPlacedEvent.ts
│   │   │   ├── OrderShippedEvent.ts
│   │   │   └── PaymentReceivedEvent.ts
│   │   │
│   │   └── Exceptions/               # Domain-specific exceptions
│   │       ├── InsufficientInventoryError.ts
│   │       └── OrderNotModifiableError.ts
│   │
│   ├── Services/                     # Domain Services
│   │   ├── PricingService.ts
│   │   ├── InventoryAllocationService.ts
│   │   └── ShippingCostCalculator.ts
│   │
│   └── Ports/                        # Interfaces for external needs
│       ├── Repositories/
│       │   ├── IOrderRepository.ts
│       │   ├── ICustomerRepository.ts
│       │   └── IProductRepository.ts
│       │
│       └── Services/
│           ├── IPaymentGateway.ts
│           └── INotificationService.ts
│
├── Application/                      # APPLICATION SERVICES LAYER
│   │
│   ├── Commands/                     # Write operations
│   │   ├── PlaceOrder/
│   │   │   ├── PlaceOrderCommand.ts
│   │   │   ├── PlaceOrderHandler.ts
│   │   │   └── PlaceOrderResult.ts
│   │   │
│   │   └── ShipOrder/
│   │       ├── ShipOrderCommand.ts
│   │       └── ShipOrderHandler.ts
│   │
│   ├── Queries/                      # Read operations
│   │   ├── GetOrderDetails/
│   │   │   ├── GetOrderDetailsQuery.ts
│   │   │   ├── GetOrderDetailsHandler.ts
│   │   │   └── OrderDetailsDto.ts
│   │   │
│   │   └── ListCustomerOrders/
│   │       ├── ListCustomerOrdersQuery.ts
│   │       └── CustomerOrdersDto.ts
│   │
│   ├── Common/                       # Shared application concerns
│   │   ├── ITransactionManager.ts
│   │   ├── IEventPublisher.ts
│   │   └── BaseHandler.ts
│   │
│   └── Behaviors/                    # Cross-cutting behaviors
│       ├── LoggingBehavior.ts
│       └── ValidationBehavior.ts
│
└── Infrastructure/                   # OUTERMOST LAYER
    │
    ├── Persistence/                  # Database implementations
    │   ├── Repositories/
    │   │   ├── PostgresOrderRepository.ts
    │   │   └── PostgresCustomerRepository.ts
    │   │
    │   ├── Mappers/                  # Domain <-> Persistence
    │   │   ├── OrderMapper.ts
    │   │   └── CustomerMapper.ts
    │   │
    │   └── Config/
    │       └── DatabaseConfig.ts
    │
    ├── Web/                          # HTTP API
    │   ├── Controllers/
    │   │   ├── OrderController.ts
    │   │   └── CustomerController.ts
    │   │
    │   ├── Middleware/
    │   │   ├── AuthMiddleware.ts
    │   │   └── ErrorHandlerMiddleware.ts
    │   │
    │   └── Mappers/                  # Request/Response <-> DTOs
    │       └── OrderRequestMapper.ts
    │
    ├── Messaging/                    # Message queue integration
    │   ├── Publishers/
    │   │   └── RabbitMQEventPublisher.ts
    │   │
    │   └── Consumers/
    │       └── PaymentEventConsumer.ts
    │
    ├── External/                     # Third-party integrations
    │   ├── StripePaymentGateway.ts
    │   └── SendGridNotificationService.ts
    │
    └── DependencyInjection/          # IoC configuration
        └── ServiceRegistration.ts

Enforce Boundaries with Build Tools

Essential Implementation Patterns

Certain patterns appear repeatedly in well-implemented Onion Architecture projects. Mastering these patterns enables you to build maintainable, testable systems.

Command Query Responsibility Segregation (CQRS) fits naturally with Onion Architecture. Commands modify state through the domain; queries read optimized views directly.

Key insight: Commands go through the full onion (validation → domain logic → persistence). Queries can bypass the domain and read directly from optimized views.

TypeScript
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
// Command: Goes through domain layer
interface PlaceOrderCommand {
    customerId: string;
    items: { productId: string; quantity: number }[];
}
 
class PlaceOrderHandler {
    constructor(
        private readonly orderRepository: IOrderRepository,
        private readonly customerRepository: ICustomerRepository,
        private readonly inventoryService: InventoryAllocationService
    ) {}
 
    async handle(command: PlaceOrderCommand): Promise<PlaceOrderResult> {
        const customer = await this.customerRepository.findById(
            new CustomerId(command.customerId)
        );
        
        // Domain model creates order with business rules
        const order = customer.placeOrder(command.items);
        
        // Domain service validates inventory
        await this.inventoryService.allocate(order);
        
        // Persist through domain repository
        await this.orderRepository.save(order);
        
        return { orderId: order.id.value };
    }
}
 
// Query: Bypasses domain, reads optimized views
interface GetOrderDetailsQuery {
    orderId: string;
}
 
class GetOrderDetailsHandler {
    constructor(
        private readonly readDb: IReadDatabase  // Optimized read model
    ) {}
 
    async handle(query: GetOrderDetailsQuery): Promise<OrderDetailsDto | null> {
        // Direct read from denormalized view - no domain traversal
        return this.readDb.query(
            `SELECT o.*, c.name as customer_name, 
                    json_agg(i.*) as items
             FROM orders_view o
             JOIN customers c ON o.customer_id = c.id
             JOIN order_items_view i ON o.id = i.order_id
             WHERE o.id = $1
             GROUP BY o.id, c.name`,
            [query.orderId]
        );
    }
}

Common Pitfalls and How to Avoid Them

Even teams that understand Onion Architecture make mistakes. Here are the most common pitfalls and how to avoid them:

Pitfall 1: Anemic Domain Model

•Symptom: Domain entities are just data containers with getters/setters. All logic lives in application services.
•Problem: You've built traditional layered architecture with extra indirection. Business rules are scattered and duplicated.
•Fix: Push behavior into entities. Ask 'what can this entity DO?' not 'what data does it HAVE?'. Methods like order.submit() and account.withdraw(amount) should contain business logic.

Anemic vs Rich Domain Model
TypeScript
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
// ❌ ANEMIC: Entity is just data, logic is external
class Order {
    id: string;
    status: string;
    items: { productId: string; quantity: number }[];
    total: number;
}
 
class OrderService {
    submitOrder(order: Order): void {
        if (order.items.length === 0) throw new Error("Empty order");
        if (order.status !== 'PENDING') throw new Error("Cannot submit");
        order.status = 'SUBMITTED';
        // Calculate total, validate items, etc.
    }
}
 
// ✅ RICH: Entity contains behavior
class Order {
    private readonly id: OrderId;
    private status: OrderStatus;
    private items: OrderItem[];
 
    submit(): void {
        if (this.items.length === 0) {
            throw new EmptyOrderError(this.id);
        }
        if (this.status !== OrderStatus.PENDING) {
            throw new InvalidStateTransitionError(this.status, OrderStatus.SUBMITTED);
        }
        this.status = OrderStatus.SUBMITTED;
    }
 
    addItem(productId: ProductId, quantity: Quantity, price: Money): void {
        if (this.status !== OrderStatus.PENDING) {
            throw new OrderNotModifiableError(this.id);
        }
        this.items.push(new OrderItem(productId, quantity, price));
    }
 
    getTotal(): Money {
        return this.items.reduce((sum, item) => sum.add(item.subtotal), Money.zero());
    }
}

Pitfall 2: Infrastructure Leaking Into Domain

•Symptom: Domain entities have @Entity, @Column, @JsonProperty annotations. Value objects know about SQL or JSON.
•Problem: Domain is coupled to persistence/serialization technology. Testing requires real infrastructure or complex mocks.
•Fix: Keep domain objects pure. Use mappers in infrastructure layer to transform between domain objects and persistence/transport formats.

Pitfall 3: Repositories Returning DTOs

•Symptom: Repository methods return DTOs, database row types, or primitive collections instead of domain aggregates.
•Problem: Domain logic can't operate on these types. Business rules end up in application services or worse, in controllers.
•Fix: Repositories return domain aggregates. Create separate read models for queries that don't need domain logic (CQRS pattern).

Pitfall 4: Application Layer Doing Domain Work

•Symptom: Application services are huge, containing hundreds of lines of business logic. Domain entities have minimal behavior.
•Problem: Application layer has become a 'God class'. Testing requires mocking everything. Business rules are hidden in orchestration code.
•Fix: Application services should orchestrate, not calculate. Push decisions into domain. If you're writing 'if/else' for business rules in application services, those rules belong in the domain.

The '10 Lines' Heuristic

Testing Strategy for Onion Architecture

Testing Strategy by Layer
Layer	Test Type	Dependencies	Speed	Coverage Focus
Domain Model	Unit Tests	None (pure logic)	Milliseconds	Business rules, invariants, state transitions
Domain Services	Unit Tests	Domain model (real)	Milliseconds	Cross-entity logic, calculations
Application Services	Integration Tests	Domain (real) + Ports (mocked)	Seconds	Orchestration, workflows, use cases
Infrastructure Adapters	Integration Tests	Real infrastructure	Seconds-Minutes	Data mapping, API contracts, persistence
Full System	E2E Tests	Everything real	Minutes	Critical paths, smoke tests

Testing Each Layer
TypeScript
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
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
// ============================================
// TESTING STRATEGY BY LAYER
// ============================================
 
// ✅ DOMAIN MODEL: Pure unit tests - no mocks needed
describe('Order', () => {
    it('should transition to submitted when items present', () => {
        const order = new Order(OrderId.generate(), customerId);
        order.addItem(productId, Quantity.of(2), Money.of(50, 'USD'));
        
        order.submit();
        
        expect(order.getStatus()).toBe(OrderStatus.SUBMITTED);
    });
 
    it('should reject submission of empty orders', () => {
        const order = new Order(OrderId.generate(), customerId);
        
        expect(() => order.submit()).toThrow(EmptyOrderError);
    });
 
    it('should calculate total correctly', () => {
        const order = new Order(OrderId.generate(), customerId);
        order.addItem(productA, Quantity.of(2), Money.of(10, 'USD'));
        order.addItem(productB, Quantity.of(1), Money.of(25, 'USD'));
        
        expect(order.getTotal()).toEqual(Money.of(45, 'USD'));
    });
});
 
// ✅ DOMAIN SERVICE: Unit tests with real domain objects
describe('InventoryAllocationService', () => {
    it('should allocate inventory for order items', () => {
        const inventory = new Inventory([
            new InventoryItem(productA, Quantity.of(100)),
            new InventoryItem(productB, Quantity.of(50))
        ]);
        const service = new InventoryAllocationService();
        const order = createOrderWithItems([
            { product: productA, quantity: 5 },
            { product: productB, quantity: 10 }
        ]);
 
        const result = service.allocate(order, inventory);
 
        expect(result.isSuccess()).toBe(true);
        expect(inventory.getAvailable(productA)).toEqual(Quantity.of(95));
        expect(inventory.getAvailable(productB)).toEqual(Quantity.of(40));
    });
});
 
// ✅ APPLICATION SERVICE: Integration test with mocked ports
describe('PlaceOrderHandler', () => {
    let handler: PlaceOrderHandler;
    let orderRepository: MockOrderRepository;
    let customerRepository: MockCustomerRepository;
    let eventPublisher: MockEventPublisher;
 
    beforeEach(() => {
        orderRepository = new MockOrderRepository();
        customerRepository = new MockCustomerRepository();
        eventPublisher = new MockEventPublisher();
        
        handler = new PlaceOrderHandler(
            orderRepository,
            customerRepository,
            new InventoryAllocationService(),  // Real domain service
            eventPublisher
        );
    });
 
    it('should create and persist order', async () => {
        customerRepository.add(new Customer(customerId, 'Test Customer'));
        
        const result = await handler.handle({
            customerId: customerId.value,
            items: [{ productId: 'prod-1', quantity: 2 }]
        });
 
        expect(result.success).toBe(true);
        expect(orderRepository.getAll()).toHaveLength(1);
        expect(eventPublisher.getPublishedEvents()).toContainEqual(
            expect.objectContaining({ type: 'OrderPlaced' })
        );
    });
});
 
// ✅ INFRASTRUCTURE ADAPTER: Integration test with real database
describe('PostgresOrderRepository', () => {
    let repository: PostgresOrderRepository;
    let connection: DatabaseConnection;
 
    beforeAll(async () => {
        connection = await createTestConnection();
        repository = new PostgresOrderRepository(connection, new OrderMapper());
    });
 
    afterEach(async () => {
        await connection.query('TRUNCATE orders, order_items CASCADE');
    });
 
    it('should persist and retrieve order correctly', async () => {
        const order = new Order(OrderId.generate(), customerId);
        order.addItem(productId, Quantity.of(3), Money.of(25, 'USD'));
        order.submit();
 
        await repository.save(order);
        const retrieved = await repository.findById(order.id);
 
        expect(retrieved).not.toBeNull();
        expect(retrieved!.id).toEqual(order.id);
        expect(retrieved!.getStatus()).toBe(OrderStatus.SUBMITTED);
        expect(retrieved!.getTotal()).toEqual(Money.of(75, 'USD'));
    });
});

The Testing Pyramid Emerges Naturally

Dependency Injection Configuration

Complete DI Configuration
TypeScript
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
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
// ============================================
// INFRASTRUCTURE: Dependency Injection Setup
// ============================================
 
// This file lives in Infrastructure layer - it knows about all layers
// and wires them together at application startup
 
import { Container } from 'inversify';
import { DataSource } from 'typeorm';
 
// Types for DI tokens
const TYPES = {
    // Domain Ports
    OrderRepository: Symbol('OrderRepository'),
    CustomerRepository: Symbol('CustomerRepository'),
    PaymentGateway: Symbol('PaymentGateway'),
    NotificationService: Symbol('NotificationService'),
    
    // Application Services
    PlaceOrderHandler: Symbol('PlaceOrderHandler'),
    ShipOrderHandler: Symbol('ShipOrderHandler'),
    GetOrderDetailsHandler: Symbol('GetOrderDetailsHandler'),
    
    // Domain Services
    InventoryAllocationService: Symbol('InventoryAllocationService'),
    ShippingCostCalculator: Symbol('ShippingCostCalculator'),
    
    // Infrastructure
    EventPublisher: Symbol('EventPublisher'),
    TransactionManager: Symbol('TransactionManager'),
    DataSource: Symbol('DataSource'),
};
 
function configureContainer(dataSource: DataSource): Container {
    const container = new Container();
 
    // === INFRASTRUCTURE BINDINGS ===
    container.bind(TYPES.DataSource).toConstantValue(dataSource);
    
    // Repository implementations
    container.bind<IOrderRepository>(TYPES.OrderRepository)
        .toDynamicValue((ctx) => new PostgresOrderRepository(
            ctx.container.get(TYPES.DataSource),
            new OrderMapper()
        ))
        .inRequestScope();
 
    container.bind<ICustomerRepository>(TYPES.CustomerRepository)
        .toDynamicValue((ctx) => new PostgresCustomerRepository(
            ctx.container.get(TYPES.DataSource),
            new CustomerMapper()
        ))
        .inRequestScope();
 
    // External service adapters
    container.bind<IPaymentGateway>(TYPES.PaymentGateway)
        .to(StripePaymentGateway)
        .inSingletonScope();
 
    container.bind<INotificationService>(TYPES.NotificationService)
        .to(SendGridNotificationService)
        .inSingletonScope();
 
    container.bind<IEventPublisher>(TYPES.EventPublisher)
        .to(RabbitMQEventPublisher)
        .inSingletonScope();
 
    container.bind<ITransactionManager>(TYPES.TransactionManager)
        .toDynamicValue((ctx) => new TypeORMTransactionManager(
            ctx.container.get(TYPES.DataSource)
        ))
        .inRequestScope();
 
    // === DOMAIN SERVICE BINDINGS ===
    container.bind(TYPES.InventoryAllocationService)
        .to(InventoryAllocationService)
        .inTransientScope();
 
    container.bind(TYPES.ShippingCostCalculator)
        .to(ShippingCostCalculator)
        .inTransientScope();
 
    // === APPLICATION SERVICE BINDINGS ===
    container.bind(TYPES.PlaceOrderHandler)
        .toDynamicValue((ctx) => new PlaceOrderHandler(
            ctx.container.get(TYPES.OrderRepository),
            ctx.container.get(TYPES.CustomerRepository),
            ctx.container.get(TYPES.InventoryAllocationService),
            ctx.container.get(TYPES.EventPublisher),
            ctx.container.get(TYPES.TransactionManager)
        ))
        .inRequestScope();
 
    container.bind(TYPES.ShipOrderHandler)
        .toDynamicValue((ctx) => new ShipOrderHandler(
            ctx.container.get(TYPES.OrderRepository),
            ctx.container.get(TYPES.EventPublisher),
            ctx.container.get(TYPES.TransactionManager)
        ))
        .inRequestScope();
 
    return container;
}
 
// Environment-specific configuration
function configureForProduction(): Container {
    const dataSource = new DataSource({
        type: 'postgres',
        url: process.env.DATABASE_URL,
        // ... production config
    });
    return configureContainer(dataSource);
}
 
function configureForTesting(): Container {
    // Use in-memory implementations for testing
    const container = new Container();
    
    container.bind<IOrderRepository>(TYPES.OrderRepository)
        .to(InMemoryOrderRepository)
        .inSingletonScope();
    
    container.bind<IPaymentGateway>(TYPES.PaymentGateway)
        .to(MockPaymentGateway)
        .inSingletonScope();
    
    // ... other test bindings
    
    return container;
}

DI Lives in Infrastructure

Migrating to Onion Architecture

Migration Phases

•Phase 1: Introduce Interfaces — Create interfaces for infrastructure dependencies (repositories, external services). Existing implementations implement these interfaces. No behavior changes.
•Phase 2: Extract Domain Model — Identify core entities and value objects. Extract them from ORM entities or DTOs into pure domain classes. Create mappers to translate between domain and persistence.
•Phase 3: Create Application Services — Wrap existing business logic in application services. These become the entry points for use cases. Controllers call application services, not repositories directly.
•Phase 4: Refactor Domain Logic — Move business rules from application services into domain entities. Introduce domain services for cross-entity logic. This is the most ongoing phase.
•Phase 5: Enforce Boundaries — Add build-time checks (module dependencies, lint rules) to prevent layer violations. Make correct structure the path of least resistance.

Phased Migration Example
TypeScript
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
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
// ============================================
// BEFORE: Traditional layered architecture
// ============================================
 
// Controller directly uses repository with ORM entities
class OrderController {
    async submitOrder(req: Request, res: Response) {
        const orderEntity = await this.orderRepo.findOne(req.params.id);
        
        // Business logic in controller
        if (orderEntity.items.length === 0) {
            return res.status(400).json({ error: 'Empty order' });
        }
        if (orderEntity.status !== 'PENDING') {
            return res.status(400).json({ error: 'Cannot submit' });
        }
        
        orderEntity.status = 'SUBMITTED';
        orderEntity.submittedAt = new Date();
        
        await this.orderRepo.save(orderEntity);
        await this.emailService.sendOrderConfirmation(orderEntity);
        
        return res.json(orderEntity);
    }
}
 
// ============================================
// PHASE 1: Introduce Interfaces
// ============================================
 
// Define interface for repository
interface IOrderRepository {
    findById(id: string): Promise<OrderEntity | null>;
    save(order: OrderEntity): Promise<void>;
}
 
// Existing implementation now implements interface
class TypeORMOrderRepository implements IOrderRepository { /* ... */ }
 
// ============================================
// PHASE 2: Extract Domain Model
// ============================================
 
// Pure domain entity (no ORM annotations)
class Order {
    constructor(
        readonly id: OrderId,
        private status: OrderStatus,
        private items: OrderItem[]
    ) {}
 
    submit(): void {
        if (this.items.length === 0) throw new EmptyOrderError(this.id);
        if (this.status !== OrderStatus.PENDING) {
            throw new InvalidStateTransitionError(this.status, OrderStatus.SUBMITTED);
        }
        this.status = OrderStatus.SUBMITTED;
    }
}
 
// Mapper between domain and persistence
class OrderMapper {
    toDomain(entity: OrderEntity): Order { /* ... */ }
    toPersistence(order: Order): OrderEntity { /* ... */ }
}
 
// Repository now returns domain objects
class TypeORMOrderRepository implements IOrderRepository {
    async findById(id: OrderId): Promise<Order | null> {
        const entity = await this.repo.findOne(id.value);
        return entity ? this.mapper.toDomain(entity) : null;
    }
}
 
// ============================================
// PHASE 3: Create Application Services
// ============================================
 
class SubmitOrderService {
    constructor(
        private readonly orderRepo: IOrderRepository,
        private readonly notificationService: INotificationService
    ) {}
 
    async execute(orderId: string): Promise<SubmitOrderResult> {
        const order = await this.orderRepo.findById(new OrderId(orderId));
        if (!order) throw new OrderNotFoundError(orderId);
 
        order.submit();  // Domain logic now in entity
 
        await this.orderRepo.save(order);
        await this.notificationService.sendOrderConfirmation(order);
 
        return { orderId: order.id.value, status: 'SUBMITTED' };
    }
}
 
// Controller becomes thin
class OrderController {
    constructor(private readonly submitOrderService: SubmitOrderService) {}
 
    async submitOrder(req: Request, res: Response) {
        try {
            const result = await this.submitOrderService.execute(req.params.id);
            return res.json(result);
        } catch (e) {
            if (e instanceof DomainException) {
                return res.status(400).json({ error: e.message });
            }
            throw e;
        }
    }
}

Strangler Fig Pattern

Production Considerations

Deploying Onion Architecture in production environments requires attention to cross-cutting concerns that span layers. Here's how to handle common production requirements:

Logging and Monitoring

•Domain layer: No logging (pure logic). Domain events serve as audit trail.
•Application layer: Log use case execution, timing, outcomes. Use structured logging.
•Infrastructure layer: Log external interactions (API calls, DB queries). Include correlation IDs.

Error Handling

•Domain layer: Throw domain-specific exceptions (business rule violations).
•Application layer: Catch domain exceptions, translate to results. Let infrastructure exceptions propagate.
•Infrastructure layer: Handle transport-specific errors. Map domain exceptions to HTTP/error codes.

Cross-Cutting Concerns by Layer
Concern	Domain	Application	Infrastructure
Validation	Business invariants	Input validation	Request/schema validation
Transactions	Aggregate boundaries	Transaction scope	Transaction implementation
Caching	N/A	Cache interface usage	Cache implementation
Security	Ownership rules	Authorization checks	Authentication
Metrics	N/A	Business metrics	Technical metrics

Aspect-Oriented Programming

Summary: Onion Architecture in Practice

We've covered the practical aspects of implementing Onion Architecture in real-world projects. Let's consolidate the key insights:

Key Takeaways

•Project structure matters — Organize folders by layer. Use build tools to enforce boundaries. Make correct structure the path of least resistance.
•Master the patterns — CQRS, Factory, Specification, Domain Events—these patterns appear repeatedly in well-designed Onion projects.
•Avoid common pitfalls — Anemic domain, infrastructure leakage, repositories returning DTOs, fat application services. Know the symptoms and fixes.
•Leverage the testing architecture — Domain unit tests (fast, many), application integration tests (focused), infrastructure tests (real resources).
•Wire with DI — The infrastructure layer configures dependency injection. Domain and application layers don't know how they're connected.
•Migrate incrementally — Introduce interfaces, extract domain, create application services, refactor behavior, enforce boundaries. No big bang.
•Handle cross-cutting concerns appropriately — Each layer has its role. Use AOP patterns to maintain clean core code.

Module complete!

Module Complete

4 / 4