Layered Architecture

1The Core Idea

Layered architecture organizes code into horizontal layers, each with one job, where a layer may only call the layer(s) directly below it:

┌─────────────────────────────┐
│  Presentation (controllers)   │  ← handles HTTP, validates input shape
├─────────────────────────────┤
│  Business logic (services)    │  ← the actual rules of the application
├─────────────────────────────┤
│  Data access (repositories)   │  ← reads/writes the database
├─────────────────────────────┤
│  Database                     │
└─────────────────────────────┘

A request flows top-down: Controller → Service → Repository → Database. A response flows back up the same path. This is the most common architecture in the industry — most frameworks (Express + a service layer, Spring MVC, Rails) nudge you into it by default.

2A Minimal Example

// data access layer
class UserRepository {
  async findById(id: string): Promise<{ id: string; email: string; passwordHash: string } | null> {
    // pretend SQL query
    return { id, email: "a@example.com", passwordHash: "hashed" };
  }
}

// business logic layer
class UserService {
  constructor(private repo: UserRepository) {}

  async getPublicProfile(id: string) {
    const user = await this.repo.findById(id);
    if (!user) throw new Error("not found");
    // business rule: never expose passwordHash outward
    return { id: user.id, email: user.email };
  }
}

// presentation layer
class UserController {
  constructor(private service: UserService) {}

  async handleGetProfile(req: { params: { id: string } }) {
    const profile = await this.service.getPublicProfile(req.params.id);
    return { status: 200, body: profile };
  }
}

Each layer only knows about the layer directly beneath it: UserController never touches SQL, UserRepository never knows what "public profile" means.

3The One Rule That Makes It Work: Layers Below Don't Know About Layers Above

UserRepository must never import or reference UserController or UserService. This is what keeps the dependency graph acyclic and each layer independently understandable — you can read UserRepository in isolation and know everything it depends on (just the database driver), without needing to know who calls it or why.

// VIOLATION: repository reaching upward
class UserRepository {
  constructor(private service: UserService) {} // ❌ data layer depending on business layer
}

If this creeps in, the layers stop being layers — you get a dependency cycle, and "just read the repository to understand what it does" stops being true, because now you also need to understand the service to understand the repository.

4Strict vs Relaxed Layering

• Strict layering: a layer may only call the layer immediately below it (Controller → Service → Repository, never Controller → Repository directly).
• Relaxed layering: a layer may call any layer below it, skipping intermediate ones when there's no logic to add.

// Relaxed: controller calls repository directly for a trivial read with no business rules
class HealthController {
  constructor(private repo: UserRepository) {} // skips a UserService that would add nothing
  async handleHealthCheck() {
    await this.repo.findById("healthcheck-user");
    return { status: 200 };
  }
}

Relaxed layering trades a small amount of consistency for avoiding pointless pass-through service methods that just forward one call — a real cost when a codebase has hundreds of such pass-throughs. Strict layering trades a bit of ceremony for a codebase where "where do I look for X" always has exactly one predictable answer regardless of how trivial X is. Most real codebases mix these deliberately, not by accident — pick one policy per project and be explicit about it, rather than letting it be decided inconsistently PR by PR.

5What Layered Architecture Does Not Solve

Layered architecture organizes where code lives, but says nothing about what the business layer is allowed to depend on. In the naive version above, UserService still typically ends up importing a specific ORM's types, a specific web framework's request/response shapes, or specific error classes from a specific library — because "business logic" is just "the middle layer," not "a framework-independent core." That's precisely the gap Clean/Hexagonal architecture (next topic) closes: it keeps the same top-down call direction but inverts the dependency direction so business logic doesn't import infrastructure at all.

// Leaky: repository returns the raw ORM model
async findById(id: string): Promise<UserModel> {   // UserModel is a Sequelize class
  return UserModel.findByPk(id);
}
// Service can now accidentally call user.reload() or rely on lazy-loaded
// associations — behavior that has nothing to do with "get a user by id"
// and will silently break the day the ORM is swapped.

// Not leaky: repository maps to a plain data shape the service actually needs
interface UserRecord { id: string; email: string; passwordHash: string }
async findById(id: string): Promise<UserRecord | null> {
  const row = await UserModel.findByPk(id);
  return row ? { id: row.id, email: row.email, passwordHash: row.passwordHash } : null;
}

⚠️ Common Pitfalls

1. Repository returning raw ORM/driver objects instead of plain data — silently couples every layer above it to that specific library's behavior, as shown in section 6.
2. Skipping the service layer "just this once" and letting it become the norm — a few controller-calls-repository shortcuts are fine as an explicit relaxed-layering policy (section 4), but uncontrolled creep means business rules end up scattered across controllers with no single place to find them.
3. Fat controllers — putting business rules (validation beyond input shape, authorization checks, calculations) directly in the controller because "it's just a few lines" — these rules then can't be reused or unit-tested independently of an HTTP request/response.
4. Anemic services that just pass through — a service layer that does nothing but forward every call to the repository unchanged adds a layer of indirection with zero benefit; if this is true for an entire module, relaxed layering (section 4) is the honest choice.
5. Cross-layer shortcuts that go the wrong direction — a repository importing a service to "trigger a side effect" (e.g., send an email after saving) creates a cycle; side effects that need to happen after persistence belong in the service, orchestrated after the repository call returns.

📋 Quick Reference

Layers: Presentation → Business logic → Data access → Database   (calls flow top-down)
Rule: a layer never calls back UP into a layer above it
Strict layering: skip nothing         Relaxed layering: skip layers that would add nothing
The real coupling risk isn't the import statement — it's leaked ORM return types and leaked driver exceptions
Test signal: if testing the service needs a real DB, the repository boundary isn't a real seam yet
Layered ≠ Clean/Hexagonal: layered controls call direction; Clean also controls *dependency* direction

🎤 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: arch_layered_architecture_theory.md · generated by tools/build_lessons.py