Onion Architecture - Learning Module

Loading content...

0/246

Core at Center, Infrastructure at Edge

The Architecture That Protects Your Domain

In 2008, Jeffrey Palermo introduced Onion Architecture, a revolutionary approach to structuring applications that challenged the traditional layered architecture paradigm. At its heart lies a simple but profound insight: your domain logic—the rules and behaviors that define your business—should never depend on infrastructure concerns like databases, web frameworks, or external services.

This seemingly simple principle has far-reaching implications. It means your core business logic can be tested without a database. It means you can switch from PostgreSQL to MongoDB without touching domain code. It means your application's most valuable intellectual property—its business rules—is protected from the volatility of technology choices.

What You Will Learn

By the end of this page, you will understand the fundamental structure of Onion Architecture, why the domain sits at the center, how dependencies flow inward toward this core, and why infrastructure is deliberately pushed to the outer edges of your system.

The Problem with Traditional Layering

To understand why Onion Architecture matters, we must first understand what it addresses. Traditional N-tier architecture organizes applications into horizontal layers:

┌──────────────────────────────────┐
│      Presentation Layer          │
├──────────────────────────────────┤
│       Business Layer             │
├──────────────────────────────────┤
│      Data Access Layer           │
├──────────────────────────────────┤
│         Database                 │
└──────────────────────────────────┘

In this model, each layer depends on the layer directly below it. The Presentation Layer calls the Business Layer, which calls the Data Access Layer, which communicates with the Database.

The fatal flaw: Dependencies flow downward toward infrastructure. Your business logic—the most valuable part of your system—depends on the database layer. This creates several serious problems:

Problems with Traditional Layering

•Database Coupling — Business logic is tightly coupled to database schemas, stored procedures, and query patterns. Schema changes ripple upward into business code.
•Testing Difficulty — Testing business logic requires a real or mocked database. Unit tests become slow integration tests, or complex mock setups obscure what's being tested.
•Technology Lock-in — Switching databases, ORMs, or data access patterns requires rewriting business layer code. The cost of change is prohibitive.
•Infrastructure Bleed — Database concerns (transactions, connection management, caching) leak into business logic, complicating what should be pure domain operations.
•Architectural Erosion — Over time, developers take shortcuts. Business logic migrates into stored procedures, or UI components call the database directly.

The Coupling Cascade

When your business layer depends on your data layer, every database decision becomes a business layer decision. Need to add a new index? It might change query patterns the business layer relies on. Want to split a table? You'll refactor business code too. The database—which should be an implementation detail—becomes a controlling force over your entire architecture.

The Onion Insight: Inverting Dependencies

Onion Architecture addresses these problems through a fundamental insight: dependencies should flow toward the center, not toward the edges.

Instead of your business logic depending on your database, your database adapters should depend on interfaces defined by your business logic. The direction of dependencies is inverted:

          Traditional                           Onion
    
     ┌─────────────┐                    ┌─────────────────┐
     │     UI      │                    │  Infrastructure │
     └──────┬──────┘                    │    (Outer)      │
            │ depends on                └────────┬────────┘
            ▼                                    │ depends on
     ┌─────────────┐                             ▼
     │  Business   │                    ┌─────────────────┐
     └──────┬──────┘                    │  Application    │
            │ depends on                │    Services     │
            ▼                           └────────┬────────┘
     ┌─────────────┐                             │ depends on
     │   Database  │                             ▼
     └─────────────┘                    ┌─────────────────┐
                                        │  Domain Model   │
                                        │    (Center)     │
                                        └─────────────────┘

This inversion is the key to everything else in Onion Architecture. By making dependencies flow inward, we create a protective barrier around our domain logic.

The Dependency Rule

The fundamental rule of Onion Architecture: Source code dependencies can only point inward. Nothing in an inner circle can know anything about something in an outer circle. In particular, the name of something declared in an outer circle must not be mentioned by code in an inner circle—whether classes, functions, variables, or any other named software entity.

How does this work in practice?

Consider a TransferFundsService that moves money between accounts. In traditional architecture, this service might depend directly on a SqlAccountRepository. In Onion Architecture:

The domain layer defines an IAccountRepository interface (what operations we need)
The business service depends on IAccountRepository (an abstraction)
The infrastructure layer provides SqlAccountRepository (concrete implementation)
At runtime, dependency injection wires SqlAccountRepository to the interface

The critical insight: the interface is defined in the inner circle, not the outer. The domain owns the contract; infrastructure adapts to it.

Visualizing the Onion Structure

The name 'Onion Architecture' comes from its characteristic visualization: concentric circles, each representing a layer of abstraction, with the domain at the center and infrastructure at the outermost edge:

                    ┌────────────────────────────────────────────────┐
                    │            INFRASTRUCTURE LAYER                 │
                    │    (Web Controllers, Databases, Messaging,      │
                    │     File Systems, External APIs, IoC Container) │
                    │  ┌──────────────────────────────────────────┐  │
                    │  │         APPLICATION SERVICES              │  │
                    │  │    (Use Cases, Orchestration Logic,       │  │
                    │  │     Application-specific Business Rules)  │  │
                    │  │  ┌──────────────────────────────────────┐│  │
                    │  │  │         DOMAIN SERVICES               ││  │
                    │  │  │  (Domain Operations that don't belong ││  │
                    │  │  │   to a single Entity or Value Object) ││  │
                    │  │  │  ┌──────────────────────────────────┐││  │
                    │  │  │  │          DOMAIN MODEL            │││  │
                    │  │  │  │   (Entities, Value Objects,      │││  │
                    │  │  │  │    Aggregates, Domain Events)    │││  │
                    │  │  │  └──────────────────────────────────┘││  │
                    │  │  └──────────────────────────────────────┘│  │
                    │  └──────────────────────────────────────────┘  │
                    └────────────────────────────────────────────────┘

Each layer encapsulates a different level of abstraction:

The Four Primary Layers

•Domain Model (Innermost Core) — The heart of the application. Contains entities, value objects, aggregates, and domain events. Represents the fundamental business concepts and rules. Has zero external dependencies.
•Domain Services — Operations that don't naturally belong to a single entity. Cross-entity business logic, domain calculations, invariant enforcement. Still within the domain, still no infrastructure dependencies.
•Application Services — The use cases of the application. Orchestrates domain objects to implement specific application behaviors. Defines interfaces for external resources (repositories, messaging).
•Infrastructure (Outermost Layer) — Everything else: databases, web frameworks, external APIs, file systems, email services, IoC containers. Adapters that implement interfaces defined by inner layers.

The critical observation: As you move from the center toward the edge, the code becomes:

More volatile (frameworks change faster than domain rules)
More dependent on external factors (network, disk, third parties)
Easier to replace (infrastructure is pluggable)
Less valuable to the business (databases are commodities; domain logic is intellectual property)

By placing the most stable, most valuable, most business-specific code at the center and the most volatile, most replaceable code at the edge, we create architectures that age gracefully.

The Domain Model Core

The innermost circle—the Domain Model—is the most protected part of your application. It contains the pure business logic: the rules, behaviors, and concepts that exist independent of any technology choices.

What lives in the Domain Model:

Domain Model Components

•Entities — Objects with identity that persists through time. A Customer, an Order, an Account. Identity matters more than attributes.
•Value Objects — Immutable objects defined purely by their attributes. A Money object, an Address, a DateRange. Two values are equal if their attributes are equal.
•Aggregates — Clusters of entities and value objects treated as a unit for data changes. Each aggregate has a root entity that controls access to the cluster.
•Domain Events — Record of something meaningful that happened in the domain. OrderPlaced, PaymentReceived, AccountOverdrawn.
•Repository Interfaces — Abstractions for retrieving and storing aggregates. Defined here, implemented in infrastructure.

Domain Model Core Example
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
// Domain Model - No dependencies on infrastructure
 
// Value Object: Immutable, equality by value
class Money {
    private constructor(
        private readonly amount: number,
        private readonly currency: string
    ) {
        if (amount < 0) throw new Error("Amount cannot be negative");
        if (!["USD", "EUR", "GBP"].includes(currency)) {
            throw new Error(`Invalid currency: ${currency}`);
        }
    }
 
    static of(amount: number, currency: string): Money {
        return new Money(amount, currency);
    }
 
    add(other: Money): Money {
        if (this.currency !== other.currency) {
            throw new Error("Cannot add different currencies");
        }
        return new Money(this.amount + other.amount, this.currency);
    }
 
    equals(other: Money): boolean {
        return this.amount === other.amount && 
               this.currency === other.currency;
    }
}
 
// Entity: Identity-based, mutable (through controlled operations)
class Account {
    private balance: Money;
 
    constructor(
        readonly id: AccountId,
        private readonly owner: CustomerId,
        initialBalance: Money
    ) {
        this.balance = initialBalance;
    }
 
    deposit(amount: Money): void {
        this.balance = this.balance.add(amount);
    }
 
    withdraw(amount: Money): void {
        const newBalance = this.balance.subtract(amount);
        if (newBalance.isNegative()) {
            throw new InsufficientFundsError(this.id, amount);
        }
        this.balance = newBalance;
    }
 
    getBalance(): Money {
        return this.balance;
    }
}
 
// Repository Interface - Defined in domain, implemented in infrastructure
interface IAccountRepository {
    findById(id: AccountId): Promise<Account | null>;
    save(account: Account): Promise<void>;
}

Domain Purity

Notice what's not in this code: SQL queries, HTTP requests, JSON parsing, framework annotations. The domain model is pure business logic. It doesn't know how it's persisted, transported, or presented. This purity is what makes it testable, portable, and durable.

The Infrastructure Edge

The outermost layer is Infrastructure: everything that isn't your core domain logic. This is where "messy" code lives—HTTP parsing, database connections, file I/O, third-party API calls. But crucially, this code is isolated from your domain and can be changed or replaced without affecting business logic.

What lives in the Infrastructure layer:

Infrastructure Components

•Repository Implementations — Concrete classes that implement repository interfaces using specific technologies (SQL, MongoDB, in-memory).
•Web Controllers/Handlers — HTTP request handling, route definitions, request/response transformation.
•External Service Adapters — Clients for third-party APIs, messaging systems, email services.
•Persistence Configuration — ORM mappings, database connection pools, migration tooling.
•IoC Container Setup — Dependency injection configuration, service registration, lifecycle management.
•Cross-cutting Concerns — Logging implementations, metrics collection, distributed tracing.

Infrastructure Implementation Example
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
// Infrastructure - Implements interfaces defined in domain
 
// Repository implementation using PostgreSQL
class PostgresAccountRepository implements IAccountRepository {
    constructor(private readonly db: DatabaseConnection) {}
 
    async findById(id: AccountId): Promise<Account | null> {
        const row = await this.db.query(
            `SELECT id, owner_id, balance, currency 
             FROM accounts WHERE id = $1`,
            [id.value]
        );
 
        if (!row) return null;
 
        // Transform database row to domain entity
        return new Account(
            new AccountId(row.id),
            new CustomerId(row.owner_id),
            Money.of(row.balance, row.currency)
        );
    }
 
    async save(account: Account): Promise<void> {
        await this.db.query(
            `INSERT INTO accounts (id, owner_id, balance, currency)
             VALUES ($1, $2, $3, $4)
             ON CONFLICT (id) DO UPDATE SET
               balance = EXCLUDED.balance`,
            [
                account.id.value,
                account.owner.value,
                account.getBalance().amount,
                account.getBalance().currency
            ]
        );
    }
}
 
// Web Controller in infrastructure layer
class AccountController {
    constructor(
        private readonly transferService: TransferFundsService
    ) {}
 
    async handleTransfer(req: Request): Promise<Response> {
        // Parse HTTP-specific concerns
        const { fromAccountId, toAccountId, amount, currency } = req.body;
 
        try {
            // Call application service
            await this.transferService.execute(
                new AccountId(fromAccountId),
                new AccountId(toAccountId),
                Money.of(parseFloat(amount), currency)
            );
 
            return { status: 200, body: { success: true } };
        } catch (error) {
            if (error instanceof InsufficientFundsError) {
                return { status: 400, body: { error: error.message } };
            }
            throw error;
        }
    }
}

Key observations about infrastructure code:

It depends on the domain — The repository implements IAccountRepository, an interface defined in the domain
It adapts external formats — Database rows are transformed to domain objects; HTTP requests become method calls
It's replaceable — You could swap PostgresAccountRepository for MongoAccountRepository without touching domain code
It contains technical details — SQL queries, JPA annotations, HTTP status codes—all the "infrastructure noise" is here

Why Infrastructure at the Edge?

Pushing infrastructure to the edge isn't an arbitrary design choice—it's a strategic response to the forces that shape software systems over time.

Benefits of Edge Infrastructure

•Technology Agility — Databases, frameworks, and cloud services change. Edge placement lets you adopt new technology without domain rewrites.
•Pure Domain Testing — Domain logic can be unit tested with simple mocks or fakes. No database spinup, no HTTP servers.
•Clean Business Logic — Domain code reads like business documentation, not technical specification.
•Team Separation — Domain experts can work on core logic while infrastructure specialists handle integrations.

Strategic Advantages

•Risk Isolation — If a third-party API changes, only the adapter layer is affected. Domain logic remains stable.
•Vendor Flexibility — Not locked to a specific cloud provider, database vendor, or framework ecosystem.
•Investment Protection — Domain logic—your competitive advantage—persists across technology generations.
•Simpler Reasoning — Each layer has clear responsibilities. Debugging is more focused.

The Volatility Gradient

Think of the onion layers as a volatility gradient. The core changes least frequently (business rules are stable). The edge changes most frequently (frameworks update, APIs evolve, databases migrate). By aligning code organization with volatility, you minimize the impact of change: volatile code is easy to replace, stable code is protected from disruption.

The Role of Interfaces: Defining Contracts

Interfaces are the architectural mechanism that enables inward-only dependencies. They serve as contracts between layers, with a crucial placement rule: interfaces are defined in inner layers and implemented in outer layers.

This placement is non-negotiable. If the interface were defined in the infrastructure layer, the domain would depend on infrastructure—violating the core principle.

Interface Placement and Ownership
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
// ===============================================
// DOMAIN LAYER - Defines interfaces (contracts)
// ===============================================
 
// These interfaces express what the domain NEEDS
// They don't say HOW those needs are met
 
interface IAccountRepository {
    findById(id: AccountId): Promise<Account | null>;
    save(account: Account): Promise<void>;
    findByCustomer(customerId: CustomerId): Promise<Account[]>;
}
 
interface INotificationService {
    notifyOverdraft(account: Account, attemptedAmount: Money): Promise<void>;
    notifyLargeTransaction(account: Account, amount: Money): Promise<void>;
}
 
interface IAuditLogger {
    logTransfer(from: Account, to: Account, amount: Money): void;
    logFailedTransfer(from: AccountId, to: AccountId, reason: string): void;
}
 
// ===============================================
// APPLICATION LAYER - Uses interfaces
// ===============================================
 
class TransferFundsService {
    constructor(
        private readonly accountRepo: IAccountRepository,
        private readonly notifications: INotificationService,
        private readonly audit: IAuditLogger
    ) {}
 
    async execute(
        fromId: AccountId, 
        toId: AccountId, 
        amount: Money
    ): Promise<void> {
        const fromAccount = await this.accountRepo.findById(fromId);
        const toAccount = await this.accountRepo.findById(toId);
        
        // Domain validation
        if (!fromAccount || !toAccount) {
            throw new AccountNotFoundError();
        }
 
        try {
            fromAccount.withdraw(amount);
            toAccount.deposit(amount);
            
            // Persist changes
            await this.accountRepo.save(fromAccount);
            await this.accountRepo.save(toAccount);
            
            // Cross-cutting concerns via interfaces
            this.audit.logTransfer(fromAccount, toAccount, amount);
            
            if (amount.exceeds(Money.of(10000, amount.currency))) {
                await this.notifications.notifyLargeTransaction(fromAccount, amount);
            }
        } catch (e) {
            if (e instanceof InsufficientFundsError) {
                await this.notifications.notifyOverdraft(fromAccount, amount);
                this.audit.logFailedTransfer(fromId, toId, e.message);
            }
            throw e;
        }
    }
}
 
// ===============================================
// INFRASTRUCTURE LAYER - Implements interfaces
// ===============================================
 
// The domain doesn't know these exist at compile time
class PostgresAccountRepository implements IAccountRepository { /* ... */ }
class EmailNotificationService implements INotificationService { /* ... */ }
class FileAuditLogger implements IAuditLogger { /* ... */ }

Interface Ownership in Onion Architecture
Aspect	Inner Layer (Domain/Application)	Outer Layer (Infrastructure)
Creates Interfaces	Yes - defines contracts for what it needs	No - only implements contracts
Depends On	Its own interfaces	Inner layer interfaces
Knows About	Domain concepts only	Domain concepts + specific technologies
Compile-time Coupling	Zero to outer layers	Coupled to interface definitions
Replaceability	Must remain stable	Easily swappable

Summary: The Onion Structure

We've established the fundamental structure and philosophy of Onion Architecture. Let's consolidate the key principles:

Key Takeaways

•Domain at the center — The innermost layer contains pure business logic: entities, value objects, aggregates, domain events. It has no infrastructure dependencies.
•Infrastructure at the edge — The outermost layer contains all technology-specific code: databases, web frameworks, external services, configuration.
•Dependencies flow inward — Each layer may only depend on layers inside it. The infrastructure depends on the domain, never vice versa.
•Interfaces enable inversion — Contracts are defined in inner layers, implemented in outer layers. This is the mechanism that reverses traditional dependency direction.
•Volatility increases outward — The most stable code (business rules) sits at the center; the most volatile code (frameworks, integrations) sits at the edge.
•Testability by design — Domain logic can be tested without infrastructure. Dependency injection enables mock/fake substitution at boundaries.

What's next:

Now that we understand the basic structure—core at center, infrastructure at edge—we'll dive deeper into the specific layers of Onion Architecture. In the next page, we'll examine each layer in detail: what belongs there, how layers communicate, and the dependency rules that govern their relationships.

Page Complete

You now understand the fundamental structure of Onion Architecture: domain-centric design with dependencies flowing inward and infrastructure pushed to the edge. This inversion of traditional layering protects your domain from technology volatility and creates systems that are testable, maintainable, and resilient to change.