System Design (HLD)Modular Monolith

Modular Monolith: The Middle Ground

LevelIntermediate

Duration60 mins

TopicModular Monolith

2 / 4

Module Boundaries

The Hardest Problem in Architecture

Ask any seasoned architect what the hardest problem in software design is, and you'll often hear: where to draw the lines. Getting module boundaries wrong is expensive—too granular and you drown in cross-module coordination; too coarse and you're back to a monolithic tangle.

The boundaries you choose today will shape your codebase for years. They determine which changes are easy and which are painful. They influence team structures, testing strategies, and eventual service extraction paths.

This page equips you with the frameworks, heuristics, and practical techniques to draw boundaries that serve your system well—boundaries that are stable enough to rely on but flexible enough to evolve.

What You Will Learn

By the end of this page, you will understand how to identify natural boundaries using Domain-Driven Design, analyze dependencies to validate your choices, and implement enforcement mechanisms that preserve your architecture over time.

Domain-Driven Boundaries

The most effective approach to module boundaries comes from Domain-Driven Design (DDD). Eric Evans' seminal work gives us two key concepts: Bounded Contexts and the Ubiquitous Language.

Bounded Contexts:

A bounded context is a semantic boundary within which a particular model applies. Inside this boundary, terms have precise meanings and the model is internally consistent. Outside the boundary, the same terms might mean something different.

Example: The Word 'Customer'

In the Sales context, a Customer is a prospect or buyer—someone with a shopping cart, wish lists, and purchase history
In the Support context, a Customer is a ticket submitter—someone with open issues, satisfaction scores, and support tier
In the Billing context, a Customer is an account—someone with payment methods, invoices, and credit limits
In the Shipping context, a Customer is a destination—someone with addresses, delivery preferences, and order tracking

Each context has a valid, internally consistent model of 'Customer'. Forcing these into a single Customer entity creates a bloated, incoherent model that serves no context well.

Converting Mermaid diagram...

Ubiquitous Language:

Within each bounded context, the team develops a precise vocabulary—the ubiquitous language. This language appears in code, documentation, and conversations. When the language changes, the code changes. When unexpected domain concepts emerge in code, it signals a modeling problem.

Translating to Module Boundaries:

Each bounded context becomes a module. The bounded context's explicit interfaces become the module's public API. The ubiquitous language shapes the module's internal structure and naming.

The Litmus Test

If domain experts from different areas of your business use the same term with different meanings, you've found a context boundary. If they use different terms for the same concept, you might be over-splitting. Listen to how experts actually talk about the domain.

Identifying Natural Boundaries

Beyond DDD theory, practical heuristics help identify where boundaries naturally want to exist. These heuristics triangulate toward good boundary placement.

Heuristic 1: Cohesion Analysis

Classes and functions that change together, are tested together, and address the same business capability belong together. High cohesion within a boundary, low coupling across boundaries. This is the modular equivalent of the Single Responsibility Principle.

Heuristic 2: Change Rate Analysis

Examine your version control history. Which files tend to change in the same commits? Which directories evolve together? Clustering by change patterns often reveals implicit boundaries that weren't part of the original design.

Heuristic 3: Team Ownership Patterns

Boundaries should align with teams. If one team owns multiple modules, they should be related. If one module requires coordination across multiple teams, it may be too large or misaligned.

Analyzing Git History for Coupling
Bash
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
# Find files that frequently change together
# This reveals implicit coupling that may indicate module boundaries
 
# Get pairs of files that changed in the same commit
git log --name-only --pretty=format: | \
  awk 'NF' | \
  sort | uniq -c | sort -rn | head -50
 
# Find the most coupled file pairs
git log --name-only --pretty=format: | \
  grep -v '^$' | \
  awk '
    NF { files[NR] = $0 }
    !NF && NR > 1 {
      for (i in files) {
        for (j in files) {
          if (i < j) pairs[files[i] "," files[j]]++
        }
      }
      delete files
    }
  END {
    for (pair in pairs) print pairs[pair], pair
  }
  ' | sort -rn | head -20
 
# Visualize directory coupling
git log --name-only --pretty=format: | \
  awk -F'/' 'NF > 1 { print $1 "/" $2 }' | \
  sort | uniq -c | sort -rn

Heuristic 4: Data Ownership

Ask: 'Who is the authoritative source for this data?' The answer often reveals module boundaries. If an Order has a total amount, the Order module owns it. If a User has a loyalty tier, the User module—or possibly a separate Loyalty module—owns it.

Data that needs to be consistent across operations often belongs in the same module. Data that can be eventually consistent often belongs in separate modules.

Heuristic 5: Business Capability Mapping

List your business capabilities: managing users, processing orders, handling payments, tracking inventory, generating reports. Each capability is a candidate module. Some capabilities are clearly separate; others may be grouped or split based on team size and complexity.

Boundary Identification Checklist

•Linguistic Boundary: Do experts use different vocabulary or the same terms with different meanings?
•Change Coupling: Do these components change together in version control?
•Data Affinity: Does this data need to be consistent or can it be eventually consistent?
•Team Alignment: Can one team own this boundary, or does it require coordination?
•Lifecycle Coherence: Do these components deploy, scale, and fail together?
•Business Capability: Does this map to a recognizable business function?

Beware of False Boundaries

Technical layers (controllers, services, repositories) are NOT good module boundaries. They create horizontal slices that require coordination for every feature. Good modules are vertical slices—containing everything needed for a business capability from API to data.

Boundary Patterns

Once you've identified where boundaries should exist, you need to implement them correctly. Several patterns help establish and maintain module boundaries.

Pattern 1: Facade Pattern (Public API)

Each module exposes a single facade that defines its public contract. All external access goes through this facade. Internal classes are not directly accessible from outside the module.

Module Facade Pattern
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
// TypeScript - Module Public API
 
// modules/order/api/OrderService.ts - The single entry point
export interface OrderService {
  // Commands
  createOrder(userId: string, items: OrderItemInput[]): Promise<OrderId>;
  cancelOrder(orderId: OrderId): Promise<void>;
  
  // Queries  
  getOrderById(orderId: OrderId): Promise<OrderDTO | null>;
  getOrdersByUser(userId: string): Promise<OrderDTO[]>;
}
 
// modules/order/api/types.ts - Public DTOs
export interface OrderDTO {
  id: string;
  userId: string;
  items: OrderItemDTO[];
  status: OrderStatus;
  total: Money;
  createdAt: Date;
}
 
export interface OrderItemDTO {
  productId: string;
  quantity: number;
  unitPrice: Money;
  subtotal: Money;
}
 
// modules/order/api/events.ts - Published domain events
export interface OrderCreatedEvent {
  type: 'order.created';
  orderId: string;
  userId: string;
  items: Array<{ productId: string; quantity: number }>;
  occurredAt: Date;
}
 
export interface OrderCancelledEvent {
  type: 'order.cancelled';
  orderId: string;
  reason: string;
  occurredAt: Date;
}
 
// modules/order/index.ts - Single export point
export { OrderService } from './api/OrderService';
export type { OrderDTO, OrderItemDTO, OrderStatus } from './api/types';
export type { OrderCreatedEvent, OrderCancelledEvent } from './api/events';
 
// INTERNAL CLASSES ARE NOT EXPORTED
// These stay hidden inside the module:
// - Order (domain entity)
// - OrderRepository
// - OrderDomainService
// - PriceCalculator
// - etc.

Pattern 2: Anti-Corruption Layer (ACL)

When modules need to communicate, an Anti-Corruption Layer translates between their models. This prevents one module's model from leaking into another, maintaining each module's integrity.

Anti-Corruption Layer 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
// The Order module needs user information but shouldn't depend
// on the User module's internal model
 
// modules/order/internal/adapters/UserAdapter.ts
import { UserService, UserDTO } from '@/modules/user';
 
// Order module's view of a user - only what Order needs
interface OrderUser {
  id: string;
  displayName: string;
  shippingPreference: 'standard' | 'express';
}
 
export class UserAdapter {
  constructor(private userService: UserService) {}
 
  async getOrderUser(userId: string): Promise<OrderUser | null> {
    const userDto = await this.userService.getUserById(userId);
    if (!userDto) return null;
    
    // Translation layer - map User module's model to Order's needs
    return {
      id: userDto.id,
      displayName: userDto.firstName + ' ' + userDto.lastName,
      shippingPreference: this.mapShippingPreference(userDto.membershipTier),
    };
  }
 
  private mapShippingPreference(tier: string): 'standard' | 'express' {
    // Order module decides its own mapping logic
    return tier === 'premium' || tier === 'enterprise' 
      ? 'express' 
      : 'standard';
  }
}
 
// Now Order module uses OrderUser internally
// If User module changes, only UserAdapter needs updating
// Order's internal code is protected from changes in User module

Pattern 3: Domain Events for Loose Coupling

Rather than modules calling each other directly, publish domain events. Interested modules subscribe to events they care about. This inverts dependencies and enables modules to evolve independently.

Event-Based Module Communication
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
// modules/order/internal/services/OrderApplicationService.ts
 
import { EventBus } from '@/shared/events';
import { OrderCreatedEvent } from '../api/events';
 
export class OrderApplicationService {
  constructor(
    private orderRepository: OrderRepository,
    private eventBus: EventBus
  ) {}
 
  async createOrder(command: CreateOrderCommand): Promise<OrderId> {
    const order = Order.create(command.userId, command.items);
    await this.orderRepository.save(order);
    
    // Publish event - other modules can subscribe
    await this.eventBus.publish<OrderCreatedEvent>({
      type: 'order.created',
      orderId: order.id.value,
      userId: command.userId,
      items: command.items.map(i => ({
        productId: i.productId,
        quantity: i.quantity,
      })),
      occurredAt: new Date(),
    });
 
    return order.id;
  }
}
 
// modules/inventory/internal/handlers/OrderEventHandler.ts
 
import { EventHandler, on } from '@/shared/events';
import { OrderCreatedEvent } from '@/modules/order';
 
export class OrderEventHandler {
  constructor(private inventoryService: InventoryService) {}
 
  @on('order.created')
  async handleOrderCreated(event: OrderCreatedEvent) {
    // Inventory module reacts to Order module's event
    // No direct coupling - Order doesn't know Inventory exists
    for (const item of event.items) {
      await this.inventoryService.reserveStock(
        item.productId, 
        item.quantity
      );
    }
  }
}
 
// modules/notification/internal/handlers/OrderEventHandler.ts
 
export class NotificationOrderEventHandler {
  @on('order.created')  
  async handleOrderCreated(event: OrderCreatedEvent) {
    // Notification module also subscribes
    // Multiple modules can react to the same event
    await this.sendOrderConfirmationEmail(event.userId, event.orderId);
  }
}

In-Process Events

In a modular monolith, these events are typically in-process (not over network). The EventBus is a simple observer pattern, not a message queue. This keeps things simple while maintaining loose coupling. If you later extract a module into a service, the event pattern translates naturally to message queues.

Dependency Analysis and Validation

Proposed boundaries should be validated through dependency analysis. Poor boundaries manifest as:

Cyclic dependencies between modules
Fat interfaces that expose too much
High fan-in to certain modules (everyone depends on them)
High fan-out from certain modules (they depend on everyone)

Techniques for Validation:

Dependency Validation Techniques

•Dependency Graphs — Visualize module dependencies. Look for cycles, hubs, and unexpected connections. Tools like dependency-cruiser (JavaScript), JDepend (Java), or NDepend (.NET) can generate these automatically.
•Instability Metrics — For each module, calculate: Instability = Efferent Coupling / (Efferent + Afferent). Stable modules (low instability) should be abstract; unstable modules (high instability) should be concrete. Mismatches indicate design problems.
•Abstractness Analysis — Highly depended-upon modules should be abstract (mostly interfaces). If a concrete implementation is widely depended upon, changes will ripple across the codebase.
•Cycle Detection — Any cycle in the module dependency graph is a red flag. Cycles make independent deployment impossible and complicate reasoning about change impact.

Dependency Analysis Configuration
JavaScript
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
// .dependency-cruiser.js - Configuration for JavaScript/TypeScript projects
 
module.exports = {
  forbidden: [
    // No cycles between modules
    {
      name: "no-circular-between-modules",
      severity: "error",
      from: { path: "^modules/([^/]+)/" },
      to: { circular: true, path: "^modules/(?!\1)[^/]+/" }
    },
    
    // Modules can only access other modules' public APIs
    {
      name: "no-internal-access",
      severity: "error",
      from: { path: "^modules/([^/]+)/" },
      to: { 
        path: "^modules/(?!\1)[^/]+/internal/",
        pathNot: "^modules/\1/" // Allow access to own internals
      }
    },
    
    // No direct database access from outside module
    {
      name: "no-cross-module-repository-access",
      severity: "error",
      from: { path: "^modules/([^/]+)/" },
      to: { 
        path: "^modules/(?!\1)[^/]+/.*[Rr]epository",
      }
    },
 
    // Shared kernel should be minimal and not depend on modules
    {
      name: "shared-should-not-depend-on-modules",
      severity: "error",
      from: { path: "^shared/" },
      to: { path: "^modules/" }
    },
  ],
  
  options: {
    doNotFollow: { path: "node_modules" },
    tsPreCompilationDeps: true,
    enhancedResolveOptions: {
      exportsFields: ["exports"],
      conditionNames: ["import", "require", "node", "default"],
    },
  }
};

Visualizing Dependencies:

Generate dependency graphs regularly and review them as part of architecture governance. A healthy modular monolith shows:

Minimal dependencies between modules
All dependencies flowing through public APIs
No cycles
Clear layers (shared kernel → modules → application entry point)

Converting Mermaid diagram...

Red Flags in Dependency Graphs

If your dependency graph looks like a hairball, your modular structure has eroded. Common symptoms: bidirectional dependencies between modules, shared code depending on modules, every module depending on a 'utils' or 'common' module that keeps growing.

Handling Cross-Cutting Concerns

Even with good boundaries, some concerns span multiple modules: logging, authentication, transactions, auditing. These cross-cutting concerns require special handling to avoid creating dependencies that violate module boundaries.

Strategy 1: Shared Kernel

A minimal shared kernel contains types and utilities that all modules need. Keep it extremely minimal—only things that genuinely belong everywhere. Common candidates:

Value types (Money, EmailAddress, DateRange)
Core events infrastructure
Authentication context
Logging interfaces

Shared Kernel Structure
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
// shared/types/money.ts - Value type used everywhere
export class Money {
  constructor(
    public readonly amount: number,
    public readonly currency: string
  ) {}
 
  add(other: Money): Money {
    if (this.currency !== other.currency) {
      throw new Error('Cannot add different currencies');
    }
    return new Money(this.amount + other.amount, this.currency);
  }
 
  multiply(factor: number): Money {
    return new Money(this.amount * factor, this.currency);
  }
 
  equals(other: Money): boolean {
    return this.amount === other.amount && this.currency === other.currency;
  }
}
 
// shared/events/EventBus.ts - Infrastructure for module communication
export interface DomainEvent {
  type: string;
  occurredAt: Date;
}
 
export interface EventBus {
  publish<T extends DomainEvent>(event: T): Promise<void>;
  subscribe<T extends DomainEvent>(
    eventType: string, 
    handler: (event: T) => Promise<void>
  ): void;
}
 
// shared/context/AuthContext.ts - Who is making the request
export interface AuthContext {
  userId: string;
  roles: string[];
  permissions: string[];
  tenantId?: string;
}
 
// shared/index.ts - Controlled exports
export { Money } from './types/money';
export type { DomainEvent, EventBus } from './events/EventBus';
export type { AuthContext } from './context/AuthContext';
 
// KEEP THE SHARED KERNEL SMALL
// If in doubt, put it in a module, not shared

Strategy 2: Aspect-Oriented Approaches

For concerns like logging and metrics, use aspects or middleware that wrap module boundaries without requiring module code to know about them:

Decorator pattern for wrapping service calls
Middleware at the application entry point
Dependency injection to swap implementations

Strategy 3: Infrastructure Layer

Some cross-cutting concerns belong in an infrastructure layer that modules consume but don't depend on directly:

Database connections and transactions
HTTP client configuration
Caching infrastructure
Message queue adapters

Modules depend on interfaces; infrastructure provides implementations.

Guidelines for Cross-Cutting Concerns

•Default to module ownership — Most things belong in a module, not shared. When in doubt, don't share.
•Shared kernel stays small — If it keeps growing, you're using it wrong. Audit it regularly.
•Use interfaces for infrastructure — Modules depend on abstractions; infrastructure provides implementations.
•Apply aspects externally — Logging, metrics, and tracing should wrap modules, not be embedded in them.
•Avoid 'common' or 'utils' modules — These become dumping grounds. Name things by what they are, not by 'things we couldn't categorize'.

The Gravity of Shared Code

Shared code has gravity—it attracts more code. Once a 'utils' module exists, developers add to it rather than finding the right home. Fight this by requiring explicit justification for any addition to shared code and by splitting shared concerns into specific, named packages.

Refactoring Existing Boundaries

Initial boundary choices are rarely perfect. As the domain evolves and understanding deepens, boundaries need adjustment. The key is making boundary changes incrementally and safely.

When to Refactor Boundaries:

Signs Boundaries Need Adjustment

•Shotgun surgery — Simple changes require modifications across multiple modules
•Feature envy — One module constantly reaches into another's data
•Parallel hierarchies — Similar structures duplicated across modules
•Growing interface — Module APIs keep expanding to accommodate new use cases
•Team friction — Teams frequently step on each other's toes
•Vocabulary confusion — Same terms used inconsistently across modules

Refactoring Strategies:

1. Bubble Context (Splitting)

When a module grows too large, extract a new module:

Identify the subset to extract
Create new module with its own API
Build adapter in original module that calls new module
Migrate callers from old code to new module's API
Remove the adapter once migration is complete

2. Merge Modules (Combining)

When modules are too granular:

Analyze which modules always change together
Create combined module with unified API
Migrate callers to new API
Deprecate old module APIs
Remove old modules

3. Strangler Pattern for Boundaries

For large-scale boundary changes:

Create new boundary alongside old
Gradually migrate functionality
Run both in parallel
Complete migration and retire old boundary

Boundaries Are Cheaper to Change Than Services

This is a key advantage of the modular monolith. Refactoring module boundaries is a refactoring—supported by IDE tools, covered by existing tests, and validated by the compiler. Refactoring service boundaries requires API versioning, deployment coordination, and often data migration. Get the boundaries right in the monolith before extracting.

Summary: Mastering Module Boundaries

Module boundaries are the fundamental structure of a modular monolith. Getting them right enables team autonomy, maintainable code, and future flexibility. Let's consolidate the key principles:

Key Takeaways

•Domain-Driven Design guides boundary identification — Bounded contexts and ubiquitous language reveal where boundaries naturally exist. Listen to domain experts.
•Multiple heuristics triangulate to good boundaries — Cohesion, change coupling, data ownership, team alignment, and business capabilities all provide signals.
•Boundaries are implemented through patterns — Facades expose public APIs, Anti-Corruption Layers translate between models, domain events enable loose coupling.
•Validation through dependency analysis — Tools that visualize and enforce dependencies catch boundary violations before they accumulate.
•Cross-cutting concerns need disciplined handling — Minimal shared kernel, aspect-oriented approaches, and infrastructure abstraction prevent coupling creep.
•Boundaries evolve with understanding — Expect to refactor boundaries as domain knowledge grows. The modular monolith makes this refactoring cheap.

What's Next:

With boundaries defined, the next page explores Preparing for Extraction—how to design your modular monolith so that modules can be extracted into services when the time is right. We'll cover data separation strategies, interface design for network boundaries, and the incremental path from module to service.

Page Complete

You now understand how to identify, implement, validate, and refactor module boundaries. Good boundaries enable team autonomy within a single codebase. Next, we'll prepare these boundaries for potential service extraction.

2 / 4

Loading learning content...

System Design (HLD)Modular Monolith

Modular Monolith: The Middle Ground

LevelIntermediate

Duration60 mins

TopicModular Monolith

2 / 4

Module Boundaries

The Hardest Problem in Architecture

What You Will Learn

Domain-Driven Boundaries

The most effective approach to module boundaries comes from Domain-Driven Design (DDD). Eric Evans' seminal work gives us two key concepts: Bounded Contexts and the Ubiquitous Language.

Bounded Contexts:

Example: The Word 'Customer'

In the Sales context, a Customer is a prospect or buyer—someone with a shopping cart, wish lists, and purchase history
In the Support context, a Customer is a ticket submitter—someone with open issues, satisfaction scores, and support tier
In the Billing context, a Customer is an account—someone with payment methods, invoices, and credit limits
In the Shipping context, a Customer is a destination—someone with addresses, delivery preferences, and order tracking

Each context has a valid, internally consistent model of 'Customer'. Forcing these into a single Customer entity creates a bloated, incoherent model that serves no context well.

Converting Mermaid diagram...

Ubiquitous Language:

Translating to Module Boundaries:

Each bounded context becomes a module. The bounded context's explicit interfaces become the module's public API. The ubiquitous language shapes the module's internal structure and naming.

The Litmus Test

Identifying Natural Boundaries

Beyond DDD theory, practical heuristics help identify where boundaries naturally want to exist. These heuristics triangulate toward good boundary placement.

Heuristic 1: Cohesion Analysis

Heuristic 2: Change Rate Analysis

Heuristic 3: Team Ownership Patterns

Boundaries should align with teams. If one team owns multiple modules, they should be related. If one module requires coordination across multiple teams, it may be too large or misaligned.

Analyzing Git History for Coupling
Bash
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
# Find files that frequently change together
# This reveals implicit coupling that may indicate module boundaries
 
# Get pairs of files that changed in the same commit
git log --name-only --pretty=format: | \
  awk 'NF' | \
  sort | uniq -c | sort -rn | head -50
 
# Find the most coupled file pairs
git log --name-only --pretty=format: | \
  grep -v '^$' | \
  awk '
    NF { files[NR] = $0 }
    !NF && NR > 1 {
      for (i in files) {
        for (j in files) {
          if (i < j) pairs[files[i] "," files[j]]++
        }
      }
      delete files
    }
  END {
    for (pair in pairs) print pairs[pair], pair
  }
  ' | sort -rn | head -20
 
# Visualize directory coupling
git log --name-only --pretty=format: | \
  awk -F'/' 'NF > 1 { print $1 "/" $2 }' | \
  sort | uniq -c | sort -rn

Heuristic 4: Data Ownership

Data that needs to be consistent across operations often belongs in the same module. Data that can be eventually consistent often belongs in separate modules.

Heuristic 5: Business Capability Mapping

Boundary Identification Checklist

•Linguistic Boundary: Do experts use different vocabulary or the same terms with different meanings?
•Change Coupling: Do these components change together in version control?
•Data Affinity: Does this data need to be consistent or can it be eventually consistent?
•Team Alignment: Can one team own this boundary, or does it require coordination?
•Lifecycle Coherence: Do these components deploy, scale, and fail together?
•Business Capability: Does this map to a recognizable business function?

Beware of False Boundaries

Boundary Patterns

Once you've identified where boundaries should exist, you need to implement them correctly. Several patterns help establish and maintain module boundaries.

Pattern 1: Facade Pattern (Public API)

Each module exposes a single facade that defines its public contract. All external access goes through this facade. Internal classes are not directly accessible from outside the module.

Module Facade Pattern
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
// TypeScript - Module Public API
 
// modules/order/api/OrderService.ts - The single entry point
export interface OrderService {
  // Commands
  createOrder(userId: string, items: OrderItemInput[]): Promise<OrderId>;
  cancelOrder(orderId: OrderId): Promise<void>;
  
  // Queries  
  getOrderById(orderId: OrderId): Promise<OrderDTO | null>;
  getOrdersByUser(userId: string): Promise<OrderDTO[]>;
}
 
// modules/order/api/types.ts - Public DTOs
export interface OrderDTO {
  id: string;
  userId: string;
  items: OrderItemDTO[];
  status: OrderStatus;
  total: Money;
  createdAt: Date;
}
 
export interface OrderItemDTO {
  productId: string;
  quantity: number;
  unitPrice: Money;
  subtotal: Money;
}
 
// modules/order/api/events.ts - Published domain events
export interface OrderCreatedEvent {
  type: 'order.created';
  orderId: string;
  userId: string;
  items: Array<{ productId: string; quantity: number }>;
  occurredAt: Date;
}
 
export interface OrderCancelledEvent {
  type: 'order.cancelled';
  orderId: string;
  reason: string;
  occurredAt: Date;
}
 
// modules/order/index.ts - Single export point
export { OrderService } from './api/OrderService';
export type { OrderDTO, OrderItemDTO, OrderStatus } from './api/types';
export type { OrderCreatedEvent, OrderCancelledEvent } from './api/events';
 
// INTERNAL CLASSES ARE NOT EXPORTED
// These stay hidden inside the module:
// - Order (domain entity)
// - OrderRepository
// - OrderDomainService
// - PriceCalculator
// - etc.

Pattern 2: Anti-Corruption Layer (ACL)

When modules need to communicate, an Anti-Corruption Layer translates between their models. This prevents one module's model from leaking into another, maintaining each module's integrity.

Anti-Corruption Layer 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
// The Order module needs user information but shouldn't depend
// on the User module's internal model
 
// modules/order/internal/adapters/UserAdapter.ts
import { UserService, UserDTO } from '@/modules/user';
 
// Order module's view of a user - only what Order needs
interface OrderUser {
  id: string;
  displayName: string;
  shippingPreference: 'standard' | 'express';
}
 
export class UserAdapter {
  constructor(private userService: UserService) {}
 
  async getOrderUser(userId: string): Promise<OrderUser | null> {
    const userDto = await this.userService.getUserById(userId);
    if (!userDto) return null;
    
    // Translation layer - map User module's model to Order's needs
    return {
      id: userDto.id,
      displayName: userDto.firstName + ' ' + userDto.lastName,
      shippingPreference: this.mapShippingPreference(userDto.membershipTier),
    };
  }
 
  private mapShippingPreference(tier: string): 'standard' | 'express' {
    // Order module decides its own mapping logic
    return tier === 'premium' || tier === 'enterprise' 
      ? 'express' 
      : 'standard';
  }
}
 
// Now Order module uses OrderUser internally
// If User module changes, only UserAdapter needs updating
// Order's internal code is protected from changes in User module

Pattern 3: Domain Events for Loose Coupling

Rather than modules calling each other directly, publish domain events. Interested modules subscribe to events they care about. This inverts dependencies and enables modules to evolve independently.

Event-Based Module Communication
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
// modules/order/internal/services/OrderApplicationService.ts
 
import { EventBus } from '@/shared/events';
import { OrderCreatedEvent } from '../api/events';
 
export class OrderApplicationService {
  constructor(
    private orderRepository: OrderRepository,
    private eventBus: EventBus
  ) {}
 
  async createOrder(command: CreateOrderCommand): Promise<OrderId> {
    const order = Order.create(command.userId, command.items);
    await this.orderRepository.save(order);
    
    // Publish event - other modules can subscribe
    await this.eventBus.publish<OrderCreatedEvent>({
      type: 'order.created',
      orderId: order.id.value,
      userId: command.userId,
      items: command.items.map(i => ({
        productId: i.productId,
        quantity: i.quantity,
      })),
      occurredAt: new Date(),
    });
 
    return order.id;
  }
}
 
// modules/inventory/internal/handlers/OrderEventHandler.ts
 
import { EventHandler, on } from '@/shared/events';
import { OrderCreatedEvent } from '@/modules/order';
 
export class OrderEventHandler {
  constructor(private inventoryService: InventoryService) {}
 
  @on('order.created')
  async handleOrderCreated(event: OrderCreatedEvent) {
    // Inventory module reacts to Order module's event
    // No direct coupling - Order doesn't know Inventory exists
    for (const item of event.items) {
      await this.inventoryService.reserveStock(
        item.productId, 
        item.quantity
      );
    }
  }
}
 
// modules/notification/internal/handlers/OrderEventHandler.ts
 
export class NotificationOrderEventHandler {
  @on('order.created')  
  async handleOrderCreated(event: OrderCreatedEvent) {
    // Notification module also subscribes
    // Multiple modules can react to the same event
    await this.sendOrderConfirmationEmail(event.userId, event.orderId);
  }
}

In-Process Events

Dependency Analysis and Validation

Proposed boundaries should be validated through dependency analysis. Poor boundaries manifest as:

Cyclic dependencies between modules
Fat interfaces that expose too much
High fan-in to certain modules (everyone depends on them)
High fan-out from certain modules (they depend on everyone)

Techniques for Validation:

Dependency Validation Techniques

•Dependency Graphs — Visualize module dependencies. Look for cycles, hubs, and unexpected connections. Tools like dependency-cruiser (JavaScript), JDepend (Java), or NDepend (.NET) can generate these automatically.
•Instability Metrics — For each module, calculate: Instability = Efferent Coupling / (Efferent + Afferent). Stable modules (low instability) should be abstract; unstable modules (high instability) should be concrete. Mismatches indicate design problems.
•Abstractness Analysis — Highly depended-upon modules should be abstract (mostly interfaces). If a concrete implementation is widely depended upon, changes will ripple across the codebase.
•Cycle Detection — Any cycle in the module dependency graph is a red flag. Cycles make independent deployment impossible and complicate reasoning about change impact.

Dependency Analysis Configuration
JavaScript
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
// .dependency-cruiser.js - Configuration for JavaScript/TypeScript projects
 
module.exports = {
  forbidden: [
    // No cycles between modules
    {
      name: "no-circular-between-modules",
      severity: "error",
      from: { path: "^modules/([^/]+)/" },
      to: { circular: true, path: "^modules/(?!\1)[^/]+/" }
    },
    
    // Modules can only access other modules' public APIs
    {
      name: "no-internal-access",
      severity: "error",
      from: { path: "^modules/([^/]+)/" },
      to: { 
        path: "^modules/(?!\1)[^/]+/internal/",
        pathNot: "^modules/\1/" // Allow access to own internals
      }
    },
    
    // No direct database access from outside module
    {
      name: "no-cross-module-repository-access",
      severity: "error",
      from: { path: "^modules/([^/]+)/" },
      to: { 
        path: "^modules/(?!\1)[^/]+/.*[Rr]epository",
      }
    },
 
    // Shared kernel should be minimal and not depend on modules
    {
      name: "shared-should-not-depend-on-modules",
      severity: "error",
      from: { path: "^shared/" },
      to: { path: "^modules/" }
    },
  ],
  
  options: {
    doNotFollow: { path: "node_modules" },
    tsPreCompilationDeps: true,
    enhancedResolveOptions: {
      exportsFields: ["exports"],
      conditionNames: ["import", "require", "node", "default"],
    },
  }
};

Visualizing Dependencies:

Generate dependency graphs regularly and review them as part of architecture governance. A healthy modular monolith shows:

Minimal dependencies between modules
All dependencies flowing through public APIs
No cycles
Clear layers (shared kernel → modules → application entry point)

Converting Mermaid diagram...

Red Flags in Dependency Graphs

Handling Cross-Cutting Concerns

Strategy 1: Shared Kernel

A minimal shared kernel contains types and utilities that all modules need. Keep it extremely minimal—only things that genuinely belong everywhere. Common candidates:

Value types (Money, EmailAddress, DateRange)
Core events infrastructure
Authentication context
Logging interfaces

Shared Kernel Structure
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
// shared/types/money.ts - Value type used everywhere
export class Money {
  constructor(
    public readonly amount: number,
    public readonly currency: string
  ) {}
 
  add(other: Money): Money {
    if (this.currency !== other.currency) {
      throw new Error('Cannot add different currencies');
    }
    return new Money(this.amount + other.amount, this.currency);
  }
 
  multiply(factor: number): Money {
    return new Money(this.amount * factor, this.currency);
  }
 
  equals(other: Money): boolean {
    return this.amount === other.amount && this.currency === other.currency;
  }
}
 
// shared/events/EventBus.ts - Infrastructure for module communication
export interface DomainEvent {
  type: string;
  occurredAt: Date;
}
 
export interface EventBus {
  publish<T extends DomainEvent>(event: T): Promise<void>;
  subscribe<T extends DomainEvent>(
    eventType: string, 
    handler: (event: T) => Promise<void>
  ): void;
}
 
// shared/context/AuthContext.ts - Who is making the request
export interface AuthContext {
  userId: string;
  roles: string[];
  permissions: string[];
  tenantId?: string;
}
 
// shared/index.ts - Controlled exports
export { Money } from './types/money';
export type { DomainEvent, EventBus } from './events/EventBus';
export type { AuthContext } from './context/AuthContext';
 
// KEEP THE SHARED KERNEL SMALL
// If in doubt, put it in a module, not shared

Strategy 2: Aspect-Oriented Approaches

For concerns like logging and metrics, use aspects or middleware that wrap module boundaries without requiring module code to know about them:

Decorator pattern for wrapping service calls
Middleware at the application entry point
Dependency injection to swap implementations

Strategy 3: Infrastructure Layer

Some cross-cutting concerns belong in an infrastructure layer that modules consume but don't depend on directly:

Database connections and transactions
HTTP client configuration
Caching infrastructure
Message queue adapters

Modules depend on interfaces; infrastructure provides implementations.

Guidelines for Cross-Cutting Concerns

•Default to module ownership — Most things belong in a module, not shared. When in doubt, don't share.
•Shared kernel stays small — If it keeps growing, you're using it wrong. Audit it regularly.
•Use interfaces for infrastructure — Modules depend on abstractions; infrastructure provides implementations.
•Apply aspects externally — Logging, metrics, and tracing should wrap modules, not be embedded in them.
•Avoid 'common' or 'utils' modules — These become dumping grounds. Name things by what they are, not by 'things we couldn't categorize'.

The Gravity of Shared Code

Refactoring Existing Boundaries

Initial boundary choices are rarely perfect. As the domain evolves and understanding deepens, boundaries need adjustment. The key is making boundary changes incrementally and safely.

When to Refactor Boundaries:

Signs Boundaries Need Adjustment

•Shotgun surgery — Simple changes require modifications across multiple modules
•Feature envy — One module constantly reaches into another's data
•Parallel hierarchies — Similar structures duplicated across modules
•Growing interface — Module APIs keep expanding to accommodate new use cases
•Team friction — Teams frequently step on each other's toes
•Vocabulary confusion — Same terms used inconsistently across modules

Refactoring Strategies:

1. Bubble Context (Splitting)

When a module grows too large, extract a new module:

Identify the subset to extract
Create new module with its own API
Build adapter in original module that calls new module
Migrate callers from old code to new module's API
Remove the adapter once migration is complete

2. Merge Modules (Combining)

When modules are too granular:

Analyze which modules always change together
Create combined module with unified API
Migrate callers to new API
Deprecate old module APIs
Remove old modules

3. Strangler Pattern for Boundaries

For large-scale boundary changes:

Create new boundary alongside old
Gradually migrate functionality
Run both in parallel
Complete migration and retire old boundary

Boundaries Are Cheaper to Change Than Services

Summary: Mastering Module Boundaries

Module boundaries are the fundamental structure of a modular monolith. Getting them right enables team autonomy, maintainable code, and future flexibility. Let's consolidate the key principles:

Key Takeaways

•Domain-Driven Design guides boundary identification — Bounded contexts and ubiquitous language reveal where boundaries naturally exist. Listen to domain experts.
•Multiple heuristics triangulate to good boundaries — Cohesion, change coupling, data ownership, team alignment, and business capabilities all provide signals.
•Boundaries are implemented through patterns — Facades expose public APIs, Anti-Corruption Layers translate between models, domain events enable loose coupling.
•Validation through dependency analysis — Tools that visualize and enforce dependencies catch boundary violations before they accumulate.
•Cross-cutting concerns need disciplined handling — Minimal shared kernel, aspect-oriented approaches, and infrastructure abstraction prevent coupling creep.
•Boundaries evolve with understanding — Expect to refactor boundaries as domain knowledge grows. The modular monolith makes this refactoring cheap.

What's Next:

Page Complete

2 / 4