Identifying Abstraction Boundaries - Designing for Abstraction | OneNoughtOne

System Design (LLD)Designing for Abstraction

Designing for Abstraction

LevelIntermediate

Duration60 mins

TopicDesigning for Abstraction

1 / 4

Identifying Abstraction Boundaries

The Invisible Architecture

Every well-designed software system is defined not just by what it does, but by what it hides. The most elegant architectures are those where each component presents a simple, comprehensible interface while concealing vast complexity within. But how do experienced engineers know where to draw these boundaries? How do they decide what to hide and what to expose?

This question—where should abstraction boundaries exist?—is one of the most consequential decisions in software design. Draw the boundary in the wrong place, and you create either a leaky abstraction that fails to simplify anything, or an over-abstraction that adds ceremony without value. Draw it correctly, and you create a system that remains comprehensible, maintainable, and evolvable for years.

This page teaches you to see what experienced architects see: the natural seams in a system, the indicators of good boundaries, and the techniques for identifying where abstractions should live.

What You Will Learn

By the end of this page, you will understand how to identify natural abstraction boundaries in software systems, recognize the signs that indicate where boundaries should exist, and apply systematic techniques for finding the right level of abstraction in your designs.

What Is an Abstraction Boundary?

An abstraction boundary is a conceptual line in your codebase that separates the what from the how. On one side of the boundary lies an interface—a description of capabilities. On the other side lies an implementation—the actual mechanisms that deliver those capabilities.

To understand this concretely, consider your car's steering wheel. The steering wheel presents a simple interface: turn left to go left, turn right to go right. Behind that interface lies an incredibly complex implementation: hydraulic or electric power steering systems, rack and pinion mechanisms, tie rods, ball joints, and sophisticated electronic stability controls. The steering wheel is an abstraction boundary—it separates what you want to do (change direction) from how it's accomplished (mechanical and electronic systems).

The Fundamental Purpose

An abstraction boundary exists to allow one part of a system to change without affecting other parts. The power steering system in a car evolved from hydraulic to electric, but the steering wheel interface remained identical. That's the power of a well-placed boundary.

In software, abstraction boundaries manifest in several forms:

Function signatures — The function name and parameters form a boundary; the function body is the hidden implementation.

Class interfaces — Public methods define what a class can do; private methods and fields hide how it works.

Module interfaces — Export statements declare the public surface; internal files remain hidden.

API contracts — Request/response schemas define interactions; server implementation is completely hidden.

Service boundaries — The service's API (REST, gRPC, GraphQL) is the interface; everything behind it is abstracted away.

Each of these represents a different scale of abstraction, but they all share the same fundamental structure: a stable, defined interface shielding a changeable implementation.

Abstraction Boundaries at Different Scales
Scale	Interface	Implementation Hidden	Change Insulation
Function	Name + parameters	Algorithm, local variables, helper calls	Can optimize without changing callers
Class	Public methods	Private state, internal methods	Can refactor internals freely
Module/Package	Exports	Internal structure, dependencies	Can restructure without affecting importers
Service	API contract	Database schema, libraries, languages	Can rewrite entirely without client changes
System	User-facing interface	Entire backend architecture	Can completely re-architect invisibly

Signs That Indicate Natural Boundaries

Abstraction boundaries aren't arbitrary lines drawn through code—they reflect natural seams in the problem domain. Experienced engineers develop an intuition for recognizing these seams. Here are the key indicators that suggest where boundaries should exist:

Indicators of Natural Abstraction Boundaries

•Rate of Change Differences — When two parts of the system change at different rates or for different reasons, there should be a boundary between them. Business logic changes with requirements; persistence logic changes with database decisions. These deserve separation.
•Different Stakeholders — When different people (or teams) are responsible for different parts, boundaries should reflect those responsibilities. The payment team shouldn't need to understand the recommendation engine's internals, and vice versa.
•Conceptual Cohesion — Things that belong together conceptually should be on the same side of a boundary. 'User authentication' is a coherent concept; 'user authentication and email rendering' is not.
•Substitutability — When you might want to swap one implementation for another (testing, environment differences, A/B testing), you need a boundary. Want to use a real payment processor in production but a mock in tests? That's a boundary.
•Independent Deployment — When parts should be deployable independently (microservices, plugins, libraries), they require clear boundaries that define their contract with the rest of the system.

Rate of Change Deserves Special Attention

Of all the indicators, rate of change is perhaps the most reliable guide. Parnas's foundational paper on information hiding (1972) established this principle: hide the design decisions most likely to change.

Consider a typical web application:

Component	Rate of Change	Change Drivers
UI styling	Weekly	Designer feedback, brand updates
Business rules	Monthly	New features, regulatory compliance
Database schema	Quarterly	Performance optimization, new features
Core domain model	Yearly	Major product pivots
Infrastructure	Years	Technology migrations

This analysis immediately suggests boundaries: UI code should be separated from business logic (different rates), business logic from database access (different drivers), and all of these from infrastructure (longest stability).

The Change Thought Experiment

When evaluating a design, ask: 'If I need to change X, what else must change with it?' If changing the database requires modifying business logic, your boundaries are in the wrong place. If adding a new payment provider requires rewriting order processing, your abstraction is leaking. The goal is to minimize the ripple effect of changes.

The Vocabulary Principle

One of the most reliable heuristics for identifying abstraction boundaries is to listen to how people naturally talk about the system. This is the Vocabulary Principle: abstraction boundaries should align with natural language boundaries in problem domain conversations.

When domain experts discuss a system, they use specific terminology for different concerns:

"The pricing engine should consider bulk discounts" — Pricing is its own concept
"We need to notify the user when their order ships" — Notification is a separate concern
"The inventory needs to reserve items during checkout" — Inventory management is distinct
"Fraud detection should flag suspicious orders" — Fraud is its own domain

Each of these natural language concepts suggests an abstraction boundary. When you find yourself saying 'the X system' or 'the Y component,' you're identifying a natural boundary in the vocabulary.

Vocabulary-Aligned Boundaries

•PaymentProcessor — handles payment logic
•NotificationService — manages notifications
•InventoryManager — tracks stock
•PricingEngine — calculates prices
•FraudDetector — identifies suspicious activity

Vocabulary-Violating Boundaries

•OrderHelper — does pricing AND notifications
•DataProcessor — mixes inventory AND fraud
•UserManager — handles auth AND preferences AND billing
•Utils — grabs anything that doesn't fit elsewhere
•Common — undefined miscellaneous functionality

The vocabulary principle extends to Domain-Driven Design's concept of Bounded Contexts. In DDD, a bounded context is a boundary within which a particular model (vocabulary) applies. The word 'Account' might mean something different in the 'Banking' bounded context versus the 'Social Media' bounded context. These natural vocabulary boundaries become explicit abstraction boundaries in the architecture.

Practical Application:

Listen to how your team and stakeholders discuss the system
Notice which nouns they use repeatedly (entities, concepts)
Notice which verbs they use (operations, processes)
Group related nouns and verbs together
Draw boundaries around those groups

This linguistic analysis often reveals abstraction boundaries more clearly than any technical analysis.

Ubiquitous Language

Domain-Driven Design calls this the 'Ubiquitous Language'—a shared vocabulary between developers and domain experts. Abstraction boundaries should respect this language. If domain experts talk about 'Orders' and 'Shipments' as separate concepts, your code should have separate abstractions for them.

The Dependency Direction Principle

Abstraction boundaries aren't just about what to hide—they're about how dependencies flow across those boundaries. The Dependency Direction Principle states: dependencies should flow from unstable (frequently changing) toward stable (rarely changing) components.

This principle has profound implications for where boundaries should exist. Consider a typical application structure:

dependency-flow.txt
┌─────────────────────────────────────────────────────────────┐
│                    USER INTERFACE                            │
│               (Changes frequently - unstable)                │
│                          │                                   │
│                          ▼                                   │
│            ┌─────────────────────────────┐                   │
│            │    APPLICATION SERVICES     │                   │
│            │    (Moderate stability)     │                   │
│            └─────────────────────────────┘                   │
│                          │                                   │
│                          ▼                                   │
│            ┌─────────────────────────────┐                   │
│            │      DOMAIN MODEL           │                   │
│            │   (Most stable - core)      │                   │
│            └─────────────────────────────┘                   │
│                          ▲                                   │
│                          │                                   │
│            ┌─────────────────────────────┐                   │
│            │     INFRASTRUCTURE          │◄── Dependencies   │
│            │  (Database, APIs, etc.)     │    point INWARD   │
│            └─────────────────────────────┘                   │
└─────────────────────────────────────────────────────────────┘
 
Dependencies flow TOWARD the center (stable core)
Outer layers depend on inner layers, never the reverse

This is the essence of Clean Architecture, Hexagonal Architecture, and Onion Architecture—they all share the same core insight: stable, high-value code should be at the center, with dependencies pointing inward.

Why does this matter for boundary identification?

When you draw a boundary, you're creating a dependency relationship. The code that uses an abstraction depends on the abstraction's interface. If that interface is unstable (changes frequently), all dependent code must change too.

Therefore, abstractions should:

Be defined at stable points in the architecture
Have interfaces that change less frequently than their implementations
Allow dependencies to flow from volatile to stable code

Inverted Dependencies

If your business logic depends on database details (specific SQL, ORM entities), your dependencies are inverted. The domain—the most stable, valuable part—is now coupled to infrastructure—which might change for purely technical reasons. This is why repositories and adapters exist: to invert the dependency so business logic remains insulated.

Practical Example: Repository Pattern

Consider how the Repository pattern creates proper dependency direction:

repository-pattern.ts
TypeScript
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
// === DOMAIN LAYER (Stable - the center) ===
// This is the most stable code in your system.
// It knows NOTHING about databases, frameworks, or external services.
 
interface UserRepository {
    findById(id: UserId): Promise<User | null>;
    findByEmail(email: Email): Promise<User | null>;
    save(user: User): Promise<void>;
    delete(id: UserId): Promise<void>;
}
 
// The User entity - pure domain logic
class User {
    constructor(
        private readonly id: UserId,
        private email: Email,
        private name: string,
        private readonly createdAt: Date
    ) {}
    
    changeEmail(newEmail: Email): void {
        this.email = newEmail;
        // Domain event, validation, etc.
    }
}
 
// === INFRASTRUCTURE LAYER (Unstable - outer ring) ===
// This code IMPLEMENTS the interface but DEPENDS ON the domain.
// Dependencies point INWARD toward the domain.
 
class PostgresUserRepository implements UserRepository {
    constructor(private db: DatabaseConnection) {}
    
    async findById(id: UserId): Promise<User | null> {
        const row = await this.db.query(
            'SELECT * FROM users WHERE id = $1', 
            [id.value]
        );
        return row ? this.toDomain(row) : null;
    }
    
    async save(user: User): Promise<void> {
        await this.db.query(
            'INSERT INTO users (id, email, name) VALUES ($1, $2, $3) ON CONFLICT (id) DO UPDATE...',
            [user.id.value, user.email.value, user.name]
        );
    }
    
    private toDomain(row: DbRow): User {
        return new User(
            new UserId(row.id),
            new Email(row.email),
            row.name,
            row.created_at
        );
    }
}
 
// === APPLICATION LAYER ===
// Depends on the domain interface, not the implementation.
// Can work with any repository implementation.
 
class UserService {
    // Injected via interface - doesn't know about Postgres
    constructor(private userRepo: UserRepository) {}
    
    async changeUserEmail(userId: UserId, newEmail: Email): Promise<void> {
        const user = await this.userRepo.findById(userId);
        if (!user) throw new UserNotFoundError(userId);
        
        user.changeEmail(newEmail);
        await this.userRepo.save(user);
    }
}

Cohesion and Coupling Analysis

The classic metrics of cohesion (how strongly related elements within a module are) and coupling (how dependent modules are on each other) provide a rigorous framework for identifying abstraction boundaries.

The goal is clear: maximize cohesion within boundaries, minimize coupling across them.

When you draw a boundary that encloses highly cohesive elements, you create a meaningful abstraction. When you draw a boundary that minimizes coupling to other parts of the system, you enable independent change and evolution.

Types of Cohesion (Best to Worst)
Type	Description	Quality
Functional	All elements contribute to a single, well-defined task	⭐ Best
Sequential	Output of one element is input to the next	Good
Communicational	Elements operate on the same data	Good
Procedural	Elements are related by order of execution	Moderate
Temporal	Elements are related by being executed at similar times	Poor
Logical	Elements are logically related but do different things	Poor
Coincidental	No meaningful relationship between elements	⚠️ Worst

Practical Cohesion Analysis

To analyze whether elements belong together (high cohesion), ask these questions:

Single Purpose Test: Can you describe what this module does with a single, coherent sentence without using 'and'?
- ✅ "Handles user authentication"
- ❌ "Handles user authentication and sends email notifications and logs metrics"
Change Together Test: When requirements change, do these elements change together?
- ✅ LoginValidator and PasswordHasher both change when auth requirements change
- ❌ LoginValidator and EmailSender change for different reasons
Conceptual Unity Test: Do these elements form a coherent mental model?
- ✅ Repository, Entity, and Value Objects all relate to the domain concept
- ❌ UserService mixed with HTTPClient and JSONParser

Coupling Types to Minimize

•Content coupling — Module directly accesses internals of another
•Common coupling — Modules share global state
•Control coupling — Module controls flow of another via parameters
•Stamp coupling — Modules share composite data unnecessarily

Acceptable Coupling Types

•Data coupling — Modules share only necessary data
•Message coupling — Modules communicate via messages/events
•Interface coupling — Modules depend only on interfaces
•No coupling — Modules are completely independent

The Coupling Visualization

Draw a dependency diagram for your system. Boundaries should cut through areas with few connections (low coupling). If you find yourself drawing a boundary that cuts through many dense connections, you're probably in the wrong place—those densely connected elements should likely be inside the same boundary.

The Seven Signals of Wrong Boundaries

Identifying where boundaries should exist is only half the skill. Equally important is recognizing where your current boundaries are wrong. Here are seven signals that indicate boundaries need to move:

Signals of Misplaced Boundaries

•Shotgun Surgery — A single logical change requires modifications in many different modules. This suggests that related functionality is scattered across boundaries instead of cohered within one.
•Feature Envy — A module spends more time accessing another module's data than its own. The boundary is between things that belong together.
•Primitive Obsession — Abstraction boundaries pass around primitive types instead of domain concepts. The boundary is at the wrong level of abstraction.
•Data Clumps — The same groups of data appear together repeatedly across boundaries. These data naturally form a concept that deserves its own boundary.
•Middleman — A module does nothing but delegate to another module. The boundary adds ceremony without value.
•Inappropriate Intimacy — Two modules know too much about each other's internals. They're either in the wrong places, or the boundary between them is poorly defined.
•Divergent Change — A single module changes for multiple, unrelated reasons. It contains multiple responsibilities that should be separated by boundaries.

Case Study: Shotgun Surgery

Imagine adding a new field to your User entity:

Layer/Module	Changes Required
Database migration	Add column
ORM Model	Add property
Repository	Update mapping
Domain Entity	Add field
DTO	Add field
Controller	Update validation
Frontend	Display new field

Some of these changes are unavoidable, but if you also have to change:

The logging module (to log the new field)
The caching layer (to invalidate on the new field)
The search service (to index the new field)
The analytics service (to track the new field)

...then you have shotgun surgery. Your boundaries are wrong. The user concept should be encapsulated such that adding a field doesn't ripple across unrelated modules.

Boundaries Evolve

Finding the right boundaries isn't a one-time activity. As systems evolve, the right boundaries change. Code that was appropriately coupled initially may need separation as requirements diverge. Regular refactoring to adjust boundaries is a sign of a healthy codebase.

Techniques for Finding Boundaries

Beyond intuition and heuristics, several systematic techniques help identify where abstraction boundaries should exist:

Event Storming is a collaborative technique that identifies domain events and the boundaries between them.

Process:

Gather domain experts and developers
Identify all domain events (past-tense verbs): 'Order Placed', 'Payment Received', 'Item Shipped'
Cluster related events together
Identify the boundaries between clusters—these are your bounded contexts
Name each bounded context with domain vocabulary

Example Output:

┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│   ORDERING      │  │    PAYMENT      │  │   SHIPPING      │
│                 │  │                 │  │                 │
│ Order Placed    │  │ Payment Init    │  │ Label Created   │
│ Order Modified  │──▶ Payment Success │──▶ Item Picked     │
│ Order Cancelled │  │ Payment Failed  │  │ Item Shipped    │
│                 │  │ Refund Issued   │  │ Item Delivered  │
└─────────────────┘  └─────────────────┘  └─────────────────┘

Natural clusters of events reveal natural abstraction boundaries.

Combining Techniques

No single technique perfectly identifies all boundaries. The best approach combines multiple methods:

Start with vocabulary analysis to identify candidate boundaries
Use event storming to validate boundaries align with business processes
Apply change history analysis to find hidden couplings
Use responsibility mapping to verify cohesion within boundaries
Check against signals of wrong boundaries to identify problems

When multiple techniques point to the same boundaries, you can be confident in your design.

Summary: Identifying Abstraction Boundaries

Identifying the right abstraction boundaries is fundamental to creating maintainable, evolvable software. Let's consolidate the key principles:

Key Takeaways

•Boundaries separate what from how — They define interfaces (what) while hiding implementations (how), enabling change on one side without affecting the other.
•Natural seams exist in every system — Look for differences in rate of change, stakeholder responsibility, conceptual cohesion, and substitutability requirements.
•Vocabulary reveals boundaries — Listen to how domain experts talk. Nouns and verbs in their language often map directly to abstraction boundaries.
•Dependencies should point inward — From unstable (frequently changing) toward stable (rarely changing) code. The most valuable code should be at the center.
•Maximize cohesion, minimize coupling — Elements within a boundary should be strongly related; connections across boundaries should be minimal.
•Watch for signals of wrong boundaries — Shotgun surgery, feature envy, and divergent change indicate boundaries in the wrong places.
•Use systematic techniques — Event storming, change history analysis, and responsibility mapping provide rigorous methods for finding boundaries.

What's Next:

Now that we can identify where abstraction boundaries should exist, the next page explores how to effectively hide implementation details behind those boundaries. We'll examine the techniques and patterns that ensure your abstractions remain clean and your implementations remain changeable.

Page Complete

You now understand how to identify natural abstraction boundaries in software systems. These skills form the foundation for designing clean, maintainable architectures. In the next page, we'll learn how to properly hide implementation details behind these boundaries.

1 / 4

Loading learning content...

System Design (LLD)Designing for Abstraction

Designing for Abstraction

LevelIntermediate

Duration60 mins

TopicDesigning for Abstraction

1 / 4

Identifying Abstraction Boundaries

The Invisible Architecture

This page teaches you to see what experienced architects see: the natural seams in a system, the indicators of good boundaries, and the techniques for identifying where abstractions should live.

What You Will Learn

What Is an Abstraction Boundary?

The Fundamental Purpose

In software, abstraction boundaries manifest in several forms:

Function signatures — The function name and parameters form a boundary; the function body is the hidden implementation.

Class interfaces — Public methods define what a class can do; private methods and fields hide how it works.

Module interfaces — Export statements declare the public surface; internal files remain hidden.

API contracts — Request/response schemas define interactions; server implementation is completely hidden.

Service boundaries — The service's API (REST, gRPC, GraphQL) is the interface; everything behind it is abstracted away.

Each of these represents a different scale of abstraction, but they all share the same fundamental structure: a stable, defined interface shielding a changeable implementation.

Abstraction Boundaries at Different Scales
Scale	Interface	Implementation Hidden	Change Insulation
Function	Name + parameters	Algorithm, local variables, helper calls	Can optimize without changing callers
Class	Public methods	Private state, internal methods	Can refactor internals freely
Module/Package	Exports	Internal structure, dependencies	Can restructure without affecting importers
Service	API contract	Database schema, libraries, languages	Can rewrite entirely without client changes
System	User-facing interface	Entire backend architecture	Can completely re-architect invisibly

Signs That Indicate Natural Boundaries

Indicators of Natural Abstraction Boundaries

•Rate of Change Differences — When two parts of the system change at different rates or for different reasons, there should be a boundary between them. Business logic changes with requirements; persistence logic changes with database decisions. These deserve separation.
•Different Stakeholders — When different people (or teams) are responsible for different parts, boundaries should reflect those responsibilities. The payment team shouldn't need to understand the recommendation engine's internals, and vice versa.
•Conceptual Cohesion — Things that belong together conceptually should be on the same side of a boundary. 'User authentication' is a coherent concept; 'user authentication and email rendering' is not.
•Substitutability — When you might want to swap one implementation for another (testing, environment differences, A/B testing), you need a boundary. Want to use a real payment processor in production but a mock in tests? That's a boundary.
•Independent Deployment — When parts should be deployable independently (microservices, plugins, libraries), they require clear boundaries that define their contract with the rest of the system.

Rate of Change Deserves Special Attention

Consider a typical web application:

Component	Rate of Change	Change Drivers
UI styling	Weekly	Designer feedback, brand updates
Business rules	Monthly	New features, regulatory compliance
Database schema	Quarterly	Performance optimization, new features
Core domain model	Yearly	Major product pivots
Infrastructure	Years	Technology migrations

The Change Thought Experiment

The Vocabulary Principle

When domain experts discuss a system, they use specific terminology for different concerns:

"The pricing engine should consider bulk discounts" — Pricing is its own concept
"We need to notify the user when their order ships" — Notification is a separate concern
"The inventory needs to reserve items during checkout" — Inventory management is distinct
"Fraud detection should flag suspicious orders" — Fraud is its own domain

Each of these natural language concepts suggests an abstraction boundary. When you find yourself saying 'the X system' or 'the Y component,' you're identifying a natural boundary in the vocabulary.

Vocabulary-Aligned Boundaries

•PaymentProcessor — handles payment logic
•NotificationService — manages notifications
•InventoryManager — tracks stock
•PricingEngine — calculates prices
•FraudDetector — identifies suspicious activity

Vocabulary-Violating Boundaries

•OrderHelper — does pricing AND notifications
•DataProcessor — mixes inventory AND fraud
•UserManager — handles auth AND preferences AND billing
•Utils — grabs anything that doesn't fit elsewhere
•Common — undefined miscellaneous functionality

Practical Application:

Listen to how your team and stakeholders discuss the system
Notice which nouns they use repeatedly (entities, concepts)
Notice which verbs they use (operations, processes)
Group related nouns and verbs together
Draw boundaries around those groups

This linguistic analysis often reveals abstraction boundaries more clearly than any technical analysis.

Ubiquitous Language

The Dependency Direction Principle

This principle has profound implications for where boundaries should exist. Consider a typical application structure:

dependency-flow.txt
┌─────────────────────────────────────────────────────────────┐
│                    USER INTERFACE                            │
│               (Changes frequently - unstable)                │
│                          │                                   │
│                          ▼                                   │
│            ┌─────────────────────────────┐                   │
│            │    APPLICATION SERVICES     │                   │
│            │    (Moderate stability)     │                   │
│            └─────────────────────────────┘                   │
│                          │                                   │
│                          ▼                                   │
│            ┌─────────────────────────────┐                   │
│            │      DOMAIN MODEL           │                   │
│            │   (Most stable - core)      │                   │
│            └─────────────────────────────┘                   │
│                          ▲                                   │
│                          │                                   │
│            ┌─────────────────────────────┐                   │
│            │     INFRASTRUCTURE          │◄── Dependencies   │
│            │  (Database, APIs, etc.)     │    point INWARD   │
│            └─────────────────────────────┘                   │
└─────────────────────────────────────────────────────────────┘
 
Dependencies flow TOWARD the center (stable core)
Outer layers depend on inner layers, never the reverse

Why does this matter for boundary identification?

Therefore, abstractions should:

Be defined at stable points in the architecture
Have interfaces that change less frequently than their implementations
Allow dependencies to flow from volatile to stable code

Inverted Dependencies

Practical Example: Repository Pattern

Consider how the Repository pattern creates proper dependency direction:

repository-pattern.ts
TypeScript
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
// === DOMAIN LAYER (Stable - the center) ===
// This is the most stable code in your system.
// It knows NOTHING about databases, frameworks, or external services.
 
interface UserRepository {
    findById(id: UserId): Promise<User | null>;
    findByEmail(email: Email): Promise<User | null>;
    save(user: User): Promise<void>;
    delete(id: UserId): Promise<void>;
}
 
// The User entity - pure domain logic
class User {
    constructor(
        private readonly id: UserId,
        private email: Email,
        private name: string,
        private readonly createdAt: Date
    ) {}
    
    changeEmail(newEmail: Email): void {
        this.email = newEmail;
        // Domain event, validation, etc.
    }
}
 
// === INFRASTRUCTURE LAYER (Unstable - outer ring) ===
// This code IMPLEMENTS the interface but DEPENDS ON the domain.
// Dependencies point INWARD toward the domain.
 
class PostgresUserRepository implements UserRepository {
    constructor(private db: DatabaseConnection) {}
    
    async findById(id: UserId): Promise<User | null> {
        const row = await this.db.query(
            'SELECT * FROM users WHERE id = $1', 
            [id.value]
        );
        return row ? this.toDomain(row) : null;
    }
    
    async save(user: User): Promise<void> {
        await this.db.query(
            'INSERT INTO users (id, email, name) VALUES ($1, $2, $3) ON CONFLICT (id) DO UPDATE...',
            [user.id.value, user.email.value, user.name]
        );
    }
    
    private toDomain(row: DbRow): User {
        return new User(
            new UserId(row.id),
            new Email(row.email),
            row.name,
            row.created_at
        );
    }
}
 
// === APPLICATION LAYER ===
// Depends on the domain interface, not the implementation.
// Can work with any repository implementation.
 
class UserService {
    // Injected via interface - doesn't know about Postgres
    constructor(private userRepo: UserRepository) {}
    
    async changeUserEmail(userId: UserId, newEmail: Email): Promise<void> {
        const user = await this.userRepo.findById(userId);
        if (!user) throw new UserNotFoundError(userId);
        
        user.changeEmail(newEmail);
        await this.userRepo.save(user);
    }
}

Cohesion and Coupling Analysis

The goal is clear: maximize cohesion within boundaries, minimize coupling across them.

Types of Cohesion (Best to Worst)
Type	Description	Quality
Functional	All elements contribute to a single, well-defined task	⭐ Best
Sequential	Output of one element is input to the next	Good
Communicational	Elements operate on the same data	Good
Procedural	Elements are related by order of execution	Moderate
Temporal	Elements are related by being executed at similar times	Poor
Logical	Elements are logically related but do different things	Poor
Coincidental	No meaningful relationship between elements	⚠️ Worst

Practical Cohesion Analysis

To analyze whether elements belong together (high cohesion), ask these questions:

Single Purpose Test: Can you describe what this module does with a single, coherent sentence without using 'and'?
- ✅ "Handles user authentication"
- ❌ "Handles user authentication and sends email notifications and logs metrics"
Change Together Test: When requirements change, do these elements change together?
- ✅ LoginValidator and PasswordHasher both change when auth requirements change
- ❌ LoginValidator and EmailSender change for different reasons
Conceptual Unity Test: Do these elements form a coherent mental model?
- ✅ Repository, Entity, and Value Objects all relate to the domain concept
- ❌ UserService mixed with HTTPClient and JSONParser

Coupling Types to Minimize

•Content coupling — Module directly accesses internals of another
•Common coupling — Modules share global state
•Control coupling — Module controls flow of another via parameters
•Stamp coupling — Modules share composite data unnecessarily

Acceptable Coupling Types

•Data coupling — Modules share only necessary data
•Message coupling — Modules communicate via messages/events
•Interface coupling — Modules depend only on interfaces
•No coupling — Modules are completely independent

The Coupling Visualization

The Seven Signals of Wrong Boundaries

Signals of Misplaced Boundaries

•Shotgun Surgery — A single logical change requires modifications in many different modules. This suggests that related functionality is scattered across boundaries instead of cohered within one.
•Feature Envy — A module spends more time accessing another module's data than its own. The boundary is between things that belong together.
•Primitive Obsession — Abstraction boundaries pass around primitive types instead of domain concepts. The boundary is at the wrong level of abstraction.
•Data Clumps — The same groups of data appear together repeatedly across boundaries. These data naturally form a concept that deserves its own boundary.
•Middleman — A module does nothing but delegate to another module. The boundary adds ceremony without value.
•Inappropriate Intimacy — Two modules know too much about each other's internals. They're either in the wrong places, or the boundary between them is poorly defined.
•Divergent Change — A single module changes for multiple, unrelated reasons. It contains multiple responsibilities that should be separated by boundaries.

Case Study: Shotgun Surgery

Imagine adding a new field to your User entity:

Layer/Module	Changes Required
Database migration	Add column
ORM Model	Add property
Repository	Update mapping
Domain Entity	Add field
DTO	Add field
Controller	Update validation
Frontend	Display new field

Some of these changes are unavoidable, but if you also have to change:

The logging module (to log the new field)
The caching layer (to invalidate on the new field)
The search service (to index the new field)
The analytics service (to track the new field)

...then you have shotgun surgery. Your boundaries are wrong. The user concept should be encapsulated such that adding a field doesn't ripple across unrelated modules.

Boundaries Evolve

Techniques for Finding Boundaries

Beyond intuition and heuristics, several systematic techniques help identify where abstraction boundaries should exist:

Event Storming is a collaborative technique that identifies domain events and the boundaries between them.

Process:

Gather domain experts and developers
Identify all domain events (past-tense verbs): 'Order Placed', 'Payment Received', 'Item Shipped'
Cluster related events together
Identify the boundaries between clusters—these are your bounded contexts
Name each bounded context with domain vocabulary

Example Output:

┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│   ORDERING      │  │    PAYMENT      │  │   SHIPPING      │
│                 │  │                 │  │                 │
│ Order Placed    │  │ Payment Init    │  │ Label Created   │
│ Order Modified  │──▶ Payment Success │──▶ Item Picked     │
│ Order Cancelled │  │ Payment Failed  │  │ Item Shipped    │
│                 │  │ Refund Issued   │  │ Item Delivered  │
└─────────────────┘  └─────────────────┘  └─────────────────┘

Natural clusters of events reveal natural abstraction boundaries.

Combining Techniques

No single technique perfectly identifies all boundaries. The best approach combines multiple methods:

Start with vocabulary analysis to identify candidate boundaries
Use event storming to validate boundaries align with business processes
Apply change history analysis to find hidden couplings
Use responsibility mapping to verify cohesion within boundaries
Check against signals of wrong boundaries to identify problems

When multiple techniques point to the same boundaries, you can be confident in your design.

Summary: Identifying Abstraction Boundaries

Identifying the right abstraction boundaries is fundamental to creating maintainable, evolvable software. Let's consolidate the key principles:

Key Takeaways

•Boundaries separate what from how — They define interfaces (what) while hiding implementations (how), enabling change on one side without affecting the other.
•Natural seams exist in every system — Look for differences in rate of change, stakeholder responsibility, conceptual cohesion, and substitutability requirements.
•Vocabulary reveals boundaries — Listen to how domain experts talk. Nouns and verbs in their language often map directly to abstraction boundaries.
•Dependencies should point inward — From unstable (frequently changing) toward stable (rarely changing) code. The most valuable code should be at the center.
•Maximize cohesion, minimize coupling — Elements within a boundary should be strongly related; connections across boundaries should be minimal.
•Watch for signals of wrong boundaries — Shotgun surgery, feature envy, and divergent change indicate boundaries in the wrong places.
•Use systematic techniques — Event storming, change history analysis, and responsibility mapping provide rigorous methods for finding boundaries.

What's Next:

Page Complete

1 / 4