Presentation, Business, Data Layers - Traditional Layered Architecture | OneNoughtOne

0/246

System Design (LLD)Traditional Layered Architecture

Traditional Layered Architecture

LevelIntermediate

Duration60 mins

TopicTraditional Layered Architecture

1 / 4

Presentation, Business, Data Layers

The Anatomy of Enterprise Software

Before there were microservices, before hexagonal architecture became the topic of conference talks, before "Clean Architecture" was published—there was layered architecture. This pattern, sometimes called N-tier architecture or multi-tier architecture, represents one of the most enduring and widely-adopted architectural patterns in software history.

If you've worked on any enterprise application built in the last three decades, you've almost certainly encountered layered architecture. From Java EE applications to .NET enterprise systems, from Spring Boot services to Ruby on Rails applications—the three-layer decomposition into Presentation, Business Logic, and Data Access has become the default mental model for organizing code.

But familiarity breeds contempt, or at least complacency. Many developers use layered architecture without truly understanding why layers exist, what belongs in each layer, or when this decomposition serves them well. This module will transform your understanding from rote familiarity to deep comprehension.

What You Will Learn

By the end of this page, you will understand the precise responsibilities of each architectural layer, the principles that define layer boundaries, and how this separation enables maintainability, testability, and team collaboration. You'll move from 'I know what layers are' to 'I understand deeply why they exist and how to use them correctly.'

The Origin of Layered Thinking

Layered architecture didn't emerge from theoretical computer science—it emerged from practical necessity. As software systems grew in complexity during the 1980s and 1990s, development teams discovered a recurring problem: unmanageable coupling.

Consider a typical early application without architectural structure:

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
// Everything mixed together - UI, logic, and database
public class CustomerScreen {
    public void displayCustomerDetails(int customerId) {
        // Direct database access in UI code
        Connection conn = DriverManager.getConnection("jdbc:mysql://localhost/db");
        PreparedStatement stmt = conn.prepareStatement(
            "SELECT * FROM customers WHERE id = ?"
        );
        stmt.setInt(1, customerId);
        ResultSet rs = stmt.executeQuery();
        
        if (rs.next()) {
            // Business logic mixed with UI
            String name = rs.getString("name");
            double creditLimit = rs.getDouble("credit_limit");
            double currentBalance = calculateBalance(customerId, conn);
            
            // Is customer credit-worthy? Business rule embedded in UI
            boolean creditWorthy = currentBalance < creditLimit * 0.8;
            
            // UI logic
            nameLabel.setText(name);
            balanceLabel.setText(formatCurrency(currentBalance));
            creditIndicator.setColor(creditWorthy ? Color.GREEN : Color.RED);
        }
        
        conn.close();
    }
    
    private double calculateBalance(int customerId, Connection conn) {
        // More mixed database and business logic...
        // This method does SQL queries AND business calculations
    }
}

This code exhibits several fatal flaws that become catastrophic as systems grow:

Problem 1: Change Amplification When you change the database schema, you must hunt through UI code to find all SQL queries. When you change a business rule, you must examine UI classes to find where it's implemented. Every change requires examining the entire codebase.

Problem 2: Untestability How do you unit test the credit-worthiness calculation? You can't—it's embedded in UI code that requires a database connection, a ResultSet, and GUI components. Testing becomes integration testing by default.

Problem 3: Duplicate Logic Another screen needs the credit-worthiness check? Copy-paste the code. Now you have two places to update when the rule changes. Three months later, you have five slightly different versions of the same rule.

Problem 4: Deployment Coupling Changing any part of the system requires redeploying everything. A small UI tweak? Redeploy. A database optimization? Redeploy the UI too.

Layered architecture emerged as the antidote to these problems.

Historical Context

The formal articulation of layered architecture principles came from patterns movements of the 1990s, including Martin Fowler's 'Patterns of Enterprise Application Architecture' (2002) and the earlier 'Pattern-Oriented Software Architecture' series. However, the practice predates the theory—architects discovered these patterns empirically.

The Layered Architecture Model

At its core, layered architecture divides a software system into horizontal slices, where each slice (layer) has a specific responsibility and well-defined relationships with other layers. The canonical three-layer model consists of:

Presentation Layer — Handles user interface and user interaction
Business Logic Layer — Contains domain logic and business rules
Data Access Layer — Manages data persistence and retrieval

This decomposition is logical, not necessarily physical. Layers can exist within a single deployable unit (a monolith) or be distributed across multiple processes (an N-tier deployment). The key is the separation of concerns in code organization.

The arrows indicate dependency direction—upper layers depend on lower layers, but lower layers should have no knowledge of upper layers. This is the fundamental rule: dependencies flow downward only.

This constraint has profound implications:

The Presentation Layer knows about the Business Layer, but the Business Layer doesn't know it's being used by a web interface
The Business Layer knows about the Data Access Layer, but the Data Access Layer doesn't know what business rules use its data
Changes in upper layers don't affect lower layers; changes in lower layers may require upper layer adjustments

Layers vs Tiers

Layers are logical separations in code—they exist in your codebase structure. Tiers are physical separations in deployment—they exist on different servers or processes. A three-layer application can be deployed as a single tier (monolith) or as three tiers (separate presentation server, application server, database server). Layers are about code organization; tiers are about deployment topology.

The Presentation Layer: Gateway to the User

The Presentation Layer sits at the top of the architecture stack and serves as the bridge between humans (or external systems) and your application's capabilities. This layer has a deceptively simple mandate: translate external requests into application operations and translate application responses into external formats.

Core Responsibilities:

Request Intake and Validation
- Accept HTTP requests, form submissions, API calls, or user events
- Perform syntactic validation (is this valid JSON? Is this a well-formed email address?)
- Note: semantic validation (is this email address registered?) belongs in the Business Layer
Request Translation
- Convert external data formats into internal representations
- Map HTTP request bodies to DTOs (Data Transfer Objects)
- Parse and deserialize incoming data
Orchestration of Business Operations
- Call appropriate Business Layer services
- Coordinate multiple service calls when needed
- Note: Complex business logic coordination should push down to a domain or application service
Response Formatting
- Convert internal objects to external representations (JSON, HTML, XML)
- Handle content negotiation
- Apply view transformations and formatting
User Experience Concerns
- Session management and authentication state
- Navigation and routing
- Error message formatting and presentation
- Localization and internationalization of display text

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
// presentation/controllers/CustomerController.ts
import { Request, Response } from 'express';
import { CustomerService } from '../../business/services/CustomerService';
import { CreateCustomerDTO, CustomerResponseDTO } from '../dto';
import { validate } from 'class-validator';
import { plainToClass } from 'class-transformer';
 
export class CustomerController {
    constructor(private readonly customerService: CustomerService) {}
 
    /**
     * Handle customer creation request
     * Notice: This controller does NOT contain business logic
     */
    async createCustomer(req: Request, res: Response): Promise<void> {
        try {
            // 1. Request translation: Convert raw request to typed DTO
            const createCustomerDto = plainToClass(CreateCustomerDTO, req.body);
            
            // 2. Syntactic validation: Is the data well-formed?
            const validationErrors = await validate(createCustomerDto);
            if (validationErrors.length > 0) {
                res.status(400).json({
                    error: 'Validation failed',
                    details: this.formatValidationErrors(validationErrors)
                });
                return;
            }
            
            // 3. Delegate to business layer: The controller doesn't know HOW
            //    customers are created, just that the service can do it
            const customer = await this.customerService.createCustomer(
                createCustomerDto.name,
                createCustomerDto.email,
                createCustomerDto.creditLimit
            );
            
            // 4. Response formatting: Convert domain object to response DTO
            const responseDto = CustomerResponseDTO.fromDomain(customer);
            
            res.status(201).json(responseDto);
        } catch (error) {
            // 5. Error handling: Present errors appropriately
            if (error instanceof CustomerAlreadyExistsError) {
                res.status(409).json({ error: error.message });
            } else if (error instanceof InvalidCreditLimitError) {
                res.status(422).json({ error: error.message });
            } else {
                // Log unexpected errors, return generic message
                console.error('Unexpected error:', error);
                res.status(500).json({ error: 'Internal server error' });
            }
        }
    }
 
    async getCustomer(req: Request, res: Response): Promise<void> {
        const customerId = req.params.id;
        
        // Syntactic validation only - is this a valid ID format?
        if (!this.isValidUUID(customerId)) {
            res.status(400).json({ error: 'Invalid customer ID format' });
            return;
        }
        
        const customer = await this.customerService.getCustomerById(customerId);
        
        if (!customer) {
            res.status(404).json({ error: 'Customer not found' });
            return;
        }
        
        res.json(CustomerResponseDTO.fromDomain(customer));
    }
 
    private formatValidationErrors(errors: ValidationError[]): object {
        // Convert validation library errors to API-friendly format
    }
 
    private isValidUUID(value: string): boolean {
        const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
        return uuidRegex.test(value);
    }
}

What the Presentation Layer Should NOT Do:

❌ Implement business rules — "If the customer's credit limit exceeds $10,000, require manager approval" belongs in the Business Layer, not in a controller

❌ Access the database directly — No SQL queries, no ORM calls, no repository access. The Presentation Layer speaks only to the Business Layer

❌ Contain reusable domain logic — If two controllers need the same logic, that logic should be in a shared Business Layer service, not duplicated in controllers

❌ Make business decisions — The controller shouldn't decide whether a customer is credit-worthy; it should call a service that makes that determination

The Thin Controller Principle

Controllers should be 'thin'—minimal code focused purely on HTTP/UI concerns. If your controller is longer than 50-100 lines, you're likely implementing business logic in the wrong place. A well-structured controller is often just translation, delegation, and response formatting.

The Business Logic Layer: The Beating Heart

The Business Logic Layer (also called the Domain Layer, Service Layer, or Application Core) is the reason your software exists. This layer encapsulates the rules, workflows, calculations, and policies that define what your application actually does.

If the Presentation Layer is about how users interact with your system, and the Data Access Layer is about where data lives, the Business Logic Layer is about what your system means—its semantic core.

Core Responsibilities:

Business Rule Implementation
- Encode domain constraints: "An order cannot exceed customer credit limit"
- Implement policies: "Premium customers get 10% discount"
- Enforce invariants: "Account balance can never go negative"
Workflow Orchestration
- Coordinate multi-step business processes
- Manage transaction boundaries (logically, not technically)
- Handle business events and triggers
Domain Calculations
- Compute derived values: totals, averages, projections
- Apply business formulas: pricing, scoring, rating
- Generate business identifiers: order numbers, invoice codes
Business Validation
- Semantic validation: "Does this customer exist?", "Is this product available?"
- Cross-field validation: "End date must be after start date"
- Business constraint checking: "Only active employees can submit expenses"

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
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
// business/services/OrderService.ts
import { Order, OrderItem, OrderStatus } from '../domain/Order';
import { Customer } from '../domain/Customer';
import { Product } from '../domain/Product';
import { OrderRepository } from '../../data/repositories/OrderRepository';
import { CustomerRepository } from '../../data/repositories/CustomerRepository';
import { ProductRepository } from '../../data/repositories/ProductRepository';
import { EventPublisher } from '../events/EventPublisher';
 
export class OrderService {
    constructor(
        private readonly orderRepository: OrderRepository,
        private readonly customerRepository: CustomerRepository,
        private readonly productRepository: ProductRepository,
        private readonly eventPublisher: EventPublisher
    ) {}
 
    /**
     * Create a new order with business rule enforcement
     * 
     * This method embodies core business logic:
     * - Customer validation and credit checking
     * - Product availability verification
     * - Pricing calculations with discounts
     * - Order total computation
     * - Business event emission
     */
    async createOrder(
        customerId: string,
        items: Array<{ productId: string; quantity: number }>
    ): Promise<Order> {
        // 1. Retrieve and validate customer
        const customer = await this.customerRepository.findById(customerId);
        if (!customer) {
            throw new CustomerNotFoundError(customerId);
        }
        
        // 2. Business rule: Only active customers can place orders
        if (!customer.isActive()) {
            throw new InactiveCustomerError(customerId);
        }
        
        // 3. Resolve products and build order items with pricing
        const orderItems = await this.resolveOrderItems(items, customer);
        
        // 4. Calculate order total with business rules
        const subtotal = this.calculateSubtotal(orderItems);
        const discount = this.calculateDiscount(customer, subtotal);
        const tax = this.calculateTax(subtotal - discount, customer.shippingAddress);
        const total = subtotal - discount + tax;
        
        // 5. Business rule: Credit limit check
        const currentOutstanding = await this.orderRepository.getOutstandingBalance(customerId);
        if (currentOutstanding + total > customer.creditLimit) {
            throw new CreditLimitExceededError(
                customerId,
                customer.creditLimit,
                currentOutstanding + total
            );
        }
        
        // 6. Create the order domain object
        const order = Order.create({
            customerId,
            items: orderItems,
            subtotal,
            discount,
            tax,
            total,
            status: OrderStatus.PENDING
        });
        
        // 7. Persist through data layer
        const savedOrder = await this.orderRepository.save(order);
        
        // 8. Publish domain event for downstream processing
        await this.eventPublisher.publish(new OrderCreatedEvent(savedOrder));
        
        return savedOrder;
    }
 
    /**
     * Business logic: Calculate applicable discount
     * 
     * Rules:
     * - Premium customers: 10% discount
     * - Orders over $500: additional 5% discount
     * - Maximum discount: 15%
     */
    private calculateDiscount(customer: Customer, subtotal: number): number {
        let discountPercentage = 0;
        
        if (customer.isPremium()) {
            discountPercentage += 0.10;
        }
        
        if (subtotal > 500) {
            discountPercentage += 0.05;
        }
        
        discountPercentage = Math.min(discountPercentage, 0.15);
        
        return subtotal * discountPercentage;
    }
 
    /**
     * Business logic: Tax calculation based on shipping destination
     */
    private calculateTax(taxableAmount: number, address: Address): number {
        const taxRate = this.getTaxRateForAddress(address);
        return taxableAmount * taxRate;
    }
 
    /**
     * Validate products, check availability, apply pricing
     */
    private async resolveOrderItems(
        items: Array<{ productId: string; quantity: number }>,
        customer: Customer
    ): Promise<OrderItem[]> {
        const orderItems: OrderItem[] = [];
        
        for (const item of items) {
            const product = await this.productRepository.findById(item.productId);
            
            if (!product) {
                throw new ProductNotFoundError(item.productId);
            }
            
            // Business rule: Check stock availability
            if (product.availableQuantity < item.quantity) {
                throw new InsufficientStockError(
                    item.productId,
                    item.quantity,
                    product.availableQuantity
                );
            }
            
            // Business rule: Apply customer-specific pricing tier
            const unitPrice = this.getPriceForCustomer(product, customer);
            
            orderItems.push(OrderItem.create({
                productId: product.id,
                productName: product.name,
                quantity: item.quantity,
                unitPrice,
                totalPrice: unitPrice * item.quantity
            }));
        }
        
        return orderItems;
    }
}

Key Characteristics of Well-Designed Business Logic:

✅ Presentation-Agnostic — The OrderService doesn't know if it's being called from a web controller, a CLI command, a message queue handler, or a test. It works the same regardless of how it's invoked.

✅ Persistence-Agnostic — The service uses repository interfaces. It doesn't know if data comes from PostgreSQL, MongoDB, or an in-memory store. It could even be a mock in tests.

✅ Testable in Isolation — You can unit test calculateDiscount() with no database, no HTTP, no external dependencies. Just create a Customer object and call the method.

✅ Expressive of Business Intent — Reading the code reveals business meaning: "Premium customers get a discount," "Orders can't exceed credit limits." The code reads like a business specification.

Domain Objects vs DTOs

The Business Layer should work with rich Domain Objects (Customer, Order, Product) that encapsulate behavior, not just data. DTOs (Data Transfer Objects) are for moving data across layer boundaries. Don't let DTOs leak into your business logic—translate them at the edges.

The Data Access Layer: Guardian of Persistence

The Data Access Layer (also called the Persistence Layer or Infrastructure Layer) handles all interactions with external data sources—databases, file systems, external APIs, caches, and any other system that stores or retrieves data.

This layer serves a critical isolation function: it shields the Business Layer from the details of how data is stored, retrieved, and managed. The business logic doesn't care whether customers are stored in PostgreSQL, MongoDB, or a flat file—it just asks for customers and receives domain objects.

Core Responsibilities:

Data Persistence
- Save domain objects to storage
- Handle object-relational mapping (ORM) or document mapping
- Manage identity generation (auto-increment, UUIDs, etc.)
Data Retrieval
- Query databases using SQL, query builders, or ORM methods
- Return domain objects, not raw database rows
- Handle result pagination and filtering
Query Optimization
- Implement efficient query strategies
- Handle lazy loading vs eager loading trade-offs
- Manage connection pooling and caching
External System Integration
- Wrap external API calls behind repository-like interfaces
- Handle serialization/deserialization
- Manage timeouts, retries, and circuit breakers
Transaction Management
- Begin, commit, and rollback transactions
- Handle connection management
- Support unit of work patterns

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
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
// data/repositories/OrderRepository.ts
 
// First, the interface that the Business Layer depends on
// This interface lives at the boundary - it could be in the business layer
export interface OrderRepository {
    findById(id: string): Promise<Order | null>;
    findByCustomerId(customerId: string, options?: PaginationOptions): Promise<Order[]>;
    save(order: Order): Promise<Order>;
    update(order: Order): Promise<Order>;
    delete(id: string): Promise<void>;
    getOutstandingBalance(customerId: string): Promise<number>;
}
 
// The concrete implementation that handles actual database operations
// data/repositories/impl/PostgresOrderRepository.ts
import { Pool, QueryResult } from 'pg';
import { Order, OrderItem, OrderStatus } from '../../../business/domain/Order';
 
export class PostgresOrderRepository implements OrderRepository {
    constructor(private readonly pool: Pool) {}
 
    async findById(id: string): Promise<Order | null> {
        const orderResult = await this.pool.query(
            `SELECT o.*, 
                    json_agg(
                        json_build_object(
                            'id', oi.id,
                            'product_id', oi.product_id,
                            'product_name', oi.product_name,
                            'quantity', oi.quantity,
                            'unit_price', oi.unit_price,
                            'total_price', oi.total_price
                        )
                    ) as items
             FROM orders o
             LEFT JOIN order_items oi ON o.id = oi.order_id
             WHERE o.id = $1
             GROUP BY o.id`,
            [id]
        );
 
        if (orderResult.rows.length === 0) {
            return null;
        }
 
        // Map database row to domain object
        return this.mapToDomain(orderResult.rows[0]);
    }
 
    async save(order: Order): Promise<Order> {
        const client = await this.pool.connect();
        
        try {
            await client.query('BEGIN');
 
            // Insert order
            const orderResult = await client.query(
                `INSERT INTO orders 
                 (id, customer_id, subtotal, discount, tax, total, status, created_at)
                 VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
                 RETURNING *`,
                [
                    order.id,
                    order.customerId,
                    order.subtotal,
                    order.discount,
                    order.tax,
                    order.total,
                    order.status,
                    order.createdAt
                ]
            );
 
            // Insert order items
            for (const item of order.items) {
                await client.query(
                    `INSERT INTO order_items 
                     (id, order_id, product_id, product_name, quantity, unit_price, total_price)
                     VALUES ($1, $2, $3, $4, $5, $6, $7)`,
                    [
                        item.id,
                        order.id,
                        item.productId,
                        item.productName,
                        item.quantity,
                        item.unitPrice,
                        item.totalPrice
                    ]
                );
            }
 
            await client.query('COMMIT');
            
            return order;
        } catch (error) {
            await client.query('ROLLBACK');
            throw error;
        } finally {
            client.release();
        }
    }
 
    async getOutstandingBalance(customerId: string): Promise<number> {
        const result = await this.pool.query(
            `SELECT COALESCE(SUM(total), 0) as outstanding
             FROM orders
             WHERE customer_id = $1
             AND status IN ('PENDING', 'CONFIRMED', 'SHIPPED')`,
            [customerId]
        );
        
        return parseFloat(result.rows[0].outstanding);
    }
 
    /**
     * Map database row to domain object
     * This is where the translation between persistence format
     * and domain model occurs
     */
    private mapToDomain(row: any): Order {
        const items = row.items
            .filter((item: any) => item.id !== null)
            .map((item: any) => OrderItem.create({
                id: item.id,
                productId: item.product_id,
                productName: item.product_name,
                quantity: item.quantity,
                unitPrice: parseFloat(item.unit_price),
                totalPrice: parseFloat(item.total_price)
            }));
 
        return Order.reconstitute({
            id: row.id,
            customerId: row.customer_id,
            items,
            subtotal: parseFloat(row.subtotal),
            discount: parseFloat(row.discount),
            tax: parseFloat(row.tax),
            total: parseFloat(row.total),
            status: row.status as OrderStatus,
            createdAt: row.created_at,
            updatedAt: row.updated_at
        });
    }
}

Key Characteristics of Well-Designed Data Access:

✅ Interface-Based — The Business Layer depends on the OrderRepository interface, not the PostgresOrderRepository implementation. This enables testing with mocks and swapping implementations.

✅ Domain Object Output — The repository returns Order domain objects, not database rows or ORM entities. The Business Layer never sees database-specific types.

✅ Encapsulated SQL — All SQL lives in this layer. Changing from Postgres to MySQL affects only this layer.

✅ Transaction Management — The repository handles database transactions. The Business Layer expresses what should be atomic; the Data Layer implements how.

Repository Pattern

The Repository pattern, used extensively in the Data Access Layer, provides a collection-like interface for accessing domain objects. We'll explore this pattern in much greater depth in the DDD chapter on Repositories.

Layer Boundaries and Communication

Understanding how layers communicate is as important as understanding what each layer does. The contracts between layers define the system's flexibility and maintainability.

Data Flow Through Layers:

Data transforms as it moves through layers, adapting to each layer's needs and abstractions:

Different Objects for Different Layers:

Many developers mistakenly use the same object type throughout all layers. This creates tight coupling. Instead, each layer should have its own object types:

Object Types Across Layers
Layer	Object Type	Purpose	Characteristics
Presentation	DTOs (Data Transfer Objects)	Carry data across layer boundaries	Simple data containers, serializable, validation annotations
Presentation	View Models	Shape data for UI rendering	UI-specific formatting, computed display properties
Business	Domain Objects/Entities	Encapsulate business logic and state	Rich behavior, invariant enforcement, identity
Business	Value Objects	Represent immutable values	No identity, equality by value, immutable
Data	Database Entities/Records	Map to database schema	ORM annotations, database-specific types, IDs
Data	Data Mappers	Transform between domain and database	Mapping logic, type conversion

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
// Presentation Layer: DTO for API communication
// presentation/dto/CreateOrderDTO.ts
export class CreateOrderDTO {
    @IsNotEmpty()
    @IsUUID()
    customerId: string;
 
    @IsArray()
    @ValidateNested({ each: true })
    items: OrderItemDTO[];
}
 
export class OrderItemDTO {
    @IsUUID()
    productId: string;
 
    @IsPositive()
    @IsInt()
    quantity: number;
}
 
// Business Layer: Rich Domain Object
// business/domain/Order.ts
export class Order {
    private constructor(
        readonly id: string,
        readonly customerId: string,
        private items: OrderItem[],
        private _status: OrderStatus,
        private _subtotal: number,
        private _discount: number,
        private _tax: number
    ) {
        // Invariant: Order must have at least one item
        if (items.length === 0) {
            throw new InvalidOrderError('Order must have at least one item');
        }
    }
 
    get total(): number {
        return this._subtotal - this._discount + this._tax;
    }
 
    get status(): OrderStatus {
        return this._status;
    }
 
    // Business behavior: Only pending orders can be canceled
    cancel(): void {
        if (this._status !== OrderStatus.PENDING) {
            throw new OrderCannotBeCanceledError(
                `Order ${this.id} cannot be canceled: status is ${this._status}`
            );
        }
        this._status = OrderStatus.CANCELED;
    }
 
    // Business behavior: Calculate if order is eligible for express shipping
    isEligibleForExpressShipping(): boolean {
        return this.total > 100 && this.items.length <= 5;
    }
}
 
// Data Layer: Database entity for ORM
// data/entities/OrderEntity.ts (e.g., TypeORM)
@Entity('orders')
export class OrderEntity {
    @PrimaryColumn('uuid')
    id: string;
 
    @Column('uuid', { name: 'customer_id' })
    customerId: string;
 
    @Column('decimal', { precision: 10, scale: 2 })
    subtotal: string; // Decimal stored as string in some ORMs
 
    @Column('varchar', { length: 20 })
    status: string;
 
    @CreateDateColumn({ name: 'created_at' })
    createdAt: Date;
 
    @OneToMany(() => OrderItemEntity, item => item.order)
    items: OrderItemEntity[];
}

Avoid Object Leakage

A common anti-pattern is letting database entities leak into controllers or DTOs leak into domain logic. This creates hidden coupling. If your controller is importing ORM annotations or your domain object has @Column decorators, you have object leakage. Keep layer-specific types within their layers.

Practical Directory Structure

Theory is valuable, but implementation requires concrete decisions about how to organize code. Here's a practical directory structure that embodies layered architecture principles:

src/
├── presentation/                  # Presentation Layer
│   ├── controllers/               # HTTP request handlers
│   │   ├── CustomerController.ts
│   │   ├── OrderController.ts
│   │   └── ProductController.ts
│   ├── dto/                       # Data Transfer Objects
│   │   ├── request/               # Incoming request DTOs
│   │   │   ├── CreateCustomerDTO.ts
│   │   │   └── CreateOrderDTO.ts
│   │   └── response/              # Outgoing response DTOs
│   │       ├── CustomerResponseDTO.ts
│   │       └── OrderResponseDTO.ts
│   ├── middleware/                # Express/framework middleware
│   │   ├── authMiddleware.ts
│   │   └── errorHandlerMiddleware.ts
│   └── routes/                    # Route definitions
│       └── index.ts
│
├── business/                      # Business Logic Layer
│   ├── domain/                    # Domain objects (entities, value objects)
│   │   ├── Customer.ts
│   │   ├── Order.ts
│   │   ├── Product.ts
│   │   └── valueObjects/
│   │       ├── Money.ts
│   │       ├── EmailAddress.ts
│   │       └── Address.ts
│   ├── services/                  # Business/Application services
│   │   ├── CustomerService.ts
│   │   ├── OrderService.ts
│   │   └── ProductService.ts
│   ├── events/                    # Domain events
│   │   ├── OrderCreatedEvent.ts
│   │   └── EventPublisher.ts
│   ├── errors/                    # Business exceptions
│   │   ├── CustomerNotFoundError.ts
│   │   └── CreditLimitExceededError.ts
│   └── interfaces/                # Repository interfaces (ports)
│       ├── CustomerRepository.ts
│       ├── OrderRepository.ts
│       └── ProductRepository.ts
│
├── data/                          # Data Access Layer
│   ├── repositories/              # Repository implementations
│   │   ├── PostgresCustomerRepository.ts
│   │   ├── PostgresOrderRepository.ts
│   │   └── PostgresProductRepository.ts
│   ├── entities/                  # ORM entities
│   │   ├── CustomerEntity.ts
│   │   ├── OrderEntity.ts
│   │   └── ProductEntity.ts
│   ├── mappers/                   # Domain <-> Entity mappers
│   │   ├── CustomerMapper.ts
│   │   └── OrderMapper.ts
│   └── migrations/                # Database migrations
│       └── ...
│
├── infrastructure/                # Cross-cutting infrastructure
│   ├── config/                    # Configuration
│   │   └── database.ts
│   ├── logging/                   # Logging infrastructure
│   └── di/                        # Dependency injection setup
│       └── container.ts
│
└── app.ts                         # Application entry point

Key Observations:

Clear Layer Boundaries — Each top-level directory represents a layer. A developer can immediately understand where to find or place code.
Repository Interfaces in Business Layer — The interface for OrderRepository lives in the business layer (business/interfaces), but the implementation (PostgresOrderRepository) lives in the data layer. This follows the Dependency Inversion Principle.
Separate Request and Response DTOs — Input validation concerns differ from output formatting concerns. Separating them makes each cleaner.
Domain Objects Separate from ORM Entities — The domain layer's Order.ts is a rich object with behavior. The data layer's OrderEntity.ts is a simple ORM mapping. The mapper bridges them.

Start Simple, Extract as Needed

For smaller projects, this structure might feel like overkill. Start with a simpler version—perhaps just controllers/, services/, and repositories/. As complexity grows, extract sub-directories. Architecture should serve the code, not the other way around.

Summary: The Three-Layer Foundation

We've covered the anatomy of traditional layered architecture in depth. Let's consolidate the essential knowledge:

Key Takeaways

•Presentation Layer — Handles user/system interaction. Translates external requests to internal calls. Contains no business logic. Stays 'thin' and focused on HTTP/UI concerns.
•Business Logic Layer — The application's semantic core. Implements business rules, workflows, and validations. Agnostic to presentation and persistence details.
•Data Access Layer — Manages all data persistence. Shields business logic from storage implementation. Returns domain objects, not database rows.
•Dependencies Flow Downward — Upper layers depend on lower layers. Lower layers have no knowledge of upper layers. This enables independent changes and testing.
•Each Layer Has Its Object Types — DTOs for presentation, Domain Objects for business, Entities for data. Avoid letting layer-specific types leak across boundaries.
•Layered Architecture Is Logical, Not Physical — Layers exist in code organization. They can be deployed together (monolith) or separately (multi-tier). The pattern is about separation of concerns.

What's Next:

Now that we understand what each layer does, the next page examines how layers depend on each other and the rules that govern these dependencies. We'll explore dependency direction, the Dependency Inversion Principle applied to layers, and common violations that undermine the architecture's benefits.

Page Complete

You now have a deep understanding of the three canonical layers in traditional layered architecture—their responsibilities, their internal structure, and how data flows between them. Next, we'll explore the critical topic of layer dependencies and the rules that keep layers properly decoupled.

System Design (LLD)Traditional Layered Architecture

Traditional Layered Architecture

LevelIntermediate

Duration60 mins

TopicTraditional Layered Architecture

1 / 4

Presentation, Business, Data Layers

The Anatomy of Enterprise Software

What You Will Learn

The Origin of Layered Thinking

Consider a typical early application without architectural structure:

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
// Everything mixed together - UI, logic, and database
public class CustomerScreen {
    public void displayCustomerDetails(int customerId) {
        // Direct database access in UI code
        Connection conn = DriverManager.getConnection("jdbc:mysql://localhost/db");
        PreparedStatement stmt = conn.prepareStatement(
            "SELECT * FROM customers WHERE id = ?"
        );
        stmt.setInt(1, customerId);
        ResultSet rs = stmt.executeQuery();
        
        if (rs.next()) {
            // Business logic mixed with UI
            String name = rs.getString("name");
            double creditLimit = rs.getDouble("credit_limit");
            double currentBalance = calculateBalance(customerId, conn);
            
            // Is customer credit-worthy? Business rule embedded in UI
            boolean creditWorthy = currentBalance < creditLimit * 0.8;
            
            // UI logic
            nameLabel.setText(name);
            balanceLabel.setText(formatCurrency(currentBalance));
            creditIndicator.setColor(creditWorthy ? Color.GREEN : Color.RED);
        }
        
        conn.close();
    }
    
    private double calculateBalance(int customerId, Connection conn) {
        // More mixed database and business logic...
        // This method does SQL queries AND business calculations
    }
}

This code exhibits several fatal flaws that become catastrophic as systems grow:

Problem 4: Deployment Coupling Changing any part of the system requires redeploying everything. A small UI tweak? Redeploy. A database optimization? Redeploy the UI too.

Layered architecture emerged as the antidote to these problems.

Historical Context

The Layered Architecture Model

Presentation Layer — Handles user interface and user interaction
Business Logic Layer — Contains domain logic and business rules
Data Access Layer — Manages data persistence and retrieval

This constraint has profound implications:

The Presentation Layer knows about the Business Layer, but the Business Layer doesn't know it's being used by a web interface
The Business Layer knows about the Data Access Layer, but the Data Access Layer doesn't know what business rules use its data
Changes in upper layers don't affect lower layers; changes in lower layers may require upper layer adjustments

Layers vs Tiers

The Presentation Layer: Gateway to the User

Core Responsibilities:

Request Intake and Validation
- Accept HTTP requests, form submissions, API calls, or user events
- Perform syntactic validation (is this valid JSON? Is this a well-formed email address?)
- Note: semantic validation (is this email address registered?) belongs in the Business Layer
Request Translation
- Convert external data formats into internal representations
- Map HTTP request bodies to DTOs (Data Transfer Objects)
- Parse and deserialize incoming data
Orchestration of Business Operations
- Call appropriate Business Layer services
- Coordinate multiple service calls when needed
- Note: Complex business logic coordination should push down to a domain or application service
Response Formatting
- Convert internal objects to external representations (JSON, HTML, XML)
- Handle content negotiation
- Apply view transformations and formatting
User Experience Concerns
- Session management and authentication state
- Navigation and routing
- Error message formatting and presentation
- Localization and internationalization of display text

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
// presentation/controllers/CustomerController.ts
import { Request, Response } from 'express';
import { CustomerService } from '../../business/services/CustomerService';
import { CreateCustomerDTO, CustomerResponseDTO } from '../dto';
import { validate } from 'class-validator';
import { plainToClass } from 'class-transformer';
 
export class CustomerController {
    constructor(private readonly customerService: CustomerService) {}
 
    /**
     * Handle customer creation request
     * Notice: This controller does NOT contain business logic
     */
    async createCustomer(req: Request, res: Response): Promise<void> {
        try {
            // 1. Request translation: Convert raw request to typed DTO
            const createCustomerDto = plainToClass(CreateCustomerDTO, req.body);
            
            // 2. Syntactic validation: Is the data well-formed?
            const validationErrors = await validate(createCustomerDto);
            if (validationErrors.length > 0) {
                res.status(400).json({
                    error: 'Validation failed',
                    details: this.formatValidationErrors(validationErrors)
                });
                return;
            }
            
            // 3. Delegate to business layer: The controller doesn't know HOW
            //    customers are created, just that the service can do it
            const customer = await this.customerService.createCustomer(
                createCustomerDto.name,
                createCustomerDto.email,
                createCustomerDto.creditLimit
            );
            
            // 4. Response formatting: Convert domain object to response DTO
            const responseDto = CustomerResponseDTO.fromDomain(customer);
            
            res.status(201).json(responseDto);
        } catch (error) {
            // 5. Error handling: Present errors appropriately
            if (error instanceof CustomerAlreadyExistsError) {
                res.status(409).json({ error: error.message });
            } else if (error instanceof InvalidCreditLimitError) {
                res.status(422).json({ error: error.message });
            } else {
                // Log unexpected errors, return generic message
                console.error('Unexpected error:', error);
                res.status(500).json({ error: 'Internal server error' });
            }
        }
    }
 
    async getCustomer(req: Request, res: Response): Promise<void> {
        const customerId = req.params.id;
        
        // Syntactic validation only - is this a valid ID format?
        if (!this.isValidUUID(customerId)) {
            res.status(400).json({ error: 'Invalid customer ID format' });
            return;
        }
        
        const customer = await this.customerService.getCustomerById(customerId);
        
        if (!customer) {
            res.status(404).json({ error: 'Customer not found' });
            return;
        }
        
        res.json(CustomerResponseDTO.fromDomain(customer));
    }
 
    private formatValidationErrors(errors: ValidationError[]): object {
        // Convert validation library errors to API-friendly format
    }
 
    private isValidUUID(value: string): boolean {
        const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
        return uuidRegex.test(value);
    }
}

What the Presentation Layer Should NOT Do:

❌ Implement business rules — "If the customer's credit limit exceeds $10,000, require manager approval" belongs in the Business Layer, not in a controller

❌ Access the database directly — No SQL queries, no ORM calls, no repository access. The Presentation Layer speaks only to the Business Layer

❌ Contain reusable domain logic — If two controllers need the same logic, that logic should be in a shared Business Layer service, not duplicated in controllers

❌ Make business decisions — The controller shouldn't decide whether a customer is credit-worthy; it should call a service that makes that determination

The Thin Controller Principle

The Business Logic Layer: The Beating Heart

Core Responsibilities:

Business Rule Implementation
- Encode domain constraints: "An order cannot exceed customer credit limit"
- Implement policies: "Premium customers get 10% discount"
- Enforce invariants: "Account balance can never go negative"
Workflow Orchestration
- Coordinate multi-step business processes
- Manage transaction boundaries (logically, not technically)
- Handle business events and triggers
Domain Calculations
- Compute derived values: totals, averages, projections
- Apply business formulas: pricing, scoring, rating
- Generate business identifiers: order numbers, invoice codes
Business Validation
- Semantic validation: "Does this customer exist?", "Is this product available?"
- Cross-field validation: "End date must be after start date"
- Business constraint checking: "Only active employees can submit expenses"

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
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
// business/services/OrderService.ts
import { Order, OrderItem, OrderStatus } from '../domain/Order';
import { Customer } from '../domain/Customer';
import { Product } from '../domain/Product';
import { OrderRepository } from '../../data/repositories/OrderRepository';
import { CustomerRepository } from '../../data/repositories/CustomerRepository';
import { ProductRepository } from '../../data/repositories/ProductRepository';
import { EventPublisher } from '../events/EventPublisher';
 
export class OrderService {
    constructor(
        private readonly orderRepository: OrderRepository,
        private readonly customerRepository: CustomerRepository,
        private readonly productRepository: ProductRepository,
        private readonly eventPublisher: EventPublisher
    ) {}
 
    /**
     * Create a new order with business rule enforcement
     * 
     * This method embodies core business logic:
     * - Customer validation and credit checking
     * - Product availability verification
     * - Pricing calculations with discounts
     * - Order total computation
     * - Business event emission
     */
    async createOrder(
        customerId: string,
        items: Array<{ productId: string; quantity: number }>
    ): Promise<Order> {
        // 1. Retrieve and validate customer
        const customer = await this.customerRepository.findById(customerId);
        if (!customer) {
            throw new CustomerNotFoundError(customerId);
        }
        
        // 2. Business rule: Only active customers can place orders
        if (!customer.isActive()) {
            throw new InactiveCustomerError(customerId);
        }
        
        // 3. Resolve products and build order items with pricing
        const orderItems = await this.resolveOrderItems(items, customer);
        
        // 4. Calculate order total with business rules
        const subtotal = this.calculateSubtotal(orderItems);
        const discount = this.calculateDiscount(customer, subtotal);
        const tax = this.calculateTax(subtotal - discount, customer.shippingAddress);
        const total = subtotal - discount + tax;
        
        // 5. Business rule: Credit limit check
        const currentOutstanding = await this.orderRepository.getOutstandingBalance(customerId);
        if (currentOutstanding + total > customer.creditLimit) {
            throw new CreditLimitExceededError(
                customerId,
                customer.creditLimit,
                currentOutstanding + total
            );
        }
        
        // 6. Create the order domain object
        const order = Order.create({
            customerId,
            items: orderItems,
            subtotal,
            discount,
            tax,
            total,
            status: OrderStatus.PENDING
        });
        
        // 7. Persist through data layer
        const savedOrder = await this.orderRepository.save(order);
        
        // 8. Publish domain event for downstream processing
        await this.eventPublisher.publish(new OrderCreatedEvent(savedOrder));
        
        return savedOrder;
    }
 
    /**
     * Business logic: Calculate applicable discount
     * 
     * Rules:
     * - Premium customers: 10% discount
     * - Orders over $500: additional 5% discount
     * - Maximum discount: 15%
     */
    private calculateDiscount(customer: Customer, subtotal: number): number {
        let discountPercentage = 0;
        
        if (customer.isPremium()) {
            discountPercentage += 0.10;
        }
        
        if (subtotal > 500) {
            discountPercentage += 0.05;
        }
        
        discountPercentage = Math.min(discountPercentage, 0.15);
        
        return subtotal * discountPercentage;
    }
 
    /**
     * Business logic: Tax calculation based on shipping destination
     */
    private calculateTax(taxableAmount: number, address: Address): number {
        const taxRate = this.getTaxRateForAddress(address);
        return taxableAmount * taxRate;
    }
 
    /**
     * Validate products, check availability, apply pricing
     */
    private async resolveOrderItems(
        items: Array<{ productId: string; quantity: number }>,
        customer: Customer
    ): Promise<OrderItem[]> {
        const orderItems: OrderItem[] = [];
        
        for (const item of items) {
            const product = await this.productRepository.findById(item.productId);
            
            if (!product) {
                throw new ProductNotFoundError(item.productId);
            }
            
            // Business rule: Check stock availability
            if (product.availableQuantity < item.quantity) {
                throw new InsufficientStockError(
                    item.productId,
                    item.quantity,
                    product.availableQuantity
                );
            }
            
            // Business rule: Apply customer-specific pricing tier
            const unitPrice = this.getPriceForCustomer(product, customer);
            
            orderItems.push(OrderItem.create({
                productId: product.id,
                productName: product.name,
                quantity: item.quantity,
                unitPrice,
                totalPrice: unitPrice * item.quantity
            }));
        }
        
        return orderItems;
    }
}

Key Characteristics of Well-Designed Business Logic:

✅ Persistence-Agnostic — The service uses repository interfaces. It doesn't know if data comes from PostgreSQL, MongoDB, or an in-memory store. It could even be a mock in tests.

✅ Testable in Isolation — You can unit test calculateDiscount() with no database, no HTTP, no external dependencies. Just create a Customer object and call the method.

Domain Objects vs DTOs

The Data Access Layer: Guardian of Persistence

Core Responsibilities:

Data Persistence
- Save domain objects to storage
- Handle object-relational mapping (ORM) or document mapping
- Manage identity generation (auto-increment, UUIDs, etc.)
Data Retrieval
- Query databases using SQL, query builders, or ORM methods
- Return domain objects, not raw database rows
- Handle result pagination and filtering
Query Optimization
- Implement efficient query strategies
- Handle lazy loading vs eager loading trade-offs
- Manage connection pooling and caching
External System Integration
- Wrap external API calls behind repository-like interfaces
- Handle serialization/deserialization
- Manage timeouts, retries, and circuit breakers
Transaction Management
- Begin, commit, and rollback transactions
- Handle connection management
- Support unit of work patterns

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
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
// data/repositories/OrderRepository.ts
 
// First, the interface that the Business Layer depends on
// This interface lives at the boundary - it could be in the business layer
export interface OrderRepository {
    findById(id: string): Promise<Order | null>;
    findByCustomerId(customerId: string, options?: PaginationOptions): Promise<Order[]>;
    save(order: Order): Promise<Order>;
    update(order: Order): Promise<Order>;
    delete(id: string): Promise<void>;
    getOutstandingBalance(customerId: string): Promise<number>;
}
 
// The concrete implementation that handles actual database operations
// data/repositories/impl/PostgresOrderRepository.ts
import { Pool, QueryResult } from 'pg';
import { Order, OrderItem, OrderStatus } from '../../../business/domain/Order';
 
export class PostgresOrderRepository implements OrderRepository {
    constructor(private readonly pool: Pool) {}
 
    async findById(id: string): Promise<Order | null> {
        const orderResult = await this.pool.query(
            `SELECT o.*, 
                    json_agg(
                        json_build_object(
                            'id', oi.id,
                            'product_id', oi.product_id,
                            'product_name', oi.product_name,
                            'quantity', oi.quantity,
                            'unit_price', oi.unit_price,
                            'total_price', oi.total_price
                        )
                    ) as items
             FROM orders o
             LEFT JOIN order_items oi ON o.id = oi.order_id
             WHERE o.id = $1
             GROUP BY o.id`,
            [id]
        );
 
        if (orderResult.rows.length === 0) {
            return null;
        }
 
        // Map database row to domain object
        return this.mapToDomain(orderResult.rows[0]);
    }
 
    async save(order: Order): Promise<Order> {
        const client = await this.pool.connect();
        
        try {
            await client.query('BEGIN');
 
            // Insert order
            const orderResult = await client.query(
                `INSERT INTO orders 
                 (id, customer_id, subtotal, discount, tax, total, status, created_at)
                 VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
                 RETURNING *`,
                [
                    order.id,
                    order.customerId,
                    order.subtotal,
                    order.discount,
                    order.tax,
                    order.total,
                    order.status,
                    order.createdAt
                ]
            );
 
            // Insert order items
            for (const item of order.items) {
                await client.query(
                    `INSERT INTO order_items 
                     (id, order_id, product_id, product_name, quantity, unit_price, total_price)
                     VALUES ($1, $2, $3, $4, $5, $6, $7)`,
                    [
                        item.id,
                        order.id,
                        item.productId,
                        item.productName,
                        item.quantity,
                        item.unitPrice,
                        item.totalPrice
                    ]
                );
            }
 
            await client.query('COMMIT');
            
            return order;
        } catch (error) {
            await client.query('ROLLBACK');
            throw error;
        } finally {
            client.release();
        }
    }
 
    async getOutstandingBalance(customerId: string): Promise<number> {
        const result = await this.pool.query(
            `SELECT COALESCE(SUM(total), 0) as outstanding
             FROM orders
             WHERE customer_id = $1
             AND status IN ('PENDING', 'CONFIRMED', 'SHIPPED')`,
            [customerId]
        );
        
        return parseFloat(result.rows[0].outstanding);
    }
 
    /**
     * Map database row to domain object
     * This is where the translation between persistence format
     * and domain model occurs
     */
    private mapToDomain(row: any): Order {
        const items = row.items
            .filter((item: any) => item.id !== null)
            .map((item: any) => OrderItem.create({
                id: item.id,
                productId: item.product_id,
                productName: item.product_name,
                quantity: item.quantity,
                unitPrice: parseFloat(item.unit_price),
                totalPrice: parseFloat(item.total_price)
            }));
 
        return Order.reconstitute({
            id: row.id,
            customerId: row.customer_id,
            items,
            subtotal: parseFloat(row.subtotal),
            discount: parseFloat(row.discount),
            tax: parseFloat(row.tax),
            total: parseFloat(row.total),
            status: row.status as OrderStatus,
            createdAt: row.created_at,
            updatedAt: row.updated_at
        });
    }
}

Key Characteristics of Well-Designed Data Access:

✅ Domain Object Output — The repository returns Order domain objects, not database rows or ORM entities. The Business Layer never sees database-specific types.

✅ Encapsulated SQL — All SQL lives in this layer. Changing from Postgres to MySQL affects only this layer.

✅ Transaction Management — The repository handles database transactions. The Business Layer expresses what should be atomic; the Data Layer implements how.

Repository Pattern

Layer Boundaries and Communication

Understanding how layers communicate is as important as understanding what each layer does. The contracts between layers define the system's flexibility and maintainability.

Data Flow Through Layers:

Data transforms as it moves through layers, adapting to each layer's needs and abstractions:

Different Objects for Different Layers:

Many developers mistakenly use the same object type throughout all layers. This creates tight coupling. Instead, each layer should have its own object types:

Object Types Across Layers
Layer	Object Type	Purpose	Characteristics
Presentation	DTOs (Data Transfer Objects)	Carry data across layer boundaries	Simple data containers, serializable, validation annotations
Presentation	View Models	Shape data for UI rendering	UI-specific formatting, computed display properties
Business	Domain Objects/Entities	Encapsulate business logic and state	Rich behavior, invariant enforcement, identity
Business	Value Objects	Represent immutable values	No identity, equality by value, immutable
Data	Database Entities/Records	Map to database schema	ORM annotations, database-specific types, IDs
Data	Data Mappers	Transform between domain and database	Mapping logic, type conversion

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
// Presentation Layer: DTO for API communication
// presentation/dto/CreateOrderDTO.ts
export class CreateOrderDTO {
    @IsNotEmpty()
    @IsUUID()
    customerId: string;
 
    @IsArray()
    @ValidateNested({ each: true })
    items: OrderItemDTO[];
}
 
export class OrderItemDTO {
    @IsUUID()
    productId: string;
 
    @IsPositive()
    @IsInt()
    quantity: number;
}
 
// Business Layer: Rich Domain Object
// business/domain/Order.ts
export class Order {
    private constructor(
        readonly id: string,
        readonly customerId: string,
        private items: OrderItem[],
        private _status: OrderStatus,
        private _subtotal: number,
        private _discount: number,
        private _tax: number
    ) {
        // Invariant: Order must have at least one item
        if (items.length === 0) {
            throw new InvalidOrderError('Order must have at least one item');
        }
    }
 
    get total(): number {
        return this._subtotal - this._discount + this._tax;
    }
 
    get status(): OrderStatus {
        return this._status;
    }
 
    // Business behavior: Only pending orders can be canceled
    cancel(): void {
        if (this._status !== OrderStatus.PENDING) {
            throw new OrderCannotBeCanceledError(
                `Order ${this.id} cannot be canceled: status is ${this._status}`
            );
        }
        this._status = OrderStatus.CANCELED;
    }
 
    // Business behavior: Calculate if order is eligible for express shipping
    isEligibleForExpressShipping(): boolean {
        return this.total > 100 && this.items.length <= 5;
    }
}
 
// Data Layer: Database entity for ORM
// data/entities/OrderEntity.ts (e.g., TypeORM)
@Entity('orders')
export class OrderEntity {
    @PrimaryColumn('uuid')
    id: string;
 
    @Column('uuid', { name: 'customer_id' })
    customerId: string;
 
    @Column('decimal', { precision: 10, scale: 2 })
    subtotal: string; // Decimal stored as string in some ORMs
 
    @Column('varchar', { length: 20 })
    status: string;
 
    @CreateDateColumn({ name: 'created_at' })
    createdAt: Date;
 
    @OneToMany(() => OrderItemEntity, item => item.order)
    items: OrderItemEntity[];
}

Avoid Object Leakage

Practical Directory Structure

Theory is valuable, but implementation requires concrete decisions about how to organize code. Here's a practical directory structure that embodies layered architecture principles:

src/
├── presentation/                  # Presentation Layer
│   ├── controllers/               # HTTP request handlers
│   │   ├── CustomerController.ts
│   │   ├── OrderController.ts
│   │   └── ProductController.ts
│   ├── dto/                       # Data Transfer Objects
│   │   ├── request/               # Incoming request DTOs
│   │   │   ├── CreateCustomerDTO.ts
│   │   │   └── CreateOrderDTO.ts
│   │   └── response/              # Outgoing response DTOs
│   │       ├── CustomerResponseDTO.ts
│   │       └── OrderResponseDTO.ts
│   ├── middleware/                # Express/framework middleware
│   │   ├── authMiddleware.ts
│   │   └── errorHandlerMiddleware.ts
│   └── routes/                    # Route definitions
│       └── index.ts
│
├── business/                      # Business Logic Layer
│   ├── domain/                    # Domain objects (entities, value objects)
│   │   ├── Customer.ts
│   │   ├── Order.ts
│   │   ├── Product.ts
│   │   └── valueObjects/
│   │       ├── Money.ts
│   │       ├── EmailAddress.ts
│   │       └── Address.ts
│   ├── services/                  # Business/Application services
│   │   ├── CustomerService.ts
│   │   ├── OrderService.ts
│   │   └── ProductService.ts
│   ├── events/                    # Domain events
│   │   ├── OrderCreatedEvent.ts
│   │   └── EventPublisher.ts
│   ├── errors/                    # Business exceptions
│   │   ├── CustomerNotFoundError.ts
│   │   └── CreditLimitExceededError.ts
│   └── interfaces/                # Repository interfaces (ports)
│       ├── CustomerRepository.ts
│       ├── OrderRepository.ts
│       └── ProductRepository.ts
│
├── data/                          # Data Access Layer
│   ├── repositories/              # Repository implementations
│   │   ├── PostgresCustomerRepository.ts
│   │   ├── PostgresOrderRepository.ts
│   │   └── PostgresProductRepository.ts
│   ├── entities/                  # ORM entities
│   │   ├── CustomerEntity.ts
│   │   ├── OrderEntity.ts
│   │   └── ProductEntity.ts
│   ├── mappers/                   # Domain <-> Entity mappers
│   │   ├── CustomerMapper.ts
│   │   └── OrderMapper.ts
│   └── migrations/                # Database migrations
│       └── ...
│
├── infrastructure/                # Cross-cutting infrastructure
│   ├── config/                    # Configuration
│   │   └── database.ts
│   ├── logging/                   # Logging infrastructure
│   └── di/                        # Dependency injection setup
│       └── container.ts
│
└── app.ts                         # Application entry point

Key Observations:

Clear Layer Boundaries — Each top-level directory represents a layer. A developer can immediately understand where to find or place code.
Repository Interfaces in Business Layer — The interface for OrderRepository lives in the business layer (business/interfaces), but the implementation (PostgresOrderRepository) lives in the data layer. This follows the Dependency Inversion Principle.
Separate Request and Response DTOs — Input validation concerns differ from output formatting concerns. Separating them makes each cleaner.
Domain Objects Separate from ORM Entities — The domain layer's Order.ts is a rich object with behavior. The data layer's OrderEntity.ts is a simple ORM mapping. The mapper bridges them.

Start Simple, Extract as Needed

Summary: The Three-Layer Foundation

We've covered the anatomy of traditional layered architecture in depth. Let's consolidate the essential knowledge:

Key Takeaways

•Presentation Layer — Handles user/system interaction. Translates external requests to internal calls. Contains no business logic. Stays 'thin' and focused on HTTP/UI concerns.
•Business Logic Layer — The application's semantic core. Implements business rules, workflows, and validations. Agnostic to presentation and persistence details.
•Data Access Layer — Manages all data persistence. Shields business logic from storage implementation. Returns domain objects, not database rows.
•Dependencies Flow Downward — Upper layers depend on lower layers. Lower layers have no knowledge of upper layers. This enables independent changes and testing.
•Each Layer Has Its Object Types — DTOs for presentation, Domain Objects for business, Entities for data. Avoid letting layer-specific types leak across boundaries.
•Layered Architecture Is Logical, Not Physical — Layers exist in code organization. They can be deployed together (monolith) or separately (multi-tier). The pattern is about separation of concerns.

What's Next:

Page Complete