High-Level Modules — Policy and Business Logic - High-Level vs Low-Level Modules | OneNoughtOne

0/290

System Design (LLD)Dependency Inversion Principle

High-Level vs Low-Level Modules

LevelIntermediate

Duration50 mins

TopicDependency Inversion Principle

1 / 4

High-Level Modules — Policy and Business Logic

The Heart of Your System

In the vast landscape of a software system — with its databases, API endpoints, message queues, and user interfaces — there exists a core that defines what the system actually does. This core contains the policies, rules, and business logic that give the system its purpose and value. Without this core, you just have plumbing; with it, you have a solution to a real-world problem.

This core is what we call the high-level layer of your system. Understanding what constitutes a high-level module — and more importantly, why it deserves special architectural attention — is fundamental to applying the Dependency Inversion Principle effectively.

What You Will Learn

By the end of this page, you will understand what makes a module 'high-level,' recognize policy and business logic in real codebases, distinguish between core domain logic and peripheral concerns, and appreciate why high-level modules are the most valuable — and most vulnerable — parts of your architecture.

Defining High-Level Modules

A high-level module is a component that encapsulates the essential purpose of your system — the business rules, policies, and domain logic that justify the system's existence. If you stripped away all the databases, frameworks, and infrastructure, the high-level logic would still represent what your organization needs to accomplish.

The Policy Analogy

Consider a company's expense reimbursement policy:

"Employees may claim expenses up to $500 without manager approval. Expenses above $500 require manager approval. Expenses above $5,000 require VP approval and a business justification."

This is policy — a set of business rules that define how the organization operates. These rules exist independently of:

Whether expenses are submitted via a web form, mobile app, or paper
Whether the data is stored in PostgreSQL, MongoDB, or an Excel spreadsheet
Whether approvals are routed via email, Slack, or carrier pigeon

The policy is the what; everything else is the how.

The Essential Question

To identify high-level logic, ask: 'If I described what this code does to a business stakeholder who knows nothing about programming, would they care?' If yes — that's high-level. If your description involves databases, HTTP, or specific technologies, you're probably describing low-level concerns.

Characteristics of High-Level Modules

High-level modules share several defining characteristics that distinguish them from their low-level counterparts:

Characteristics of High-Level Modules
Characteristic	Description	Example
Business Vocabulary	Uses language from the problem domain, not technical domain	`ProcessLoanApplication`, `CalculateShippingCost`, `ApproveExpense`
Defines 'What' Not 'How'	Specifies outcomes and behaviors, not mechanisms	"Orders over $100 get free shipping" vs "INSERT INTO orders..."
Technology-Agnostic	Can be described without mentioning specific technologies	Pricing logic works whether data comes from SQL, NoSQL, or in-memory cache
Stable Over Time	Changes when business requirements change, not when infrastructure changes	Tax calculation rules change with legislation, not with database migrations
High Business Value	Directly contributes to the organization's competitive advantage or core mission	A bank's fraud detection algorithms vs. its logging infrastructure

Business Logic in Depth

Business logic is the encoded representation of the rules, workflows, and decisions that a business makes. It's the computational embodiment of organizational knowledge. Let's examine the layers and forms that business logic takes.

Categories of Business Logic

Business logic isn't monolithic — it manifests in several distinct categories, each with its own characteristics:

Categories of Business Logic

•Domain Rules — The core constraints and behaviors inherent to the business domain. Example: 'A bank account cannot have a negative balance unless it has overdraft protection.' These are usually the most stable rules.
•Calculation Logic — Formulas and algorithms that transform data into meaningful results. Example: 'Calculate the total order price including applicable discounts, taxes, and shipping based on the customer's tier and location.'
•Workflow Logic — The sequences of steps and state transitions that define business processes. Example: 'An insurance claim must go through validation, assessment, approval, and payment stages in order.'
•Decision Logic — The conditional branching that determines different outcomes based on business criteria. Example: 'If the customer has been with us for more than 5 years and has no late payments, offer the premium rate.'
•Validation Rules — The constraints that ensure data integrity from a business perspective. Example: 'A social security number must be exactly 9 digits and not be a known invalid number like 000-00-0000.'

A Concrete Example: E-Commerce Pricing

Let's examine how business logic manifests in a real e-commerce pricing scenario. Consider the following pricing rules:

Base price comes from the product catalog
Members get 10% off on all items
Bulk orders (10+ items) get an additional 5% off
Seasonal sales apply promotional discounts
Total discount cannot exceed 30%

Here's how this business logic might be expressed in code:

PricingPolicy.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
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
/**
 * PricingPolicy — A high-level module containing business pricing rules.
 * 
 * Notice:
 * - No mention of databases, HTTP, or file systems
 * - Uses business vocabulary (Member, Product, Promotion)
 * - Rules are explicit and readable by domain experts
 * - Dependencies are abstractions, not concrete implementations
 */
interface Product {
    id: string;
    name: string;
    basePrice: Money;
    category: ProductCategory;
}
 
interface PricingContext {
    product: Product;
    quantity: number;
    customer: Customer;
    activePromotions: Promotion[];
    pricingDate: Date;
}
 
interface PricingResult {
    originalPrice: Money;
    finalPrice: Money;
    appliedDiscounts: AppliedDiscount[];
    savingsBreakdown: SavingsBreakdown;
}
 
class PricingPolicy {
    private static readonly MEMBER_DISCOUNT_PERCENT = 10;
    private static readonly BULK_ORDER_THRESHOLD = 10;
    private static readonly BULK_DISCOUNT_PERCENT = 5;
    private static readonly MAX_TOTAL_DISCOUNT_PERCENT = 30;
    
    /**
     * Calculate the final price for a purchase.
     * 
     * This is pure business logic — it takes a context and returns a result.
     * No I/O, no side effects, no infrastructure concerns.
     */
    calculatePrice(context: PricingContext): PricingResult {
        const originalPrice = context.product.basePrice.multiply(context.quantity);
        const discounts: AppliedDiscount[] = [];
        
        // Rule 1: Member discount
        if (context.customer.isMember()) {
            discounts.push({
                type: 'MEMBER_DISCOUNT',
                description: 'Member exclusive: 10% off',
                percent: PricingPolicy.MEMBER_DISCOUNT_PERCENT,
            });
        }
        
        // Rule 2: Bulk order discount
        if (context.quantity >= PricingPolicy.BULK_ORDER_THRESHOLD) {
            discounts.push({
                type: 'BULK_DISCOUNT',
                description: `Bulk order discount for ${context.quantity}+ items`,
                percent: PricingPolicy.BULK_DISCOUNT_PERCENT,
            });
        }
        
        // Rule 3: Promotional discounts
        const applicablePromotions = this.findApplicablePromotions(
            context.product,
            context.activePromotions,
            context.pricingDate
        );
        
        for (const promo of applicablePromotions) {
            discounts.push({
                type: 'PROMOTIONAL',
                description: promo.description,
                percent: promo.discountPercent,
            });
        }
        
        // Rule 4: Cap total discount at maximum
        const totalDiscountPercent = this.calculateCappedDiscount(discounts);
        const finalPrice = originalPrice.applyDiscount(totalDiscountPercent);
        
        return {
            originalPrice,
            finalPrice,
            appliedDiscounts: discounts,
            savingsBreakdown: this.buildSavingsBreakdown(originalPrice, finalPrice, discounts),
        };
    }
    
    private calculateCappedDiscount(discounts: AppliedDiscount[]): number {
        const rawTotal = discounts.reduce((sum, d) => sum + d.percent, 0);
        return Math.min(rawTotal, PricingPolicy.MAX_TOTAL_DISCOUNT_PERCENT);
    }
    
    private findApplicablePromotions(
        product: Product,
        promotions: Promotion[],
        date: Date
    ): Promotion[] {
        return promotions.filter(promo =>
            promo.isActiveOn(date) && promo.appliesTo(product)
        );
    }
    
    private buildSavingsBreakdown(
        original: Money,
        final: Money,
        discounts: AppliedDiscount[]
    ): SavingsBreakdown {
        // Build detailed breakdown for display purposes
        // Pure calculation, no side effects
        return {
            totalSaved: original.subtract(final),
            percentSaved: original.subtract(final).divideBy(original).toPercent(),
            discountsApplied: discounts.length,
        };
    }
}

What This Code Doesn't Contain

Notice what's absent from this high-level module: No SQL queries, no HTTP calls, no file system access, no framework annotations, no configuration loading. It's pure business logic. You could test it without any infrastructure, explain it to a product manager, and port it to any technology stack without change.

Policy Layers and Abstraction Levels

High-level modules aren't flat — they form layers of abstraction, with higher layers representing broader, more strategic policies and lower layers representing more specific, tactical decisions. Understanding this hierarchy is crucial for proper system architecture.

The Policy Hierarchy

Robert C. Martin (Uncle Bob), who formalized the Dependency Inversion Principle, describes software as layers of policies arranged by their level of abstraction:

Converting Mermaid diagram...

Understanding the Layers

Each layer serves a distinct purpose and has different stability characteristics:

Policy Layer Characteristics
Layer	Stability	Change Drivers	Example Rules
Enterprise Policy	Most stable (years)	Regulatory changes, organizational restructuring	"All financial transactions must be auditable", "Customer PII must be encrypted"
Application Policy	Stable (months)	New features, product pivots	"Premium users can export reports", "Orders ship within 2 business days"
Domain Layer	Fairly stable (months)	Domain model evolution, new entity types	"An Order contains LineItems", "A Subscription has a renewal date"
Interface Adapters	Moderate (weeks)	API changes, new UI requirements	"REST endpoints return JSON", "GraphQL resolvers map to domain objects"
Infrastructure	Least stable (days/weeks)	Technology upgrades, scaling needs, vendor changes	"Use PostgreSQL 15", "Deploy to AWS Lambda"

The Stability Trap

Many systems get this inverted. They make high-level business logic depend on low-level infrastructure — the exact opposite of what they should do. When the database schema changes, the business rules break. When the framework upgrades, the domain logic needs rewriting. This is the disease that DIP cures.

Policy Independence Principle

A key insight from this hierarchy is that policies at higher levels should be expressible and executable independently of lower levels. Your enterprise security policy shouldn't mention PostgreSQL. Your pricing logic shouldn't contain HTTP status codes. Your domain model shouldn't know about JSON serialization.

This independence isn't just an aesthetic preference — it's a structural necessity for maintainability:

Benefits of Policy Independence

•Testability — Pure policy logic can be tested without infrastructure, leading to fast, reliable tests
•Portability — Business rules work across different deployment environments and technology stacks
•Understandability — Domain experts can review and validate business logic without parsing infrastructure code
•Longevity — Policies survive technology migrations because they don't depend on what's being replaced
•Parallelization — Teams can work on policy and infrastructure independently with clear boundaries

Real-World High-Level Module Examples

Let's examine how high-level modules manifest across different domains. These examples illustrate the universal pattern: business-critical logic that defines what the system does, decoupled from how it does it.

High-Level Modules in Banking

A banking system's high-level modules encode the fundamental rules of financial transactions:

TransferPolicy.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
/**
 * TransferPolicy — High-level banking business rules
 */
class TransferPolicy {
    // Business rule: transfer limits based on account type and verification
    private readonly DAILY_LIMITS: Record<AccountTier, Money> = {
        BASIC: Money.of(1000, 'USD'),
        VERIFIED: Money.of(10000, 'USD'),
        PREMIUM: Money.of(100000, 'USD'),
    };
    
    validateTransfer(transfer: TransferRequest): ValidationResult {
        const errors: PolicyViolation[] = [];
        
        // Rule: Insufficient funds (core banking invariant)
        if (transfer.sourceAccount.availableBalance.isLessThan(transfer.amount)) {
            errors.push(PolicyViolation.insufficientFunds(
                transfer.amount,
                transfer.sourceAccount.availableBalance
            ));
        }
        
        // Rule: Daily limit enforcement
        const dailyTotal = transfer.sourceAccount.todaysTransferTotal.add(transfer.amount);
        const limit = this.DAILY_LIMITS[transfer.sourceAccount.tier];
        if (dailyTotal.isGreaterThan(limit)) {
            errors.push(PolicyViolation.dailyLimitExceeded(dailyTotal, limit));
        }
        
        // Rule: Account status check
        if (transfer.sourceAccount.isFrozen || transfer.targetAccount.isFrozen) {
            errors.push(PolicyViolation.accountFrozen());
        }
        
        // Rule: Same-account transfer prohibition
        if (transfer.sourceAccount.equals(transfer.targetAccount)) {
            errors.push(PolicyViolation.sameAccountTransfer());
        }
        
        return errors.length === 0
            ? ValidationResult.success()
            : ValidationResult.failed(errors);
    }
}

What's High-Level Here

Notice the business vocabulary: 'insufficient funds', 'daily limit', 'account frozen'. These are concepts a bank compliance officer would recognize and care about. The policy doesn't know if accounts are in PostgreSQL or an external banking API.

Identifying High-Level Concerns in Your Code

How do you recognize high-level concerns when reading or writing code? Here are practical techniques for identifying policy and business logic:

The 'Would a Business Person Care?' Test

For each piece of code, ask whether a non-technical business stakeholder would care about what it does:

They Would Care About

•"Customers who haven't ordered in 6 months get a win-back discount"
•"Orders over $50 ship free to domestic addresses"
•"New users get 3 free premium features for 14 days"
•"Inventory alerts trigger when stock falls below reorder point"
•"Referral bonuses apply after referee's first purchase"

They Wouldn't Care About

•"Connection pool is set to 20 with 5-second timeout"
•"JSON responses are gzipped for payloads over 1KB"
•"Database uses B-tree indexes on frequently queried columns"
•"Retry logic uses exponential backoff with jitter"
•"Cache invalidation happens via pub/sub messages"

The 'Survives Technology Change' Test

Imagine your company decides to migrate from PostgreSQL to MongoDB, or from REST to GraphQL, or from AWS to Azure. Which parts of your code would survive unchanged?

Survives unchanged: High-level policy
Requires modification: Low-level implementation

The 'Unit Testable Without Mocks' Criterion

If testing a piece of code requires mocking databases, HTTP clients, file systems, or message queues, that code is probably entangled with low-level concerns. Pure high-level logic should be testable with simple unit tests using plain objects.

The Extraction Technique

When you find high-level logic mixed with low-level details, mentally (or actually) extract the business rules into their own pure functions or classes. If what remains is just I/O glue code, you've found the boundary. The extracted portion is your high-level module.

The Strategic Value of High-Level Modules

Understanding why high-level modules are valuable clarifies why the Dependency Inversion Principle is so important.

The Core Asset

High-level modules represent your organization's core intellectual property in code form. Consider:

Why High-Level Modules Are Your Most Valuable Assets

•Competitive Differentiation — Your pricing algorithms, recommendation engines, and business rules are what distinguish you from competitors. Amazon's recommendation logic is worth billions; their PostgreSQL installation is irrelevant.
•Accumulated Knowledge — High-level modules encode years of domain expertise, edge case handling, and business learning. This knowledge is irreplaceable and should be protected.
•Regulatory Compliance — In regulated industries, your compliance logic is subject to audits. It must be clearly identifiable, testable, and maintainable independent of infrastructure.
•Technology Independence — Companies regularly migrate databases, change cloud providers, and adopt new frameworks. High-level modules that don't depend on these can survive any migration.
•Team Scalability — Clear separation allows domain experts to work on business logic while infrastructure engineers handle deployment concerns. Neither blocks the other.

The Protection Imperative

Given their value, high-level modules deserve protection from unnecessary change. Every time infrastructure details leak into business logic:

Testing becomes harder — You need databases for unit tests
Changes become riskier — Updating a library might break business rules
Understanding becomes harder — Business logic is buried in infrastructure noise
Reuse becomes impossible — Business rules can't be used in different contexts
Evolution becomes slower — Simple changes require understanding complex dependencies

The Dependency Inversion Principle is the primary tool for achieving this protection. Rather than having high-level policy depend on low-level details, both should depend on abstractions, with the abstractions "owned" by the high-level layer.

Key Insight

High-level modules should be the most stable, most tested, and most protected parts of your codebase. They change when the business changes, not when the technology changes. Every dependency flowing into them is a potential source of instability. DIP ensures those dependencies point the right direction.

Summary: High-Level Modules — Policy and Business Logic

We've established a comprehensive understanding of what constitutes high-level modules and why they matter:

Key Takeaways

•High-level modules encode business policy — The rules, decisions, and logic that define what your system does and why it matters to the organization.
•Business logic is multi-faceted — It includes domain rules, calculation logic, workflow logic, decision logic, and validation rules, each serving different purposes.
•Policy layers form a hierarchy — From enterprise policies to application logic to domain models, with stability increasing at higher levels.
•High-level modules should be technology-agnostic — They should be describable, testable, and executable without mentioning specific technologies.
•They represent core intellectual property — Your competitive advantage lives in your business logic, not your infrastructure.
•Protection through abstraction is essential — High-level modules deserve architectural protection from low-level volatility.

Coming Up Next:

Now that we understand high-level modules, the next page examines their counterpart: low-level modules and implementation details. We'll explore what makes something 'low-level,' why these modules are inherently more volatile, and how to recognize the boundary between policy and mechanism in your code.

Page Complete

You now have a deep understanding of high-level modules as carriers of business policy and organizational value. This foundation is essential for understanding why the Dependency Inversion Principle advocates for protecting these modules through proper dependency direction.

System Design (LLD)Dependency Inversion Principle

High-Level vs Low-Level Modules

LevelIntermediate

Duration50 mins

TopicDependency Inversion Principle

1 / 4

High-Level Modules — Policy and Business Logic

The Heart of Your System

What You Will Learn

Defining High-Level Modules

The Policy Analogy

Consider a company's expense reimbursement policy:

"Employees may claim expenses up to $500 without manager approval. Expenses above $500 require manager approval. Expenses above $5,000 require VP approval and a business justification."

This is policy — a set of business rules that define how the organization operates. These rules exist independently of:

Whether expenses are submitted via a web form, mobile app, or paper
Whether the data is stored in PostgreSQL, MongoDB, or an Excel spreadsheet
Whether approvals are routed via email, Slack, or carrier pigeon

The policy is the what; everything else is the how.

The Essential Question

Characteristics of High-Level Modules

High-level modules share several defining characteristics that distinguish them from their low-level counterparts:

Characteristics of High-Level Modules
Characteristic	Description	Example
Business Vocabulary	Uses language from the problem domain, not technical domain	`ProcessLoanApplication`, `CalculateShippingCost`, `ApproveExpense`
Defines 'What' Not 'How'	Specifies outcomes and behaviors, not mechanisms	"Orders over $100 get free shipping" vs "INSERT INTO orders..."
Technology-Agnostic	Can be described without mentioning specific technologies	Pricing logic works whether data comes from SQL, NoSQL, or in-memory cache
Stable Over Time	Changes when business requirements change, not when infrastructure changes	Tax calculation rules change with legislation, not with database migrations
High Business Value	Directly contributes to the organization's competitive advantage or core mission	A bank's fraud detection algorithms vs. its logging infrastructure

Business Logic in Depth

Categories of Business Logic

Business logic isn't monolithic — it manifests in several distinct categories, each with its own characteristics:

Categories of Business Logic

•Domain Rules — The core constraints and behaviors inherent to the business domain. Example: 'A bank account cannot have a negative balance unless it has overdraft protection.' These are usually the most stable rules.
•Calculation Logic — Formulas and algorithms that transform data into meaningful results. Example: 'Calculate the total order price including applicable discounts, taxes, and shipping based on the customer's tier and location.'
•Workflow Logic — The sequences of steps and state transitions that define business processes. Example: 'An insurance claim must go through validation, assessment, approval, and payment stages in order.'
•Decision Logic — The conditional branching that determines different outcomes based on business criteria. Example: 'If the customer has been with us for more than 5 years and has no late payments, offer the premium rate.'
•Validation Rules — The constraints that ensure data integrity from a business perspective. Example: 'A social security number must be exactly 9 digits and not be a known invalid number like 000-00-0000.'

A Concrete Example: E-Commerce Pricing

Let's examine how business logic manifests in a real e-commerce pricing scenario. Consider the following pricing rules:

Base price comes from the product catalog
Members get 10% off on all items
Bulk orders (10+ items) get an additional 5% off
Seasonal sales apply promotional discounts
Total discount cannot exceed 30%

Here's how this business logic might be expressed in code:

PricingPolicy.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
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
/**
 * PricingPolicy — A high-level module containing business pricing rules.
 * 
 * Notice:
 * - No mention of databases, HTTP, or file systems
 * - Uses business vocabulary (Member, Product, Promotion)
 * - Rules are explicit and readable by domain experts
 * - Dependencies are abstractions, not concrete implementations
 */
interface Product {
    id: string;
    name: string;
    basePrice: Money;
    category: ProductCategory;
}
 
interface PricingContext {
    product: Product;
    quantity: number;
    customer: Customer;
    activePromotions: Promotion[];
    pricingDate: Date;
}
 
interface PricingResult {
    originalPrice: Money;
    finalPrice: Money;
    appliedDiscounts: AppliedDiscount[];
    savingsBreakdown: SavingsBreakdown;
}
 
class PricingPolicy {
    private static readonly MEMBER_DISCOUNT_PERCENT = 10;
    private static readonly BULK_ORDER_THRESHOLD = 10;
    private static readonly BULK_DISCOUNT_PERCENT = 5;
    private static readonly MAX_TOTAL_DISCOUNT_PERCENT = 30;
    
    /**
     * Calculate the final price for a purchase.
     * 
     * This is pure business logic — it takes a context and returns a result.
     * No I/O, no side effects, no infrastructure concerns.
     */
    calculatePrice(context: PricingContext): PricingResult {
        const originalPrice = context.product.basePrice.multiply(context.quantity);
        const discounts: AppliedDiscount[] = [];
        
        // Rule 1: Member discount
        if (context.customer.isMember()) {
            discounts.push({
                type: 'MEMBER_DISCOUNT',
                description: 'Member exclusive: 10% off',
                percent: PricingPolicy.MEMBER_DISCOUNT_PERCENT,
            });
        }
        
        // Rule 2: Bulk order discount
        if (context.quantity >= PricingPolicy.BULK_ORDER_THRESHOLD) {
            discounts.push({
                type: 'BULK_DISCOUNT',
                description: `Bulk order discount for ${context.quantity}+ items`,
                percent: PricingPolicy.BULK_DISCOUNT_PERCENT,
            });
        }
        
        // Rule 3: Promotional discounts
        const applicablePromotions = this.findApplicablePromotions(
            context.product,
            context.activePromotions,
            context.pricingDate
        );
        
        for (const promo of applicablePromotions) {
            discounts.push({
                type: 'PROMOTIONAL',
                description: promo.description,
                percent: promo.discountPercent,
            });
        }
        
        // Rule 4: Cap total discount at maximum
        const totalDiscountPercent = this.calculateCappedDiscount(discounts);
        const finalPrice = originalPrice.applyDiscount(totalDiscountPercent);
        
        return {
            originalPrice,
            finalPrice,
            appliedDiscounts: discounts,
            savingsBreakdown: this.buildSavingsBreakdown(originalPrice, finalPrice, discounts),
        };
    }
    
    private calculateCappedDiscount(discounts: AppliedDiscount[]): number {
        const rawTotal = discounts.reduce((sum, d) => sum + d.percent, 0);
        return Math.min(rawTotal, PricingPolicy.MAX_TOTAL_DISCOUNT_PERCENT);
    }
    
    private findApplicablePromotions(
        product: Product,
        promotions: Promotion[],
        date: Date
    ): Promotion[] {
        return promotions.filter(promo =>
            promo.isActiveOn(date) && promo.appliesTo(product)
        );
    }
    
    private buildSavingsBreakdown(
        original: Money,
        final: Money,
        discounts: AppliedDiscount[]
    ): SavingsBreakdown {
        // Build detailed breakdown for display purposes
        // Pure calculation, no side effects
        return {
            totalSaved: original.subtract(final),
            percentSaved: original.subtract(final).divideBy(original).toPercent(),
            discountsApplied: discounts.length,
        };
    }
}

What This Code Doesn't Contain

Policy Layers and Abstraction Levels

The Policy Hierarchy

Robert C. Martin (Uncle Bob), who formalized the Dependency Inversion Principle, describes software as layers of policies arranged by their level of abstraction:

Converting Mermaid diagram...

Understanding the Layers

Each layer serves a distinct purpose and has different stability characteristics:

Policy Layer Characteristics
Layer	Stability	Change Drivers	Example Rules
Enterprise Policy	Most stable (years)	Regulatory changes, organizational restructuring	"All financial transactions must be auditable", "Customer PII must be encrypted"
Application Policy	Stable (months)	New features, product pivots	"Premium users can export reports", "Orders ship within 2 business days"
Domain Layer	Fairly stable (months)	Domain model evolution, new entity types	"An Order contains LineItems", "A Subscription has a renewal date"
Interface Adapters	Moderate (weeks)	API changes, new UI requirements	"REST endpoints return JSON", "GraphQL resolvers map to domain objects"
Infrastructure	Least stable (days/weeks)	Technology upgrades, scaling needs, vendor changes	"Use PostgreSQL 15", "Deploy to AWS Lambda"

The Stability Trap

Policy Independence Principle

This independence isn't just an aesthetic preference — it's a structural necessity for maintainability:

Benefits of Policy Independence

•Testability — Pure policy logic can be tested without infrastructure, leading to fast, reliable tests
•Portability — Business rules work across different deployment environments and technology stacks
•Understandability — Domain experts can review and validate business logic without parsing infrastructure code
•Longevity — Policies survive technology migrations because they don't depend on what's being replaced
•Parallelization — Teams can work on policy and infrastructure independently with clear boundaries

Real-World High-Level Module Examples

High-Level Modules in Banking

A banking system's high-level modules encode the fundamental rules of financial transactions:

TransferPolicy.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
/**
 * TransferPolicy — High-level banking business rules
 */
class TransferPolicy {
    // Business rule: transfer limits based on account type and verification
    private readonly DAILY_LIMITS: Record<AccountTier, Money> = {
        BASIC: Money.of(1000, 'USD'),
        VERIFIED: Money.of(10000, 'USD'),
        PREMIUM: Money.of(100000, 'USD'),
    };
    
    validateTransfer(transfer: TransferRequest): ValidationResult {
        const errors: PolicyViolation[] = [];
        
        // Rule: Insufficient funds (core banking invariant)
        if (transfer.sourceAccount.availableBalance.isLessThan(transfer.amount)) {
            errors.push(PolicyViolation.insufficientFunds(
                transfer.amount,
                transfer.sourceAccount.availableBalance
            ));
        }
        
        // Rule: Daily limit enforcement
        const dailyTotal = transfer.sourceAccount.todaysTransferTotal.add(transfer.amount);
        const limit = this.DAILY_LIMITS[transfer.sourceAccount.tier];
        if (dailyTotal.isGreaterThan(limit)) {
            errors.push(PolicyViolation.dailyLimitExceeded(dailyTotal, limit));
        }
        
        // Rule: Account status check
        if (transfer.sourceAccount.isFrozen || transfer.targetAccount.isFrozen) {
            errors.push(PolicyViolation.accountFrozen());
        }
        
        // Rule: Same-account transfer prohibition
        if (transfer.sourceAccount.equals(transfer.targetAccount)) {
            errors.push(PolicyViolation.sameAccountTransfer());
        }
        
        return errors.length === 0
            ? ValidationResult.success()
            : ValidationResult.failed(errors);
    }
}

What's High-Level Here

Identifying High-Level Concerns in Your Code

How do you recognize high-level concerns when reading or writing code? Here are practical techniques for identifying policy and business logic:

The 'Would a Business Person Care?' Test

For each piece of code, ask whether a non-technical business stakeholder would care about what it does:

They Would Care About

•"Customers who haven't ordered in 6 months get a win-back discount"
•"Orders over $50 ship free to domestic addresses"
•"New users get 3 free premium features for 14 days"
•"Inventory alerts trigger when stock falls below reorder point"
•"Referral bonuses apply after referee's first purchase"

They Wouldn't Care About

•"Connection pool is set to 20 with 5-second timeout"
•"JSON responses are gzipped for payloads over 1KB"
•"Database uses B-tree indexes on frequently queried columns"
•"Retry logic uses exponential backoff with jitter"
•"Cache invalidation happens via pub/sub messages"

The 'Survives Technology Change' Test

Imagine your company decides to migrate from PostgreSQL to MongoDB, or from REST to GraphQL, or from AWS to Azure. Which parts of your code would survive unchanged?

Survives unchanged: High-level policy
Requires modification: Low-level implementation

The 'Unit Testable Without Mocks' Criterion

The Extraction Technique

The Strategic Value of High-Level Modules

Understanding why high-level modules are valuable clarifies why the Dependency Inversion Principle is so important.

The Core Asset

High-level modules represent your organization's core intellectual property in code form. Consider:

Why High-Level Modules Are Your Most Valuable Assets

•Competitive Differentiation — Your pricing algorithms, recommendation engines, and business rules are what distinguish you from competitors. Amazon's recommendation logic is worth billions; their PostgreSQL installation is irrelevant.
•Accumulated Knowledge — High-level modules encode years of domain expertise, edge case handling, and business learning. This knowledge is irreplaceable and should be protected.
•Regulatory Compliance — In regulated industries, your compliance logic is subject to audits. It must be clearly identifiable, testable, and maintainable independent of infrastructure.
•Technology Independence — Companies regularly migrate databases, change cloud providers, and adopt new frameworks. High-level modules that don't depend on these can survive any migration.
•Team Scalability — Clear separation allows domain experts to work on business logic while infrastructure engineers handle deployment concerns. Neither blocks the other.

The Protection Imperative

Given their value, high-level modules deserve protection from unnecessary change. Every time infrastructure details leak into business logic:

Testing becomes harder — You need databases for unit tests
Changes become riskier — Updating a library might break business rules
Understanding becomes harder — Business logic is buried in infrastructure noise
Reuse becomes impossible — Business rules can't be used in different contexts
Evolution becomes slower — Simple changes require understanding complex dependencies

Key Insight

Summary: High-Level Modules — Policy and Business Logic

We've established a comprehensive understanding of what constitutes high-level modules and why they matter:

Key Takeaways

•High-level modules encode business policy — The rules, decisions, and logic that define what your system does and why it matters to the organization.
•Business logic is multi-faceted — It includes domain rules, calculation logic, workflow logic, decision logic, and validation rules, each serving different purposes.
•Policy layers form a hierarchy — From enterprise policies to application logic to domain models, with stability increasing at higher levels.
•High-level modules should be technology-agnostic — They should be describable, testable, and executable without mentioning specific technologies.
•They represent core intellectual property — Your competitive advantage lives in your business logic, not your infrastructure.
•Protection through abstraction is essential — High-level modules deserve architectural protection from low-level volatility.

Coming Up Next:

Page Complete