System Design (LLD)Dependency Inversion Principle

High-Level vs Low-Level Modules

LevelIntermediate

Duration50 mins

TopicDependency Inversion Principle

2 / 4

Low-Level Modules — Implementation Details

The Machinery Behind the Policy

If high-level modules represent the what and why of your system, then low-level modules represent the how. They are the implementation machinery — the databases, network protocols, file systems, frameworks, and libraries that make abstract policies concrete and executable.

Low-level modules are not inferior to high-level modules; they are different. They serve different purposes, change for different reasons, and require different architectural treatment. Understanding this distinction is fundamental to applying the Dependency Inversion Principle correctly.

What You Will Learn

By the end of this page, you will understand what makes a module 'low-level,' recognize the various categories of implementation details, appreciate why low-level modules are inherently more volatile than high-level ones, and learn to identify the boundaries between policy and mechanism in real code.

Defining Low-Level Modules

A low-level module is a component that deals with how something is done — the specific technical mechanisms, protocols, and implementations that make abstract operations concrete. While high-level modules express intent, low-level modules fulfill that intent through specific technological means.

The Mechanism Analogy

Consider the difference between a policy and its implementation:

Policy: "Persist customer orders reliably so they survive system restarts."

This policy says nothing about how persistence works. It could be achieved through:

Writing to a PostgreSQL database
Storing in MongoDB
Appending to a log file
Sending to a distributed message queue
Saving to cloud object storage

Each of these is a mechanism — a low-level implementation detail that fulfills the high-level policy. The policy is stable; the mechanism is a technology choice that could change.

Characteristics of Low-Level Modules

Low-level modules share defining characteristics that distinguish them from high-level counterparts:

Characteristics of Low-Level Modules
Characteristic	Description	Example
Technical Vocabulary	Uses language from technology domain, not business domain	`HttpClient`, `DatabaseConnection`, `MessageQueue`, `FileReader`
Defines 'How' Not 'What'	Specifies mechanisms and implementations, not outcomes	"Execute SQL query" vs "Find customer", "Send HTTP POST" vs "Notify user"
Technology-Specific	Tied to specific technologies, protocols, or platforms	AWS SDK, PostgreSQL driver, Redis client, gRPC stubs
Volatile Over Time	Changes when technology changes, upgrades, or better alternatives emerge	Migrating from REST to GraphQL, upgrading database versions
Replaceable	Multiple implementations can satisfy the same high-level requirement	PostgreSQL or MySQL for relational storage, RabbitMQ or Kafka for messaging

The Essential Test

To identify low-level code, ask: 'If I described what this code does to a business stakeholder, would I need to explain technical concepts?' If your explanation involves protocols, formats, drivers, or platforms — that's low-level. 'We save to PostgreSQL' requires explaining databases. 'We remember the customer's order' doesn't.

Categories of Implementation Details

Implementation details manifest across several distinct categories, each with its own characteristics and volatility patterns. Understanding these categories helps you recognize low-level concerns wherever they appear.

Categories of Low-Level Implementation Details

•Data Persistence — How and where data is stored: relational databases, document stores, key-value caches, file systems, object storage. This includes connection management, query construction, transaction handling, and schema management.
•Network Communication — How systems communicate: HTTP/REST, gRPC, WebSockets, message queues, email protocols. This includes serialization formats, authentication mechanisms, retry logic, and connection pooling.
•User Interface — How information is presented: web frameworks, mobile SDKs, CLI libraries, terminal output. This includes templating, state management, event handling, and rendering.
•External Services — How third-party systems are accessed: payment gateways, identity providers, shipping APIs, notification services. This includes SDK usage, credential management, and error handling.
•Platform Infrastructure — How the system runs: cloud providers, container orchestration, serverless platforms, operating system services. This includes deployment, scaling, logging, and monitoring.
•Development Tools — How the system is built: build systems, testing frameworks, code generation, development servers. These affect developer experience but not runtime behavior.

Detailed Breakdown: Data Persistence

Let's examine one category in depth. Data persistence is perhaps the most common source of low-level entanglement in business applications:

persistence-implementations.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
/**
 * These are all LOW-LEVEL implementation details for the same 
 * high-level concept: "persist an order"
 */
 
// PostgreSQL implementation detail
class PostgresOrderRepository {
    async save(order: Order): Promise<void> {
        await this.pool.query(
            `INSERT INTO orders (id, customer_id, status, created_at, total)
             VALUES ($1, $2, $3, $4, $5)
             ON CONFLICT (id) DO UPDATE SET status = $3, total = $5`,
            [order.id, order.customerId, order.status, order.createdAt, order.total]
        );
        
        // Low-level: SQL syntax, parameter binding, conflict handling
        for (const item of order.items) {
            await this.pool.query(
                `INSERT INTO order_items (order_id, product_id, quantity, price)
                 VALUES ($1, $2, $3, $4)`,
                [order.id, item.productId, item.quantity, item.price]
            );
        }
    }
}
 
// MongoDB implementation detail
class MongoOrderRepository {
    async save(order: Order): Promise<void> {
        await this.collection.updateOne(
            { _id: order.id },
            { 
                $set: {
                    customerId: order.customerId,
                    status: order.status,
                    createdAt: order.createdAt,
                    total: order.total,
                    // Low-level: document structure, embedded items
                    items: order.items.map(item => ({
                        productId: item.productId,
                        quantity: item.quantity,
                        price: item.price,
                    })),
                }
            },
            { upsert: true }
        );
    }
}
 
// Redis (for caching) implementation detail
class RedisOrderCache {
    async save(order: Order): Promise<void> {
        const key = `order:${order.id}`;
        // Low-level: key naming, serialization, TTL management
        await this.redis.setex(
            key,
            3600, // TTL in seconds
            JSON.stringify({
                id: order.id,
                customerId: order.customerId,
                status: order.status,
                total: order.total,
                itemCount: order.items.length,
            })
        );
    }
}
 
// File system implementation detail
class FileOrderRepository {
    async save(order: Order): Promise<void> {
        const filePath = path.join(this.storageDir, `${order.id}.json`);
        // Low-level: file paths, JSON serialization, file system operations
        await fs.writeFile(
            filePath,
            JSON.stringify(order, null, 2),
            'utf-8'
        );
    }
}

Same Policy, Different Mechanisms

All four implementations satisfy the same high-level requirement: 'persist an order.' But each involves completely different technologies, syntax, and operational characteristics. The high-level policy shouldn't need to know which one is being used — that's the essence of Dependency Inversion.

Why Low-Level Modules Are Volatile

A critical insight that motivates the Dependency Inversion Principle is that low-level modules change frequently, and the reasons for those changes are fundamentally different from why high-level modules change.

Sources of Low-Level Volatility

Low-level modules are subject to multiple forces that drive change independently of business requirements:

Forces Driving Low-Level Change
Change Driver	Description	Impact
Technology Evolution	New versions, deprecated APIs, security patches	PostgreSQL 14→15, React 17→18, Node.js 16→20
Scaling Requirements	Growth demands different infrastructure	SQLite→PostgreSQL, monolith→microservices, files→S3
Cost Optimization	Cheaper or more efficient alternatives	AWS→GCP migration, Heroku→Kubernetes, licensed→open-source
Performance Tuning	Bottlenecks require different implementations	Adding Redis cache, switching to faster serialization
Vendor Changes	Third parties change APIs, pricing, or sunset products	Twilio API v2→v3, SendGrid→Mailgun, Parse shutdown
Security Vulnerabilities	Urgent patches and library updates	Log4j remediation, TLS version upgrades
Organizational Decisions	Standardization, acquisitions, strategic pivots	Company-wide Oracle→PostgreSQL migration

The Volatility Asymmetry

Notice that these changes have nothing to do with business requirements. Your pricing algorithm doesn't care if you upgrade PostgreSQL. Your approval workflow doesn't care if you switch from AWS to GCP. Your domain rules don't care if you migrate from REST to GraphQL.

This creates a fundamental asymmetry:

High-Level Changes When...

•Business requirements change
•Regulatory landscape evolves
•New features are added
•Business model pivots
•Domain understanding deepens

Low-Level Changes When...

•Libraries release new versions
•Cloud providers change APIs
•Performance requires optimization
•Scale demands different tech
•Security vulnerabilities emerge

The Coupling Danger

When high-level modules depend directly on low-level modules, every low-level change forces high-level changes. Your business rules break when you upgrade the database driver. Your domain logic needs modification when you switch REST frameworks. This is exactly what DIP prevents.

Common Low-Level Implementation Patterns

Let's examine common patterns of low-level code across different categories. Recognizing these patterns helps you identify implementation details in your own codebase.

Database Access Patterns

Database code is quintessentially low-level — it's all about how data is stored and retrieved:

database-low-level.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
/**
 * Low-level database implementation details
 */
class CustomerDatabaseAccess {
    private pool: Pool;
    
    // Low-level: Connection management
    async connect(): Promise<void> {
        this.pool = new Pool({
            host: process.env.DB_HOST,
            port: parseInt(process.env.DB_PORT || '5432'),
            database: process.env.DB_NAME,
            user: process.env.DB_USER,
            password: process.env.DB_PASSWORD,
            max: 20,               // Connection pool size
            idleTimeoutMillis: 30000,
            connectionTimeoutMillis: 2000,
        });
    }
    
    // Low-level: SQL query construction and parameter binding
    async findById(customerId: string): Promise<CustomerRow | null> {
        const result = await this.pool.query<CustomerRow>(
            `SELECT id, email, name, tier, created_at, 
                    subscription_status, last_login_at
             FROM customers 
             WHERE id = $1 AND deleted_at IS NULL`,
            [customerId]
        );
        
        return result.rows[0] || null;
    }
    
    // Low-level: Transaction handling
    async updateWithTransaction(
        customerId: string,
        updates: CustomerUpdates,
        auditEntry: AuditEntry
    ): Promise<void> {
        const client = await this.pool.connect();
        try {
            await client.query('BEGIN');
            
            await client.query(
                `UPDATE customers SET 
                    name = COALESCE($2, name),
                    email = COALESCE($3, email),
                    tier = COALESCE($4, tier),
                    updated_at = NOW()
                 WHERE id = $1`,
                [customerId, updates.name, updates.email, updates.tier]
            );
            
            await client.query(
                `INSERT INTO audit_log (entity_type, entity_id, action, actor_id, details)
                 VALUES ('customer', $1, $2, $3, $4)`,
                [customerId, auditEntry.action, auditEntry.actorId, 
                 JSON.stringify(auditEntry.details)]
            );
            
            await client.query('COMMIT');
        } catch (error) {
            await client.query('ROLLBACK');
            throw error;
        } finally {
            client.release();
        }
    }
    
    // Low-level: Pagination and query building
    async findByTier(
        tier: CustomerTier,
        pagination: Pagination
    ): Promise<PaginatedResult<CustomerRow>> {
        const countResult = await this.pool.query(
            'SELECT COUNT(*) as total FROM customers WHERE tier = $1 AND deleted_at IS NULL',
            [tier]
        );
        
        const result = await this.pool.query<CustomerRow>(
            `SELECT * FROM customers 
             WHERE tier = $1 AND deleted_at IS NULL
             ORDER BY created_at DESC
             LIMIT $2 OFFSET $3`,
            [tier, pagination.limit, pagination.offset]
        );
        
        return {
            items: result.rows,
            total: parseInt(countResult.rows[0].total),
            hasMore: pagination.offset + result.rows.length < parseInt(countResult.rows[0].total),
        };
    }
}

What Makes This Low-Level

Connection pooling configuration, SQL syntax, transaction management, parameter binding, pagination mechanics — these are all implementation details. A business user asking 'find customers in the premium tier' doesn't care about LIMIT/OFFSET or connection timeouts.

The Implementation vs Interface Distinction

A crucial aspect of understanding low-level modules is recognizing the difference between an interface (what a component promises to do) and an implementation (how it actually does it).

The Interface as Contract

An interface defines a contract — a set of operations and their expected behaviors without specifying implementation:

interface-vs-implementation.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
/**
 * INTERFACE (High-Level)
 * Defines WHAT the component does, not HOW
 */
interface OrderRepository {
    /**
     * Persist an order, creating if new or updating if exists
     * @throws OrderPersistenceError if persistence fails
     */
    save(order: Order): Promise<void>;
    
    /**
     * Retrieve an order by its unique identifier
     * @returns The order if found, null otherwise
     */
    findById(id: OrderId): Promise<Order | null>;
    
    /**
     * Find all orders for a specific customer
     */
    findByCustomerId(customerId: CustomerId): Promise<Order[]>;
    
    /**
     * Find orders matching given criteria
     */
    findByCriteria(criteria: OrderSearchCriteria): Promise<Order[]>;
}
 
/**
 * IMPLEMENTATION A (Low-Level: PostgreSQL)
 * Defines HOW it's done with PostgreSQL
 */
class PostgresOrderRepository implements OrderRepository {
    constructor(private pool: Pool) {}
    
    async save(order: Order): Promise<void> {
        // PostgreSQL-specific SQL, transactions, etc.
        await this.pool.query(`INSERT INTO orders...`, [...]);
    }
    
    async findById(id: OrderId): Promise<Order | null> {
        const result = await this.pool.query(
            'SELECT * FROM orders WHERE id = $1',
            [id.value]
        );
        return result.rows[0] ? this.mapToDomain(result.rows[0]) : null;
    }
    // ... other implementations
}
 
/**
 * IMPLEMENTATION B (Low-Level: MongoDB)
 * Defines HOW it's done with MongoDB
 */
class MongoOrderRepository implements OrderRepository {
    constructor(private collection: Collection) {}
    
    async save(order: Order): Promise<void> {
        // MongoDB-specific operations
        await this.collection.updateOne(
            { _id: order.id.value },
            { $set: this.mapToDocument(order) },
            { upsert: true }
        );
    }
    
    async findById(id: OrderId): Promise<Order | null> {
        const doc = await this.collection.findOne({ _id: id.value });
        return doc ? this.mapToDomain(doc) : null;
    }
    // ... other implementations
}
 
/**
 * IMPLEMENTATION C (Low-Level: In-Memory)
 * Defines HOW it's done in memory (for testing)
 */
class InMemoryOrderRepository implements OrderRepository {
    private orders: Map<string, Order> = new Map();
    
    async save(order: Order): Promise<void> {
        this.orders.set(order.id.value, order);
    }
    
    async findById(id: OrderId): Promise<Order | null> {
        return this.orders.get(id.value) || null;
    }
    // ... other implementations
}

Key Observations

Notice several important patterns in this code:

•The interface uses domain vocabulary — Order, OrderId, CustomerId. No SQL, no MongoDB collections, no implementation hints.
•Each implementation is self-contained — PostgreSQL implementation knows nothing about MongoDB and vice versa.
•Implementations are interchangeable — Any code depending on OrderRepository works with any implementation.
•Testing becomes trivial — Use InMemoryOrderRepository for unit tests without database setup.
•The interface is stable — It changes only when the business concept of 'persisting orders' changes, not when you upgrade PostgreSQL.

The DIP Connection

This is exactly what DIP prescribes: high-level modules (like OrderService) depend on the interface (OrderRepository), not on any specific implementation. The interface is 'owned' by the high-level layer and implemented by the low-level layer. Both depend on the abstraction, but the abstraction is defined by the high-level needs.

Recognizing Low-Level Code in Practice

How do you recognize low-level implementation details when reviewing or writing code? Here are practical heuristics:

The Technology Fingerprint Test

Low-level code often has distinctive "fingerprints" — syntax, keywords, or patterns that immediately reveal the underlying technology:

Technology Fingerprints in Code
Fingerprint	Indicates	What It Hides
`SELECT`, `INSERT`, `JOIN`	SQL Database	Relational data storage mechanism
`$set`, `$push`, `findOne`	MongoDB	Document database mechanism
`GET`, `POST`, `headers`	HTTP Communication	Network protocol details
`await`, `Promise`, `async`	Async I/O Patterns	Concurrency mechanism
`JSON.stringify`, `Buffer`	Serialization	Data format transformation
Class decorators like `@Entity`	ORM Framework	Object-relational mapping
`.subscribe`, `.pipe`	Reactive Patterns	Event streaming mechanism

The Import Statement Audit

A quick way to assess whether code is high-level or low-level is to examine its imports. Low-level code typically imports from:

import-analysis.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// LOW-LEVEL imports — technology-specific dependencies
import { Pool, QueryResult } from 'pg';                    // Database driver
import axios from 'axios';                                  // HTTP client
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';  // Cloud SDK
import amqp from 'amqplib';                                // Message queue
import Redis from 'ioredis';                               // Cache client
import { Kafka, Producer } from 'kafkajs';                 // Streaming platform
 
// HIGH-LEVEL imports — domain and abstraction dependencies  
import { Order, OrderId, OrderStatus } from './domain/order';         // Domain entities
import { Customer, CustomerTier } from './domain/customer';           // Domain entities
import { Money, Currency } from './domain/value-objects';             // Value objects
import { OrderRepository } from './repositories/order-repository';    // Abstract interfaces
import { PricingPolicy } from './policies/pricing-policy';            // Business rules
import { OrderValidationRules } from './rules/order-validation';      // Domain rules

The Import Principle

High-level modules should have imports that read like a business glossary, not a technology stack. If your OrderService imports pg, axios, and aws-sdk, it's entangled with low-level concerns. It should import OrderRepository, PaymentGateway, and StorageService — abstractions that hide technology choices.

The Proper Role of Low-Level Modules

Low-level modules aren't problems to be eliminated — they're essential components that need proper placement in your architecture. Their role is to serve as pluggable implementations of high-level abstractions.

The Service Relationship

Think of the relationship between high-level and low-level modules as a service relationship:

•High-level modules are clients — They define what services they need through abstractions (interfaces).
•Low-level modules are service providers — They implement those abstractions with specific technologies.
•Abstractions are contracts — They define the terms of service between clients and providers.
•Clients own the contracts — The interface is designed for high-level needs, implemented by low-level means.

Converting Mermaid diagram...

Benefits of Proper Placement

When low-level modules are properly positioned as implementations of high-level abstractions:

Benefits of Proper Low-Level Placement

•Technology migration becomes isolated — Replacing PostgreSQL with CockroachDB means writing a new implementation, not touching business logic.
•Testing becomes fast and reliable — Unit tests use in-memory implementations; integration tests use real databases. Both test the same business logic.
•Concurrent development enables parallelism — Domain experts work on business rules while infrastructure engineers optimize database queries. Neither blocks the other.
•Onboarding becomes clearer — New developers can understand business logic without parsing SQL or HTTP details. They can read domain code as a specification.
•Debugging becomes targeted — Is the bug in business logic or persistence? With proper separation, the answer is immediately clear from logs and stack traces.

Summary: Low-Level Modules — Implementation Details

Key Takeaways

•Low-level modules implement 'how' — They are the technical mechanisms that make abstract policies executable: databases, networks, file systems, frameworks.
•They span multiple categories — Data persistence, network communication, UI rendering, external services, platform infrastructure, and development tools.
•They are inherently volatile — Technology evolution, scaling needs, cost optimization, and security patches all drive frequent changes independent of business requirements.
•Implementation and interface are distinct — Interfaces define what's needed (high-level), implementations define how it's done (low-level).
•Technology fingerprints reveal low-level code — SQL keywords, HTTP headers, SDK imports, and framework decorators all signal implementation details.
•Their proper role is as pluggable implementations — Low-level modules should implement interfaces defined by high-level needs, making them replaceable and testable.

Coming Up Next:

With clear understanding of both high-level and low-level modules, the next page addresses the practical challenge: how do you identify which level a piece of code belongs to? We'll explore systematic techniques for analyzing codebases, recognizing level violations, and classifying components properly.

Page Complete

You now have a comprehensive understanding of low-level modules as implementation machinery. This knowledge is essential for recognizing inappropriate dependencies — where high-level policy depends on low-level mechanism — and understanding why such dependencies violate the Dependency Inversion Principle.

2 / 4

Loading learning content...

System Design (LLD)Dependency Inversion Principle

High-Level vs Low-Level Modules

LevelIntermediate

Duration50 mins

TopicDependency Inversion Principle

2 / 4

Low-Level Modules — Implementation Details

The Machinery Behind the Policy

What You Will Learn

Defining Low-Level Modules

The Mechanism Analogy

Consider the difference between a policy and its implementation:

Policy: "Persist customer orders reliably so they survive system restarts."

This policy says nothing about how persistence works. It could be achieved through:

Writing to a PostgreSQL database
Storing in MongoDB
Appending to a log file
Sending to a distributed message queue
Saving to cloud object storage

Each of these is a mechanism — a low-level implementation detail that fulfills the high-level policy. The policy is stable; the mechanism is a technology choice that could change.

Characteristics of Low-Level Modules

Low-level modules share defining characteristics that distinguish them from high-level counterparts:

Characteristics of Low-Level Modules
Characteristic	Description	Example
Technical Vocabulary	Uses language from technology domain, not business domain	`HttpClient`, `DatabaseConnection`, `MessageQueue`, `FileReader`
Defines 'How' Not 'What'	Specifies mechanisms and implementations, not outcomes	"Execute SQL query" vs "Find customer", "Send HTTP POST" vs "Notify user"
Technology-Specific	Tied to specific technologies, protocols, or platforms	AWS SDK, PostgreSQL driver, Redis client, gRPC stubs
Volatile Over Time	Changes when technology changes, upgrades, or better alternatives emerge	Migrating from REST to GraphQL, upgrading database versions
Replaceable	Multiple implementations can satisfy the same high-level requirement	PostgreSQL or MySQL for relational storage, RabbitMQ or Kafka for messaging

The Essential Test

Categories of Implementation Details

Categories of Low-Level Implementation Details

•Data Persistence — How and where data is stored: relational databases, document stores, key-value caches, file systems, object storage. This includes connection management, query construction, transaction handling, and schema management.
•Network Communication — How systems communicate: HTTP/REST, gRPC, WebSockets, message queues, email protocols. This includes serialization formats, authentication mechanisms, retry logic, and connection pooling.
•User Interface — How information is presented: web frameworks, mobile SDKs, CLI libraries, terminal output. This includes templating, state management, event handling, and rendering.
•External Services — How third-party systems are accessed: payment gateways, identity providers, shipping APIs, notification services. This includes SDK usage, credential management, and error handling.
•Platform Infrastructure — How the system runs: cloud providers, container orchestration, serverless platforms, operating system services. This includes deployment, scaling, logging, and monitoring.
•Development Tools — How the system is built: build systems, testing frameworks, code generation, development servers. These affect developer experience but not runtime behavior.

Detailed Breakdown: Data Persistence

Let's examine one category in depth. Data persistence is perhaps the most common source of low-level entanglement in business applications:

persistence-implementations.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
/**
 * These are all LOW-LEVEL implementation details for the same 
 * high-level concept: "persist an order"
 */
 
// PostgreSQL implementation detail
class PostgresOrderRepository {
    async save(order: Order): Promise<void> {
        await this.pool.query(
            `INSERT INTO orders (id, customer_id, status, created_at, total)
             VALUES ($1, $2, $3, $4, $5)
             ON CONFLICT (id) DO UPDATE SET status = $3, total = $5`,
            [order.id, order.customerId, order.status, order.createdAt, order.total]
        );
        
        // Low-level: SQL syntax, parameter binding, conflict handling
        for (const item of order.items) {
            await this.pool.query(
                `INSERT INTO order_items (order_id, product_id, quantity, price)
                 VALUES ($1, $2, $3, $4)`,
                [order.id, item.productId, item.quantity, item.price]
            );
        }
    }
}
 
// MongoDB implementation detail
class MongoOrderRepository {
    async save(order: Order): Promise<void> {
        await this.collection.updateOne(
            { _id: order.id },
            { 
                $set: {
                    customerId: order.customerId,
                    status: order.status,
                    createdAt: order.createdAt,
                    total: order.total,
                    // Low-level: document structure, embedded items
                    items: order.items.map(item => ({
                        productId: item.productId,
                        quantity: item.quantity,
                        price: item.price,
                    })),
                }
            },
            { upsert: true }
        );
    }
}
 
// Redis (for caching) implementation detail
class RedisOrderCache {
    async save(order: Order): Promise<void> {
        const key = `order:${order.id}`;
        // Low-level: key naming, serialization, TTL management
        await this.redis.setex(
            key,
            3600, // TTL in seconds
            JSON.stringify({
                id: order.id,
                customerId: order.customerId,
                status: order.status,
                total: order.total,
                itemCount: order.items.length,
            })
        );
    }
}
 
// File system implementation detail
class FileOrderRepository {
    async save(order: Order): Promise<void> {
        const filePath = path.join(this.storageDir, `${order.id}.json`);
        // Low-level: file paths, JSON serialization, file system operations
        await fs.writeFile(
            filePath,
            JSON.stringify(order, null, 2),
            'utf-8'
        );
    }
}

Same Policy, Different Mechanisms

Why Low-Level Modules Are Volatile

Sources of Low-Level Volatility

Low-level modules are subject to multiple forces that drive change independently of business requirements:

Forces Driving Low-Level Change
Change Driver	Description	Impact
Technology Evolution	New versions, deprecated APIs, security patches	PostgreSQL 14→15, React 17→18, Node.js 16→20
Scaling Requirements	Growth demands different infrastructure	SQLite→PostgreSQL, monolith→microservices, files→S3
Cost Optimization	Cheaper or more efficient alternatives	AWS→GCP migration, Heroku→Kubernetes, licensed→open-source
Performance Tuning	Bottlenecks require different implementations	Adding Redis cache, switching to faster serialization
Vendor Changes	Third parties change APIs, pricing, or sunset products	Twilio API v2→v3, SendGrid→Mailgun, Parse shutdown
Security Vulnerabilities	Urgent patches and library updates	Log4j remediation, TLS version upgrades
Organizational Decisions	Standardization, acquisitions, strategic pivots	Company-wide Oracle→PostgreSQL migration

The Volatility Asymmetry

This creates a fundamental asymmetry:

High-Level Changes When...

•Business requirements change
•Regulatory landscape evolves
•New features are added
•Business model pivots
•Domain understanding deepens

Low-Level Changes When...

•Libraries release new versions
•Cloud providers change APIs
•Performance requires optimization
•Scale demands different tech
•Security vulnerabilities emerge

The Coupling Danger

Common Low-Level Implementation Patterns

Let's examine common patterns of low-level code across different categories. Recognizing these patterns helps you identify implementation details in your own codebase.

Database Access Patterns

Database code is quintessentially low-level — it's all about how data is stored and retrieved:

database-low-level.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
/**
 * Low-level database implementation details
 */
class CustomerDatabaseAccess {
    private pool: Pool;
    
    // Low-level: Connection management
    async connect(): Promise<void> {
        this.pool = new Pool({
            host: process.env.DB_HOST,
            port: parseInt(process.env.DB_PORT || '5432'),
            database: process.env.DB_NAME,
            user: process.env.DB_USER,
            password: process.env.DB_PASSWORD,
            max: 20,               // Connection pool size
            idleTimeoutMillis: 30000,
            connectionTimeoutMillis: 2000,
        });
    }
    
    // Low-level: SQL query construction and parameter binding
    async findById(customerId: string): Promise<CustomerRow | null> {
        const result = await this.pool.query<CustomerRow>(
            `SELECT id, email, name, tier, created_at, 
                    subscription_status, last_login_at
             FROM customers 
             WHERE id = $1 AND deleted_at IS NULL`,
            [customerId]
        );
        
        return result.rows[0] || null;
    }
    
    // Low-level: Transaction handling
    async updateWithTransaction(
        customerId: string,
        updates: CustomerUpdates,
        auditEntry: AuditEntry
    ): Promise<void> {
        const client = await this.pool.connect();
        try {
            await client.query('BEGIN');
            
            await client.query(
                `UPDATE customers SET 
                    name = COALESCE($2, name),
                    email = COALESCE($3, email),
                    tier = COALESCE($4, tier),
                    updated_at = NOW()
                 WHERE id = $1`,
                [customerId, updates.name, updates.email, updates.tier]
            );
            
            await client.query(
                `INSERT INTO audit_log (entity_type, entity_id, action, actor_id, details)
                 VALUES ('customer', $1, $2, $3, $4)`,
                [customerId, auditEntry.action, auditEntry.actorId, 
                 JSON.stringify(auditEntry.details)]
            );
            
            await client.query('COMMIT');
        } catch (error) {
            await client.query('ROLLBACK');
            throw error;
        } finally {
            client.release();
        }
    }
    
    // Low-level: Pagination and query building
    async findByTier(
        tier: CustomerTier,
        pagination: Pagination
    ): Promise<PaginatedResult<CustomerRow>> {
        const countResult = await this.pool.query(
            'SELECT COUNT(*) as total FROM customers WHERE tier = $1 AND deleted_at IS NULL',
            [tier]
        );
        
        const result = await this.pool.query<CustomerRow>(
            `SELECT * FROM customers 
             WHERE tier = $1 AND deleted_at IS NULL
             ORDER BY created_at DESC
             LIMIT $2 OFFSET $3`,
            [tier, pagination.limit, pagination.offset]
        );
        
        return {
            items: result.rows,
            total: parseInt(countResult.rows[0].total),
            hasMore: pagination.offset + result.rows.length < parseInt(countResult.rows[0].total),
        };
    }
}

What Makes This Low-Level

The Implementation vs Interface Distinction

A crucial aspect of understanding low-level modules is recognizing the difference between an interface (what a component promises to do) and an implementation (how it actually does it).

The Interface as Contract

An interface defines a contract — a set of operations and their expected behaviors without specifying implementation:

interface-vs-implementation.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
/**
 * INTERFACE (High-Level)
 * Defines WHAT the component does, not HOW
 */
interface OrderRepository {
    /**
     * Persist an order, creating if new or updating if exists
     * @throws OrderPersistenceError if persistence fails
     */
    save(order: Order): Promise<void>;
    
    /**
     * Retrieve an order by its unique identifier
     * @returns The order if found, null otherwise
     */
    findById(id: OrderId): Promise<Order | null>;
    
    /**
     * Find all orders for a specific customer
     */
    findByCustomerId(customerId: CustomerId): Promise<Order[]>;
    
    /**
     * Find orders matching given criteria
     */
    findByCriteria(criteria: OrderSearchCriteria): Promise<Order[]>;
}
 
/**
 * IMPLEMENTATION A (Low-Level: PostgreSQL)
 * Defines HOW it's done with PostgreSQL
 */
class PostgresOrderRepository implements OrderRepository {
    constructor(private pool: Pool) {}
    
    async save(order: Order): Promise<void> {
        // PostgreSQL-specific SQL, transactions, etc.
        await this.pool.query(`INSERT INTO orders...`, [...]);
    }
    
    async findById(id: OrderId): Promise<Order | null> {
        const result = await this.pool.query(
            'SELECT * FROM orders WHERE id = $1',
            [id.value]
        );
        return result.rows[0] ? this.mapToDomain(result.rows[0]) : null;
    }
    // ... other implementations
}
 
/**
 * IMPLEMENTATION B (Low-Level: MongoDB)
 * Defines HOW it's done with MongoDB
 */
class MongoOrderRepository implements OrderRepository {
    constructor(private collection: Collection) {}
    
    async save(order: Order): Promise<void> {
        // MongoDB-specific operations
        await this.collection.updateOne(
            { _id: order.id.value },
            { $set: this.mapToDocument(order) },
            { upsert: true }
        );
    }
    
    async findById(id: OrderId): Promise<Order | null> {
        const doc = await this.collection.findOne({ _id: id.value });
        return doc ? this.mapToDomain(doc) : null;
    }
    // ... other implementations
}
 
/**
 * IMPLEMENTATION C (Low-Level: In-Memory)
 * Defines HOW it's done in memory (for testing)
 */
class InMemoryOrderRepository implements OrderRepository {
    private orders: Map<string, Order> = new Map();
    
    async save(order: Order): Promise<void> {
        this.orders.set(order.id.value, order);
    }
    
    async findById(id: OrderId): Promise<Order | null> {
        return this.orders.get(id.value) || null;
    }
    // ... other implementations
}

Key Observations

Notice several important patterns in this code:

•The interface uses domain vocabulary — Order, OrderId, CustomerId. No SQL, no MongoDB collections, no implementation hints.
•Each implementation is self-contained — PostgreSQL implementation knows nothing about MongoDB and vice versa.
•Implementations are interchangeable — Any code depending on OrderRepository works with any implementation.
•Testing becomes trivial — Use InMemoryOrderRepository for unit tests without database setup.
•The interface is stable — It changes only when the business concept of 'persisting orders' changes, not when you upgrade PostgreSQL.

The DIP Connection

Recognizing Low-Level Code in Practice

How do you recognize low-level implementation details when reviewing or writing code? Here are practical heuristics:

The Technology Fingerprint Test

Low-level code often has distinctive "fingerprints" — syntax, keywords, or patterns that immediately reveal the underlying technology:

Technology Fingerprints in Code
Fingerprint	Indicates	What It Hides
`SELECT`, `INSERT`, `JOIN`	SQL Database	Relational data storage mechanism
`$set`, `$push`, `findOne`	MongoDB	Document database mechanism
`GET`, `POST`, `headers`	HTTP Communication	Network protocol details
`await`, `Promise`, `async`	Async I/O Patterns	Concurrency mechanism
`JSON.stringify`, `Buffer`	Serialization	Data format transformation
Class decorators like `@Entity`	ORM Framework	Object-relational mapping
`.subscribe`, `.pipe`	Reactive Patterns	Event streaming mechanism

The Import Statement Audit

A quick way to assess whether code is high-level or low-level is to examine its imports. Low-level code typically imports from:

import-analysis.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// LOW-LEVEL imports — technology-specific dependencies
import { Pool, QueryResult } from 'pg';                    // Database driver
import axios from 'axios';                                  // HTTP client
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';  // Cloud SDK
import amqp from 'amqplib';                                // Message queue
import Redis from 'ioredis';                               // Cache client
import { Kafka, Producer } from 'kafkajs';                 // Streaming platform
 
// HIGH-LEVEL imports — domain and abstraction dependencies  
import { Order, OrderId, OrderStatus } from './domain/order';         // Domain entities
import { Customer, CustomerTier } from './domain/customer';           // Domain entities
import { Money, Currency } from './domain/value-objects';             // Value objects
import { OrderRepository } from './repositories/order-repository';    // Abstract interfaces
import { PricingPolicy } from './policies/pricing-policy';            // Business rules
import { OrderValidationRules } from './rules/order-validation';      // Domain rules

The Import Principle

The Proper Role of Low-Level Modules

The Service Relationship

Think of the relationship between high-level and low-level modules as a service relationship:

•High-level modules are clients — They define what services they need through abstractions (interfaces).
•Low-level modules are service providers — They implement those abstractions with specific technologies.
•Abstractions are contracts — They define the terms of service between clients and providers.
•Clients own the contracts — The interface is designed for high-level needs, implemented by low-level means.

Converting Mermaid diagram...

Benefits of Proper Placement

When low-level modules are properly positioned as implementations of high-level abstractions:

Benefits of Proper Low-Level Placement

•Technology migration becomes isolated — Replacing PostgreSQL with CockroachDB means writing a new implementation, not touching business logic.
•Testing becomes fast and reliable — Unit tests use in-memory implementations; integration tests use real databases. Both test the same business logic.
•Concurrent development enables parallelism — Domain experts work on business rules while infrastructure engineers optimize database queries. Neither blocks the other.
•Onboarding becomes clearer — New developers can understand business logic without parsing SQL or HTTP details. They can read domain code as a specification.
•Debugging becomes targeted — Is the bug in business logic or persistence? With proper separation, the answer is immediately clear from logs and stack traces.

Summary: Low-Level Modules — Implementation Details

Key Takeaways

•Low-level modules implement 'how' — They are the technical mechanisms that make abstract policies executable: databases, networks, file systems, frameworks.
•They span multiple categories — Data persistence, network communication, UI rendering, external services, platform infrastructure, and development tools.
•They are inherently volatile — Technology evolution, scaling needs, cost optimization, and security patches all drive frequent changes independent of business requirements.
•Implementation and interface are distinct — Interfaces define what's needed (high-level), implementations define how it's done (low-level).
•Technology fingerprints reveal low-level code — SQL keywords, HTTP headers, SDK imports, and framework decorators all signal implementation details.
•Their proper role is as pluggable implementations — Low-level modules should implement interfaces defined by high-level needs, making them replaceable and testable.

Coming Up Next:

Page Complete

2 / 4