Onion Architecture: Domain-Centric System Design

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

// ============================================
// DOMAIN MODEL LAYER - Pure business logic
// ============================================
 
// Value Object: Immutable, equality by attributes
class OrderId {
    constructor(readonly value: string) {
        if (!value || value.length < 10) {
            throw new InvalidOrderIdError(value);
        }
    }
 
    equals(other: OrderId): boolean {
        return this.value === other.value;
    }
}
 
class Money {
    private constructor(
        readonly amount: number,
        readonly currency: Currency
    ) {}
 
    static of(amount: number, currency: Currency): Money {
        if (amount < 0) throw new NegativeAmountError(amount);
        return new Money(amount, currency);
    }
 
    add(other: Money): Money {
        this.assertSameCurrency(other);
        return Money.of(this.amount + other.amount, this.currency);
    }
 
    multiply(factor: number): Money {
        return Money.of(this.amount * factor, this.currency);
    }
 
    private assertSameCurrency(other: Money): void {
        if (this.currency !== other.currency) {
            throw new CurrencyMismatchError(this.currency, other.currency);
        }
    }
}
 
// Entity: Identity-based, state changes through methods
class Order {
    private items: OrderItem[] = [];
    private status: OrderStatus = OrderStatus.PENDING;
    private domainEvents: DomainEvent[] = [];
 
    constructor(
        readonly id: OrderId,
        readonly customerId: CustomerId,
        private readonly createdAt: Date
    ) {}
 
    addItem(product: ProductId, quantity: number, unitPrice: Money): void {
        if (this.status !== OrderStatus.PENDING) {
            throw new OrderNotModifiableError(this.id);
        }
        
        const existingItem = this.items.find(i => i.productId.equals(product));
        if (existingItem) {
            existingItem.increaseQuantity(quantity);
        } else {
            this.items.push(new OrderItem(product, quantity, unitPrice));
        }
    }
 
    submit(): void {
        if (this.items.length === 0) {
            throw new EmptyOrderError(this.id);
        }
        if (this.status !== OrderStatus.PENDING) {
            throw new InvalidOrderStateTransitionError(this.status, OrderStatus.SUBMITTED);
        }
        
        this.status = OrderStatus.SUBMITTED;
        this.domainEvents.push(new OrderSubmittedEvent(this.id, this.getTotal()));
    }
 
    getTotal(): Money {
        return this.items.reduce(
            (sum, item) => sum.add(item.getSubtotal()),
            Money.of(0, Currency.USD)
        );
    }
 
    pullDomainEvents(): DomainEvent[] {
        const events = [...this.domainEvents];
        this.domainEvents = [];
        return events;
    }
}
 
// Domain Event: Immutable record of what happened
class OrderSubmittedEvent implements DomainEvent {
    readonly occurredAt: Date = new Date();
    
    constructor(
        readonly orderId: OrderId,
        readonly orderTotal: Money
    ) {}
}
 
// Repository Interface: Defined in domain, implemented in infrastructure
interface IOrderRepository {
    findById(id: OrderId): Promise<Order | null>;
    save(order: Order): Promise<void>;
    nextId(): OrderId;
}
 
// Domain Exception: Business-rule specific
class OrderNotModifiableError extends Error {
    constructor(orderId: OrderId) {
        super(`Order ${orderId.value} is not in a modifiable state`);
        this.name = 'OrderNotModifiableError';
    }
}

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

// ============================================
// DOMAIN SERVICES LAYER - Cross-entity operations
// ============================================
 
// Domain Service: Funds transfer between accounts
class FundsTransferService {
    // Note: This is a pure domain service with no infrastructure dependencies
    
    transfer(
        source: Account,
        destination: Account,
        amount: Money
    ): TransferResult {
        // Business rules enforced here
        if (!source.canWithdraw(amount)) {
            return TransferResult.failed(
                new InsufficientFundsError(source.id, amount)
            );
        }
 
        if (source.owner.equals(destination.owner)) {
            // Same-owner transfers don't have daily limits
            return this.executeTransfer(source, destination, amount);
        }
 
        // Cross-customer transfers have daily limits
        const dailyTransferred = source.getTodaysTransferTotal();
        const limit = source.getDailyTransferLimit();
        
        if (dailyTransferred.add(amount).exceeds(limit)) {
            return TransferResult.failed(
                new DailyLimitExceededError(source.id, limit)
            );
        }
 
        return this.executeTransfer(source, destination, amount);
    }
 
    private executeTransfer(
        source: Account,
        destination: Account,
        amount: Money
    ): TransferResult {
        source.withdraw(amount);
        destination.deposit(amount);
        
        return TransferResult.success(
            new FundsTransferredEvent(source.id, destination.id, amount)
        );
    }
}
 
// Domain Service: Shipping cost calculation
class ShippingCostCalculator {
    calculate(
        origin: Address,
        destination: Address,
        packages: Package[],
        shippingMethod: ShippingMethod
    ): Money {
        const baseRate = this.getBaseRate(shippingMethod);
        const distanceMultiplier = this.calculateDistanceMultiplier(origin, destination);
        const weightCharge = this.calculateWeightCharge(packages);
        const dimensionalCharge = this.calculateDimensionalCharge(packages);
        
        // Business rule: charge the higher of weight or dimensional
        const variableCharge = weightCharge.exceeds(dimensionalCharge) 
            ? weightCharge 
            : dimensionalCharge;
 
        return baseRate.add(variableCharge).multiply(distanceMultiplier);
    }
 
    private getBaseRate(method: ShippingMethod): Money {
        switch (method) {
            case ShippingMethod.EXPRESS: return Money.of(15.99, Currency.USD);
            case ShippingMethod.STANDARD: return Money.of(5.99, Currency.USD);
            case ShippingMethod.ECONOMY: return Money.of(2.99, Currency.USD);
        }
    }
 
    private calculateDistanceMultiplier(origin: Address, destination: Address): number {
        // Domain logic for zone-based distance calculation
        if (origin.isInternational(destination)) return 3.5;
        if (origin.state !== destination.state) return 1.5;
        return 1.0;
    }
}
 
// Domain Service: Discount eligibility specification
class PromotionEligibilityService {
    isEligible(
        customer: Customer,
        promotion: Promotion,
        cart: ShoppingCart
    ): EligibilityResult {
        const checks: EligibilityCheck[] = [
            this.checkMinimumPurchase(cart, promotion),
            this.checkCustomerTier(customer, promotion),
            this.checkNotAlreadyUsed(customer, promotion),
            this.checkValidDateRange(promotion),
            this.checkProductCategories(cart, promotion),
        ];
 
        const failures = checks.filter(c => !c.passed);
        
        return failures.length === 0
            ? EligibilityResult.eligible(promotion)
            : EligibilityResult.ineligible(failures.map(f => f.reason));
    }
}

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
131
132
133
134
135
136
137
138
139
140
141
142
143

// ============================================
// APPLICATION SERVICES LAYER - Use case orchestration
// ============================================
 
// Command: Represents intent from outside the domain
interface TransferFundsCommand {
    sourceAccountId: string;
    destinationAccountId: string;
    amount: number;
    currency: string;
    initiatedBy: string;
}
 
// Result: Use case outcome
interface TransferFundsResult {
    success: boolean;
    transactionId?: string;
    error?: string;
}
 
// Application Service: Orchestrates the use case
class TransferFundsUseCase {
    constructor(
        private readonly accountRepository: IAccountRepository,
        private readonly transferService: FundsTransferService,
        private readonly eventPublisher: IEventPublisher,
        private readonly transactionManager: ITransactionManager,
        private readonly auditLog: IAuditLog
    ) {}
 
    async execute(command: TransferFundsCommand): Promise<TransferFundsResult> {
        // Input validation (application-level, not domain-level)
        if (!command.sourceAccountId || !command.destinationAccountId) {
            return { success: false, error: 'Account IDs are required' };
        }
 
        // Begin transaction boundary
        return await this.transactionManager.executeInTransaction(async () => {
            // 1. Load aggregates from repository
            const sourceAccount = await this.accountRepository.findById(
                new AccountId(command.sourceAccountId)
            );
            const destAccount = await this.accountRepository.findById(
                new AccountId(command.destinationAccountId)
            );
 
            if (!sourceAccount || !destAccount) {
                return { success: false, error: 'Account not found' };
            }
 
            // 2. Execute domain logic via domain service
            const transferResult = this.transferService.transfer(
                sourceAccount,
                destAccount,
                Money.of(command.amount, command.currency as Currency)
            );
 
            if (!transferResult.isSuccess) {
                await this.auditLog.logFailedTransfer(
                    command,
                    transferResult.error!
                );
                return { 
                    success: false, 
                    error: transferResult.error!.message 
                };
            }
 
            // 3. Persist changes
            await this.accountRepository.save(sourceAccount);
            await this.accountRepository.save(destAccount);
 
            // 4. Publish domain events
            const events = [
                ...sourceAccount.pullDomainEvents(),
                ...destAccount.pullDomainEvents(),
                transferResult.event!
            ];
            
            for (const event of events) {
                await this.eventPublisher.publish(event);
            }
 
            // 5. Audit logging
            await this.auditLog.logSuccessfulTransfer(command, events);
 
            return {
                success: true,
                transactionId: transferResult.event!.transactionId
            };
        });
    }
}
 
// Another Application Service: Query handler
interface GetAccountBalanceQuery {
    accountId: string;
    asOf?: Date;
}
 
interface AccountBalanceResult {
    accountId: string;
    balance: { amount: number; currency: string };
    lastUpdated: Date;
}
 
class GetAccountBalanceHandler {
    constructor(
        private readonly accountRepository: IAccountRepository,
        private readonly balanceCache: IBalanceCache
    ) {}
 
    async handle(query: GetAccountBalanceQuery): Promise<AccountBalanceResult | null> {
        // Try cache first
        const cached = await this.balanceCache.get(query.accountId);
        if (cached && !query.asOf) {
            return cached;
        }
 
        // Load from repository
        const account = await this.accountRepository.findById(
            new AccountId(query.accountId)
        );
 
        if (!account) return null;
 
        const result: AccountBalanceResult = {
            accountId: account.id.value,
            balance: {
                amount: account.getBalance().amount,
                currency: account.getBalance().currency
            },
            lastUpdated: account.getLastModified()
        };
 
        // Update cache
        if (!query.asOf) {
            await this.balanceCache.set(query.accountId, result);
        }
 
        return result;
    }
}

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
131
132
133
134
135
136
137
138
139
140
141
142

// ============================================
// INFRASTRUCTURE LAYER - Technology implementations
// ============================================
 
// Repository implementation with PostgreSQL
class PostgresAccountRepository implements IAccountRepository {
    constructor(
        private readonly pool: Pool,
        private readonly mapper: AccountMapper
    ) {}
 
    async findById(id: AccountId): Promise<Account | null> {
        const result = await this.pool.query(
            `SELECT id, owner_id, balance, currency, status, created_at, updated_at
             FROM accounts 
             WHERE id = $1`,
            [id.value]
        );
 
        if (result.rowCount === 0) return null;
        
        return this.mapper.toDomain(result.rows[0]);
    }
 
    async save(account: Account): Promise<void> {
        const data = this.mapper.toPersistence(account);
        
        await this.pool.query(
            `INSERT INTO accounts (id, owner_id, balance, currency, status, created_at, updated_at)
             VALUES ($1, $2, $3, $4, $5, $6, NOW())
             ON CONFLICT (id) DO UPDATE SET
               balance = EXCLUDED.balance,
               status = EXCLUDED.status,
               updated_at = NOW()`,
            [data.id, data.ownerId, data.balance, data.currency, data.status, data.createdAt]
        );
    }
 
    nextId(): AccountId {
        return new AccountId(crypto.randomUUID());
    }
}
 
// Mapper: Translates between persistence and domain models
class AccountMapper {
    toDomain(row: AccountRow): Account {
        return Account.reconstitute({
            id: new AccountId(row.id),
            owner: new CustomerId(row.owner_id),
            balance: Money.of(parseFloat(row.balance), row.currency as Currency),
            status: row.status as AccountStatus,
            createdAt: row.created_at
        });
    }
 
    toPersistence(account: Account): AccountRow {
        const snapshot = account.toSnapshot();
        return {
            id: snapshot.id,
            owner_id: snapshot.ownerId,
            balance: snapshot.balance.toString(),
            currency: snapshot.currency,
            status: snapshot.status,
            created_at: snapshot.createdAt
        };
    }
}
 
// Event Publisher implementation with RabbitMQ
class RabbitMQEventPublisher implements IEventPublisher {
    constructor(
        private readonly channel: Channel,
        private readonly serializer: EventSerializer
    ) {}
 
    async publish(event: DomainEvent): Promise<void> {
        const routingKey = this.getRoutingKey(event);
        const message = this.serializer.serialize(event);
        
        await this.channel.publish(
            'domain-events',
            routingKey,
            Buffer.from(message),
            { 
                persistent: true,
                contentType: 'application/json',
                headers: {
                    eventType: event.constructor.name,
                    occurredAt: event.occurredAt.toISOString()
                }
            }
        );
    }
 
    private getRoutingKey(event: DomainEvent): string {
        // Convention: domain.aggregate.event
        return `banking.account.${event.constructor.name.toLowerCase()}`;
    }
}
 
// Web Controller (Primary Adapter)
class AccountController {
    constructor(
        private readonly transferUseCase: TransferFundsUseCase,
        private readonly balanceQuery: GetAccountBalanceHandler
    ) {}
 
    async handleTransfer(req: Request, res: Response): Promise<void> {
        const command: TransferFundsCommand = {
            sourceAccountId: req.body.from,
            destinationAccountId: req.body.to,
            amount: parseFloat(req.body.amount),
            currency: req.body.currency,
            initiatedBy: req.user.id
        };
 
        const result = await this.transferUseCase.execute(command);
 
        if (result.success) {
            res.status(200).json({
                transactionId: result.transactionId,
                status: 'completed'
            });
        } else {
            res.status(400).json({
                error: result.error
            });
        }
    }
 
    async handleGetBalance(req: Request, res: Response): Promise<void> {
        const result = await this.balanceQuery.handle({
            accountId: req.params.accountId
        });
 
        if (result) {
            res.status(200).json(result);
        } else {
            res.status(404).json({ error: 'Account not found' });
        }
    }
}

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
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160

// ============================================
// COMPLETE DATA FLOW THROUGH LAYERS
// ============================================
 
// 1. INFRASTRUCTURE: HTTP Request arrives
// Raw HTTP data, framework-specific types
 
class OrderController {
    constructor(private readonly submitOrderUseCase: SubmitOrderUseCase) {}
 
    async handleSubmitOrder(req: Request, res: Response): Promise<void> {
        // Transform HTTP request to Command DTO
        const command: SubmitOrderCommand = {
            orderId: req.params.orderId,
            requestedBy: req.user.id,
            requestedAt: new Date()
        };
 
        // Call Application Layer with DTO
        const result = await this.submitOrderUseCase.execute(command);
 
        // Transform Result DTO to HTTP response
        if (result.success) {
            res.status(200).json({
                orderId: result.orderId,
                status: result.newStatus,
                estimatedDelivery: result.estimatedDelivery
            });
        } else {
            res.status(400).json({ error: result.errorMessage });
        }
    }
}
 
// 2. APPLICATION LAYER: Command DTO received
// Orchestrates domain objects, uses DTOs for input/output
 
interface SubmitOrderCommand {
    orderId: string;
    requestedBy: string;
    requestedAt: Date;
}
 
interface SubmitOrderResult {
    success: boolean;
    orderId?: string;
    newStatus?: string;
    estimatedDelivery?: Date;
    errorMessage?: string;
}
 
class SubmitOrderUseCase {
    constructor(
        private readonly orderRepository: IOrderRepository,
        private readonly eventPublisher: IEventPublisher
    ) {}
 
    async execute(command: SubmitOrderCommand): Promise<SubmitOrderResult> {
        try {
            // Load domain object from repository
            const order = await this.orderRepository.findById(
                new OrderId(command.orderId)
            );
 
            if (!order) {
                return { success: false, errorMessage: 'Order not found' };
            }
 
            // Invoke domain logic (returns void, mutates entity)
            order.submit();
 
            // Save domain object via repository
            await this.orderRepository.save(order);
 
            // Publish domain events
            const events = order.pullDomainEvents();
            for (const event of events) {
                await this.eventPublisher.publish(event);
            }
 
            // Return Result DTO (transformed from domain)
            return {
                success: true,
                orderId: order.id.value,
                newStatus: order.getStatus().toString(),
                estimatedDelivery: order.getEstimatedDelivery()
            };
        } catch (error) {
            if (error instanceof DomainException) {
                return { success: false, errorMessage: error.message };
            }
            throw error;
        }
    }
}
 
// 3. DOMAIN LAYER: Pure business logic
// No knowledge of how it's called or where data comes from
 
class Order {
    private status: OrderStatus = OrderStatus.PENDING;
    private items: OrderItem[] = [];
    private domainEvents: DomainEvent[] = [];
 
    submit(): void {
        // Pure business validation - no external dependencies
        if (this.items.length === 0) {
            throw new EmptyOrderException(this.id);
        }
        if (this.status !== OrderStatus.PENDING) {
            throw new InvalidStateTransitionException(
                this.status, 
                OrderStatus.SUBMITTED
            );
        }
 
        // State change
        this.status = OrderStatus.SUBMITTED;
        
        // Record domain event
        this.domainEvents.push(
            new OrderSubmittedEvent(this.id, this.getTotal())
        );
    }
 
    getStatus(): OrderStatus { return this.status; }
    
    getEstimatedDelivery(): Date {
        // Domain logic for delivery estimation
        const baseDays = this.shippingMethod === ShippingMethod.EXPRESS ? 2 : 5;
        const date = new Date();
        date.setDate(date.getDate() + baseDays);
        return date;
    }
}
 
// 4. INFRASTRUCTURE: Repository Implementation
// Transforms between domain objects and persistence format
 
class PostgresOrderRepository implements IOrderRepository {
    async findById(id: OrderId): Promise<Order | null> {
        // Query database (infrastructure concern)
        const row = await this.db.query('SELECT * FROM orders WHERE id = $1', [id.value]);
        if (!row) return null;
 
        // Transform persistence format to domain object
        return this.mapper.toDomain(row);
    }
 
    async save(order: Order): Promise<void> {
        // Transform domain object to persistence format
        const row = this.mapper.toPersistence(order);
        
        // Save to database (infrastructure concern)
        await this.db.query(
            'UPDATE orders SET status = $2, updated_at = NOW() WHERE id = $1',
            [row.id, row.status]
        );
    }
}