Services and Repositories

This topic assumes familiarity with backend/frameworks/05-controllers (thin controllers delegate outward) and backend/frameworks/09-dependency_injection (how the objects described here actually get wired together). It also connects to architecture/architecture/07-repository_pattern, which covers the repository abstraction as a general design pattern — this topic is about how that pattern plugs specifically into a framework's controller/service layering, not the pattern's design rationale in the abstract.

1Three Layers, Three Jobs

A typical framework-backed backend splits request handling into three layers, each with exactly one job:

Controller  -> parse the request, call a service, shape the response  (backend/frameworks/05-controllers)
Service     -> business logic: rules, orchestration, decisions
Repository  -> data access: talk to the database (or any other storage), nothing else

@Controller("orders")
class OrderController {
  constructor(private orderService: OrderService) {}

  @Post()
  async create(@Body() dto: CreateOrderDto) {
    return this.orderService.placeOrder(dto); // controller does NOT touch the database
  }
}

@Injectable()
class OrderService {
  constructor(private orderRepo: OrderRepository, private inventoryRepo: InventoryRepository) {}

  async placeOrder(dto: CreateOrderDto) {
    const inStock = await this.inventoryRepo.checkStock(dto.productId, dto.quantity);
    if (!inStock) throw new BadRequestException("insufficient stock"); // BUSINESS RULE lives here
    return this.orderRepo.create(dto); // delegates the actual write
  }
}

@Injectable()
class OrderRepository {
  constructor(private db: Database) {}
  create(dto: CreateOrderDto) {
    return this.db.query("INSERT INTO orders ...", [dto]); // ONLY data access, no business rules
  }
}

Each arrow flows one direction: controller calls service, service calls repository — a repository never calls back up into a service, and a controller never talks to a repository directly.

2Why the Service Layer Exists at All

It's tempting to ask why OrderController can't just call OrderRepository directly and skip the middle layer — for a single trivial CRUD operation, it could. The service layer earns its place the moment there's a decision to make that isn't itself a database query: checking stock before allowing an order, applying a discount rule, coordinating a write across two repositories (orders and inventory) as one logical operation, sending a notification after a successful write. None of that is "get/set a row" — it's business logic, and business logic belongs in the service, not smeared across the controller (which should stay a thin request/response adapter) or the repository (which should stay ignorant of why a query runs, only how).

3Why the Repository Layer Exists at All

Symmetrically, the repository exists to isolate how data is stored from what the business logic needs to do with it. OrderService calls orderRepo.create(dto) without knowing or caring whether that's a raw SQL INSERT, an ORM call, a call to a third-party API, or (in a test) an in-memory array push:

class InMemoryOrderRepository implements OrderRepository {
  private orders: Order[] = [];
  create(dto: CreateOrderDto) {
    const order = { id: this.orders.length + 1, ...dto };
    this.orders.push(order);
    return order;
  }
}

This is the same substitutability payoff covered in backend/frameworks/09-dependency_injection — because OrderService depends on the repository's interface, not a concrete database-backed class, a test can construct OrderService with InMemoryOrderRepository and exercise the real business logic (the stock check, the discount rule) with zero real I/O.

4What Belongs Where — A Concrete Sorting Exercise

The dividing line is always the same question: is this a decision about what should happen, or a mechanical detail of how data gets read or written? The former is a service's job; the latter is a repository's.

5Repositories Return Domain Data, Not Raw Storage Shapes

A well-designed repository hides its storage mechanics behind method names that describe what is being asked for, not how it's fetched — findActiveCustomers(), not runQuery(sql). This is what actually makes swapping the underlying storage possible later (moving from a SQL database to a different store) without touching every service that calls the repository: the service-facing contract is a set of meaningful method names, never a leaked SQL string or an ORM-specific query builder object.

⚠️ Common Pitfalls

1. Putting business logic in the repository. A repository method that decides "skip this row if the discount would make the total negative" has smuggled a business rule into the data-access layer, which means that rule can never be tested without a real (or in-memory) storage backend, defeating the whole reason a service layer exists.
2. Putting data-access details in the service. A service that builds raw SQL strings or ORM query objects directly has skipped the repository entirely, coupling business logic to one specific storage technology.
3. A fat controller that calls the repository directly, "just this once." Every exception erodes the "controllers never touch repositories" rule, and the business logic that belonged in a service ends up duplicated the next time a second controller needs the same operation.
4. A repository interface shaped exactly like a SQL table. If every method maps 1:1 to a raw column, the abstraction isn't actually hiding storage details — it's just SQL with extra steps, and swapping storage mechanisms later means rewriting every consumer anyway.

📋 Quick Reference

Controller  -> HTTP in/out only: parse request, call service, shape response
Service     -> business logic: rules, decisions, orchestration across repositories
Repository  -> data access only: how storage works, hidden behind meaningful method names
Flow        -> Controller -> Service -> Repository (never backwards, never skipped)
Payoff      -> swap a repository for an in-memory fake in tests without touching the service

🎤 Interview Q&A

🛠️ Practice exercises

Each exercise is a file in this topic folder. Code exercises are self-checking: run them and make the checks pass.

✅ Check yourself

Source: fw_services_and_repositories_theory.md · generated by tools/build_lessons.py