System Design (HLD)Depending on Abstractions

Depending on Abstractions

LevelIntermediate

Duration75 mins

TopicDepending on Abstractions

2 / 4

Ownership of Abstractions

The Most Important Question in DIP

In our previous exploration of interfaces as abstraction mechanisms, we established that interfaces create boundaries between components. We saw how both high-level and low-level modules can depend on interfaces rather than on each other.

But we glossed over a question that turns out to be the most important question in dependency inversion: Who defines and owns the interface?

This question might seem like a minor detail—an implementation afterthought. It is anything but. The answer to this question determines whether your dependency inversion actually works, or whether you've merely added an unnecessary layer of indirection while preserving all the coupling problems you were trying to solve.

Get interface ownership wrong, and you'll have all the complexity of abstraction with none of the benefits. Get it right, and you unlock the full power of the Dependency Inversion Principle.

What You Will Master

By the end of this page, you will understand why interface ownership matters, how wrong ownership undermines DIP, and the correct principles for placing interfaces. You'll learn the crucial distinction between consumer-owned and provider-owned abstractions, and how this distinction affects coupling, testing, and system evolution.

The Ownership Problem

When we introduce an interface between two components, we create three entities:

The Consumer — The component that uses the interface
The Interface — The abstraction defining the contract
The Implementation — The component that provides the service

The implementation clearly belongs logically with its provider—a StripePaymentProcessor implementation belongs in the Stripe integration module. But where does the interface belong?

There are two possible answers:

Option A: Interface lives with the implementation (provider-owned)

[High-Level Module] → [Low-Level Module: Interface + Implementation]

Option B: Interface lives with the consumer (consumer-owned)

[High-Level Module: Interface] ← [Low-Level Module: Implementation]

The choice between these options has profound implications that we need to explore in depth.

The Naive Approach That Feels Right But Is Wrong:

Developers often intuitively place interfaces with their implementations. This feels natural because:

The implementation team understands the capabilities being abstracted
The interface and implementation can be versioned together
IDE refactoring tools extract interfaces to the same package

But this intuition leads to a critical failure mode. Let's trace through why.

The Ownership Trap

Many developers believe they've applied DIP when they've created an interface that the high-level module uses. But if that interface is defined and owned by the low-level module, the dependency hasn't been inverted—it's been hidden behind a thin abstraction layer that provides false comfort.

Provider-Owned Abstractions: The Anti-Pattern

Let's examine what happens when interfaces are owned by the provider (the low-level module that implements them).

Scenario: Email Service

You're building an order processing system that needs to send confirmation emails. You decide to depend on an interface rather than a concrete email service. The email team provides this:

provider_owned_problem.ts
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
// ❌ PROBLEMATIC: Interface owned by email module (low-level)
 
// ===========================================
// email-service module (low-level provider)
// ===========================================
// File: email-service/EmailService.ts
export interface EmailService {
    sendEmail(
        to: string[],
        cc: string[],
        bcc: string[],
        subject: string,
        htmlBody: string,
        plainTextBody: string,
        attachments: EmailAttachment[],
        headers: EmailHeaders,
        priority: EmailPriority,
        trackingPixel: boolean,
        openTracking: boolean,
        clickTracking: boolean,
    ): Promise<SendResult>;
    
    getEmailStatus(messageId: string): Promise<EmailStatus>;
    getDeliveryReport(messageId: string): Promise<DeliveryReport>;
    getBounces(since: Date): Promise<BounceReport[]>;
    getComplaints(since: Date): Promise<ComplaintReport[]>;
}
 
// File: email-service/GmailEmailService.ts
export class GmailEmailService implements EmailService {
    // Gmail-specific implementation
}
 
// ===========================================
// order-processing module (high-level consumer)  
// ===========================================
// File: order-processing/OrderProcessor.ts
import { EmailService, SendResult } from 'email-service';  // ← Dependency!
 
class OrderProcessor {
    constructor(private emailService: EmailService) {}
    
    async processOrder(order: Order): Promise<void> {
        // ... order processing logic ...
        
        // Send confirmation - forced to use email-centric API
        await this.emailService.sendEmail(
            [order.customer.email],
            [],          // cc - don't need
            [],          // bcc - don't need
            'Order Confirmation',
            this.buildHtmlEmail(order),
            this.buildTextEmail(order),
            [],          // attachments - don't need
            {},          // headers - don't need
            'normal',    // priority - don't care
            false,       // tracking - don't care
            false,       // open tracking - don't care
            false,       // click tracking - don't care
        );
    }
}

Why This Is Broken:

At first glance, this looks like dependency inversion—we're depending on an interface, not a concrete class. But examine the reality:

1. The import statement reveals the truth:

import { EmailService } from 'email-service'

The high-level module (order-processing) has a compile-time dependency on the low-level module (email-service). If email-service changes, order-processing must be recompiled. If email-service is unavailable, order-processing cannot be built.

2. The interface is designed for the provider, not the consumer:

Look at all those parameters the OrderProcessor doesn't need (cc, bcc, attachments, tracking options). The interface exposes email-specific concepts (tracking pixels, bounces, complaints) that have nothing to do with order confirmation.

3. The consumer cannot use a non-email alternative:

What if you want to send order confirmations via SMS or push notification? The interface assumes email as the transport. You'd need to create a fake "email" wrapper around SMS—a clear design smell.

4. Changes to email-service cascade to consumers:

When the email team adds a new parameter (say, scheduling options), all consumers must update their calls, even if they don't use the feature.

Provider-Owned Interface Problems

•Dependency direction unchanged — High-level still depends on low-level module
•Provider-centric design — Interface reflects implementation capabilities, not consumer needs
•Fat interface — Includes operations irrelevant to many consumers
•Technology lock-in — Interface assumes specific technology (email vs. other transports)
•Change propagation — Provider changes force consumer updates
•Testing complexity — Must mock email-specific concepts even when testing order logic

The Hidden Dependency

When interfaces are owned by providers, you haven't inverted any dependencies—you've merely added a level of indirection. The high-level module still depends on the low-level module (to get the interface definition), and is still designed around the low-level module's concepts. This is arguably worse than no interface at all, because it provides an illusion of decoupling.

Consumer-Owned Abstractions: The Correct Pattern

Now let's see how consumer-owned abstractions properly implement the Dependency Inversion Principle.

Scenario: The Same Order Processing System

Instead of using the email service's interface, the order processing module defines its own interface representing what it needs:

consumer_owned_correct.ts
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
// ✅ CORRECT: Interface owned by order-processing module (high-level)
 
// ===========================================
// order-processing module (high-level consumer)
// ===========================================
// File: order-processing/ports/OrderNotifier.ts
// This interface is OWNED by order-processing, not email-service
 
export interface OrderNotifier {
    /**
     * Sends an order confirmation to the customer.
     * The implementation decides HOW (email, SMS, push, etc.)
     */
    sendOrderConfirmation(order: Order): Promise<NotificationResult>;
    
    /**
     * Notifies the customer that their order has shipped.
     */
    sendShippingNotification(order: Order, tracking: TrackingInfo): Promise<NotificationResult>;
    
    /**
     * Notifies the customer of order cancellation.
     */
    sendCancellationNotification(order: Order, reason: string): Promise<NotificationResult>;
}
 
// File: order-processing/OrderProcessor.ts
// NO import from email-service! Interface is local.
 
class OrderProcessor {
    constructor(private orderNotifier: OrderNotifier) {}
    
    async processOrder(order: Order): Promise<void> {
        // ... order processing logic ...
        
        // Clean, high-level call focused on WHAT, not HOW
        await this.orderNotifier.sendOrderConfirmation(order);
    }
}
 
// ===========================================
// email-adapter module (low-level, implements the interface)
// ===========================================
// File: email-adapter/EmailOrderNotifier.ts
import { OrderNotifier, Order, TrackingInfo, NotificationResult } from 'order-processing';
import { GmailClient } from 'gmail-sdk';
 
export class EmailOrderNotifier implements OrderNotifier {
    constructor(private gmailClient: GmailClient) {}
    
    async sendOrderConfirmation(order: Order): Promise<NotificationResult> {
        // This adapter handles all the email-specific details
        const html = this.buildConfirmationHtml(order);
        const text = this.buildConfirmationText(order);
        
        const result = await this.gmailClient.send({
            to: order.customer.email,
            subject: `Order Confirmation #${order.id}`,
            html,
            text,
            // All email-specific options handled here, 
            // invisible to the order-processing module
        });
        
        return { success: result.sent, messageId: result.id };
    }
    
    // ... other notification methods
}
 
// ===========================================
// sms-adapter module (alternative implementation)
// ===========================================
// File: sms-adapter/SmsOrderNotifier.ts
import { OrderNotifier } from 'order-processing';
import { TwilioClient } from 'twilio-sdk';
 
export class SmsOrderNotifier implements OrderNotifier {
    constructor(private twilioClient: TwilioClient) {}
    
    async sendOrderConfirmation(order: Order): Promise<NotificationResult> {
        const message = `Order #${order.id} confirmed! Total: ${order.total}`;
        await this.twilioClient.sendSms(order.customer.phone, message);
        return { success: true };
    }
    
    // ... other notification methods
}

Why This Works:

1. The dependency direction is truly inverted:

[order-processing: OrderProcessor + OrderNotifier interface]
                          ↑
           [email-adapter: EmailOrderNotifier]

The low-level module (email-adapter) now depends on the high-level module (order-processing) to get the interface. The arrow has flipped!

2. The interface is designed for the consumer:

The OrderNotifier interface speaks the language of orders—sendOrderConfirmation, sendShippingNotification. It doesn't mention email, SMTP, HTML, or tracking pixels. The consumer gets exactly what it needs.

3. Implementations are freely substitutable:

Email, SMS, push notification, Slack—any transport that can implement OrderNotifier works. The consumer doesn't know or care.

4. Changes to implementations don't affect consumers:

The email service can add scheduling, analytics, or any other feature. The adapter handles them; OrderProcessor is unaffected.

5. The consumer is independently testable:

consumer_testing.ts
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
// Testing is trivial because the interface is focused and consumer-owned
 
class MockOrderNotifier implements OrderNotifier {
    public confirmationsSent: Order[] = [];
    
    async sendOrderConfirmation(order: Order): Promise<NotificationResult> {
        this.confirmationsSent.push(order);
        return { success: true };
    }
    
    // ... other methods
}
 
describe('OrderProcessor', () => {
    it('sends confirmation after successful order', async () => {
        const mockNotifier = new MockOrderNotifier();
        const processor = new OrderProcessor(mockNotifier);
        
        await processor.processOrder(testOrder);
        
        expect(mockNotifier.confirmationsSent).toContainEqual(testOrder);
    });
});
 
// No email-specific mocking needed. The test is focused on order logic.

Consumer-Owned Interface Benefits

•True dependency inversion — Low-level depends on high-level's abstraction
•Consumer-centric design — Interface represents consumer's needs, not provider's capabilities
•Focused interface — Only operations the consumer actually uses
•Technology agnostic — Interface doesn't assume any particular implementation
•Isolation from changes — Provider changes stay in adapter, don't cascade
•Simple testing — Mock the focused interface, test in isolation

The Ownership Rule

Interfaces should be owned by the module that uses them, not the module that implements them. This ensures the interface serves the consumer's needs and that the dependency arrow truly points from low-level to high-level.

The Hexagonal Architecture Perspective

The concept of interface ownership is formalized in Hexagonal Architecture (also known as Ports and Adapters), introduced by Alistair Cockburn. This architecture provides a clear model for understanding where interfaces belong.

The Hexagonal Model:

Imagine your application as a hexagon. At the center is your domain logic—the business rules and policies that define your application's purpose. This is the high-level module.

Around the edge of the hexagon are ports—interfaces that define how the outside world interacts with your application. There are two types:

Driving Ports (Primary) — Used by external actors to interact with the application (e.g., OrderService interface called by HTTP handlers)
Driven Ports (Secondary) — Used by the application to interact with external systems (e.g., OrderRepository, PaymentGateway, NotificationSender)

Outside the hexagon are adapters—implementations that connect ports to actual infrastructure (databases, APIs, message queues, etc.).

hexagonal_structure.ts
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
// Hexagonal Architecture in practice
 
// ===========================================
// CORE DOMAIN (center of the hexagon)
// ===========================================
 
// Driven Ports - owned by the domain, implemented by infrastructure
// These are the interfaces we've been discussing
 
interface OrderRepository {                    // Driven Port
    save(order: Order): Promise<Order>;
    findById(id: OrderId): Promise<Order | null>;
}
 
interface PaymentGateway {                     // Driven Port
    charge(amount: Money, method: PaymentMethod): Promise<ChargeResult>;
}
 
interface InventoryService {                   // Driven Port
    reserve(items: OrderItem[]): Promise<Reservation>;
    release(reservationId: string): Promise<void>;
}
 
// Domain Service - uses ports, contains business logic
class OrderProcessor {
    constructor(
        private orderRepo: OrderRepository,    // Uses driven port
        private paymentGateway: PaymentGateway,
        private inventoryService: InventoryService,
    ) {}
    
    async createOrder(request: CreateOrderRequest): Promise<Order> {
        // Pure business logic - no infrastructure details
        const reservation = await this.inventoryService.reserve(request.items);
        const payment = await this.paymentGateway.charge(request.total, request.paymentMethod);
        const order = Order.create(request, reservation.id, payment.chargeId);
        return this.orderRepo.save(order);
    }
}
 
// Driving Port - how external actors interact with the domain
interface OrderApplicationService {            // Driving Port
    createOrder(command: CreateOrderCommand): Promise<OrderResult>;
    cancelOrder(command: CancelOrderCommand): Promise<CancellationResult>;
}
 
// ===========================================
// ADAPTERS (outside the hexagon)
// ===========================================
 
// Driven Adapters - implement driven ports
class PostgresOrderRepository implements OrderRepository {
    // SQL-specific implementation
}
 
class StripePaymentGateway implements PaymentGateway {
    // Stripe-specific implementation
}
 
class HttpInventoryService implements InventoryService {
    // HTTP client to inventory microservice
}
 
// Driving Adapters - use driving ports
class HttpOrderController {
    constructor(private orderService: OrderApplicationService) {}
    
    // HTTP-specific handling, delegates to domain
    async handleCreateOrder(req: HttpRequest): Promise<HttpResponse> {
        const command = this.parseRequest(req);
        const result = await this.orderService.createOrder(command);
        return this.buildResponse(result);
    }
}

The Key Insight:

In Hexagonal Architecture, all ports (interfaces) are owned by the domain. The domain doesn't know about PostgreSQL, Stripe, or HTTP—it knows about OrderRepository, PaymentGateway, and OrderApplicationService. These are defined in domain terms.

Adapters live outside the domain and depend on the domain's ports. This means:

The domain can be tested without any real infrastructure
Adapters can be swapped without domain changes
New adapters can be added without modifying existing code
The domain's design is driven by business needs, not by infrastructure constraints

The Dependency Rule:

In Hexagonal Architecture, dependencies always point inward—from adapters toward the domain. Adapters depend on ports; ports are owned by the domain. This is the Dependency Inversion Principle expressed architecturally.

Ports and Ownership

Hexagonal Architecture makes interface ownership explicit through the concept of ports. Ports are always defined by the application core (high-level), not by the infrastructure (low-level). This reinforces that abstractions should be owned by their consumers.

Package and Module Structure

Understanding interface ownership is one thing; implementing it correctly in your codebase structure is another. Let's examine how to organize packages and modules to reinforce correct ownership.

The Wrong Structure (Provider-Owned):

wrong_structure.txt

# ❌ PROBLEMATIC: Interface lives with implementation
 
project/
├── email-service/
│   ├── EmailService.ts         # Interface defined here
│   ├── GmailEmailService.ts    # Implementation
│   └── index.ts                # Exports both
│
├── order-processing/
│   ├── OrderProcessor.ts       # Imports from email-service
│   └── index.ts
│
└── package.json
    # order-processing depends on email-service (wrong direction)

The Correct Structure (Consumer-Owned):

correct_structure.txt
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
# ✅ CORRECT: Interface lives with consumer
 
project/
├── order-processing/
│   ├── domain/
│   │   ├── Order.ts            # Domain entities
│   │   └── OrderProcessor.ts   # Uses port
│   │
│   ├── ports/
│   │   ├── OrderNotifier.ts    # Interface - OWNED by order-processing
│   │   └── OrderRepository.ts  # Interface - OWNED by order-processing
│   │
│   └── index.ts
│
├── email-adapter/
│   ├── EmailOrderNotifier.ts   # Implements OrderNotifier from order-processing
│   └── index.ts                # Imports from order-processing (correct direction)
│
├── postgres-adapter/
│   ├── PostgresOrderRepository.ts  # Implements OrderRepository
│   └── index.ts                    # Imports from order-processing
│
└── package.json
    # email-adapter and postgres-adapter depend on order-processing
    # order-processing has NO dependencies on adapters

Common Folder Organization Patterns:

Ports Folder Pattern

•Create ports/ directory in domain module
•All driven interfaces live here
•Clearly signals "these are our abstractions"
•Easy to identify all external dependencies

Adapters Folder Pattern

•Create adapters/ directory for implementations
•Organize by technology (postgres, redis, stripe)
•Each adapter module imports from domain
•Clearly signals "infrastructure integration"

comprehensive_structure.txt
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
# Comprehensive project structure with correct ownership
 
project/
├── src/
│   ├── domain/                     # Core business logic
│   │   ├── entities/
│   │   │   ├── Order.ts
│   │   │   ├── Customer.ts
│   │   │   └── Product.ts
│   │   │
│   │   ├── services/
│   │   │   ├── OrderProcessor.ts
│   │   │   └── PricingCalculator.ts
│   │   │
│   │   └── ports/                  # Consumer-owned interfaces
│   │       ├── repositories/
│   │       │   ├── OrderRepository.ts
│   │       │   └── ProductRepository.ts
│   │       │
│   │       ├── gateways/
│   │       │   ├── PaymentGateway.ts
│   │       │   └── ShippingGateway.ts
│   │       │
│   │       └── notifiers/
│   │           └── OrderNotifier.ts
│   │
│   ├── adapters/                   # Infrastructure implementations
│   │   ├── persistence/
│   │   │   ├── postgres/
│   │   │   │   ├── PostgresOrderRepository.ts
│   │   │   │   └── PostgresProductRepository.ts
│   │   │   └── redis/
│   │   │       └── RedisCacheRepository.ts
│   │   │
│   │   ├── payment/
│   │   │   ├── StripePaymentGateway.ts
│   │   │   └── PayPalPaymentGateway.ts
│   │   │
│   │   └── notification/
│   │       ├── EmailOrderNotifier.ts
│   │       └── SmsOrderNotifier.ts
│   │
│   └── api/                        # Entry points (driving adapters)
│       ├── http/
│       │   └── OrderController.ts
│       └── graphql/
│           └── OrderResolver.ts
│
└── tests/
    ├── unit/
    │   └── domain/                 # Unit tests use mock implementations
    │       └── OrderProcessor.test.ts
    │
    └── integration/
        └── adapters/               # Integration tests use real implementations
            └── PostgresOrderRepository.test.ts

Module Dependency Validation

Use tools like dependency-cruiser (Node.js), deptrac (PHP), or architectural fitness functions to enforce that adapters depend on domain and never the reverse. Automated validation prevents accidental introduction of wrong-direction dependencies.

Shared Abstractions: When Multiple Consumers Need the Same Interface

A natural question arises: What happens when multiple high-level modules need the same abstraction? Do we duplicate interfaces?

The Shared Kernel Pattern:

When multiple domain modules need the same abstraction, you have several options:

Option 1: Duplicate Focused Interfaces

If different consumers have different needs, they should define their own interfaces even if there's overlap. This maintains consumer-centric design.

duplicate_interfaces.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// Order module needs specific notification capability
// File: order-processing/ports/OrderNotifier.ts
interface OrderNotifier {
    notifyOrderConfirmation(order: Order): Promise<void>;
    notifyOrderShipped(order: Order, tracking: TrackingInfo): Promise<void>;
}
 
// Marketing module has different needs
// File: marketing/ports/CampaignNotifier.ts
interface CampaignNotifier {
    sendPromotion(campaign: Campaign, customers: Customer[]): Promise<BatchResult>;
    sendNewsletter(newsletter: Newsletter, subscribers: Subscriber[]): Promise<BatchResult>;
}
 
// Both might be implemented by the same EmailService underneath,
// but each consumer has its own tailored interface

Option 2: Extract to Shared Kernel

When multiple modules genuinely need the exact same abstraction (same methods, same semantics), extract the interface to a shared module that both depend on. This shared module should be:

Extremely stable (rarely changes)
Carefully designed (approved by all consumers)
Focused on truly shared concepts

shared_kernel.ts
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
// Shared abstractions for genuinely common concepts
// File: shared-kernel/ports/AuditLogger.ts
 
/**
 * Shared interface for audit logging.
 * Used by multiple modules that need consistent audit trails.
 * Changes to this interface require coordination across all consumers.
 */
export interface AuditLogger {
    logAction(
        actor: ActorId,
        action: AuditAction,
        resource: ResourceId,
        details: AuditDetails,
    ): Promise<void>;
    
    getAuditTrail(
        resource: ResourceId,
        filter: AuditFilter,
    ): Promise<AuditEntry[]>;
}
 
// Multiple modules depend on shared-kernel
// order-processing/
//   └── AuditService using AuditLogger
// inventory/
//   └── StockAuditor using AuditLogger  
// payment/
//   └── TransactionAuditor using AuditLogger

Guidelines for Shared Abstractions:

When to Share vs. When to Duplicate

•Share when: The abstraction represents a universal concept (logging, caching, metrics) with identical semantics across consumers
•Duplicate when: Consumers have subtly different needs that would pollute a shared interface
•Share when: The interface is stable and unlikely to change based on any single consumer's needs
•Duplicate when: You anticipate divergent requirements over time
•Share when: Consumers agree on the abstraction's design and will coordinate on changes
•Duplicate when: Consumers are owned by different teams with different priorities

The Shared Abstraction Trap

Over-sharing creates coupling between unrelated modules. If changing an interface requires coordinating multiple teams, you've replaced implementation coupling with interface coupling. When in doubt, duplicate. It's easier to consolidate later than to untangle premature shared abstractions.

The Adapter Pattern for Interface Ownership

In many real-world scenarios, you'll work with third-party libraries or services that have their own interfaces. You can't modify these external interfaces, so how do you achieve consumer-owned abstractions?

The answer is the Adapter Pattern—a wrapper that translates between your interface and the external one.

The Problem:

You're using a payment service SDK that exposes StripeClient. Your domain shouldn't depend on Stripe's interface directly (that would be provider-owned).

The Solution:

adapter_pattern.ts
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
// ===========================================
// DOMAIN - defines what it needs
// ===========================================
 
// Your domain's interface - consumer-owned
interface PaymentGateway {
    charge(amount: Money, method: PaymentMethodDetails): Promise<ChargeResult>;
    refund(chargeId: ChargeId, amount?: Money): Promise<RefundResult>;
    getCharge(chargeId: ChargeId): Promise<ChargeInfo>;
}
 
// Domain entities - in your terms
interface ChargeResult {
    success: boolean;
    chargeId: ChargeId;
    authorizationCode?: string;
    error?: PaymentError;
}
 
// ===========================================
// ADAPTER - translates between interfaces
// ===========================================
 
import Stripe from 'stripe';  // Third-party SDK
 
class StripePaymentGatewayAdapter implements PaymentGateway {
    constructor(private stripeClient: Stripe) {}
    
    async charge(amount: Money, method: PaymentMethodDetails): Promise<ChargeResult> {
        try {
            // Translate from domain terms to Stripe terms
            const stripeCharge = await this.stripeClient.charges.create({
                amount: this.toStripeAmount(amount),
                currency: amount.currency.toLowerCase(),
                source: this.toStripeSource(method),
                description: method.description,
            });
            
            // Translate from Stripe response to domain terms
            return {
                success: stripeCharge.status === 'succeeded',
                chargeId: new ChargeId(stripeCharge.id),
                authorizationCode: stripeCharge.authorization_code,
            };
            
        } catch (error) {
            return this.handleStripeError(error);
        }
    }
    
    async refund(chargeId: ChargeId, amount?: Money): Promise<RefundResult> {
        // Similar translation logic
    }
    
    async getCharge(chargeId: ChargeId): Promise<ChargeInfo> {
        // Similar translation logic
    }
    
    // Private translation methods
    private toStripeAmount(money: Money): number {
        // Convert Money to Stripe's cents-based integer
        return Math.round(money.amount * 100);
    }
    
    private toStripeSource(method: PaymentMethodDetails): Stripe.SourceCreateParams {
        // Convert domain payment method to Stripe source
    }
    
    private handleStripeError(error: unknown): ChargeResult {
        // Translate Stripe errors to domain errors
    }
}
 
// ===========================================
// USAGE
// ===========================================
 
// Domain service uses domain interface
class PaymentService {
    constructor(private paymentGateway: PaymentGateway) {}
    
    async processPayment(order: Order): Promise<PaymentOutcome> {
        // Speaks in domain terms only
        const result = await this.paymentGateway.charge(
            order.total,
            order.paymentMethod,
        );
        
        if (!result.success) {
            throw new PaymentFailedException(result.error);
        }
        
        return PaymentOutcome.successful(result.chargeId);
    }
}
 
// Composition root wires everything together
const stripeClient = new Stripe(config.stripeKey);
const paymentGateway = new StripePaymentGatewayAdapter(stripeClient);
const paymentService = new PaymentService(paymentGateway);

The Adapter's Responsibilities:

Protocol Translation — Convert between domain types and external types
Error Translation — Map external exceptions to domain exceptions
Semantic Adaptation — Bridge conceptual differences between systems
Isolation — Shield the domain from SDK/library changes

Benefits of the Adapter Approach:

Adapter Benefits

•Domain purity — Domain code never sees third-party types
•Swappability — Switch payment providers by writing new adapter
•Testability — Domain tests mock the interface, not the SDK
•SDK updates — Changes isolated to adapter class
•Multi-provider — Can have multiple adapters for same interface
•Resilience wrappers — Adapter can add retry, circuit breaker, etc.

The Anti-Corruption Layer

In Domain-Driven Design, this adapter layer is called the Anti-Corruption Layer (ACL). It 'protects' your domain from being 'corrupted' by external concepts. The ACL ensures that external systems don't dictate your domain's terminology, structure, or behavior.

Summary: The Ownership Principle

Interface ownership is not a detail—it is the mechanism that determines whether dependency inversion actually works. Let's consolidate the key insights:

Key Takeaways

•Consumer-owned interfaces — Interfaces should belong to the module that uses them, not the module that implements them.
•Provider-owned interfaces are an anti-pattern — They preserve the wrong dependency direction while adding complexity.
•Design interfaces for consumers — Focus on what consumers need, not what implementations can provide.
•Dependencies should flow toward abstractions — Both high and low-level modules depend on the interface; low-level implements it.
•Package structure should reflect ownership — Place interfaces with their consuming module (ports folder pattern).
•Use adapters for third-party integrations — Create consumer-owned interfaces and adapt external libraries to them.
•Be cautious with shared abstractions — Over-sharing creates coupling; duplicate when consumers have different needs.

The Simple Test:

To check if you've done interface ownership correctly, ask:

"If we delete the implementation module entirely, can the consumer module still compile?"

If yes, you have correct ownership—the consumer owns its interface and has no dependency on the implementation. If no, the interface is still owned by the provider, and you haven't truly inverted the dependency.

What's Next:

Now that we understand how to define and own interfaces correctly, we'll explore where they should appear in a system. The next page examines Abstractions at Boundaries—the principle that interfaces should mark the seams between architectural layers and components, creating explicit contracts at every point where components interact.

Page Complete

You now understand why interface ownership matters and how to implement it correctly. You've learned that consumer-owned abstractions are the key to true dependency inversion, while provider-owned abstractions merely add indirection without decoupling. Next, we'll explore where these abstractions should appear in your system architecture.

2 / 4

Loading learning content...

System Design (HLD)Depending on Abstractions

Depending on Abstractions

LevelIntermediate

Duration75 mins

TopicDepending on Abstractions

2 / 4

Ownership of Abstractions

The Most Important Question in DIP

But we glossed over a question that turns out to be the most important question in dependency inversion: Who defines and owns the interface?

Get interface ownership wrong, and you'll have all the complexity of abstraction with none of the benefits. Get it right, and you unlock the full power of the Dependency Inversion Principle.

What You Will Master

The Ownership Problem

When we introduce an interface between two components, we create three entities:

The Consumer — The component that uses the interface
The Interface — The abstraction defining the contract
The Implementation — The component that provides the service

The implementation clearly belongs logically with its provider—a StripePaymentProcessor implementation belongs in the Stripe integration module. But where does the interface belong?

There are two possible answers:

Option A: Interface lives with the implementation (provider-owned)

[High-Level Module] → [Low-Level Module: Interface + Implementation]

Option B: Interface lives with the consumer (consumer-owned)

[High-Level Module: Interface] ← [Low-Level Module: Implementation]

The choice between these options has profound implications that we need to explore in depth.

The Naive Approach That Feels Right But Is Wrong:

Developers often intuitively place interfaces with their implementations. This feels natural because:

The implementation team understands the capabilities being abstracted
The interface and implementation can be versioned together
IDE refactoring tools extract interfaces to the same package

But this intuition leads to a critical failure mode. Let's trace through why.

The Ownership Trap

Provider-Owned Abstractions: The Anti-Pattern

Let's examine what happens when interfaces are owned by the provider (the low-level module that implements them).

Scenario: Email Service

You're building an order processing system that needs to send confirmation emails. You decide to depend on an interface rather than a concrete email service. The email team provides this:

provider_owned_problem.ts
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
// ❌ PROBLEMATIC: Interface owned by email module (low-level)
 
// ===========================================
// email-service module (low-level provider)
// ===========================================
// File: email-service/EmailService.ts
export interface EmailService {
    sendEmail(
        to: string[],
        cc: string[],
        bcc: string[],
        subject: string,
        htmlBody: string,
        plainTextBody: string,
        attachments: EmailAttachment[],
        headers: EmailHeaders,
        priority: EmailPriority,
        trackingPixel: boolean,
        openTracking: boolean,
        clickTracking: boolean,
    ): Promise<SendResult>;
    
    getEmailStatus(messageId: string): Promise<EmailStatus>;
    getDeliveryReport(messageId: string): Promise<DeliveryReport>;
    getBounces(since: Date): Promise<BounceReport[]>;
    getComplaints(since: Date): Promise<ComplaintReport[]>;
}
 
// File: email-service/GmailEmailService.ts
export class GmailEmailService implements EmailService {
    // Gmail-specific implementation
}
 
// ===========================================
// order-processing module (high-level consumer)  
// ===========================================
// File: order-processing/OrderProcessor.ts
import { EmailService, SendResult } from 'email-service';  // ← Dependency!
 
class OrderProcessor {
    constructor(private emailService: EmailService) {}
    
    async processOrder(order: Order): Promise<void> {
        // ... order processing logic ...
        
        // Send confirmation - forced to use email-centric API
        await this.emailService.sendEmail(
            [order.customer.email],
            [],          // cc - don't need
            [],          // bcc - don't need
            'Order Confirmation',
            this.buildHtmlEmail(order),
            this.buildTextEmail(order),
            [],          // attachments - don't need
            {},          // headers - don't need
            'normal',    // priority - don't care
            false,       // tracking - don't care
            false,       // open tracking - don't care
            false,       // click tracking - don't care
        );
    }
}

Why This Is Broken:

At first glance, this looks like dependency inversion—we're depending on an interface, not a concrete class. But examine the reality:

1. The import statement reveals the truth:

import { EmailService } from 'email-service'

2. The interface is designed for the provider, not the consumer:

3. The consumer cannot use a non-email alternative:

What if you want to send order confirmations via SMS or push notification? The interface assumes email as the transport. You'd need to create a fake "email" wrapper around SMS—a clear design smell.

4. Changes to email-service cascade to consumers:

When the email team adds a new parameter (say, scheduling options), all consumers must update their calls, even if they don't use the feature.

Provider-Owned Interface Problems

•Dependency direction unchanged — High-level still depends on low-level module
•Provider-centric design — Interface reflects implementation capabilities, not consumer needs
•Fat interface — Includes operations irrelevant to many consumers
•Technology lock-in — Interface assumes specific technology (email vs. other transports)
•Change propagation — Provider changes force consumer updates
•Testing complexity — Must mock email-specific concepts even when testing order logic

The Hidden Dependency

Consumer-Owned Abstractions: The Correct Pattern

Now let's see how consumer-owned abstractions properly implement the Dependency Inversion Principle.

Scenario: The Same Order Processing System

Instead of using the email service's interface, the order processing module defines its own interface representing what it needs:

consumer_owned_correct.ts
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
// ✅ CORRECT: Interface owned by order-processing module (high-level)
 
// ===========================================
// order-processing module (high-level consumer)
// ===========================================
// File: order-processing/ports/OrderNotifier.ts
// This interface is OWNED by order-processing, not email-service
 
export interface OrderNotifier {
    /**
     * Sends an order confirmation to the customer.
     * The implementation decides HOW (email, SMS, push, etc.)
     */
    sendOrderConfirmation(order: Order): Promise<NotificationResult>;
    
    /**
     * Notifies the customer that their order has shipped.
     */
    sendShippingNotification(order: Order, tracking: TrackingInfo): Promise<NotificationResult>;
    
    /**
     * Notifies the customer of order cancellation.
     */
    sendCancellationNotification(order: Order, reason: string): Promise<NotificationResult>;
}
 
// File: order-processing/OrderProcessor.ts
// NO import from email-service! Interface is local.
 
class OrderProcessor {
    constructor(private orderNotifier: OrderNotifier) {}
    
    async processOrder(order: Order): Promise<void> {
        // ... order processing logic ...
        
        // Clean, high-level call focused on WHAT, not HOW
        await this.orderNotifier.sendOrderConfirmation(order);
    }
}
 
// ===========================================
// email-adapter module (low-level, implements the interface)
// ===========================================
// File: email-adapter/EmailOrderNotifier.ts
import { OrderNotifier, Order, TrackingInfo, NotificationResult } from 'order-processing';
import { GmailClient } from 'gmail-sdk';
 
export class EmailOrderNotifier implements OrderNotifier {
    constructor(private gmailClient: GmailClient) {}
    
    async sendOrderConfirmation(order: Order): Promise<NotificationResult> {
        // This adapter handles all the email-specific details
        const html = this.buildConfirmationHtml(order);
        const text = this.buildConfirmationText(order);
        
        const result = await this.gmailClient.send({
            to: order.customer.email,
            subject: `Order Confirmation #${order.id}`,
            html,
            text,
            // All email-specific options handled here, 
            // invisible to the order-processing module
        });
        
        return { success: result.sent, messageId: result.id };
    }
    
    // ... other notification methods
}
 
// ===========================================
// sms-adapter module (alternative implementation)
// ===========================================
// File: sms-adapter/SmsOrderNotifier.ts
import { OrderNotifier } from 'order-processing';
import { TwilioClient } from 'twilio-sdk';
 
export class SmsOrderNotifier implements OrderNotifier {
    constructor(private twilioClient: TwilioClient) {}
    
    async sendOrderConfirmation(order: Order): Promise<NotificationResult> {
        const message = `Order #${order.id} confirmed! Total: ${order.total}`;
        await this.twilioClient.sendSms(order.customer.phone, message);
        return { success: true };
    }
    
    // ... other notification methods
}

Why This Works:

1. The dependency direction is truly inverted:

[order-processing: OrderProcessor + OrderNotifier interface]
                          ↑
           [email-adapter: EmailOrderNotifier]

The low-level module (email-adapter) now depends on the high-level module (order-processing) to get the interface. The arrow has flipped!

2. The interface is designed for the consumer:

3. Implementations are freely substitutable:

Email, SMS, push notification, Slack—any transport that can implement OrderNotifier works. The consumer doesn't know or care.

4. Changes to implementations don't affect consumers:

The email service can add scheduling, analytics, or any other feature. The adapter handles them; OrderProcessor is unaffected.

5. The consumer is independently testable:

consumer_testing.ts
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
// Testing is trivial because the interface is focused and consumer-owned
 
class MockOrderNotifier implements OrderNotifier {
    public confirmationsSent: Order[] = [];
    
    async sendOrderConfirmation(order: Order): Promise<NotificationResult> {
        this.confirmationsSent.push(order);
        return { success: true };
    }
    
    // ... other methods
}
 
describe('OrderProcessor', () => {
    it('sends confirmation after successful order', async () => {
        const mockNotifier = new MockOrderNotifier();
        const processor = new OrderProcessor(mockNotifier);
        
        await processor.processOrder(testOrder);
        
        expect(mockNotifier.confirmationsSent).toContainEqual(testOrder);
    });
});
 
// No email-specific mocking needed. The test is focused on order logic.

Consumer-Owned Interface Benefits

•True dependency inversion — Low-level depends on high-level's abstraction
•Consumer-centric design — Interface represents consumer's needs, not provider's capabilities
•Focused interface — Only operations the consumer actually uses
•Technology agnostic — Interface doesn't assume any particular implementation
•Isolation from changes — Provider changes stay in adapter, don't cascade
•Simple testing — Mock the focused interface, test in isolation

The Ownership Rule

The Hexagonal Architecture Perspective

The Hexagonal Model:

Imagine your application as a hexagon. At the center is your domain logic—the business rules and policies that define your application's purpose. This is the high-level module.

Around the edge of the hexagon are ports—interfaces that define how the outside world interacts with your application. There are two types:

Driving Ports (Primary) — Used by external actors to interact with the application (e.g., OrderService interface called by HTTP handlers)
Driven Ports (Secondary) — Used by the application to interact with external systems (e.g., OrderRepository, PaymentGateway, NotificationSender)

Outside the hexagon are adapters—implementations that connect ports to actual infrastructure (databases, APIs, message queues, etc.).

hexagonal_structure.ts
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
// Hexagonal Architecture in practice
 
// ===========================================
// CORE DOMAIN (center of the hexagon)
// ===========================================
 
// Driven Ports - owned by the domain, implemented by infrastructure
// These are the interfaces we've been discussing
 
interface OrderRepository {                    // Driven Port
    save(order: Order): Promise<Order>;
    findById(id: OrderId): Promise<Order | null>;
}
 
interface PaymentGateway {                     // Driven Port
    charge(amount: Money, method: PaymentMethod): Promise<ChargeResult>;
}
 
interface InventoryService {                   // Driven Port
    reserve(items: OrderItem[]): Promise<Reservation>;
    release(reservationId: string): Promise<void>;
}
 
// Domain Service - uses ports, contains business logic
class OrderProcessor {
    constructor(
        private orderRepo: OrderRepository,    // Uses driven port
        private paymentGateway: PaymentGateway,
        private inventoryService: InventoryService,
    ) {}
    
    async createOrder(request: CreateOrderRequest): Promise<Order> {
        // Pure business logic - no infrastructure details
        const reservation = await this.inventoryService.reserve(request.items);
        const payment = await this.paymentGateway.charge(request.total, request.paymentMethod);
        const order = Order.create(request, reservation.id, payment.chargeId);
        return this.orderRepo.save(order);
    }
}
 
// Driving Port - how external actors interact with the domain
interface OrderApplicationService {            // Driving Port
    createOrder(command: CreateOrderCommand): Promise<OrderResult>;
    cancelOrder(command: CancelOrderCommand): Promise<CancellationResult>;
}
 
// ===========================================
// ADAPTERS (outside the hexagon)
// ===========================================
 
// Driven Adapters - implement driven ports
class PostgresOrderRepository implements OrderRepository {
    // SQL-specific implementation
}
 
class StripePaymentGateway implements PaymentGateway {
    // Stripe-specific implementation
}
 
class HttpInventoryService implements InventoryService {
    // HTTP client to inventory microservice
}
 
// Driving Adapters - use driving ports
class HttpOrderController {
    constructor(private orderService: OrderApplicationService) {}
    
    // HTTP-specific handling, delegates to domain
    async handleCreateOrder(req: HttpRequest): Promise<HttpResponse> {
        const command = this.parseRequest(req);
        const result = await this.orderService.createOrder(command);
        return this.buildResponse(result);
    }
}

The Key Insight:

Adapters live outside the domain and depend on the domain's ports. This means:

The domain can be tested without any real infrastructure
Adapters can be swapped without domain changes
New adapters can be added without modifying existing code
The domain's design is driven by business needs, not by infrastructure constraints

The Dependency Rule:

Ports and Ownership

Package and Module Structure

Understanding interface ownership is one thing; implementing it correctly in your codebase structure is another. Let's examine how to organize packages and modules to reinforce correct ownership.

The Wrong Structure (Provider-Owned):

wrong_structure.txt

# ❌ PROBLEMATIC: Interface lives with implementation
 
project/
├── email-service/
│   ├── EmailService.ts         # Interface defined here
│   ├── GmailEmailService.ts    # Implementation
│   └── index.ts                # Exports both
│
├── order-processing/
│   ├── OrderProcessor.ts       # Imports from email-service
│   └── index.ts
│
└── package.json
    # order-processing depends on email-service (wrong direction)

The Correct Structure (Consumer-Owned):

correct_structure.txt
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
# ✅ CORRECT: Interface lives with consumer
 
project/
├── order-processing/
│   ├── domain/
│   │   ├── Order.ts            # Domain entities
│   │   └── OrderProcessor.ts   # Uses port
│   │
│   ├── ports/
│   │   ├── OrderNotifier.ts    # Interface - OWNED by order-processing
│   │   └── OrderRepository.ts  # Interface - OWNED by order-processing
│   │
│   └── index.ts
│
├── email-adapter/
│   ├── EmailOrderNotifier.ts   # Implements OrderNotifier from order-processing
│   └── index.ts                # Imports from order-processing (correct direction)
│
├── postgres-adapter/
│   ├── PostgresOrderRepository.ts  # Implements OrderRepository
│   └── index.ts                    # Imports from order-processing
│
└── package.json
    # email-adapter and postgres-adapter depend on order-processing
    # order-processing has NO dependencies on adapters

Common Folder Organization Patterns:

Ports Folder Pattern

•Create ports/ directory in domain module
•All driven interfaces live here
•Clearly signals "these are our abstractions"
•Easy to identify all external dependencies

Adapters Folder Pattern

•Create adapters/ directory for implementations
•Organize by technology (postgres, redis, stripe)
•Each adapter module imports from domain
•Clearly signals "infrastructure integration"

comprehensive_structure.txt
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
# Comprehensive project structure with correct ownership
 
project/
├── src/
│   ├── domain/                     # Core business logic
│   │   ├── entities/
│   │   │   ├── Order.ts
│   │   │   ├── Customer.ts
│   │   │   └── Product.ts
│   │   │
│   │   ├── services/
│   │   │   ├── OrderProcessor.ts
│   │   │   └── PricingCalculator.ts
│   │   │
│   │   └── ports/                  # Consumer-owned interfaces
│   │       ├── repositories/
│   │       │   ├── OrderRepository.ts
│   │       │   └── ProductRepository.ts
│   │       │
│   │       ├── gateways/
│   │       │   ├── PaymentGateway.ts
│   │       │   └── ShippingGateway.ts
│   │       │
│   │       └── notifiers/
│   │           └── OrderNotifier.ts
│   │
│   ├── adapters/                   # Infrastructure implementations
│   │   ├── persistence/
│   │   │   ├── postgres/
│   │   │   │   ├── PostgresOrderRepository.ts
│   │   │   │   └── PostgresProductRepository.ts
│   │   │   └── redis/
│   │   │       └── RedisCacheRepository.ts
│   │   │
│   │   ├── payment/
│   │   │   ├── StripePaymentGateway.ts
│   │   │   └── PayPalPaymentGateway.ts
│   │   │
│   │   └── notification/
│   │       ├── EmailOrderNotifier.ts
│   │       └── SmsOrderNotifier.ts
│   │
│   └── api/                        # Entry points (driving adapters)
│       ├── http/
│       │   └── OrderController.ts
│       └── graphql/
│           └── OrderResolver.ts
│
└── tests/
    ├── unit/
    │   └── domain/                 # Unit tests use mock implementations
    │       └── OrderProcessor.test.ts
    │
    └── integration/
        └── adapters/               # Integration tests use real implementations
            └── PostgresOrderRepository.test.ts

Module Dependency Validation

Shared Abstractions: When Multiple Consumers Need the Same Interface

A natural question arises: What happens when multiple high-level modules need the same abstraction? Do we duplicate interfaces?

The Shared Kernel Pattern:

When multiple domain modules need the same abstraction, you have several options:

Option 1: Duplicate Focused Interfaces

If different consumers have different needs, they should define their own interfaces even if there's overlap. This maintains consumer-centric design.

duplicate_interfaces.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// Order module needs specific notification capability
// File: order-processing/ports/OrderNotifier.ts
interface OrderNotifier {
    notifyOrderConfirmation(order: Order): Promise<void>;
    notifyOrderShipped(order: Order, tracking: TrackingInfo): Promise<void>;
}
 
// Marketing module has different needs
// File: marketing/ports/CampaignNotifier.ts
interface CampaignNotifier {
    sendPromotion(campaign: Campaign, customers: Customer[]): Promise<BatchResult>;
    sendNewsletter(newsletter: Newsletter, subscribers: Subscriber[]): Promise<BatchResult>;
}
 
// Both might be implemented by the same EmailService underneath,
// but each consumer has its own tailored interface

Option 2: Extract to Shared Kernel

When multiple modules genuinely need the exact same abstraction (same methods, same semantics), extract the interface to a shared module that both depend on. This shared module should be:

Extremely stable (rarely changes)
Carefully designed (approved by all consumers)
Focused on truly shared concepts

shared_kernel.ts
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
// Shared abstractions for genuinely common concepts
// File: shared-kernel/ports/AuditLogger.ts
 
/**
 * Shared interface for audit logging.
 * Used by multiple modules that need consistent audit trails.
 * Changes to this interface require coordination across all consumers.
 */
export interface AuditLogger {
    logAction(
        actor: ActorId,
        action: AuditAction,
        resource: ResourceId,
        details: AuditDetails,
    ): Promise<void>;
    
    getAuditTrail(
        resource: ResourceId,
        filter: AuditFilter,
    ): Promise<AuditEntry[]>;
}
 
// Multiple modules depend on shared-kernel
// order-processing/
//   └── AuditService using AuditLogger
// inventory/
//   └── StockAuditor using AuditLogger  
// payment/
//   └── TransactionAuditor using AuditLogger

Guidelines for Shared Abstractions:

When to Share vs. When to Duplicate

•Share when: The abstraction represents a universal concept (logging, caching, metrics) with identical semantics across consumers
•Duplicate when: Consumers have subtly different needs that would pollute a shared interface
•Share when: The interface is stable and unlikely to change based on any single consumer's needs
•Duplicate when: You anticipate divergent requirements over time
•Share when: Consumers agree on the abstraction's design and will coordinate on changes
•Duplicate when: Consumers are owned by different teams with different priorities

The Shared Abstraction Trap

The Adapter Pattern for Interface Ownership

The answer is the Adapter Pattern—a wrapper that translates between your interface and the external one.

The Problem:

You're using a payment service SDK that exposes StripeClient. Your domain shouldn't depend on Stripe's interface directly (that would be provider-owned).

The Solution:

adapter_pattern.ts
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
// ===========================================
// DOMAIN - defines what it needs
// ===========================================
 
// Your domain's interface - consumer-owned
interface PaymentGateway {
    charge(amount: Money, method: PaymentMethodDetails): Promise<ChargeResult>;
    refund(chargeId: ChargeId, amount?: Money): Promise<RefundResult>;
    getCharge(chargeId: ChargeId): Promise<ChargeInfo>;
}
 
// Domain entities - in your terms
interface ChargeResult {
    success: boolean;
    chargeId: ChargeId;
    authorizationCode?: string;
    error?: PaymentError;
}
 
// ===========================================
// ADAPTER - translates between interfaces
// ===========================================
 
import Stripe from 'stripe';  // Third-party SDK
 
class StripePaymentGatewayAdapter implements PaymentGateway {
    constructor(private stripeClient: Stripe) {}
    
    async charge(amount: Money, method: PaymentMethodDetails): Promise<ChargeResult> {
        try {
            // Translate from domain terms to Stripe terms
            const stripeCharge = await this.stripeClient.charges.create({
                amount: this.toStripeAmount(amount),
                currency: amount.currency.toLowerCase(),
                source: this.toStripeSource(method),
                description: method.description,
            });
            
            // Translate from Stripe response to domain terms
            return {
                success: stripeCharge.status === 'succeeded',
                chargeId: new ChargeId(stripeCharge.id),
                authorizationCode: stripeCharge.authorization_code,
            };
            
        } catch (error) {
            return this.handleStripeError(error);
        }
    }
    
    async refund(chargeId: ChargeId, amount?: Money): Promise<RefundResult> {
        // Similar translation logic
    }
    
    async getCharge(chargeId: ChargeId): Promise<ChargeInfo> {
        // Similar translation logic
    }
    
    // Private translation methods
    private toStripeAmount(money: Money): number {
        // Convert Money to Stripe's cents-based integer
        return Math.round(money.amount * 100);
    }
    
    private toStripeSource(method: PaymentMethodDetails): Stripe.SourceCreateParams {
        // Convert domain payment method to Stripe source
    }
    
    private handleStripeError(error: unknown): ChargeResult {
        // Translate Stripe errors to domain errors
    }
}
 
// ===========================================
// USAGE
// ===========================================
 
// Domain service uses domain interface
class PaymentService {
    constructor(private paymentGateway: PaymentGateway) {}
    
    async processPayment(order: Order): Promise<PaymentOutcome> {
        // Speaks in domain terms only
        const result = await this.paymentGateway.charge(
            order.total,
            order.paymentMethod,
        );
        
        if (!result.success) {
            throw new PaymentFailedException(result.error);
        }
        
        return PaymentOutcome.successful(result.chargeId);
    }
}
 
// Composition root wires everything together
const stripeClient = new Stripe(config.stripeKey);
const paymentGateway = new StripePaymentGatewayAdapter(stripeClient);
const paymentService = new PaymentService(paymentGateway);

The Adapter's Responsibilities:

Protocol Translation — Convert between domain types and external types
Error Translation — Map external exceptions to domain exceptions
Semantic Adaptation — Bridge conceptual differences between systems
Isolation — Shield the domain from SDK/library changes

Benefits of the Adapter Approach:

Adapter Benefits

•Domain purity — Domain code never sees third-party types
•Swappability — Switch payment providers by writing new adapter
•Testability — Domain tests mock the interface, not the SDK
•SDK updates — Changes isolated to adapter class
•Multi-provider — Can have multiple adapters for same interface
•Resilience wrappers — Adapter can add retry, circuit breaker, etc.

The Anti-Corruption Layer

Summary: The Ownership Principle

Interface ownership is not a detail—it is the mechanism that determines whether dependency inversion actually works. Let's consolidate the key insights:

Key Takeaways

•Consumer-owned interfaces — Interfaces should belong to the module that uses them, not the module that implements them.
•Provider-owned interfaces are an anti-pattern — They preserve the wrong dependency direction while adding complexity.
•Design interfaces for consumers — Focus on what consumers need, not what implementations can provide.
•Dependencies should flow toward abstractions — Both high and low-level modules depend on the interface; low-level implements it.
•Package structure should reflect ownership — Place interfaces with their consuming module (ports folder pattern).
•Use adapters for third-party integrations — Create consumer-owned interfaces and adapt external libraries to them.
•Be cautious with shared abstractions — Over-sharing creates coupling; duplicate when consumers have different needs.

The Simple Test:

To check if you've done interface ownership correctly, ask:

"If we delete the implementation module entirely, can the consumer module still compile?"

What's Next:

Page Complete

2 / 4