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

Package: OrderService
┌─────────────────────────────────────────────────────────────┐
│                                                             │
│  Afferent Coupling (Ca = 5)                                │
│  ─────────────────────────────                              │
│  Who depends on me?                                         │
│  • CheckoutController → OrderService                       │
│  • AdminDashboard → OrderService                           │
│  • ReportingModule → OrderService                          │
│  • NotificationService → OrderService                      │
│  • MobileAPI → OrderService                                │
│                                                             │
│  This package is heavily depended upon.                    │
│  Changes to its public interface are HIGH RISK.            │
│                                                             │
│  Efferent Coupling (Ce = 3)                                │
│  ─────────────────────────────                              │
│  Who do I depend on?                                        │
│  • OrderService → UserRepository                           │
│  • OrderService → PaymentGateway                           │
│  • OrderService → InventoryService                         │
│                                                             │
│  This package has moderate external dependencies.          │
│  Changes in these packages may affect me.                  │
│                                                             │
│  Instability I = 3 / (5 + 3) = 0.375                       │
│  ─────────────────────────────                              │
│  This package is moderately stable.                         │
│  It has more responsibility than freedom to change.        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

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

Abstractness (A)
│
1.0 ┤ ○ Zone of Uselessness
    │   (Abstract but nobody depends on it)
    │    ╲
    │     ╲  Main Sequence
    │      ╲  (A + I = 1)
0.5 ┤       ╲ ●●●● (Healthy packages)
    │        ╲
    │         ╲
    │          ╲
    │           ╲
0.0 ┼────────────○─────────────── Instability (I)
    0.0        0.5           1.0
              Zone of Pain
           (Concrete but stable
            - hard to change,
            painful to extend)
 
Legend:
○ = Problematic packages (avoid these zones)
● = Healthy packages (along the main sequence)
 
Abstractness (A) = Abstract classes/interfaces ÷ Total classes
Instability (I) = Ce ÷ (Ca + Ce)
 
Ideal: Packages fall on or near the main sequence line.
- Highly abstract packages should be stable (low I)
- Highly unstable packages can be concrete (low A)

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

// ❌ BEFORE: Circular dependency
// order-service/OrderService.ts
import { UserService } from '../user-service/UserService';
export class OrderService {
    constructor(private userService: UserService) {}
    createOrder(userId: string) {
        const user = this.userService.getUser(userId);
        // ...create order
    }
}
 
// user-service/UserService.ts
import { OrderService } from '../order-service/OrderService'; // CYCLE!
export class UserService {
    constructor(private orderService: OrderService) {}
    getUserOrders(userId: string) {
        return this.orderService.getOrdersForUser(userId);
    }
}
 
// ✅ AFTER: Broken with Dependency Inversion
// user-service/interfaces/OrderProvider.ts (interface in user-service)
export interface OrderProvider {
    getOrdersForUser(userId: string): Order[];
}
 
// user-service/UserService.ts (depends only on interface)
import { OrderProvider } from './interfaces/OrderProvider';
export class UserService {
    constructor(private orderProvider: OrderProvider) {}
    getUserOrders(userId: string) {
        return this.orderProvider.getOrdersForUser(userId);
    }
}
 
// order-service/OrderService.ts (implements the interface)
import { OrderProvider } from '../user-service/interfaces/OrderProvider';
import { UserService } from '../user-service/UserService';
 
export class OrderService implements OrderProvider {
    constructor(private userService: UserService) {}
    
    createOrder(userId: string) {
        const user = this.userService.getUser(userId);
        // ...
    }
    
    getOrdersForUser(userId: string): Order[] {
        // ...
    }
}
 
// Now: UserService → OrderProvider (interface)
//      OrderService → UserService
//      OrderService implements OrderProvider
// No cycle! UserService doesn't know about OrderService.

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

// architecture.test.ts
import { buildDependencyGraph, findCycles } from './arch-testing-utils';
 
describe('Package Architecture', () => {
    it('should have no circular dependencies between packages', () => {
        const graph = buildDependencyGraph('./src');
        const cycles = findCycles(graph);
        
        if (cycles.length > 0) {
            const cycleDescriptions = cycles.map(cycle => 
                cycle.join(' → ') + ' → ' + cycle[0]
            );
            
            fail(
                'Circular dependencies detected:
' +
                cycleDescriptions.join('
') +
                '
 
Use Dependency Inversion or extract shared packages to break these cycles.'
            );
        }
        
        expect(cycles).toHaveLength(0);
    });
    
    it('should follow layer dependency rules', () => {
        const violations = checkLayerViolations('./src', {
            layers: [
                { name: 'domain', pattern: '**/domain/**' },
                { name: 'application', pattern: '**/application/**', allowedDependencies: ['domain'] },
                { name: 'infrastructure', pattern: '**/infrastructure/**', allowedDependencies: ['domain', 'application'] },
            ]
        });
        
        expect(violations).toHaveLength(0);
    });
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// order-processing/index.ts
// ❌ BAD: Export everything, large coupling surface
export * from './OrderService';
export * from './OrderRepository';
export * from './OrderValidator';
export * from './Order';
export * from './OrderItem';
export * from './OrderStatus';
export * from './internal/OrderCalculator';
export * from './internal/TaxService';
 
// ✅ GOOD: Explicit public API, minimal surface
export { OrderService } from './OrderService';
export { Order, OrderStatus } from './Order';
export type { OrderId, CreateOrderRequest } from './Order';
 
// Everything else is internal - not exported
// Clients can only couple to OrderService and Order types
// Internal changes (OrderCalculator, TaxService) don't affect clients