The Service Layer — Decoupling Business Logic from HTTP

Client HTTP Request
      │
      ▼
┌─────────────────────────────────────────────────────────────┐
│  Controller / Route Handler (Express / FastAPI)             │
│  - Extracts params from request                             │
│  - Calls: orderService.createOrder({ customerId, items })    │
└─────────────────────────────┬───────────────────────────────┘
                              │ (Plain Domain Data Transfer Object)
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  Service Layer (Pure Business Operations)                   │
│  - Checks inventory invariants                              │
│  - Applies business discounts & loyalty points              │
│  - Coordinates transaction across database tables           │
└─────────────────────────────┬───────────────────────────────┘
                              │ (Calls data persistence methods)
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  Data / Repository Layer (SQL / ORM / Driver)               │
│  - Executes queries: INSERT INTO orders, UPDATE inventory   │
└─────────────────────────────┬───────────────────────────────┘
                              │ (Returns raw database entities)
                              ▼
                        Service Layer
                              │ (Returns created domain Order object)
                              ▼
                         Controller
                              │ (Converts to JSON + HTTP 201 Created)
                              ▼
                     Client HTTP Response

// controllers/orderController.js - EVERYTHING JUMBLED IN ONE FUNCTION
app.post('/orders', async (req, res) => {
  // 1. HTTP concerns
  const { customerId, items, couponCode } = req.body;
  if (!customerId || !items) return res.status(400).json({ error: 'Missing fields' });

  // 2. Direct database queries
  const customer = await db.query('SELECT * FROM users WHERE id = $1', [customerId]);
  
  // 3. Business calculations & discounts
  let subtotal = 0;
  for (const item of items) {
    const product = await db.query('SELECT * FROM products WHERE id = $1', [item.id]);
    if (product.stock < item.quantity) {
      return res.status(400).json({ error: 'Product ' + product.name + ' out of stock' });
    }
    subtotal += product.price * item.quantity;
  }

  // 4. More business rules
  let discount = 0;
  if (customer.isVip) discount += subtotal * 0.15;
  if (couponCode === 'SAVE10') discount += 10;
  const tax = (subtotal - discount) * 0.08;
  const total = subtotal - discount + tax;

  // 5. Data mutations & transaction
  const order = await db.query('INSERT INTO orders (user_id, total) VALUES ($1, $2) RETURNING *', [customerId, total]);
  for (const item of items) {
    await db.query('UPDATE products SET stock = stock - $1 WHERE id = $2', [item.quantity, item.id]);
  }

  // 6. External notifications
  await emailClient.sendReceipt(customer.email, order.id);

  // 7. Response
  res.status(201).json({ order, subtotal, discount, total });
});

// controllers/orderController.ts
import { Request, Response, NextFunction } from 'express';
import { orderService } from '../services/orderService';
import { InsufficientStockError } from '../errors/domainErrors';

export async function createOrderHandler(req: Request, res: Response, next: NextFunction) {
  try {
    // 1. Extract plain DTO from request
    const { customerId, items, promoCode } = req.body;

    // 2. Delegate directly to the business service layer
    const order = await orderService.createOrder({
      customerId,
      items,
      promoCode
    });

    // 3. Return canonical HTTP 201 Created response
    return res.status(201).json({
      success: true,
      data: order
    });
  } catch (error) {
    // 4. Map domain-specific exceptions to client HTTP errors
    if (error instanceof InsufficientStockError) {
      return res.status(422).json({ error: error.message, code: 'OUT_OF_STOCK' });
    }
    return next(error); // Forward unexpected errors to global error middleware
  }
}

// services/orderService.ts
import { inventoryRepo } from '../repositories/inventoryRepo';
import { orderRepo } from '../repositories/orderRepo';
import { InsufficientStockError } from '../errors/domainErrors';

export interface CreateOrderInput {
  customerId: string;
  items: Array<{ productId: string; quantity: number }>;
  promoCode?: string;
}

export class OrderService {
  async createOrder({ customerId, items, promoCode }: CreateOrderInput) {
    // 1. Business Invariant: Check stock for all requested items
    for (const item of items) {
      const stock = await inventoryRepo.getStock(item.productId);
      if (stock < item.quantity) {
        throw new InsufficientStockError(`Product ${item.productId} has insufficient stock`);
      }
    }

    // 2. Business Calculation: Compute pricing & discounts
    const subtotal = await this.calculateSubtotal(items);
    const discount = this.calculateDiscount(subtotal, promoCode);
    const tax = (subtotal - discount) * 0.08;
    const grandTotal = subtotal - discount + tax;

    // 3. Coordinate Persistence
    const order = await orderRepo.create({
      customerId,
      items,
      pricing: { subtotal, discount, tax, grandTotal }
    });

    // 4. Update warehouse inventory
    for (const item of items) {
      await inventoryRepo.decrementStock(item.productId, item.quantity);
    }

    return order; // Plain domain object!
  }

  private calculateDiscount(subtotal: number, promoCode?: string): number {
    if (promoCode === 'SAVE10' && subtotal > 50) return 10;
    return 0;
  }

  private async calculateSubtotal(items: Array<{ productId: string; quantity: number }>): Promise<number> {
    // Queries product prices and sums amounts
    let sum = 0;
    for (const item of items) {
      const price = await inventoryRepo.getPrice(item.productId);
      sum += price * item.quantity;
    }
    return sum;
  }
}

export const orderService = new OrderService();