System Design (HLD)ISP in Practice

ISP in Practice

LevelIntermediate

Duration60 mins

TopicISP in Practice

4 / 4

Balancing Granularity

The Goldilocks Problem in Interface Design

We've spent this chapter advocating for interface segregation—splitting fat interfaces into focused, role-based contracts. But there's a danger in taking this advice too far. Extreme granularity creates its own problems: an explosion of single-method interfaces, dependency injection nightmares, and cognitive overload from tracking dozens of tiny contracts.

The goal isn't "as many interfaces as possible." The goal is the right number of interfaces—enough to avoid ISP violations, but not so many that the cure becomes worse than the disease. This page explores the art of finding that balance.

What You Will Learn

By the end of this page, you will understand the symptoms of over-segregation, develop heuristics for appropriate interface granularity, and be able to make pragmatic decisions that balance ISP purity with practical maintainability.

The Spectrum of Granularity

Interface granularity exists on a spectrum. Both extremes are problematic—the sweet spot lies somewhere in the middle, and the exact position depends on context.

The Granularity Spectrum:

Interface Granularity Spectrum
Level	Description	Trade-offs
Monolithic	1 interface for entire domain (e.g., `UserManager` with 50 methods)	Simple to find things; impossible to decouple
Domain-Aggregate	1 interface per domain aggregate (e.g., `UserRepository`, `OrderRepository`)	Clear boundaries; some role conflation
Role-Based	1 interface per role (e.g., `UserReader`, `UserWriter`, `UserAuthenticator`)	Clean ISP; moderate interface count
Capability-Based	1 interface per capability (e.g., `Readable`, `Writable`, `Searchable`)	Maximum reuse; requires composition
Single-Method	1 interface per method (e.g., `CanCreateUser`, `CanDeleteUser`)	Ultimate ISP purity; explosion of types

Too Coarse (Under-Segregation)

•Fat interfaces with many methods
•Consumers depend on unused methods
•Changes ripple to unrelated components
•Testing requires excessive mocking
•Can't substitute implementations

Too Fine (Over-Segregation)

•Explosion of interface types
•DI containers become unmanageable
•Cognitive load tracking relationships
•Excessive type declarations
•Composition becomes a puzzle

The Sweet Spot is Contextual

There's no universal "correct" granularity. A microservices architecture might favor finer granularity (each service has focused interfaces). A monolithic CRUD application might favor coarser granularity (repository per entity). The right answer depends on team size, change frequency, testing requirements, and architectural style.

Signs of Over-Segregation

Over-segregation is less common than under-segregation, but it happens—especially when developers take ISP advice to an extreme. Recognize these warning signs:

Over-Segregation Symptoms

•Dependency injection has 10+ constructor parameters — Each tiny interface becomes a separate dependency
•Interfaces are always used together — If consumers always import 5 interfaces together, they should be one interface
•Interface names require context to understand — ICanProcessPaymentStep3After is too granular
•Refactoring touches dozens of interface files — A simple change cascades through the type system
•New developers are overwhelmed — Finding where functionality lives requires archaeology
•Composition boilerplate exceeds business logic — More code glues interfaces together than does actual work

Over-Segregation Example
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
// Over-segregated - each method is its own interface
interface UserCreator {
    createUser(data: CreateUserDTO): Promise<User>;
}
 
interface UserReaderById {
    getUserById(id: string): Promise<User | null>;
}
 
interface UserReaderByEmail {
    getUserByEmail(email: string): Promise<User | null>;
}
 
interface UserUpdater {
    updateUser(id: string, data: UpdateUserDTO): Promise<User>;
}
 
interface UserDeleter {
    deleteUser(id: string): Promise<void>;
}
 
interface UserExistenceChecker {
    userExists(id: string): Promise<boolean>;
}
 
interface UserCounter {
    countUsers(): Promise<number>;
}
 
// Now a service that needs basic CRUD has this nightmare:
class UserProfileService {
    constructor(
        private userReaderById: UserReaderById,
        private userReaderByEmail: UserReaderByEmail,
        private userUpdater: UserUpdater,
        private userExistenceChecker: UserExistenceChecker,
        // ... and so on
    ) {}
    
    // 7 interface dependencies for basic profile management!
}
 
// DI container configuration becomes unreadable
container.bind<UserCreator>(TYPES.UserCreator).to(UserRepositoryImpl);
container.bind<UserReaderById>(TYPES.UserReaderById).to(UserRepositoryImpl);
container.bind<UserReaderByEmail>(TYPES.UserReaderByEmail).to(UserRepositoryImpl);
container.bind<UserUpdater>(TYPES.UserUpdater).to(UserRepositoryImpl);
container.bind<UserDeleter>(TYPES.UserDeleter).to(UserRepositoryImpl);
container.bind<UserExistenceChecker>(TYPES.UserExistenceChecker).to(UserRepositoryImpl);
container.bind<UserCounter>(TYPES.UserCounter).to(UserRepositoryImpl);
// All 7 bindings point to the same implementation!

The example above demonstrates ISP taken to an absurd extreme. While each interface is perfectly "segregated," the system is harder to understand, harder to configure, and provides no practical benefit—because all these interfaces are always used together and implemented by the same class.

The Cohesion Principle for Granularity

The key to appropriate granularity is cohesion: methods that naturally belong together should stay together. ISP says "don't force unrelated methods on consumers." It doesn't say "separate every method into its own interface."

Cohesion Indicators for Keeping Methods Together:

Methods Should Stay Together When...

•They operate on the same state — getBalance() and deposit() both work with account balance
•They're called in sequence — openTransaction(), commit(), rollback() are a unit
•They satisfy a single user story — "As a user, I can view and edit my profile" = read + update together
•They change together — Adding a field means updating both getter and setter
•Splitting would require passing data between interfaces — If methodA() produces data that methodB() consumes, they're cohesive

Cohesive Interface Design
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
// Appropriate granularity - cohesive method groups
 
// User identity management - cohesive because:
// - Same data (user identity, credentials)
// - Same stakeholder (auth team)
// - Called together during login/registration flows
interface UserIdentityManager {
    findByCredentials(email: string, password: string): Promise<User | null>;
    createUser(data: CreateUserDTO): Promise<User>;
    updateCredentials(userId: string, newEmail?: string, newPassword?: string): Promise<void>;
    verifyEmail(userId: string, token: string): Promise<boolean>;
}
 
// User profile - cohesive because:
// - Different data (display info, preferences)
// - Different stakeholder (product team)
// - Called together during profile views/edits
interface UserProfileManager {
    getProfile(userId: string): Promise<UserProfile>;
    updateProfile(userId: string, data: UpdateProfileDTO): Promise<void>;
    uploadAvatar(userId: string, image: Buffer): Promise<string>;
    getPreferences(userId: string): Promise<UserPreferences>;
    updatePreferences(userId: string, prefs: UserPreferences): Promise<void>;
}
 
// User social graph - cohesive because:
// - Different data (relationships)
// - Different stakeholder (social features team)
// - All relate to user connections
interface UserSocialGraph {
    follow(userId: string, targetUserId: string): Promise<void>;
    unfollow(userId: string, targetUserId: string): Promise<void>;
    getFollowers(userId: string): Promise<User[]>;
    getFollowing(userId: string): Promise<User[]>;
    blockUser(userId: string, blockedUserId: string): Promise<void>;
}
 
// Now services depend on what they need, but not excessively
class AuthService {
    constructor(private identity: UserIdentityManager) {}
    // 1 dependency for auth concerns
}
 
class ProfileController {
    constructor(
        private identity: UserIdentityManager,
        private profile: UserProfileManager
    ) {}
    // 2 dependencies for profile with auth
}
 
class SocialFeedService {
    constructor(
        private profile: UserProfileManager,
        private social: UserSocialGraph
    ) {}
    // 2 dependencies for social features
}

The 3-6 Method Rule of Thumb

A well-designed interface typically has 3-6 methods. Fewer than 3 suggests possible over-segregation (unless it's a genuine single-capability interface like Comparable). More than 7 suggests possible under-segregation. This is a heuristic, not a rule—but it guides initial interface sizing before deeper analysis.

Role-Based Granularity Strategy

The most reliable granularity strategy is role-based segregation: one interface per role a consumer might play. This naturally groups cohesive methods while avoiding the extremes of monolithic or single-method interfaces.

Identify Roles, Not Individual Methods:

Role-Based Interface Design
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
// Role identification for Order domain
 
// Role: Order Creator
// Who plays this role: Checkout service, Order import tool, API endpoint
// Methods needed: creating orders from various sources
interface OrderCreator {
    createFromCart(cart: Cart, customer: Customer): Promise<Order>;
    createFromImport(data: OrderImportData): Promise<Order>;
    createDraft(partial: Partial<Order>): Promise<DraftOrder>;
}
 
// Role: Order Reader
// Who plays this role: Order details page, Customer dashboard, API
// Methods needed: retrieving orders in various ways
interface OrderReader {
    getById(id: string): Promise<Order | null>;
    getByCustomer(customerId: string): Promise<Order[]>;
    search(criteria: OrderSearchCriteria): Promise<Page<Order>>;
}
 
// Role: Order State Changer
// Who plays this role: Warehouse system, Admin dashboard, Background jobs
// Methods needed: transitioning order states
interface OrderStateChanger {
    submit(orderId: string): Promise<void>;
    confirm(orderId: string): Promise<void>;
    cancel(orderId: string, reason: CancellationReason): Promise<void>;
    fulfill(orderId: string, fulfillment: FulfillmentDetails): Promise<void>;
    complete(orderId: string): Promise<void>;
}
 
// Role: Order Financial Handler
// Who plays this role: Finance system, Refund processor, Invoicing
// Methods needed: financial operations on orders
interface OrderFinancialHandler {
    applyDiscount(orderId: string, discount: Discount): Promise<void>;
    processRefund(orderId: string, amount: Money): Promise<Refund>;
    generateInvoice(orderId: string): Promise<Invoice>;
}
 
// Consumers declare which roles they play
class CheckoutService implements OrderCreater {
    // Only implements creation role
}
 
class CustomerDashboardService {
    constructor(private reader: OrderReader) {
        // Only depends on reading role
    }
}
 
class WarehouseIntegration {
    constructor(
        private reader: OrderReader,
        private stateChanger: OrderStateChanger
    ) {
        // Reads orders and changes their state
    }
}

Benefits of Role-Based Granularity:

Natural sizing: Roles typically encompass 3-7 related methods
Clear naming: Role names like Creator, Reader, Handler are intuitive
Stakeholder alignment: Each role often maps to a team or feature area
Testability: Mock entire roles, not individual operations
Evolution-friendly: New capabilities fit into existing roles or form new ones

Composition Over Proliferation

When interfaces are appropriately sized, consumers can compose them to express exactly what they need. This is preferable to creating an interface for every possible combination of capabilities.

Composition Patterns:

Interface Composition
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
// Base role interfaces
interface Readable<T> {
    findById(id: string): Promise<T | null>;
    findAll(filter?: Filter): Promise<T[]>;
}
 
interface Writable<T> {
    save(entity: T): Promise<T>;
    delete(id: string): Promise<void>;
}
 
interface Searchable<T> {
    search(query: SearchQuery): Promise<Page<T>>;
    count(filter?: Filter): Promise<number>;
}
 
// Composition via intersection types
type ReadWriteRepository<T> = Readable<T> & Writable<T>;
type FullRepository<T> = Readable<T> & Writable<T> & Searchable<T>;
 
// Or explicit combined interfaces when semantically meaningful
interface CRUDRepository<T> extends Readable<T>, Writable<T> {}
 
// Consumers choose their composition
class ReadOnlyReportService {
    constructor(private products: Readable<Product>) {
        // Can only read - write operations not available
    }
}
 
class InventoryManager {
    constructor(private products: ReadWriteRepository<Product>) {
        // Can read and write
    }
}
 
class ProductSearchController {
    constructor(private products: Searchable<Product>) {
        // Only search capability
    }
}
 
// Implementation provides all capabilities
class ProductRepository implements FullRepository<Product> {
    findById(id: string) { /* ... */ }
    findAll(filter?: Filter) { /* ... */ }
    save(entity: Product) { /* ... */ }
    delete(id: string) { /* ... */ }
    search(query: SearchQuery) { /* ... */ }
    count(filter?: Filter) { /* ... */ }
}
 
// DI binds the full implementation; consumers see only their declared type
container.bind<FullRepository<Product>>(TYPES.ProductRepo).to(ProductRepository);

Composition vs. Inheritance of Interfaces

Interface inheritance (interface B extends A) is appropriate when B is truly a specialized role that includes A's capabilities. Interface intersection (A & B) is appropriate when combining independent capabilities. Don't use inheritance to avoid creating a new interface—if the roles are distinct, use intersection or explicit combined interfaces.

The Aggregation Pattern for Complex Domains

In complex domains, you may have well-segregated role interfaces but want to provide a convenient aggregate for consumers that need multiple roles. The Aggregator Pattern offers a facade without sacrificing ISP.

The Pattern:

Design segregated role interfaces (ISP-compliant)
Create an aggregate interface that extends all roles (convenience)
Consumers choose: specific roles or the aggregate
The aggregate exists for convenience, not because ISP requires it

Aggregator Pattern
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
// Step 1: Segregated role interfaces
interface OrderReader {
    getOrder(id: string): Promise<Order | null>;
    getOrdersByCustomer(customerId: string): Promise<Order[]>;
}
 
interface OrderWriter {
    createOrder(data: CreateOrderDTO): Promise<Order>;
    updateOrder(id: string, data: UpdateOrderDTO): Promise<Order>;
    deleteOrder(id: string): Promise<void>;
}
 
interface OrderStateManager {
    submitOrder(id: string): Promise<void>;
    cancelOrder(id: string): Promise<void>;
    fulfillOrder(id: string): Promise<void>;
}
 
interface OrderSearcher {
    searchOrders(criteria: SearchCriteria): Promise<Page<Order>>;
    countOrders(filter?: OrderFilter): Promise<number>;
}
 
// Step 2: Aggregate interface for convenience
interface OrderService extends 
    OrderReader, 
    OrderWriter, 
    OrderStateManager, 
    OrderSearcher {
    // No additional methods - just combines roles
}
 
// Step 3: Consumers CHOOSE their dependency level
// Focused consumers use specific roles:
class OrderDetailsController {
    constructor(private orderReader: OrderReader) {
        // Minimal dependency
    }
}
 
class WarehouseIntegration {
    constructor(private stateManager: OrderStateManager) {
        // Only state transitions
    }
}
 
// Full-service consumers use the aggregate:
class OrderAdminDashboard {
    constructor(private orderService: OrderService) {
        // Explicitly needs all capabilities
    }
}
 
// Step 4: Implementation provides the aggregate
class OrderServiceImpl implements OrderService {
    // Implements all methods from all interfaces
}
 
// DI configuration can bind both ways
container.bind<OrderService>(TYPES.OrderService).to(OrderServiceImpl);
container.bind<OrderReader>(TYPES.OrderReader).toService(TYPES.OrderService);
container.bind<OrderWriter>(TYPES.OrderWriter).toService(TYPES.OrderService);
// Narrow dependencies resolve to the same implementation

Aggregates Don't Violate ISP

The aggregate interface doesn't violate ISP because consumers aren't forced to use it. It's an option for consumers who genuinely need all capabilities. The key is that the segregated interfaces exist and are available. Consumers who only need OrderReader can depend on OrderReader, not the aggregate. The aggregate is convenience, not coercion.

Contextual Granularity Decisions

The right granularity depends on context. Here's how to adjust your approach based on system characteristics:

Granularity Guidelines by Context
Context	Lean Toward	Rationale
Microservices architecture	Finer granularity	Each service already isolated; clear ownership matters
Monolithic CRUD application	Coarser granularity	Less change friction; simpler navigation
Library/SDK for external consumers	Finer granularity	Consumers can't refactor your code; flexibility crucial
Internal team code	Moderate granularity	Can refactor if needed; balance complexity
High team turnover	Finer granularity with clear naming	Self-documentation via interface roles
Mature, stable domain	Coarser granularity	Changes are rare; simplicity wins
Rapidly evolving domain	Finer granularity	Isolation protects against change ripple
Strong testing requirements	Finer granularity	Easier mocking, clearer test scope

Context-Aware Decisions
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
// Example: E-commerce platform decisions
 
// CONTEXT: Payment integration (external dependency, high change risk)
// DECISION: Fine granularity to isolate vendor-specific changes
 
interface PaymentAuthorizer {
    authorize(amount: Money, method: PaymentMethod): Promise<AuthorizationResult>;
}
 
interface PaymentCapturer {
    capture(authorizationId: string): Promise<CaptureResult>;
}
 
interface PaymentRefunder {
    refund(transactionId: string, amount?: Money): Promise<RefundResult>;
}
 
// Rationale: Payment vendors change APIs frequently.
// Segregated interfaces mean only affected operations need updates.
 
 
// CONTEXT: User profile (internal, stable domain)
// DECISION: Moderate granularity - role-based but not per-method
 
interface UserProfileService {
    getProfile(userId: string): Promise<UserProfile>;
    updateProfile(userId: string, data: ProfileUpdateDTO): Promise<void>;
    uploadAvatar(userId: string, image: Buffer): Promise<string>;
    getActivityHistory(userId: string): Promise<ActivityEntry[]>;
}
 
// Rationale: Profile operations are stable and commonly used together.
// Splitting into getProfile/updateProfile/avatar/history would add
// complexity without benefit - these are always used by profile consumers.
 
 
// CONTEXT: Admin analytics (internal, power users)
// DECISION: Coarser granularity - admins use many features together
 
interface AdminDashboardService {
    getUserMetrics(timeRange: TimeRange): Promise<UserMetrics>;
    getRevenueMetrics(timeRange: TimeRange): Promise<RevenueMetrics>;
    getSystemHealth(): Promise<SystemHealth>;
    generateReport(type: ReportType, options: ReportOptions): Promise<Report>;
    exportData(format: ExportFormat, filter: DataFilter): Promise<Buffer>;
}
 
// Rationale: Admin dashboard always shows all metrics together.
// Splitting would add DI complexity without benefit - there's only
// one consumer (AdminDashboard) that needs all capabilities.

Refactoring Granularity

What if you've realized your interfaces are at the wrong granularity level—either too coarse or too fine? Refactoring is possible, but requires care.

From Coarse to Fine (Splitting):

Splitting Strategy

•Identify role boundaries — Use consumer analysis to find natural split points
•Create new interfaces — Define the segregated interfaces alongside existing monolith
•Make monolith extend new interfaces — FatInterface extends RoleA, RoleB, RoleC
•Gradually migrate consumers — Update each consumer to depend on specific roles
•Deprecate the monolith — Once all consumers migrated, remove the fat interface

From Fine to Coarse (Merging):

Merging Strategy

•Identify always-together interfaces — Find interfaces that every consumer imports together
•Create combined interface — Either intersection type or new interface extending all
•Update consumers — Replace multiple dependencies with the combined interface
•Evaluate orphaned interfaces — Keep granular interfaces if any consumer uses them alone
•Simplify DI configuration — Reduce binding count to combined interface

Granularity Refactoring Example
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
// BEFORE: Over-segregated interfaces
interface ProductGetter {
    getProduct(id: string): Promise<Product>;
}
interface ProductLister {
    listProducts(): Promise<Product[]>;
}
interface ProductSearcher {
    searchProducts(query: string): Promise<Product[]>;
}
interface ProductCreator {
    createProduct(data: CreateProductDTO): Promise<Product>;
}
interface ProductUpdater {
    updateProduct(id: string, data: UpdateProductDTO): Promise<Product>;
}
interface ProductDeleter {
    deleteProduct(id: string): Promise<void>;
}
 
// Consumer has 6 dependencies for basic CRUD + search
class ProductService {
    constructor(
        private getter: ProductGetter,
        private lister: ProductLister,
        private searcher: ProductSearcher,
        private creator: ProductCreator,
        private updater: ProductUpdater,
        private deleter: ProductDeleter,
    ) {}
}
 
// AFTER: Role-based consolidation
// Step 1: Create combined role interfaces
interface ProductReader {
    getProduct(id: string): Promise<Product>;
    listProducts(): Promise<Product[]>;
    searchProducts(query: string): Promise<Product[]>;
}
 
interface ProductWriter {
    createProduct(data: CreateProductDTO): Promise<Product>;
    updateProduct(id: string, data: UpdateProductDTO): Promise<Product>;
    deleteProduct(id: string): Promise<void>;
}
 
// Step 2: Keep granular as aliases if any consumers still need them
type ProductGetter = Pick<ProductReader, 'getProduct'>;
type ProductSearcher = Pick<ProductReader, 'searchProducts'>;
// ... etc, for backward compatibility
 
// Step 3: Update consumers to role-based dependencies
class ProductService {
    constructor(
        private reader: ProductReader,
        private writer: ProductWriter,
    ) {
        // 2 dependencies instead of 6
    }
}
 
// Step 4: Simplify DI
container.bind<ProductReader>(TYPES.ProductReader).to(ProductRepositoryImpl);
container.bind<ProductWriter>(TYPES.ProductWriter).to(ProductRepositoryImpl);
 
// Step 5: Remove aliases after all consumers migrated
// (Delete the type aliases and granular interface types)

Summary: Mastering Interface Granularity

Interface granularity is an art, not a science. But informed by the principles in this page, you can make deliberate, defensible decisions about how to size your interfaces.

Key Takeaways

•Granularity is a spectrum — Both extremes (monolithic and per-method) are problematic
•Over-segregation creates its own problems — DI explosion, cognitive overload, excessive composition boilerplate
•Use cohesion as your guide — Methods that belong together (same state, sequence, story) should stay together
•Role-based granularity is the sweet spot — One interface per role naturally sizes to 3-7 methods
•Composition is powerful — Small interfaces combine via intersection types for consumers needing multiple roles
•Aggregates are convenience, not coercion — Provide combined interfaces for power users without forcing them on focused consumers
•Context matters — Adjust granularity based on architecture style, team composition, and change frequency
•Refactoring is possible — Both splitting and merging can be done incrementally with backward compatibility

Module Complete!

You've now mastered the Interface Segregation Principle in its entirety:

Page 1 showed you ISP in real-world frameworks and systems
Page 2 cataloged common ISP mistakes and anti-patterns
Page 3 gave you a systematic checklist for ISP evaluation
Page 4 taught you to balance granularity for practical maintainability

With this knowledge, you can design interfaces that serve their consumers without burdening them, evolve without breaking unrelated code, and maintain without drowning in complexity. ISP is one of the most impactful SOLID principles for day-to-day software design—apply it wisely.

Module Complete

Congratulations! You've completed the ISP in Practice module. You now understand how ISP manifests in production systems, can identify common violations, have a systematic evaluation checklist, and know how to balance interface granularity. You're equipped to apply ISP pragmatically in real-world software design.

4 / 4

Loading learning content...

System Design (HLD)ISP in Practice

ISP in Practice

LevelIntermediate

Duration60 mins

TopicISP in Practice

4 / 4

Balancing Granularity

The Goldilocks Problem in Interface Design

What You Will Learn

The Spectrum of Granularity

Interface granularity exists on a spectrum. Both extremes are problematic—the sweet spot lies somewhere in the middle, and the exact position depends on context.

The Granularity Spectrum:

Interface Granularity Spectrum
Level	Description	Trade-offs
Monolithic	1 interface for entire domain (e.g., `UserManager` with 50 methods)	Simple to find things; impossible to decouple
Domain-Aggregate	1 interface per domain aggregate (e.g., `UserRepository`, `OrderRepository`)	Clear boundaries; some role conflation
Role-Based	1 interface per role (e.g., `UserReader`, `UserWriter`, `UserAuthenticator`)	Clean ISP; moderate interface count
Capability-Based	1 interface per capability (e.g., `Readable`, `Writable`, `Searchable`)	Maximum reuse; requires composition
Single-Method	1 interface per method (e.g., `CanCreateUser`, `CanDeleteUser`)	Ultimate ISP purity; explosion of types

Too Coarse (Under-Segregation)

•Fat interfaces with many methods
•Consumers depend on unused methods
•Changes ripple to unrelated components
•Testing requires excessive mocking
•Can't substitute implementations

Too Fine (Over-Segregation)

•Explosion of interface types
•DI containers become unmanageable
•Cognitive load tracking relationships
•Excessive type declarations
•Composition becomes a puzzle

The Sweet Spot is Contextual

Signs of Over-Segregation

Over-segregation is less common than under-segregation, but it happens—especially when developers take ISP advice to an extreme. Recognize these warning signs:

Over-Segregation Symptoms

•Dependency injection has 10+ constructor parameters — Each tiny interface becomes a separate dependency
•Interfaces are always used together — If consumers always import 5 interfaces together, they should be one interface
•Interface names require context to understand — ICanProcessPaymentStep3After is too granular
•Refactoring touches dozens of interface files — A simple change cascades through the type system
•New developers are overwhelmed — Finding where functionality lives requires archaeology
•Composition boilerplate exceeds business logic — More code glues interfaces together than does actual work

Over-Segregation Example
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
// Over-segregated - each method is its own interface
interface UserCreator {
    createUser(data: CreateUserDTO): Promise<User>;
}
 
interface UserReaderById {
    getUserById(id: string): Promise<User | null>;
}
 
interface UserReaderByEmail {
    getUserByEmail(email: string): Promise<User | null>;
}
 
interface UserUpdater {
    updateUser(id: string, data: UpdateUserDTO): Promise<User>;
}
 
interface UserDeleter {
    deleteUser(id: string): Promise<void>;
}
 
interface UserExistenceChecker {
    userExists(id: string): Promise<boolean>;
}
 
interface UserCounter {
    countUsers(): Promise<number>;
}
 
// Now a service that needs basic CRUD has this nightmare:
class UserProfileService {
    constructor(
        private userReaderById: UserReaderById,
        private userReaderByEmail: UserReaderByEmail,
        private userUpdater: UserUpdater,
        private userExistenceChecker: UserExistenceChecker,
        // ... and so on
    ) {}
    
    // 7 interface dependencies for basic profile management!
}
 
// DI container configuration becomes unreadable
container.bind<UserCreator>(TYPES.UserCreator).to(UserRepositoryImpl);
container.bind<UserReaderById>(TYPES.UserReaderById).to(UserRepositoryImpl);
container.bind<UserReaderByEmail>(TYPES.UserReaderByEmail).to(UserRepositoryImpl);
container.bind<UserUpdater>(TYPES.UserUpdater).to(UserRepositoryImpl);
container.bind<UserDeleter>(TYPES.UserDeleter).to(UserRepositoryImpl);
container.bind<UserExistenceChecker>(TYPES.UserExistenceChecker).to(UserRepositoryImpl);
container.bind<UserCounter>(TYPES.UserCounter).to(UserRepositoryImpl);
// All 7 bindings point to the same implementation!

The Cohesion Principle for Granularity

Cohesion Indicators for Keeping Methods Together:

Methods Should Stay Together When...

•They operate on the same state — getBalance() and deposit() both work with account balance
•They're called in sequence — openTransaction(), commit(), rollback() are a unit
•They satisfy a single user story — "As a user, I can view and edit my profile" = read + update together
•They change together — Adding a field means updating both getter and setter
•Splitting would require passing data between interfaces — If methodA() produces data that methodB() consumes, they're cohesive

Cohesive Interface Design
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
// Appropriate granularity - cohesive method groups
 
// User identity management - cohesive because:
// - Same data (user identity, credentials)
// - Same stakeholder (auth team)
// - Called together during login/registration flows
interface UserIdentityManager {
    findByCredentials(email: string, password: string): Promise<User | null>;
    createUser(data: CreateUserDTO): Promise<User>;
    updateCredentials(userId: string, newEmail?: string, newPassword?: string): Promise<void>;
    verifyEmail(userId: string, token: string): Promise<boolean>;
}
 
// User profile - cohesive because:
// - Different data (display info, preferences)
// - Different stakeholder (product team)
// - Called together during profile views/edits
interface UserProfileManager {
    getProfile(userId: string): Promise<UserProfile>;
    updateProfile(userId: string, data: UpdateProfileDTO): Promise<void>;
    uploadAvatar(userId: string, image: Buffer): Promise<string>;
    getPreferences(userId: string): Promise<UserPreferences>;
    updatePreferences(userId: string, prefs: UserPreferences): Promise<void>;
}
 
// User social graph - cohesive because:
// - Different data (relationships)
// - Different stakeholder (social features team)
// - All relate to user connections
interface UserSocialGraph {
    follow(userId: string, targetUserId: string): Promise<void>;
    unfollow(userId: string, targetUserId: string): Promise<void>;
    getFollowers(userId: string): Promise<User[]>;
    getFollowing(userId: string): Promise<User[]>;
    blockUser(userId: string, blockedUserId: string): Promise<void>;
}
 
// Now services depend on what they need, but not excessively
class AuthService {
    constructor(private identity: UserIdentityManager) {}
    // 1 dependency for auth concerns
}
 
class ProfileController {
    constructor(
        private identity: UserIdentityManager,
        private profile: UserProfileManager
    ) {}
    // 2 dependencies for profile with auth
}
 
class SocialFeedService {
    constructor(
        private profile: UserProfileManager,
        private social: UserSocialGraph
    ) {}
    // 2 dependencies for social features
}

The 3-6 Method Rule of Thumb

Role-Based Granularity Strategy

Identify Roles, Not Individual Methods:

Role-Based Interface Design
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
// Role identification for Order domain
 
// Role: Order Creator
// Who plays this role: Checkout service, Order import tool, API endpoint
// Methods needed: creating orders from various sources
interface OrderCreator {
    createFromCart(cart: Cart, customer: Customer): Promise<Order>;
    createFromImport(data: OrderImportData): Promise<Order>;
    createDraft(partial: Partial<Order>): Promise<DraftOrder>;
}
 
// Role: Order Reader
// Who plays this role: Order details page, Customer dashboard, API
// Methods needed: retrieving orders in various ways
interface OrderReader {
    getById(id: string): Promise<Order | null>;
    getByCustomer(customerId: string): Promise<Order[]>;
    search(criteria: OrderSearchCriteria): Promise<Page<Order>>;
}
 
// Role: Order State Changer
// Who plays this role: Warehouse system, Admin dashboard, Background jobs
// Methods needed: transitioning order states
interface OrderStateChanger {
    submit(orderId: string): Promise<void>;
    confirm(orderId: string): Promise<void>;
    cancel(orderId: string, reason: CancellationReason): Promise<void>;
    fulfill(orderId: string, fulfillment: FulfillmentDetails): Promise<void>;
    complete(orderId: string): Promise<void>;
}
 
// Role: Order Financial Handler
// Who plays this role: Finance system, Refund processor, Invoicing
// Methods needed: financial operations on orders
interface OrderFinancialHandler {
    applyDiscount(orderId: string, discount: Discount): Promise<void>;
    processRefund(orderId: string, amount: Money): Promise<Refund>;
    generateInvoice(orderId: string): Promise<Invoice>;
}
 
// Consumers declare which roles they play
class CheckoutService implements OrderCreater {
    // Only implements creation role
}
 
class CustomerDashboardService {
    constructor(private reader: OrderReader) {
        // Only depends on reading role
    }
}
 
class WarehouseIntegration {
    constructor(
        private reader: OrderReader,
        private stateChanger: OrderStateChanger
    ) {
        // Reads orders and changes their state
    }
}

Benefits of Role-Based Granularity:

Natural sizing: Roles typically encompass 3-7 related methods
Clear naming: Role names like Creator, Reader, Handler are intuitive
Stakeholder alignment: Each role often maps to a team or feature area
Testability: Mock entire roles, not individual operations
Evolution-friendly: New capabilities fit into existing roles or form new ones

Composition Over Proliferation

When interfaces are appropriately sized, consumers can compose them to express exactly what they need. This is preferable to creating an interface for every possible combination of capabilities.

Composition Patterns:

Interface Composition
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
// Base role interfaces
interface Readable<T> {
    findById(id: string): Promise<T | null>;
    findAll(filter?: Filter): Promise<T[]>;
}
 
interface Writable<T> {
    save(entity: T): Promise<T>;
    delete(id: string): Promise<void>;
}
 
interface Searchable<T> {
    search(query: SearchQuery): Promise<Page<T>>;
    count(filter?: Filter): Promise<number>;
}
 
// Composition via intersection types
type ReadWriteRepository<T> = Readable<T> & Writable<T>;
type FullRepository<T> = Readable<T> & Writable<T> & Searchable<T>;
 
// Or explicit combined interfaces when semantically meaningful
interface CRUDRepository<T> extends Readable<T>, Writable<T> {}
 
// Consumers choose their composition
class ReadOnlyReportService {
    constructor(private products: Readable<Product>) {
        // Can only read - write operations not available
    }
}
 
class InventoryManager {
    constructor(private products: ReadWriteRepository<Product>) {
        // Can read and write
    }
}
 
class ProductSearchController {
    constructor(private products: Searchable<Product>) {
        // Only search capability
    }
}
 
// Implementation provides all capabilities
class ProductRepository implements FullRepository<Product> {
    findById(id: string) { /* ... */ }
    findAll(filter?: Filter) { /* ... */ }
    save(entity: Product) { /* ... */ }
    delete(id: string) { /* ... */ }
    search(query: SearchQuery) { /* ... */ }
    count(filter?: Filter) { /* ... */ }
}
 
// DI binds the full implementation; consumers see only their declared type
container.bind<FullRepository<Product>>(TYPES.ProductRepo).to(ProductRepository);

Composition vs. Inheritance of Interfaces

The Aggregation Pattern for Complex Domains

The Pattern:

Design segregated role interfaces (ISP-compliant)
Create an aggregate interface that extends all roles (convenience)
Consumers choose: specific roles or the aggregate
The aggregate exists for convenience, not because ISP requires it

Aggregator Pattern
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
// Step 1: Segregated role interfaces
interface OrderReader {
    getOrder(id: string): Promise<Order | null>;
    getOrdersByCustomer(customerId: string): Promise<Order[]>;
}
 
interface OrderWriter {
    createOrder(data: CreateOrderDTO): Promise<Order>;
    updateOrder(id: string, data: UpdateOrderDTO): Promise<Order>;
    deleteOrder(id: string): Promise<void>;
}
 
interface OrderStateManager {
    submitOrder(id: string): Promise<void>;
    cancelOrder(id: string): Promise<void>;
    fulfillOrder(id: string): Promise<void>;
}
 
interface OrderSearcher {
    searchOrders(criteria: SearchCriteria): Promise<Page<Order>>;
    countOrders(filter?: OrderFilter): Promise<number>;
}
 
// Step 2: Aggregate interface for convenience
interface OrderService extends 
    OrderReader, 
    OrderWriter, 
    OrderStateManager, 
    OrderSearcher {
    // No additional methods - just combines roles
}
 
// Step 3: Consumers CHOOSE their dependency level
// Focused consumers use specific roles:
class OrderDetailsController {
    constructor(private orderReader: OrderReader) {
        // Minimal dependency
    }
}
 
class WarehouseIntegration {
    constructor(private stateManager: OrderStateManager) {
        // Only state transitions
    }
}
 
// Full-service consumers use the aggregate:
class OrderAdminDashboard {
    constructor(private orderService: OrderService) {
        // Explicitly needs all capabilities
    }
}
 
// Step 4: Implementation provides the aggregate
class OrderServiceImpl implements OrderService {
    // Implements all methods from all interfaces
}
 
// DI configuration can bind both ways
container.bind<OrderService>(TYPES.OrderService).to(OrderServiceImpl);
container.bind<OrderReader>(TYPES.OrderReader).toService(TYPES.OrderService);
container.bind<OrderWriter>(TYPES.OrderWriter).toService(TYPES.OrderService);
// Narrow dependencies resolve to the same implementation

Aggregates Don't Violate ISP

Contextual Granularity Decisions

The right granularity depends on context. Here's how to adjust your approach based on system characteristics:

Granularity Guidelines by Context
Context	Lean Toward	Rationale
Microservices architecture	Finer granularity	Each service already isolated; clear ownership matters
Monolithic CRUD application	Coarser granularity	Less change friction; simpler navigation
Library/SDK for external consumers	Finer granularity	Consumers can't refactor your code; flexibility crucial
Internal team code	Moderate granularity	Can refactor if needed; balance complexity
High team turnover	Finer granularity with clear naming	Self-documentation via interface roles
Mature, stable domain	Coarser granularity	Changes are rare; simplicity wins
Rapidly evolving domain	Finer granularity	Isolation protects against change ripple
Strong testing requirements	Finer granularity	Easier mocking, clearer test scope

Context-Aware Decisions
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
// Example: E-commerce platform decisions
 
// CONTEXT: Payment integration (external dependency, high change risk)
// DECISION: Fine granularity to isolate vendor-specific changes
 
interface PaymentAuthorizer {
    authorize(amount: Money, method: PaymentMethod): Promise<AuthorizationResult>;
}
 
interface PaymentCapturer {
    capture(authorizationId: string): Promise<CaptureResult>;
}
 
interface PaymentRefunder {
    refund(transactionId: string, amount?: Money): Promise<RefundResult>;
}
 
// Rationale: Payment vendors change APIs frequently.
// Segregated interfaces mean only affected operations need updates.
 
 
// CONTEXT: User profile (internal, stable domain)
// DECISION: Moderate granularity - role-based but not per-method
 
interface UserProfileService {
    getProfile(userId: string): Promise<UserProfile>;
    updateProfile(userId: string, data: ProfileUpdateDTO): Promise<void>;
    uploadAvatar(userId: string, image: Buffer): Promise<string>;
    getActivityHistory(userId: string): Promise<ActivityEntry[]>;
}
 
// Rationale: Profile operations are stable and commonly used together.
// Splitting into getProfile/updateProfile/avatar/history would add
// complexity without benefit - these are always used by profile consumers.
 
 
// CONTEXT: Admin analytics (internal, power users)
// DECISION: Coarser granularity - admins use many features together
 
interface AdminDashboardService {
    getUserMetrics(timeRange: TimeRange): Promise<UserMetrics>;
    getRevenueMetrics(timeRange: TimeRange): Promise<RevenueMetrics>;
    getSystemHealth(): Promise<SystemHealth>;
    generateReport(type: ReportType, options: ReportOptions): Promise<Report>;
    exportData(format: ExportFormat, filter: DataFilter): Promise<Buffer>;
}
 
// Rationale: Admin dashboard always shows all metrics together.
// Splitting would add DI complexity without benefit - there's only
// one consumer (AdminDashboard) that needs all capabilities.

Refactoring Granularity

What if you've realized your interfaces are at the wrong granularity level—either too coarse or too fine? Refactoring is possible, but requires care.

From Coarse to Fine (Splitting):

Splitting Strategy

•Identify role boundaries — Use consumer analysis to find natural split points
•Create new interfaces — Define the segregated interfaces alongside existing monolith
•Make monolith extend new interfaces — FatInterface extends RoleA, RoleB, RoleC
•Gradually migrate consumers — Update each consumer to depend on specific roles
•Deprecate the monolith — Once all consumers migrated, remove the fat interface

From Fine to Coarse (Merging):

Merging Strategy

•Identify always-together interfaces — Find interfaces that every consumer imports together
•Create combined interface — Either intersection type or new interface extending all
•Update consumers — Replace multiple dependencies with the combined interface
•Evaluate orphaned interfaces — Keep granular interfaces if any consumer uses them alone
•Simplify DI configuration — Reduce binding count to combined interface

Granularity Refactoring Example
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
// BEFORE: Over-segregated interfaces
interface ProductGetter {
    getProduct(id: string): Promise<Product>;
}
interface ProductLister {
    listProducts(): Promise<Product[]>;
}
interface ProductSearcher {
    searchProducts(query: string): Promise<Product[]>;
}
interface ProductCreator {
    createProduct(data: CreateProductDTO): Promise<Product>;
}
interface ProductUpdater {
    updateProduct(id: string, data: UpdateProductDTO): Promise<Product>;
}
interface ProductDeleter {
    deleteProduct(id: string): Promise<void>;
}
 
// Consumer has 6 dependencies for basic CRUD + search
class ProductService {
    constructor(
        private getter: ProductGetter,
        private lister: ProductLister,
        private searcher: ProductSearcher,
        private creator: ProductCreator,
        private updater: ProductUpdater,
        private deleter: ProductDeleter,
    ) {}
}
 
// AFTER: Role-based consolidation
// Step 1: Create combined role interfaces
interface ProductReader {
    getProduct(id: string): Promise<Product>;
    listProducts(): Promise<Product[]>;
    searchProducts(query: string): Promise<Product[]>;
}
 
interface ProductWriter {
    createProduct(data: CreateProductDTO): Promise<Product>;
    updateProduct(id: string, data: UpdateProductDTO): Promise<Product>;
    deleteProduct(id: string): Promise<void>;
}
 
// Step 2: Keep granular as aliases if any consumers still need them
type ProductGetter = Pick<ProductReader, 'getProduct'>;
type ProductSearcher = Pick<ProductReader, 'searchProducts'>;
// ... etc, for backward compatibility
 
// Step 3: Update consumers to role-based dependencies
class ProductService {
    constructor(
        private reader: ProductReader,
        private writer: ProductWriter,
    ) {
        // 2 dependencies instead of 6
    }
}
 
// Step 4: Simplify DI
container.bind<ProductReader>(TYPES.ProductReader).to(ProductRepositoryImpl);
container.bind<ProductWriter>(TYPES.ProductWriter).to(ProductRepositoryImpl);
 
// Step 5: Remove aliases after all consumers migrated
// (Delete the type aliases and granular interface types)

Summary: Mastering Interface Granularity

Interface granularity is an art, not a science. But informed by the principles in this page, you can make deliberate, defensible decisions about how to size your interfaces.

Key Takeaways

•Granularity is a spectrum — Both extremes (monolithic and per-method) are problematic
•Over-segregation creates its own problems — DI explosion, cognitive overload, excessive composition boilerplate
•Use cohesion as your guide — Methods that belong together (same state, sequence, story) should stay together
•Role-based granularity is the sweet spot — One interface per role naturally sizes to 3-7 methods
•Composition is powerful — Small interfaces combine via intersection types for consumers needing multiple roles
•Aggregates are convenience, not coercion — Provide combined interfaces for power users without forcing them on focused consumers
•Context matters — Adjust granularity based on architecture style, team composition, and change frequency
•Refactoring is possible — Both splitting and merging can be done incrementally with backward compatibility

Module Complete!

You've now mastered the Interface Segregation Principle in its entirety:

Page 1 showed you ISP in real-world frameworks and systems
Page 2 cataloged common ISP mistakes and anti-patterns
Page 3 gave you a systematic checklist for ISP evaluation
Page 4 taught you to balance granularity for practical maintainability

Module Complete

4 / 4