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

// ABSTRACTION WITHOUT DECOUPLING
// The interface abstracts the implementation, but clients are still coupled
 
interface INotificationService {
    sendEmail(to: string, subject: string, body: EmailBody): Promise<void>;
    sendSMS(to: string, message: string): Promise<void>;
    sendPush(deviceId: string, payload: PushPayload): Promise<void>;
    sendSlack(channel: string, message: SlackMessage): Promise<void>;
    sendWebhook(url: string, payload: WebhookPayload): Promise<void>;
    scheduleSend(notification: Notification, time: Date): Promise<ScheduleId>;
    getDeliveryStatus(notificationId: string): Promise<DeliveryStatus>;
    retryFailedNotifications(): Promise<RetryResult>;
}
 
// The OrderService only sends email confirmations
class OrderService {
    constructor(private notifications: INotificationService) {}
    
    async completeOrder(order: Order): Promise<void> {
        // Only uses one method
        await this.notifications.sendEmail(
            order.customerEmail,
            'Order Confirmation',
            this.buildConfirmationEmail(order)
        );
    }
}
 
// Despite abstraction:
// - If sendSlack() signature changes, OrderService may need recompilation
// - OrderService must import SlackMessage, PushPayload, WebhookPayload types
// - Tests must stub 8 methods even though 7 are never called
// - Cannot deploy OrderService without NotificationService team coordination
 
 
// ABSTRACTION WITH DECOUPLING
// Each interface provides both abstraction AND isolation
 
interface IEmailSender {
    sendEmail(to: string, subject: string, body: EmailBody): Promise<void>;
}
 
interface ISMSSender {
    sendSMS(to: string, message: string): Promise<void>;
}
 
interface IPushNotifier {
    sendPush(deviceId: string, payload: PushPayload): Promise<void>;
}
 
// OrderService only depends on what it uses
class OrderServiceDecoupled {
    constructor(private emailSender: IEmailSender) {}  // Only this one interface!
    
    async completeOrder(order: Order): Promise<void> {
        await this.emailSender.sendEmail(
            order.customerEmail,
            'Order Confirmation',
            this.buildConfirmationEmail(order)
        );
    }
}
 
// Now truly decoupled:
// - SMS, Push, Slack changes don't affect OrderService at all
// - OrderService only imports EmailBody type
// - Tests only stub one 1-method interface
// - OrderService can deploy completely independently

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

// ANALYZING INTERFACE QUALITY FOR DECOUPLING
 
// ❌ POOR: Provider-centric, kitchen-sink interface
interface IDataPersistence {
    // Database operations
    connect(connectionString: string): Promise<Connection>;
    disconnect(): Promise<void>;
    query<T>(sql: string, params: unknown[]): Promise<T[]>;
    execute(sql: string, params: unknown[]): Promise<ExecuteResult>;
    
    // Transaction control
    beginTransaction(): Promise<Transaction>;
    commit(tx: Transaction): Promise<void>;
    rollback(tx: Transaction): Promise<void>;
    
    // Connection pooling
    getPoolStats(): PoolStatistics;
    drainPool(): Promise<void>;
    
    // Migration
    runMigrations(): Promise<MigrationResult>;
    rollbackMigration(version: number): Promise<void>;
    
    // Backup
    createBackup(): Promise<BackupHandle>;
    restoreFromBackup(handle: BackupHandle): Promise<void>;
}
 
// Problems:
// - Purpose: "database stuff" (too vague)
// - Surface area: 14 methods, 10+ types
// - Stability: Migration APIs change often
// - Design: Provider-centric ("here's what our DB can do")
 
 
// ✅ GOOD: Client-centric, minimal decoupling interfaces
 
// For application code that needs to read/write domain objects
interface IEntityRepository<T> {
    findById(id: string): Promise<T | null>;
    findAll(criteria: QueryCriteria<T>): Promise<T[]>;
    save(entity: T): Promise<T>;
    delete(id: string): Promise<boolean>;
}
// Purpose: "Persist and retrieve domain entities" (one sentence, no 'and'-splitting)
// Surface area: 4 methods, 2 types (T and QueryCriteria)
// Stability: CRUD is extremely stable
// Design: Client-centric ("here's what the domain layer needs")
 
 
// For transaction boundaries (separate concern)
interface ITransactionScope {
    execute<T>(work: () => Promise<T>): Promise<T>;
}
// Purpose: "Execute work atomically"
// Surface area: 1 method, 0 additional types
// Stability: Transaction semantics are stable
// Design: Client only cares about atomicity, not how
 
 
// For operations tooling (completely separate audience)
interface IDatabaseAdmin {
    runMigrations(): Promise<MigrationResult>;
    createBackup(): Promise<BackupHandle>;
    restoreFromBackup(handle: BackupHandle): Promise<void>;
}
// Purpose: "Administrative database operations"
// Surface area: 3 methods, clear admin focus
// Stability: Ops tooling, less stable, but isolated
// Design: Ops team's perspective, not app developers

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

// ARCHITECTURAL BOUNDARY EXAMPLE: Order Service → Payment Service
 
// BOUNDARY DEFINITION
// The Order Service needs to process payments but shouldn't know how payments work internally.
// The Payment Service can switch processors, add fraud detection, change retry logic.
// Neither side should be affected by the other's internal changes.
 
// ====== ORDER SERVICE SIDE (Consumer of payment capability) ======
 
// The Order Service defines what it needs (Dependency Inversion!)
interface IPaymentCapability {
    // Express the capability, not the implementation
    chargeForOrder(request: OrderPaymentRequest): Promise<PaymentResult>;
}
 
// Types are owned by the Order Service domain
interface OrderPaymentRequest {
    orderId: string;
    customerId: string;
    amount: MoneyAmount;
    idempotencyKey: string;  // Ensures retry safety
}
 
interface PaymentResult {
    success: boolean;
    transactionId: string;
    failureReason?: PaymentFailureReason;
}
 
type PaymentFailureReason = 
    | 'INSUFFICIENT_FUNDS'
    | 'CARD_DECLINED'
    | 'PROCESSOR_ERROR'
    | 'INVALID_REQUEST';
 
// Order Service only sees domains concepts
class OrderProcessor {
    constructor(private payments: IPaymentCapability) {}
    
    async processOrder(order: Order): Promise<ProcessResult> {
        const paymentResult = await this.payments.chargeForOrder({
            orderId: order.id,
            customerId: order.customerId,
            amount: order.total,
            idempotencyKey: `order-${order.id}`,
        });
        
        if (!paymentResult.success) {
            return { success: false, error: paymentResult.failureReason };
        }
        
        return { success: true, transactionId: paymentResult.transactionId };
    }
}
 
 
// ====== PAYMENT SERVICE SIDE (Provider of payment capability) ======
 
// Internal Payment Service types (these DO NOT cross the boundary)
interface StripeChargeRequest {
    amount: number;
    currency: string;
    customer: string;
    metadata: Record<string, string>;
    idempotency_key: string;
}
 
interface FraudCheckResult {
    riskScore: number;
    recommendation: 'ALLOW' | 'BLOCK' | 'REVIEW';
    signals: FraudSignal[];
}
 
// Adapter that implements the boundary interface
class PaymentCapabilityAdapter implements IPaymentCapability {
    constructor(
        private stripe: StripeClient,
        private fraudService: FraudService,
        private retryPolicy: RetryPolicy,
        private auditLog: AuditLogger,
    ) {}
    
    async chargeForOrder(request: OrderPaymentRequest): Promise<PaymentResult> {
        // All this complexity is HIDDEN from Order Service
        
        // 1. Check fraud
        const fraudCheck = await this.fraudService.assess(request);
        if (fraudCheck.recommendation === 'BLOCK') {
            return { success: false, transactionId: '', failureReason: 'CARD_DECLINED' };
        }
        
        // 2. Translate to Stripe format
        const stripeRequest: StripeChargeRequest = {
            amount: request.amount.cents,
            currency: request.amount.currency,
            customer: await this.lookupStripeCustomer(request.customerId),
            metadata: { orderId: request.orderId },
            idempotency_key: request.idempotencyKey,
        };
        
        // 3. Charge with retry
        const charge = await this.retryPolicy.execute(() =>
            this.stripe.charges.create(stripeRequest)
        );
        
        // 4. Audit
        await this.auditLog.logCharge(request, charge);
        
        return {
            success: charge.status === 'succeeded',
            transactionId: charge.id,
            failureReason: charge.status !== 'succeeded' 
                ? this.mapStripeFailure(charge.failure_code) 
                : undefined,
        };
    }
}
 
// RESULT:
// - Order Service knows nothing about Stripe, fraud detection, retries, auditing
// - Payment Service can switch to different processor without Order Service changes
// - Both sides can deploy independently
// - Testing Order Service only requires a simple IPaymentCapability mock

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

// SCENARIO: Platform with 3 teams
// - Catalog Team: manages product catalog
// - Search Team: provides search capabilities  
// - Storefront Team: builds customer-facing UI
 
// ❌ WITHOUT ISP: Storefront couples to everything
interface IProductService {
    // Catalog operations
    getProduct(id: string): Product;
    listProducts(filter: ProductFilter): Product[];
    
    // Admin operations (used by Catalog Team internally)
    createProduct(data: CreateProductRequest): Product;
    updateProduct(id: string, data: UpdateProductRequest): Product;
    deleteProduct(id: string): void;
    
    // Search operations (implemented by Search Team)
    searchProducts(query: SearchQuery): SearchResults;
    suggestProducts(prefix: string): Suggestion[];
    
    // Inventory (cross-cutting concern)
    getInventory(productId: string): InventoryLevel;
    reserveInventory(productId: string, quantity: number): Reservation;
    
    // Analytics (used by various teams)
    getProductAnalytics(productId: string): ProductAnalytics;
    trackProductView(productId: string, userId: string): void;
}
 
// Storefront only shows products, but:
// - Must wait for Catalog Team's admin API stabilization
// - Must update when Search Team changes query format
// - Must retest when Analytics tracking changes
// - 3 teams must coordinate every release!
 
 
// ✅ WITH ISP: Each team owns their interface contract
 
// Consumer: Storefront | Provider: Catalog Team
interface IProductReader {
    getProduct(id: string): Product;
    listProducts(filter: ProductFilter): Product[];
}
 
// Consumer: Storefront | Provider: Search Team
interface IProductSearch {
    searchProducts(query: SearchQuery): SearchResults;
    suggestProducts(prefix: string): Suggestion[];
}
 
// Consumer: Checkout Service | Provider: Catalog Team
interface IInventoryChecker {
    getInventory(productId: string): InventoryLevel;
    reserveInventory(productId: string, quantity: number): Reservation;
}
 
// Consumer: Internal Tools | Provider: Catalog Team (admin only)
interface IProductAdmin {
    createProduct(data: CreateProductRequest): Product;
    updateProduct(id: string, data: UpdateProductRequest): Product;
    deleteProduct(id: string): void;
}
 
// Consumer: Analytics Dashboard | Provider: Catalog Team
interface IProductAnalytics {
    getProductAnalytics(productId: string): ProductAnalytics;
    trackProductView(productId: string, userId: string): void;
}
 
 
// TEAM AUTONOMY RESULTS:
 
// Storefront Team:
// - Depends on: IProductReader, IProductSearch
// - Can release anytime Catalog and Search contracts are stable
// - Not blocked by Admin or Analytics changes
 
// Catalog Team:
// - Owns: IProductReader, IInventoryChecker, IProductAdmin, IProductAnalytics
// - Can refactor internal product storage freely
// - Admin changes don't affect Storefront
 
// Search Team:
// - Owns: IProductSearch
// - Can experiment with search algorithms
// - Changes to suggestions don't affect listing pages
 
// Each team can:
// - Maintain their own release schedule
// - Refactor internal implementation freely
// - Version their interfaces independently
// - Test against stable interface contracts

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

// PATTERN 1: Interface Inheritance for Capability Extension
 
// Base capability: read-only data access
interface IDataReader<T> {
    findById(id: string): T | null;
    findAll(): T[];
}
 
// Extended capability: read + write
interface IDataWriter<T> extends IDataReader<T> {
    save(entity: T): T;
    delete(id: string): boolean;
}
 
// Even more capability: full admin
interface IDataAdmin<T> extends IDataWriter<T> {
    purgeAll(): number;
    bulkImport(entities: T[]): ImportResult;
}
 
// Clients request only the capability level they need
class ReportGenerator {
    constructor(private data: IDataReader<Report>) {}  // Read-only is sufficient
}
 
class ReportEditor {
    constructor(private data: IDataWriter<Report>) {}  // Needs write access
}
 
class ReportAdminTool {
    constructor(private data: IDataAdmin<Report>) {}   // Needs full control
}
 
 
// PATTERN 2: Facade Aggregation for Convenience
 
// Individual capabilities remain segregated
interface IOrderReader {
    getOrder(id: string): Order;
    getOrderHistory(customerId: string): Order[];
}
 
interface IOrderWriter {
    createOrder(data: CreateOrderData): Order;
    updateOrder(id: string, data: UpdateOrderData): Order;
}
 
interface IOrderStatus {
    getOrderStatus(id: string): OrderStatus;
    updateOrderStatus(id: string, status: OrderStatus): void;
}
 
// Convenience aggregation for a specific use case (Order Management Dashboard)
interface IOrderManagementFullAccess 
    extends IOrderReader, IOrderWriter, IOrderStatus {}
 
// The dashboard explicitly declares its broad needs
class OrderManagementDashboard {
    constructor(private orders: IOrderManagementFullAccess) {}
    // Clear that this component needs everything
}
 
// Other clients can still use minimal interfaces
class OrderTracker {
    constructor(private orders: IOrderReader) {}  // Just reads
}
 
 
// PATTERN 3: Composite Implementation
 
// Single implementation, multiple interfaces
class OrderService 
    implements IOrderReader, IOrderWriter, IOrderStatus {
    
    private orders: Map<string, Order> = new Map();
    
    // IOrderReader implementation
    getOrder(id: string): Order {
        return this.orders.get(id) ?? null;
    }
    
    getOrderHistory(customerId: string): Order[] {
        return [...this.orders.values()]
            .filter(o => o.customerId === customerId);
    }
    
    // IOrderWriter implementation
    createOrder(data: CreateOrderData): Order {
        const order = new Order(data);
        this.orders.set(order.id, order);
        return order;
    }
    
    updateOrder(id: string, data: UpdateOrderData): Order {
        const order = this.getOrder(id);
        Object.assign(order, data);
        return order;
    }
    
    // IOrderStatus implementation
    getOrderStatus(id: string): OrderStatus {
        return this.getOrder(id)?.status ?? 'UNKNOWN';
    }
    
    updateOrderStatus(id: string, status: OrderStatus): void {
        const order = this.getOrder(id);
        if (order) order.status = status;
    }
}
 
// Dependency injection provides the appropriate interface
const readerClient = new OrderTracker(orderService as IOrderReader);
const writerClient = new OrderEditor(orderService as IOrderWriter);
// Both get decoupled views of the same implementation

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

// BEFORE: Legacy fat interface with many clients
 
interface IUserManagerLegacy {
    // Used by ProfilePage
    getUser(id: string): User;
    updateProfile(id: string, data: ProfileData): User;
    
    // Used by AuthController
    validateCredentials(email: string, password: string): AuthResult;
    generateToken(userId: string): Token;
    revokeToken(token: string): void;
    
    // Used by AdminDashboard
    listAllUsers(): User[];
    suspendUser(id: string): void;
    deleteUser(id: string): void;
    
    // Used by ReportingService
    getUserActivity(userId: string): ActivityRecord[];
    getLoginHistory(userId: string): LoginEvent[];
}
 
// All 3 clients import this interface
// Any change affects all 3 clients
 
 
// STEP 2: Analyze actual usage per client
 
// ProfilePage uses: getUser, updateProfile (2 methods)
// AuthController uses: validateCredentials, generateToken, revokeToken (3 methods)
// AdminDashboard uses: listAllUsers, suspendUser, deleteUser (3 methods)
// ReportingService uses: getUserActivity, getLoginHistory (2 methods)
 
// Total: 4 distinct usage patterns, 10 methods in fat interface
 
 
// STEP 3: Extract minimal interfaces for each usage pattern
 
// For ProfilePage
interface IProfileManager {
    getUser(id: string): User;
    updateProfile(id: string, data: ProfileData): User;
}
 
// For AuthController
interface IAuthenticator {
    validateCredentials(email: string, password: string): AuthResult;
    generateToken(userId: string): Token;
    revokeToken(token: string): void;
}
 
// For AdminDashboard
interface IUserAdmin {
    listAllUsers(): User[];
    suspendUser(id: string): void;
    deleteUser(id: string): void;
}
 
// For ReportingService
interface IUserAnalytics {
    getUserActivity(userId: string): ActivityRecord[];
    getLoginHistory(userId: string): LoginEvent[];
}
 
 
// STEP 4: Adapt existing implementation (additive, nothing breaks)
 
class UserManager 
    implements IUserManagerLegacy, IProfileManager, IAuthenticator, IUserAdmin, IUserAnalytics {
    // Existing implementation unchanged
    // Now satisfies all the new interfaces too
    
    getUser(id: string): User { /* existing code */ }
    updateProfile(id: string, data: ProfileData): User { /* existing code */ }
    validateCredentials(email: string, password: string): AuthResult { /* existing code */ }
    // ... all other methods unchanged
}
 
 
// STEP 5: Migrate clients one at a time
 
// Before migration
class ProfilePageBefore {
    constructor(private users: IUserManagerLegacy) {}  // Fat interface
}
 
// After migration (minimal change)
class ProfilePageAfter {
    constructor(private profiles: IProfileManager) {}  // Minimal interface
}
 
// Each migration is an isolated PR:
// - ProfilePage: IUserManagerLegacy → IProfileManager
// - AuthController: IUserManagerLegacy → IAuthenticator
// - AdminDashboard: IUserManagerLegacy → IUserAdmin
// - ReportingService: IUserManagerLegacy → IUserAnalytics
 
 
// STEP 6: After all clients migrated, deprecate legacy
 
/** @deprecated Use IProfileManager, IAuthenticator, IUserAdmin, or IUserAnalytics */
interface IUserManagerLegacy 
    extends IProfileManager, IAuthenticator, IUserAdmin, IUserAnalytics {}
 
// Eventually remove when no code references it

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

// Decoupling Metrics Calculator
 
interface ComponentMetrics {
    name: string;
    afferentCoupling: number;    // How many depend on this
    efferentCoupling: number;    // How many this depends on
    instability: number;          // Ce / (Ca + Ce)
    abstractness: number;         // Abstract types / Total types
    distanceFromMainSequence: number;  // |A + I - 1|
}
 
function analyzeComponent(component: Component): ComponentMetrics {
    const ca = countDependents(component);        // Who depends on me?
    const ce = countDependencies(component);      // What do I depend on?
    const instability = ca + ce === 0 ? 0 : ce / (ca + ce);
    const abstractness = countAbstractTypes(component) / countTotalTypes(component);
    const distance = Math.abs(abstractness + instability - 1);
    
    return {
        name: component.name,
        afferentCoupling: ca,
        efferentCoupling: ce,
        instability,
        abstractness,
        distanceFromMainSequence: distance,
    };
}
 
 
// EXAMPLE ANALYSIS: Before and After ISP
 
// Before: IOrderManagement (fat interface)
const beforeMetrics: ComponentMetrics = {
    name: 'IOrderManagement',
    afferentCoupling: 47,      // 47 clients depend on it
    efferentCoupling: 23,      // Exposes 23 domain types
    instability: 0.33,         // Moderately stable (many dependents)
    abstractness: 1.0,         // Pure interface
    distanceFromMainSequence: 0.33,  // Some distance from ideal
};
 
// After: Segregated interfaces
const afterMetrics: ComponentMetrics[] = [
    {
        name: 'IOrderReader',
        afferentCoupling: 28,   // Many still read orders
        efferentCoupling: 3,    // Only Order, filter types
        instability: 0.10,      // Very stable
        abstractness: 1.0,
        distanceFromMainSequence: 0.10,  // Excellent
    },
    {
        name: 'IOrderWriter',
        afferentCoupling: 8,    // Fewer write operations
        efferentCoupling: 5,    // Order + mutation types
        instability: 0.38,      // Moderate stability
        abstractness: 1.0,
        distanceFromMainSequence: 0.38,
    },
    {
        name: 'IOrderAdmin',
        afferentCoupling: 3,    // Only admin tools
        efferentCoupling: 7,    // Admin-specific types
        instability: 0.70,      // Less stable (ok for admin)
        abstractness: 1.0,
        distanceFromMainSequence: 0.30,
    },
];
 
// KEY IMPROVEMENTS:
// - Average instability decreased (changes affect fewer clients)
// - Efferent coupling per interface drastically reduced
// - Admin volatility is isolated from main read path