System Design (HLD)Depending on Abstractions

Depending on Abstractions

LevelIntermediate

Duration75 mins

TopicDepending on Abstractions

4 / 4

Stable Abstractions Principle

The Paradox of Change and Stability

Software systems must simultaneously embrace two contradictory forces: change and stability.

Systems must change because requirements evolve, technology advances, and business needs shift. Yet systems must also be stable—we can't rebuild everything from scratch with each new requirement. We need foundations we can rely upon, contracts that hold, and behaviors that remain predictable.

How do we reconcile these opposing forces? The answer lies in carefully separating what should be stable from what can change freely. This separation is formalized in the Stable Abstractions Principle (SAP): Abstractions should be stable; implementations should be volatile.

This principle is the keystone of the Dependency Inversion Principle. It explains why we depend on abstractions and how to design them so that depending on them is safe.

What You Will Master

By the end of this page, you will understand how stability and abstraction are related, how to measure and design for stability, and why the most abstract components should be the most stable. You'll learn practical techniques for creating stable interfaces and managing inevitable change when it does occur.

Understanding Stability in Software

Before we can discuss stable abstractions, we need a precise definition of stability in software engineering.

Stability ≠ Unchangeable:

Stability does not mean the component never changes. It means the component is hard to change—not because it's frozen, but because many other components depend on it. Changing a stable component has widespread consequences, so we change it carefully and infrequently.

Stability ≠ Quality:

A stable component isn't necessarily better than a volatile one. Both have their roles. Stable components provide the foundation; volatile components implement the specifics. The goal is to put the right components in each category.

Robert Martin's Stability Definition:

In his work on package design principles, Robert C. Martin provided a quantitative definition:

Stability = the difficulty of changing a component.

Difficulty increases when:

Many other components depend on this one (incoming dependencies)
Few components are depended upon (outgoing dependencies)

A component with many dependents and few dependencies is highly stable—changing it affects many others, but external changes don't affect it.

stability_metrics.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
// Measuring Stability: The Instability Metric
 
// For a package/module/component P:
//   Ca = Afferent Couplings (incoming: number of classes outside P that depend on classes inside P)
//   Ce = Efferent Couplings (outgoing: number of classes inside P that depend on classes outside P)
//   I = Instability = Ce / (Ca + Ce)
//   Range: 0 (maximally stable) to 1 (maximally unstable)
 
// Example 1: Domain Core
// ─────────────────────
// Many modules depend on our domain entities
// Domain entities depend on little else
 
// OrderEntity depends on: Money, OrderId, OrderStatus (all internal)
// External modules depend on OrderEntity: OrderRepository, OrderService, 
//   OrderController, ShippingService, BillingService
// Ca = 5, Ce = 0, I = 0 / (5 + 0) = 0.0 → Maximally Stable
 
// Example 2: Stripe Adapter
// ─────────────────────────
// Nothing depends on our Stripe adapter (could swap it)
// Stripe adapter depends on: PaymentGateway interface, Stripe SDK, domain types
 
// No external module depends on StripeAdapter
// StripeAdapter depends on: PaymentGateway, Order, Money, Stripe SDK
// Ca = 0, Ce = 4, I = 4 / (0 + 4) = 1.0 → Maximally Unstable
 
// This is exactly right:
// - Stable components (domain) are depended upon, don't depend outward
// - Unstable components (adapters) depend on stable ones, nothing depends on them
// - Changing adapters is safe; changing domain requires careful consideration

Stable Components

•Many incoming dependencies
•Few outgoing dependencies
•Hard to change (high impact)
•Examples: core interfaces, domain entities, shared abstractions
•Should contain abstract types

Unstable Components

•Few incoming dependencies
•Many outgoing dependencies
•Easy to change (low impact)
•Examples: adapters, UI handlers, tool integrations
•Should contain concrete types

Stability Is Structural, Not Intentional

Stability emerges from dependency structure, not from labels or intentions. A component becomes stable when many things depend on it—regardless of whether you planned it that way. This is why dependency management is critical: uncontrolled dependencies make the wrong things stable.

The Zones: Designing for the Right Stability

Robert Martin introduced two diagnostic zones for understanding component design based on stability and abstractness:

Abstractness (A):

The ratio of abstract types to total types in a component.

A = 0: All concrete classes, no abstractions
A = 1: All interfaces/abstract classes

The I-A Graph:

  1.0 ┌─────────────────────────────────────────┐
      │ Zone of Uselessness               (1,1) │
      │   \                                     │
A     │    \                                    │
b     │     \  Main Sequence                    │
s     │      \    (the ideal line)              │
t  0.5├───────\────────────────────────────────┤
r     │        \                                │
a     │         \                               │
c     │          \                              │
t     │           \                             │
      │            \                            │
  0.0 │ (0,0)       \              Zone of Pain │
      └─────────────────────────────────────────┘
           0.0              0.5              1.0
                      Instability (I)

The Zone of Pain (Bottom Left: Low A, Low I):

Components that are:

Highly stable (hard to change)
Highly concrete (no abstractions)

This is painful because concrete components are rigid—they specify how things work. When such components are also highly stable (many things depend on them), changes are both necessary (concrete details need updating) and difficult (many dependents break).

Examples of Zone of Pain residents:

Database schema classes that are directly used everywhere
Utility classes with many concrete methods and many callers
Configuration classes that concrete code depends on directly

The Zone of Uselessness (Top Right: High A, High I):

Components that are:

Highly abstract (all interfaces)
Highly unstable (nothing depends on them)

Abstractions only have value when things depend on them. An interface that nothing uses is dead code—a useless abstraction that adds complexity without benefit.

Examples of Zone of Uselessness:

"Designed for extensibility" interfaces with no implementations
Speculative abstractions for requirements that never came
Abstract base classes that only have one subclass ever

The Main Sequence: The Ideal Balance

•The line from (0,0) to (1,1) — Represents the ideal balance between stability and abstractness
•Stable components should be abstract — If many things depend on you, be an interface so they don't depend on details
•Unstable components should be concrete — If nothing depends on you, you can safely be a concrete implementation
•Distance from the main sequence — Measures design quality; components far from the line are problematic

The Stable Dependencies Principle

The companion principle to SAP is the Stable Dependencies Principle (SDP): 'Depend in the direction of stability.' Combine SAP and SDP, and you get: 'Depend on stable abstractions.' This is Dependency Inversion stated in terms of package design.

Designing Interfaces for Stability

Since stable components should be abstract, and since interfaces will be depended upon by many things, interface design requires special care. A poorly designed interface that becomes stable is a permanent liability.

Principles for Stable Interface Design:

1. Design for the Consumer:

Stable interfaces should reflect what consumers need, not what implementations provide. Consumer needs tend to be more stable than implementation details.

2. Minimize the Surface Area:

Every method in an interface is a commitment. Stable interfaces should be minimal—include only what consumers actually need, nothing speculative.

3. Use Primitive and Abstract Types:

Interface parameters and return types should be primitives, value objects, or other abstractions—not concrete types that might change.

stable_interface_design.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
// ❌ UNSTABLE: Leaks implementation details and concrete types
 
interface UserRepository {
    // Exposes ORM-specific concepts
    findWithEagerLoading(id: string, relations: string[]): Promise<User>;
    
    // Exposes SQL concepts
    findByRawQuery(sql: string, params: any[]): Promise<User[]>;
    
    // Exposes internal database structure
    findByJoinedTables(
        userFilter: UserTableFilter,
        profileFilter: ProfileTableFilter,
        orderBy: ColumnReference
    ): Promise<UserWithProfile[]>;
    
    // Uses concrete types
    saveWithTransaction(user: User, txn: PostgresTransaction): Promise<void>;
}
 
// ✅ STABLE: Abstract, consumer-focused, technology-agnostic
 
interface UserRepository {
    // Operations defined in domain terms
    save(user: User): Promise<void>;
    findById(id: UserId): Promise<User | null>;
    findByEmail(email: EmailAddress): Promise<User | null>;
    findActive(): Promise<User[]>;
    
    // Uses domain types, not database types
    exists(id: UserId): Promise<boolean>;
    delete(id: UserId): Promise<void>;
}
 
// ❌ UNSTABLE: Too many methods, implementation-driven
 
interface NotificationService {
    sendEmail(to: string, subject: string, body: string, html: string): Promise<void>;
    sendEmailWithAttachments(to: string, subject: string, body: string, attachments: File[]): Promise<void>;
    sendSms(phone: string, message: string): Promise<void>;
    sendPush(deviceToken: string, title: string, body: string, data: object): Promise<void>;
    sendSlack(channel: string, message: string, blocks: SlackBlock[]): Promise<void>;
    scheduleEmail(to: string, subject: string, body: string, sendAt: Date): Promise<void>;
    // ... 20 more methods for each delivery channel variation
}
 
// ✅ STABLE: Minimal, polymorphic, consumer-focused
 
interface NotificationSender {
    send(notification: Notification, recipient: Recipient): Promise<DeliveryResult>;
}
 
// Variations handled by types, not method proliferation
type Notification = 
    | OrderConfirmationNotification
    | ShippingUpdateNotification
    | PasswordResetNotification;
 
type Recipient = 
    | EmailRecipient
    | SmsRecipient
    | PushRecipient;

4. Prefer Immutable Data Structures:

Data that crosses stable interfaces should be immutable. Mutable data creates hidden contracts about who can modify it and when.

5. Define Clear Semantics:

Stable interfaces need clear documentation of their contract—not just method signatures, but preconditions, postconditions, error conditions, and behavioral expectations.

6. Anticipate Extension, Not Specifics:

Design interfaces so new behaviors can be added without changing the interface. Use patterns like:

Command objects instead of parameter lists
Strategy injection instead of conditional logic
Event interfaces instead of callback method proliferation

extensible_design.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
// ❌ HARD TO EXTEND: Adding features means adding parameters
 
interface PaymentProcessor {
    processPayment(
        amount: Money,
        cardNumber: string,
        expiry: string,
        cvv: string,
        billingAddress: Address,
        // Oops, need 3D Secure now:
        threeDSecureData?: ThreeDSecureData,
        // Oops, need fraud check:
        fraudCheckOptions?: FraudCheckOptions,
        // Oops, need custom metadata:
        metadata?: Record<string, string>,
        // ... interface bloat continues
    ): Promise<PaymentResult>;
}
 
// ✅ EXTENSIBLE: New features don't change the interface
 
interface PaymentProcessor {
    processPayment(request: PaymentRequest): Promise<PaymentResult>;
}
 
// Request object can evolve without interface change
interface PaymentRequest {
    amount: Money;
    method: PaymentMethod;
    // Add new optional properties without breaking consumers
    threeDSecure?: ThreeDSecureData;
    fraudCheck?: FraudCheckOptions;
    metadata?: Metadata;
}
 
// Even better: use a builder for complex requests
const request = PaymentRequest.builder()
    .amount(Money.of(100, 'USD'))
    .card(card)
    .withThreeDSecure(threeDSecureData)
    .withFraudCheck(FraudCheckLevel.High)
    .build();

The Open-Closed Principle Connection

Stable interfaces naturally support the Open-Closed Principle. Open for extension: new implementations can be added. Closed for modification: the interface itself doesn't change. This connection isn't coincidental—both principles work together to create flexible, stable architectures.

Managing Interface Evolution

Despite our best efforts, interfaces sometimes need to change. Managing these changes without breaking dependent code is a critical skill.

Types of Interface Changes:

Interface Change Classification
Change Type	Example	Breaking?	Strategy
Add method	addNewOperation()	No*	Default implementations or new interface
Add optional parameter	find(id, options?)	No	Default value preserves behavior
Widen return type	User → User \| null	Usually no	Consumers handle broader type
Add required parameter	find(id, tenant)	Yes	New method or version
Remove method	deleteOperation()	Yes	Deprecate first, new interface
Narrow return type	User \| null → User	Yes	New method or version
Change parameter type	string → UserId	Yes	Deprecate + new method
Change semantics	Same signature, different behavior	Yes (subtle)	New method with clear name

Strategy 1: Interface Versioning

Create new interface versions for breaking changes:

interface_versioning.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
// Original interface
interface PaymentGateway {
    charge(amount: Money, card: CardDetails): Promise<ChargeResult>;
}
 
// Breaking change needed: add 3D Secure requirement
// Don't modify! Create a new version:
 
interface PaymentGatewayV2 extends PaymentGateway {
    chargeWithVerification(
        amount: Money,
        card: CardDetails,
        verification: VerificationResult
    ): Promise<ChargeResult>;
}
 
// Or, if completely redesigned:
interface PaymentGatewayV2 {
    processPayment(request: PaymentRequest): Promise<PaymentResult>;
    
    // Backward compatibility helper
    static fromV1(v1: PaymentGateway): PaymentGatewayV2 {
        return new PaymentGatewayV2Adapter(v1);
    }
}
 
// Migration path:
// 1. Introduce V2 interface
// 2. Migrate consumers gradually
// 3. Deprecate V1
// 4. Remove V1 after migration complete

Strategy 2: Extension Interfaces

Add new capabilities through additional interfaces rather than modifying existing ones:

extension_interfaces.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
// Original interface - stable, unchanged
interface OrderRepository {
    save(order: Order): Promise<void>;
    findById(id: OrderId): Promise<Order | null>;
    findByCustomer(customerId: CustomerId): Promise<Order[]>;
}
 
// New capability needed: batch operations
// Don't add to OrderRepository! Create extension interface:
 
interface BatchOrderRepository extends OrderRepository {
    saveBatch(orders: Order[]): Promise<void>;
    findByIds(ids: OrderId[]): Promise<Map<OrderId, Order>>;
}
 
// Consumers that need batch ops depend on BatchOrderRepository
// Consumers that don't need batch ops continue with OrderRepository
// No changes to existing code
 
// Implementation provides both:
class PostgresOrderRepository implements BatchOrderRepository {
    // Implements all methods
}
 
// Service chooses what it needs:
class OrderMigrationService {
    constructor(private repo: BatchOrderRepository) {}  // Needs batch
}
 
class OrderDetailsService {
    constructor(private repo: OrderRepository) {}  // Only needs basic
}

Strategy 3: The Adapter Pattern for Compatibility

When you must support both old and new interfaces:

compatibility_adapter.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
// Old interface that consumers depend on
interface LegacyPaymentService {
    pay(amount: number, cardToken: string): Promise<boolean>;
}
 
// New interface with richer model
interface PaymentService {
    processPayment(request: PaymentRequest): Promise<PaymentResult>;
}
 
// Adapter allows gradual migration
class LegacyPaymentServiceAdapter implements LegacyPaymentService {
    constructor(private newService: PaymentService) {}
    
    async pay(amount: number, cardToken: string): Promise<boolean> {
        const request = PaymentRequest.create({
            amount: Money.fromCents(amount, 'USD'),
            method: PaymentMethod.fromToken(cardToken),
        });
        
        const result = await this.newService.processPayment(request);
        
        // Translate rich result to simple boolean
        return result.status === PaymentStatus.Success;
    }
}
 
// Old consumers continue working:
const legacyService: LegacyPaymentService = new LegacyPaymentServiceAdapter(newPaymentService);
const success = await legacyService.pay(1000, 'tok_123');
 
// New consumers use rich interface:
const result = await paymentService.processPayment(request);

Semantic Versioning for Interfaces

When interfaces are published (especially in libraries or APIs), follow semantic versioning: MAJOR for breaking changes, MINOR for backward-compatible additions, PATCH for fixes. This communicates to consumers the risk level of upgrading.

Stable Abstractions in Practice

Let's see how stable abstractions work in a realistic system design.

Case Study: E-Commerce Platform

We're building an e-commerce platform with these requirements:

Multiple payment providers (Stripe, PayPal, Apple Pay)
Multiple shipping carriers (UPS, FedEx, USPS)
Multiple notification channels (email, SMS, push)
Analytics integration (could change providers)

The Stability Structure:

stability_architecture.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
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
// ============================================
// STABLE CORE: Domain entities and interfaces
// I ≈ 0.1, A ≈ 0.8 (stable and abstract)
// ============================================
 
// domain/entities/Order.ts - Stable, many dependents
class Order {
    private constructor(
        readonly id: OrderId,
        readonly customerId: CustomerId,
        readonly items: readonly OrderItem[],
        private _status: OrderStatus,
        readonly shippingAddress: Address,
    ) {}
    
    static create(customerId: CustomerId, items: OrderItem[], address: Address): Order {
        // Business rules here
    }
    
    get total(): Money {
        return this.items.reduce((sum, item) => sum.add(item.subtotal), Money.zero());
    }
    
    submit(): void {
        if (this.items.length === 0) {
            throw new EmptyOrderError();
        }
        this._status = OrderStatus.Submitted;
    }
    
    // Rich domain model with business logic
}
 
// domain/ports/PaymentGateway.ts - Stable abstraction
interface PaymentGateway {
    authorize(amount: Money, method: PaymentMethod): Promise<Authorization>;
    capture(authorization: Authorization): Promise<PaymentResult>;
    refund(paymentId: PaymentId, amount?: Money): Promise<RefundResult>;
}
 
// domain/ports/ShippingService.ts - Stable abstraction
interface ShippingService {
    calculateRates(items: OrderItem[], destination: Address): Promise<ShippingRate[]>;
    createShipment(order: Order, rate: ShippingRate): Promise<Shipment>;
    trackShipment(shipmentId: ShipmentId): Promise<TrackingInfo>;
}
 
// domain/ports/NotificationSender.ts - Stable abstraction
interface NotificationSender {
    send(notification: Notification): Promise<SendResult>;
}
 
// domain/services/OrderProcessor.ts - Stable service
class OrderProcessor {
    constructor(
        private paymentGateway: PaymentGateway,
        private shippingService: ShippingService,
        private notificationSender: NotificationSender,
        private orderRepository: OrderRepository,
    ) {}
    
    async processOrder(order: Order, payment: PaymentMethod): Promise<ProcessedOrder> {
        // Orchestrates the order fulfillment
        // Uses stable interfaces, unaware of concrete providers
    }
}
 
// ============================================
// UNSTABLE EDGE: Adapters and integrations
// I ≈ 0.9, A ≈ 0.1 (unstable and concrete)
// ============================================
 
// adapters/payment/StripeGateway.ts - Unstable, can change
class StripePaymentGateway implements PaymentGateway {
    constructor(private stripe: Stripe) {}
    
    async authorize(amount: Money, method: PaymentMethod): Promise<Authorization> {
        // Stripe-specific implementation
        const paymentIntent = await this.stripe.paymentIntents.create({
            amount: amount.toCents(),
            currency: amount.currency,
            payment_method: method.stripeId,
            capture_method: 'manual',
        });
        return new Authorization(paymentIntent.id, paymentIntent.client_secret);
    }
    
    // Can change Stripe SDK versions, API patterns, error handling
    // without affecting domain
}
 
// adapters/payment/PayPalGateway.ts - Another unstable adapter
class PayPalPaymentGateway implements PaymentGateway {
    constructor(private paypal: PayPalClient) {}
    
    async authorize(amount: Money, method: PaymentMethod): Promise<Authorization> {
        // PayPal-specific implementation
    }
}
 
// adapters/shipping/FedExService.ts - Unstable
class FedExShippingService implements ShippingService {
    constructor(private fedex: FedExAPI) {}
    
    async calculateRates(items: OrderItem[], dest: Address): Promise<ShippingRate[]> {
        // FedEx-specific rate calculation
    }
}
 
// adapters/notification/SendGridNotifier.ts - Unstable
class SendGridNotificationSender implements NotificationSender {
    constructor(private sendGrid: SendGridClient) {}
    
    async send(notification: Notification): Promise<SendResult> {
        // SendGrid-specific email sending
    }
}

The Dependencies in This Design:

Stable (low I, high A)              Unstable (high I, low A)
┌─────────────────────────┐         ┌─────────────────────────┐
│   Domain Core           │         │   Adapters              │
│   ─────────────────     │         │   ────────              │
│   Order                 │ ◄────── │   StripeGateway         │
│   PaymentGateway        │         │   PayPalGateway         │
│   ShippingService       │ ◄────── │   FedExService          │
│   NotificationSender    │         │   SendGridNotifier      │
│   OrderProcessor        │         │                         │
└─────────────────────────┘         └─────────────────────────┘
          │
          │ All dependencies point
          │ toward stable core
          ▼

Benefits of This Structure:

Adapters can be replaced freely — Switch from Stripe to Braintree by writing one new adapter
Core is protected — Stripe API changes don't touch OrderProcessor
Testing is straightforward — Mock the stable interfaces, test domain in isolation
Parallel development — Payment team works on adapters; domain team works on business logic
Technology evolution — Can adopt new SDKs, protocols, or providers without domain changes

The Composition Root

The Composition Root is where stable and unstable components meet—where concrete adapters are wired to abstract interfaces. This is typically in your application startup code or dependency injection configuration. It's the only place that knows about all the concrete types.

Common Stability Anti-Patterns

Understanding anti-patterns helps recognize violations of the stable abstractions principle in your own code.

Anti-Pattern 1: The Concrete Hub

A concrete class that many other components depend on, placing it in the Zone of Pain.

concrete_hub_antipattern.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
// ❌ ANTI-PATTERN: Concrete class with many dependents
 
class DatabaseConnection {
    private pool: pg.Pool;
    
    constructor(config: DbConfig) {
        this.pool = new pg.Pool(config);
    }
    
    query(sql: string, params: any[]): Promise<QueryResult> {
        return this.pool.query(sql, params);
    }
    
    transaction<T>(work: (client: PoolClient) => Promise<T>): Promise<T> {
        // Transaction handling
    }
}
 
// Many classes depend on this concrete type
class OrderRepository {
    constructor(private db: DatabaseConnection) {}  // Concrete dependency
}
 
class CustomerRepository {
    constructor(private db: DatabaseConnection) {}  // Concrete dependency
}
 
class ProductRepository {
    constructor(private db: DatabaseConnection) {}  // Concrete dependency
}
 
// DatabaseConnection is now highly stable (many dependents)
// But it's concrete (PostgreSQL-specific)
// Result: Changing database is extremely painful
 
// ✅ FIX: Abstract the database connection
 
interface DatabaseClient {
    query<T>(sql: string, params?: unknown[]): Promise<T[]>;
    execute(sql: string, params?: unknown[]): Promise<void>;
    transaction<T>(work: (client: TransactionClient) => Promise<T>): Promise<T>;
}
 
class PostgresClient implements DatabaseClient {
    // PostgreSQL-specific implementation
}
 
class MySqlClient implements DatabaseClient {
    // MySQL-specific implementation
}
 
// Now repositories depend on the abstraction

Anti-Pattern 2: The Utility Class Trap

Utility classes that accumulate dependencies become accidentally stable concrete types.

utility_trap.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
// ❌ ANTI-PATTERN: Growing utility class
 
// Starts innocent
class StringUtils {
    static capitalize(s: string): string { /* ... */ }
    static truncate(s: string, len: number): string { /* ... */ }
}
 
// Grows over time, accumulates dependencies everywhere
class StringUtils {
    static capitalize(s: string): string { /* ... */ }
    static truncate(s: string, len: number): string { /* ... */ }
    static toSlug(s: string): string { /* ... */ }
    static parseTemplate(template: string, vars: object): string { /* ... */ }
    static sanitizeHtml(s: string): string { /* ... */ }
    static extractUrls(s: string): string[] { /* ... */ }
    // 50 more methods...
}
 
// Half the codebase now depends on StringUtils
// It's concrete, stable, and IN THE ZONE OF PAIN
// Any change risks breaking unknown callers
 
// ✅ FIX: Separate by concerns and abstract where needed
 
// Pure functions for simple transforms - okay as static
const stringTransforms = {
    capitalize: (s: string) => /* ... */,
    truncate: (s: string, len: number) => /* ... */,
};
 
// Things with complex logic or external concerns become services
interface HtmlSanitizer {
    sanitize(html: string): string;
}
 
interface TemplateRenderer {
    render(template: string, variables: Record<string, unknown>): string;
}
 
// Now dependencies are targeted and replaceable

Anti-Pattern 3: The Speculative Abstraction

Interfaces created "for flexibility" that have only one implementation and no dependents.

speculative_abstraction.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
// ❌ ANTI-PATTERN: Abstraction nobody uses
 
interface IUserValidator {
    validate(user: User): ValidationResult;
}
 
class UserValidator implements IUserValidator {
    validate(user: User): ValidationResult {
        // Only implementation, ever
    }
}
 
// The interface adds nothing:
// - Only one implementation exists
// - No other implementations are planned
// - Interface just mirrors the class
// - In the Zone of Uselessness
 
// ✅ FIX: Don't abstract prematurely
 
class UserValidator {
    validate(user: User): ValidationResult {
        // Just use the class directly
    }
}
 
// Later, IF you need multiple validation strategies:
interface ValidationStrategy {
    validate(user: User): ValidationResult;
}
 
class StrictUserValidator implements ValidationStrategy { /* ... */ }
class LenientUserValidator implements ValidationStrategy { /* ... */ }
 
// Now the abstraction serves a purpose

YAGNI for Abstractions

Apply YAGNI (You Aren't Gonna Need It) to abstractions too. Create interfaces when you have a concrete need: multiple implementations, testing requirements, or clear boundary definition. Don't create them 'just in case.' Unnecessary abstractions are worse than missing ones—they obscure the code without providing benefit.

Measuring and Monitoring Stability

How do you know if your system has proper stability structure? Measurement and monitoring help identify problems before they become painful.

Metrics to Track:

1. Instability (I) per Package:

For each package/module, calculate:

I = Ce / (Ca + Ce)
Ca = incoming dependencies (other packages that depend on this one)
Ce = outgoing dependencies (packages this one depends on)

Expected values:

Domain/core packages: I ≈ 0.0-0.3
Application services: I ≈ 0.3-0.5
Adapters/infrastructure: I ≈ 0.7-1.0

2. Abstractness (A) per Package:

A = number of abstract types / total types

Expected values:

Domain interfaces: A ≈ 0.7-1.0
Concrete implementations: A ≈ 0.0-0.3

stability_analysis.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
// Example stability analysis output
 
interface PackageMetrics {
    name: string;
    abstractness: number;      // A: 0.0 to 1.0
    instability: number;       // I: 0.0 to 1.0
    distanceFromMain: number;  // D = |A + I - 1|
    dependsOn: string[];
    dependedOnBy: string[];
}
 
const analysisResult: PackageMetrics[] = [
    {
        name: 'domain/entities',
        abstractness: 0.1,      // Mostly concrete domain objects
        instability: 0.08,     // Few outgoing deps, many incoming
        distanceFromMain: 0.02, // ✓ Near main sequence (expected for low-A stable)
        dependsOn: ['domain/value-objects'],
        dependedOnBy: ['domain/services', 'adapters/postgres', 'api/http'],
    },
    {
        name: 'domain/ports',
        abstractness: 1.0,      // All interfaces
        instability: 0.0,      // No outgoing deps, many incoming
        distanceFromMain: 0.0, // ✓ Perfect on main sequence
        dependsOn: [],
        dependedOnBy: ['domain/services', 'adapters/stripe', 'adapters/sendgrid'],
    },
    {
        name: 'adapters/stripe',
        abstractness: 0.0,      // All concrete
        instability: 1.0,      // Many outgoing, no incoming
        distanceFromMain: 0.0, // ✓ Perfect on main sequence
        dependsOn: ['domain/ports', 'stripe-sdk'],
        dependedOnBy: [],
    },
    {
        name: 'shared/utilities',
        abstractness: 0.0,      // All concrete
        instability: 0.2,      // Many incoming, few outgoing
        distanceFromMain: 0.8, // ⚠️ Zone of Pain!
        dependsOn: ['logging'],
        dependedOnBy: ['domain/services', 'adapters/stripe', 'api/http', '...'],
    },
];
 
// Flag the problematic package
for (const pkg of analysisResult) {
    if (pkg.distanceFromMain > 0.5) {
        console.warn(`⚠️ ${pkg.name} is ${pkg.abstractness < 0.5 ? 'in Zone of Pain' : 'in Zone of Uselessness'}`);
    }
}

Tools for Stability Analysis:

Analysis Tools by Language

•TypeScript/JavaScript: dependency-cruiser, madge, nx affected analysis
•Java: JDepend, Structure101, ArchUnit
•C#: NDepend, Visual Studio dependency diagrams
•.NET: CppDepend, NDepend
•Python: pydeps, import-linter
•Generic: SonarQube (limited), custom scripts using AST analysis

Continuous Monitoring:

Integrate stability checks into your CI/CD pipeline:

Fail builds when forbidden dependencies are introduced
Track trends in stability metrics over time
Alert on Zone of Pain entries before they become entrenched
Require architecture review for changes that increase D significantly

Architecture Fitness Functions

Create automated 'fitness functions' that verify architectural rules. Example: 'No package with I < 0.3 should have A < 0.5' (stable packages must be abstract). These tests catch violations early, before wrong abstractions become load-bearing.

Summary: Building on Stable Foundations

The Stable Abstractions Principle completes our understanding of why and how to depend on abstractions. By ensuring that stable components are abstract and volatile components are concrete, we create systems that can evolve gracefully. Let's consolidate the key insights:

Key Takeaways

•Stability = difficulty of change — Measured by incoming dependencies; high stability means many dependents.
•The Main Sequence — Stable components should be abstract; unstable components should be concrete.
•Zone of Pain — Avoid stable concrete components; they're hard to change but full of details that need changing.
•Zone of Uselessness — Avoid unstable abstractions; interfaces nobody uses are complexity without benefit.
•Design for stability — Stable interfaces need minimal surface area, clear contracts, and extensible designs.
•Manage evolution carefully — Use versioning, extension interfaces, and adapters to evolve without breaking.
•Measure and monitor — Use tools to track stability metrics and catch architectural drift early.
•The composition root — Is the only place that knows about concrete implementations; everything else depends on abstractions.

The Complete Picture:

With this page, we've completed our exploration of Depending on Abstractions:

Interfaces as Abstraction — Understanding what abstractions are and how they work
Ownership of Abstractions — Where interfaces should live and why it matters
Abstractions at Boundaries — Recognizing where abstractions belong in system architecture
Stable Abstractions Principle — Ensuring abstractions are designed for long-term stability

Together, these concepts form the foundation of the Dependency Inversion Principle. When you depend on stable, consumer-owned abstractions at appropriate boundaries, you create systems that are testable, maintainable, and able to evolve with changing requirements.

Moving Forward:

In the next module, we'll explore Dependency Injection Fundamentals—the practical mechanism for providing implementations to components that depend on abstractions. Understanding DI transforms these principles from theory into daily practice.

Module Complete

You've mastered the art of depending on abstractions—from understanding what they are, to owning them correctly, to placing them at boundaries, to designing them for stability. These skills are foundational to building large-scale, maintainable software systems. Next, we'll explore how dependency injection makes these abstractions practical.

4 / 4

Loading learning content...

System Design (HLD)Depending on Abstractions

Depending on Abstractions

LevelIntermediate

Duration75 mins

TopicDepending on Abstractions

4 / 4

Stable Abstractions Principle

The Paradox of Change and Stability

Software systems must simultaneously embrace two contradictory forces: change and stability.

This principle is the keystone of the Dependency Inversion Principle. It explains why we depend on abstractions and how to design them so that depending on them is safe.

What You Will Master

Understanding Stability in Software

Before we can discuss stable abstractions, we need a precise definition of stability in software engineering.

Stability ≠ Unchangeable:

Stability ≠ Quality:

Robert Martin's Stability Definition:

In his work on package design principles, Robert C. Martin provided a quantitative definition:

Stability = the difficulty of changing a component.

Difficulty increases when:

Many other components depend on this one (incoming dependencies)
Few components are depended upon (outgoing dependencies)

A component with many dependents and few dependencies is highly stable—changing it affects many others, but external changes don't affect it.

stability_metrics.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
// Measuring Stability: The Instability Metric
 
// For a package/module/component P:
//   Ca = Afferent Couplings (incoming: number of classes outside P that depend on classes inside P)
//   Ce = Efferent Couplings (outgoing: number of classes inside P that depend on classes outside P)
//   I = Instability = Ce / (Ca + Ce)
//   Range: 0 (maximally stable) to 1 (maximally unstable)
 
// Example 1: Domain Core
// ─────────────────────
// Many modules depend on our domain entities
// Domain entities depend on little else
 
// OrderEntity depends on: Money, OrderId, OrderStatus (all internal)
// External modules depend on OrderEntity: OrderRepository, OrderService, 
//   OrderController, ShippingService, BillingService
// Ca = 5, Ce = 0, I = 0 / (5 + 0) = 0.0 → Maximally Stable
 
// Example 2: Stripe Adapter
// ─────────────────────────
// Nothing depends on our Stripe adapter (could swap it)
// Stripe adapter depends on: PaymentGateway interface, Stripe SDK, domain types
 
// No external module depends on StripeAdapter
// StripeAdapter depends on: PaymentGateway, Order, Money, Stripe SDK
// Ca = 0, Ce = 4, I = 4 / (0 + 4) = 1.0 → Maximally Unstable
 
// This is exactly right:
// - Stable components (domain) are depended upon, don't depend outward
// - Unstable components (adapters) depend on stable ones, nothing depends on them
// - Changing adapters is safe; changing domain requires careful consideration

Stable Components

•Many incoming dependencies
•Few outgoing dependencies
•Hard to change (high impact)
•Examples: core interfaces, domain entities, shared abstractions
•Should contain abstract types

Unstable Components

•Few incoming dependencies
•Many outgoing dependencies
•Easy to change (low impact)
•Examples: adapters, UI handlers, tool integrations
•Should contain concrete types

Stability Is Structural, Not Intentional

The Zones: Designing for the Right Stability

Robert Martin introduced two diagnostic zones for understanding component design based on stability and abstractness:

Abstractness (A):

The ratio of abstract types to total types in a component.

A = 0: All concrete classes, no abstractions
A = 1: All interfaces/abstract classes

The I-A Graph:

  1.0 ┌─────────────────────────────────────────┐
      │ Zone of Uselessness               (1,1) │
      │   \                                     │
A     │    \                                    │
b     │     \  Main Sequence                    │
s     │      \    (the ideal line)              │
t  0.5├───────\────────────────────────────────┤
r     │        \                                │
a     │         \                               │
c     │          \                              │
t     │           \                             │
      │            \                            │
  0.0 │ (0,0)       \              Zone of Pain │
      └─────────────────────────────────────────┘
           0.0              0.5              1.0
                      Instability (I)

The Zone of Pain (Bottom Left: Low A, Low I):

Components that are:

Highly stable (hard to change)
Highly concrete (no abstractions)

Examples of Zone of Pain residents:

Database schema classes that are directly used everywhere
Utility classes with many concrete methods and many callers
Configuration classes that concrete code depends on directly

The Zone of Uselessness (Top Right: High A, High I):

Components that are:

Highly abstract (all interfaces)
Highly unstable (nothing depends on them)

Abstractions only have value when things depend on them. An interface that nothing uses is dead code—a useless abstraction that adds complexity without benefit.

Examples of Zone of Uselessness:

"Designed for extensibility" interfaces with no implementations
Speculative abstractions for requirements that never came
Abstract base classes that only have one subclass ever

The Main Sequence: The Ideal Balance

•The line from (0,0) to (1,1) — Represents the ideal balance between stability and abstractness
•Stable components should be abstract — If many things depend on you, be an interface so they don't depend on details
•Unstable components should be concrete — If nothing depends on you, you can safely be a concrete implementation
•Distance from the main sequence — Measures design quality; components far from the line are problematic

The Stable Dependencies Principle

Designing Interfaces for Stability

Principles for Stable Interface Design:

1. Design for the Consumer:

Stable interfaces should reflect what consumers need, not what implementations provide. Consumer needs tend to be more stable than implementation details.

2. Minimize the Surface Area:

Every method in an interface is a commitment. Stable interfaces should be minimal—include only what consumers actually need, nothing speculative.

3. Use Primitive and Abstract Types:

Interface parameters and return types should be primitives, value objects, or other abstractions—not concrete types that might change.

stable_interface_design.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
// ❌ UNSTABLE: Leaks implementation details and concrete types
 
interface UserRepository {
    // Exposes ORM-specific concepts
    findWithEagerLoading(id: string, relations: string[]): Promise<User>;
    
    // Exposes SQL concepts
    findByRawQuery(sql: string, params: any[]): Promise<User[]>;
    
    // Exposes internal database structure
    findByJoinedTables(
        userFilter: UserTableFilter,
        profileFilter: ProfileTableFilter,
        orderBy: ColumnReference
    ): Promise<UserWithProfile[]>;
    
    // Uses concrete types
    saveWithTransaction(user: User, txn: PostgresTransaction): Promise<void>;
}
 
// ✅ STABLE: Abstract, consumer-focused, technology-agnostic
 
interface UserRepository {
    // Operations defined in domain terms
    save(user: User): Promise<void>;
    findById(id: UserId): Promise<User | null>;
    findByEmail(email: EmailAddress): Promise<User | null>;
    findActive(): Promise<User[]>;
    
    // Uses domain types, not database types
    exists(id: UserId): Promise<boolean>;
    delete(id: UserId): Promise<void>;
}
 
// ❌ UNSTABLE: Too many methods, implementation-driven
 
interface NotificationService {
    sendEmail(to: string, subject: string, body: string, html: string): Promise<void>;
    sendEmailWithAttachments(to: string, subject: string, body: string, attachments: File[]): Promise<void>;
    sendSms(phone: string, message: string): Promise<void>;
    sendPush(deviceToken: string, title: string, body: string, data: object): Promise<void>;
    sendSlack(channel: string, message: string, blocks: SlackBlock[]): Promise<void>;
    scheduleEmail(to: string, subject: string, body: string, sendAt: Date): Promise<void>;
    // ... 20 more methods for each delivery channel variation
}
 
// ✅ STABLE: Minimal, polymorphic, consumer-focused
 
interface NotificationSender {
    send(notification: Notification, recipient: Recipient): Promise<DeliveryResult>;
}
 
// Variations handled by types, not method proliferation
type Notification = 
    | OrderConfirmationNotification
    | ShippingUpdateNotification
    | PasswordResetNotification;
 
type Recipient = 
    | EmailRecipient
    | SmsRecipient
    | PushRecipient;

4. Prefer Immutable Data Structures:

Data that crosses stable interfaces should be immutable. Mutable data creates hidden contracts about who can modify it and when.

5. Define Clear Semantics:

Stable interfaces need clear documentation of their contract—not just method signatures, but preconditions, postconditions, error conditions, and behavioral expectations.

6. Anticipate Extension, Not Specifics:

Design interfaces so new behaviors can be added without changing the interface. Use patterns like:

Command objects instead of parameter lists
Strategy injection instead of conditional logic
Event interfaces instead of callback method proliferation

extensible_design.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
// ❌ HARD TO EXTEND: Adding features means adding parameters
 
interface PaymentProcessor {
    processPayment(
        amount: Money,
        cardNumber: string,
        expiry: string,
        cvv: string,
        billingAddress: Address,
        // Oops, need 3D Secure now:
        threeDSecureData?: ThreeDSecureData,
        // Oops, need fraud check:
        fraudCheckOptions?: FraudCheckOptions,
        // Oops, need custom metadata:
        metadata?: Record<string, string>,
        // ... interface bloat continues
    ): Promise<PaymentResult>;
}
 
// ✅ EXTENSIBLE: New features don't change the interface
 
interface PaymentProcessor {
    processPayment(request: PaymentRequest): Promise<PaymentResult>;
}
 
// Request object can evolve without interface change
interface PaymentRequest {
    amount: Money;
    method: PaymentMethod;
    // Add new optional properties without breaking consumers
    threeDSecure?: ThreeDSecureData;
    fraudCheck?: FraudCheckOptions;
    metadata?: Metadata;
}
 
// Even better: use a builder for complex requests
const request = PaymentRequest.builder()
    .amount(Money.of(100, 'USD'))
    .card(card)
    .withThreeDSecure(threeDSecureData)
    .withFraudCheck(FraudCheckLevel.High)
    .build();

The Open-Closed Principle Connection

Managing Interface Evolution

Despite our best efforts, interfaces sometimes need to change. Managing these changes without breaking dependent code is a critical skill.

Types of Interface Changes:

Interface Change Classification
Change Type	Example	Breaking?	Strategy
Add method	addNewOperation()	No*	Default implementations or new interface
Add optional parameter	find(id, options?)	No	Default value preserves behavior
Widen return type	User → User \| null	Usually no	Consumers handle broader type
Add required parameter	find(id, tenant)	Yes	New method or version
Remove method	deleteOperation()	Yes	Deprecate first, new interface
Narrow return type	User \| null → User	Yes	New method or version
Change parameter type	string → UserId	Yes	Deprecate + new method
Change semantics	Same signature, different behavior	Yes (subtle)	New method with clear name

Strategy 1: Interface Versioning

Create new interface versions for breaking changes:

interface_versioning.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
// Original interface
interface PaymentGateway {
    charge(amount: Money, card: CardDetails): Promise<ChargeResult>;
}
 
// Breaking change needed: add 3D Secure requirement
// Don't modify! Create a new version:
 
interface PaymentGatewayV2 extends PaymentGateway {
    chargeWithVerification(
        amount: Money,
        card: CardDetails,
        verification: VerificationResult
    ): Promise<ChargeResult>;
}
 
// Or, if completely redesigned:
interface PaymentGatewayV2 {
    processPayment(request: PaymentRequest): Promise<PaymentResult>;
    
    // Backward compatibility helper
    static fromV1(v1: PaymentGateway): PaymentGatewayV2 {
        return new PaymentGatewayV2Adapter(v1);
    }
}
 
// Migration path:
// 1. Introduce V2 interface
// 2. Migrate consumers gradually
// 3. Deprecate V1
// 4. Remove V1 after migration complete

Strategy 2: Extension Interfaces

Add new capabilities through additional interfaces rather than modifying existing ones:

extension_interfaces.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
// Original interface - stable, unchanged
interface OrderRepository {
    save(order: Order): Promise<void>;
    findById(id: OrderId): Promise<Order | null>;
    findByCustomer(customerId: CustomerId): Promise<Order[]>;
}
 
// New capability needed: batch operations
// Don't add to OrderRepository! Create extension interface:
 
interface BatchOrderRepository extends OrderRepository {
    saveBatch(orders: Order[]): Promise<void>;
    findByIds(ids: OrderId[]): Promise<Map<OrderId, Order>>;
}
 
// Consumers that need batch ops depend on BatchOrderRepository
// Consumers that don't need batch ops continue with OrderRepository
// No changes to existing code
 
// Implementation provides both:
class PostgresOrderRepository implements BatchOrderRepository {
    // Implements all methods
}
 
// Service chooses what it needs:
class OrderMigrationService {
    constructor(private repo: BatchOrderRepository) {}  // Needs batch
}
 
class OrderDetailsService {
    constructor(private repo: OrderRepository) {}  // Only needs basic
}

Strategy 3: The Adapter Pattern for Compatibility

When you must support both old and new interfaces:

compatibility_adapter.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
// Old interface that consumers depend on
interface LegacyPaymentService {
    pay(amount: number, cardToken: string): Promise<boolean>;
}
 
// New interface with richer model
interface PaymentService {
    processPayment(request: PaymentRequest): Promise<PaymentResult>;
}
 
// Adapter allows gradual migration
class LegacyPaymentServiceAdapter implements LegacyPaymentService {
    constructor(private newService: PaymentService) {}
    
    async pay(amount: number, cardToken: string): Promise<boolean> {
        const request = PaymentRequest.create({
            amount: Money.fromCents(amount, 'USD'),
            method: PaymentMethod.fromToken(cardToken),
        });
        
        const result = await this.newService.processPayment(request);
        
        // Translate rich result to simple boolean
        return result.status === PaymentStatus.Success;
    }
}
 
// Old consumers continue working:
const legacyService: LegacyPaymentService = new LegacyPaymentServiceAdapter(newPaymentService);
const success = await legacyService.pay(1000, 'tok_123');
 
// New consumers use rich interface:
const result = await paymentService.processPayment(request);

Semantic Versioning for Interfaces

Stable Abstractions in Practice

Let's see how stable abstractions work in a realistic system design.

Case Study: E-Commerce Platform

We're building an e-commerce platform with these requirements:

Multiple payment providers (Stripe, PayPal, Apple Pay)
Multiple shipping carriers (UPS, FedEx, USPS)
Multiple notification channels (email, SMS, push)
Analytics integration (could change providers)

The Stability Structure:

stability_architecture.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
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
// ============================================
// STABLE CORE: Domain entities and interfaces
// I ≈ 0.1, A ≈ 0.8 (stable and abstract)
// ============================================
 
// domain/entities/Order.ts - Stable, many dependents
class Order {
    private constructor(
        readonly id: OrderId,
        readonly customerId: CustomerId,
        readonly items: readonly OrderItem[],
        private _status: OrderStatus,
        readonly shippingAddress: Address,
    ) {}
    
    static create(customerId: CustomerId, items: OrderItem[], address: Address): Order {
        // Business rules here
    }
    
    get total(): Money {
        return this.items.reduce((sum, item) => sum.add(item.subtotal), Money.zero());
    }
    
    submit(): void {
        if (this.items.length === 0) {
            throw new EmptyOrderError();
        }
        this._status = OrderStatus.Submitted;
    }
    
    // Rich domain model with business logic
}
 
// domain/ports/PaymentGateway.ts - Stable abstraction
interface PaymentGateway {
    authorize(amount: Money, method: PaymentMethod): Promise<Authorization>;
    capture(authorization: Authorization): Promise<PaymentResult>;
    refund(paymentId: PaymentId, amount?: Money): Promise<RefundResult>;
}
 
// domain/ports/ShippingService.ts - Stable abstraction
interface ShippingService {
    calculateRates(items: OrderItem[], destination: Address): Promise<ShippingRate[]>;
    createShipment(order: Order, rate: ShippingRate): Promise<Shipment>;
    trackShipment(shipmentId: ShipmentId): Promise<TrackingInfo>;
}
 
// domain/ports/NotificationSender.ts - Stable abstraction
interface NotificationSender {
    send(notification: Notification): Promise<SendResult>;
}
 
// domain/services/OrderProcessor.ts - Stable service
class OrderProcessor {
    constructor(
        private paymentGateway: PaymentGateway,
        private shippingService: ShippingService,
        private notificationSender: NotificationSender,
        private orderRepository: OrderRepository,
    ) {}
    
    async processOrder(order: Order, payment: PaymentMethod): Promise<ProcessedOrder> {
        // Orchestrates the order fulfillment
        // Uses stable interfaces, unaware of concrete providers
    }
}
 
// ============================================
// UNSTABLE EDGE: Adapters and integrations
// I ≈ 0.9, A ≈ 0.1 (unstable and concrete)
// ============================================
 
// adapters/payment/StripeGateway.ts - Unstable, can change
class StripePaymentGateway implements PaymentGateway {
    constructor(private stripe: Stripe) {}
    
    async authorize(amount: Money, method: PaymentMethod): Promise<Authorization> {
        // Stripe-specific implementation
        const paymentIntent = await this.stripe.paymentIntents.create({
            amount: amount.toCents(),
            currency: amount.currency,
            payment_method: method.stripeId,
            capture_method: 'manual',
        });
        return new Authorization(paymentIntent.id, paymentIntent.client_secret);
    }
    
    // Can change Stripe SDK versions, API patterns, error handling
    // without affecting domain
}
 
// adapters/payment/PayPalGateway.ts - Another unstable adapter
class PayPalPaymentGateway implements PaymentGateway {
    constructor(private paypal: PayPalClient) {}
    
    async authorize(amount: Money, method: PaymentMethod): Promise<Authorization> {
        // PayPal-specific implementation
    }
}
 
// adapters/shipping/FedExService.ts - Unstable
class FedExShippingService implements ShippingService {
    constructor(private fedex: FedExAPI) {}
    
    async calculateRates(items: OrderItem[], dest: Address): Promise<ShippingRate[]> {
        // FedEx-specific rate calculation
    }
}
 
// adapters/notification/SendGridNotifier.ts - Unstable
class SendGridNotificationSender implements NotificationSender {
    constructor(private sendGrid: SendGridClient) {}
    
    async send(notification: Notification): Promise<SendResult> {
        // SendGrid-specific email sending
    }
}

The Dependencies in This Design:

Stable (low I, high A)              Unstable (high I, low A)
┌─────────────────────────┐         ┌─────────────────────────┐
│   Domain Core           │         │   Adapters              │
│   ─────────────────     │         │   ────────              │
│   Order                 │ ◄────── │   StripeGateway         │
│   PaymentGateway        │         │   PayPalGateway         │
│   ShippingService       │ ◄────── │   FedExService          │
│   NotificationSender    │         │   SendGridNotifier      │
│   OrderProcessor        │         │                         │
└─────────────────────────┘         └─────────────────────────┘
          │
          │ All dependencies point
          │ toward stable core
          ▼

Benefits of This Structure:

Adapters can be replaced freely — Switch from Stripe to Braintree by writing one new adapter
Core is protected — Stripe API changes don't touch OrderProcessor
Testing is straightforward — Mock the stable interfaces, test domain in isolation
Parallel development — Payment team works on adapters; domain team works on business logic
Technology evolution — Can adopt new SDKs, protocols, or providers without domain changes

The Composition Root

Common Stability Anti-Patterns

Understanding anti-patterns helps recognize violations of the stable abstractions principle in your own code.

Anti-Pattern 1: The Concrete Hub

A concrete class that many other components depend on, placing it in the Zone of Pain.

concrete_hub_antipattern.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
// ❌ ANTI-PATTERN: Concrete class with many dependents
 
class DatabaseConnection {
    private pool: pg.Pool;
    
    constructor(config: DbConfig) {
        this.pool = new pg.Pool(config);
    }
    
    query(sql: string, params: any[]): Promise<QueryResult> {
        return this.pool.query(sql, params);
    }
    
    transaction<T>(work: (client: PoolClient) => Promise<T>): Promise<T> {
        // Transaction handling
    }
}
 
// Many classes depend on this concrete type
class OrderRepository {
    constructor(private db: DatabaseConnection) {}  // Concrete dependency
}
 
class CustomerRepository {
    constructor(private db: DatabaseConnection) {}  // Concrete dependency
}
 
class ProductRepository {
    constructor(private db: DatabaseConnection) {}  // Concrete dependency
}
 
// DatabaseConnection is now highly stable (many dependents)
// But it's concrete (PostgreSQL-specific)
// Result: Changing database is extremely painful
 
// ✅ FIX: Abstract the database connection
 
interface DatabaseClient {
    query<T>(sql: string, params?: unknown[]): Promise<T[]>;
    execute(sql: string, params?: unknown[]): Promise<void>;
    transaction<T>(work: (client: TransactionClient) => Promise<T>): Promise<T>;
}
 
class PostgresClient implements DatabaseClient {
    // PostgreSQL-specific implementation
}
 
class MySqlClient implements DatabaseClient {
    // MySQL-specific implementation
}
 
// Now repositories depend on the abstraction

Anti-Pattern 2: The Utility Class Trap

Utility classes that accumulate dependencies become accidentally stable concrete types.

utility_trap.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
// ❌ ANTI-PATTERN: Growing utility class
 
// Starts innocent
class StringUtils {
    static capitalize(s: string): string { /* ... */ }
    static truncate(s: string, len: number): string { /* ... */ }
}
 
// Grows over time, accumulates dependencies everywhere
class StringUtils {
    static capitalize(s: string): string { /* ... */ }
    static truncate(s: string, len: number): string { /* ... */ }
    static toSlug(s: string): string { /* ... */ }
    static parseTemplate(template: string, vars: object): string { /* ... */ }
    static sanitizeHtml(s: string): string { /* ... */ }
    static extractUrls(s: string): string[] { /* ... */ }
    // 50 more methods...
}
 
// Half the codebase now depends on StringUtils
// It's concrete, stable, and IN THE ZONE OF PAIN
// Any change risks breaking unknown callers
 
// ✅ FIX: Separate by concerns and abstract where needed
 
// Pure functions for simple transforms - okay as static
const stringTransforms = {
    capitalize: (s: string) => /* ... */,
    truncate: (s: string, len: number) => /* ... */,
};
 
// Things with complex logic or external concerns become services
interface HtmlSanitizer {
    sanitize(html: string): string;
}
 
interface TemplateRenderer {
    render(template: string, variables: Record<string, unknown>): string;
}
 
// Now dependencies are targeted and replaceable

Anti-Pattern 3: The Speculative Abstraction

Interfaces created "for flexibility" that have only one implementation and no dependents.

speculative_abstraction.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
// ❌ ANTI-PATTERN: Abstraction nobody uses
 
interface IUserValidator {
    validate(user: User): ValidationResult;
}
 
class UserValidator implements IUserValidator {
    validate(user: User): ValidationResult {
        // Only implementation, ever
    }
}
 
// The interface adds nothing:
// - Only one implementation exists
// - No other implementations are planned
// - Interface just mirrors the class
// - In the Zone of Uselessness
 
// ✅ FIX: Don't abstract prematurely
 
class UserValidator {
    validate(user: User): ValidationResult {
        // Just use the class directly
    }
}
 
// Later, IF you need multiple validation strategies:
interface ValidationStrategy {
    validate(user: User): ValidationResult;
}
 
class StrictUserValidator implements ValidationStrategy { /* ... */ }
class LenientUserValidator implements ValidationStrategy { /* ... */ }
 
// Now the abstraction serves a purpose

YAGNI for Abstractions

Measuring and Monitoring Stability

How do you know if your system has proper stability structure? Measurement and monitoring help identify problems before they become painful.

Metrics to Track:

1. Instability (I) per Package:

For each package/module, calculate:

I = Ce / (Ca + Ce)
Ca = incoming dependencies (other packages that depend on this one)
Ce = outgoing dependencies (packages this one depends on)

Expected values:

Domain/core packages: I ≈ 0.0-0.3
Application services: I ≈ 0.3-0.5
Adapters/infrastructure: I ≈ 0.7-1.0

2. Abstractness (A) per Package:

A = number of abstract types / total types

Expected values:

Domain interfaces: A ≈ 0.7-1.0
Concrete implementations: A ≈ 0.0-0.3

stability_analysis.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
// Example stability analysis output
 
interface PackageMetrics {
    name: string;
    abstractness: number;      // A: 0.0 to 1.0
    instability: number;       // I: 0.0 to 1.0
    distanceFromMain: number;  // D = |A + I - 1|
    dependsOn: string[];
    dependedOnBy: string[];
}
 
const analysisResult: PackageMetrics[] = [
    {
        name: 'domain/entities',
        abstractness: 0.1,      // Mostly concrete domain objects
        instability: 0.08,     // Few outgoing deps, many incoming
        distanceFromMain: 0.02, // ✓ Near main sequence (expected for low-A stable)
        dependsOn: ['domain/value-objects'],
        dependedOnBy: ['domain/services', 'adapters/postgres', 'api/http'],
    },
    {
        name: 'domain/ports',
        abstractness: 1.0,      // All interfaces
        instability: 0.0,      // No outgoing deps, many incoming
        distanceFromMain: 0.0, // ✓ Perfect on main sequence
        dependsOn: [],
        dependedOnBy: ['domain/services', 'adapters/stripe', 'adapters/sendgrid'],
    },
    {
        name: 'adapters/stripe',
        abstractness: 0.0,      // All concrete
        instability: 1.0,      // Many outgoing, no incoming
        distanceFromMain: 0.0, // ✓ Perfect on main sequence
        dependsOn: ['domain/ports', 'stripe-sdk'],
        dependedOnBy: [],
    },
    {
        name: 'shared/utilities',
        abstractness: 0.0,      // All concrete
        instability: 0.2,      // Many incoming, few outgoing
        distanceFromMain: 0.8, // ⚠️ Zone of Pain!
        dependsOn: ['logging'],
        dependedOnBy: ['domain/services', 'adapters/stripe', 'api/http', '...'],
    },
];
 
// Flag the problematic package
for (const pkg of analysisResult) {
    if (pkg.distanceFromMain > 0.5) {
        console.warn(`⚠️ ${pkg.name} is ${pkg.abstractness < 0.5 ? 'in Zone of Pain' : 'in Zone of Uselessness'}`);
    }
}

Tools for Stability Analysis:

Analysis Tools by Language

•TypeScript/JavaScript: dependency-cruiser, madge, nx affected analysis
•Java: JDepend, Structure101, ArchUnit
•C#: NDepend, Visual Studio dependency diagrams
•.NET: CppDepend, NDepend
•Python: pydeps, import-linter
•Generic: SonarQube (limited), custom scripts using AST analysis

Continuous Monitoring:

Integrate stability checks into your CI/CD pipeline:

Fail builds when forbidden dependencies are introduced
Track trends in stability metrics over time
Alert on Zone of Pain entries before they become entrenched
Require architecture review for changes that increase D significantly

Architecture Fitness Functions

Summary: Building on Stable Foundations

Key Takeaways

•Stability = difficulty of change — Measured by incoming dependencies; high stability means many dependents.
•The Main Sequence — Stable components should be abstract; unstable components should be concrete.
•Zone of Pain — Avoid stable concrete components; they're hard to change but full of details that need changing.
•Zone of Uselessness — Avoid unstable abstractions; interfaces nobody uses are complexity without benefit.
•Design for stability — Stable interfaces need minimal surface area, clear contracts, and extensible designs.
•Manage evolution carefully — Use versioning, extension interfaces, and adapters to evolve without breaking.
•Measure and monitor — Use tools to track stability metrics and catch architectural drift early.
•The composition root — Is the only place that knows about concrete implementations; everything else depends on abstractions.

The Complete Picture:

With this page, we've completed our exploration of Depending on Abstractions:

Interfaces as Abstraction — Understanding what abstractions are and how they work
Ownership of Abstractions — Where interfaces should live and why it matters
Abstractions at Boundaries — Recognizing where abstractions belong in system architecture
Stable Abstractions Principle — Ensuring abstractions are designed for long-term stability

Moving Forward:

Module Complete

4 / 4