Chapter 3 — Key Concepts You Must Know

The why

When a senior developer tells you "the controller is calling the repository directly — that breaks layered architecture," you need to know what all those words mean.

Read through once. The goal is recognition — when you see a term in a code review, you know where to look it up.

Architecture Concepts

Layered Architecture

Plain English: Each part of the code has one job and only talks to the part directly below it.

• Controller knows HTTP (routes, request bodies, response codes). Knows nothing about SQL.
• Service knows business rules (if restaurant is closed, throw an error). Knows nothing about HTTP.
• Repository knows the database (queries, inserts). Knows nothing about users or business rules.

Why it matters: If your controller imports a Sequelize model directly, now you need a running database to test your HTTP logic. Split it out and you can test each layer in isolation.

// ❌ Anti-pattern: controller doing SQL directly
@Get(':id')
async findOne(@Param('id') id: string) {
  return Order.findByPk(id);  // SQL in the HTTP layer
}
 
// ✅ Correct: controller delegates to service
@Get(':id')
async findOne(@Param('id') id: string) {
  return this.ordersService.findOne(id);
}

Bounded Context

Plain English: A self-contained area of the app that owns its own data and doesn't let others touch it directly.

In QuickBite: Users, Restaurants, Orders, Payments, and Deliveries are all separate bounded contexts. Each has its own module, models, and services.

If OrdersService needs to notify the restaurant, it doesn’t call Restaurant.update(...) directly. It calls RestaurantsService.notifyNewOrder(...). The day Restaurants moves to a separate microservice, only that one call needs to change.

Dependency Injection (DI)

Plain English: Instead of a class creating its own dependencies, they are "injected" (handed) to it from outside.

class OrdersService {
  private restaurantsService = new RestaurantsService();  // creates its own — hard to test!
}

class OrdersService {
  constructor(private restaurantsService: RestaurantsService

NestJS's DI system reads the @Module definitions and automatically wires everything together. You declare what you need; NestJS provides it.

DTO (Data Transfer Object)

Plain English: The shape of data that crosses a layer boundary — what the client sends and what the server returns.

Think of it as a form. When a client sends POST /orders, the body must match the CreateOrderDto form. If any field is wrong, the request is rejected before it touches your business logic.

// ❌ Dangerous: leaks internal fields
return order;  // returns internal flags, deleted_at, hashed tokens, everything
 
// ✅ Safe: only expose what you intend
return OrderResponse.from(order);  // { id, status, totalAmount, createdAt }

Event-Driven Pattern

Plain English: When something happens, announce it. Let other parts of the system react independently.

Instead of:

// OrdersService knows too much
await this.emailService.sendConfirmation(order);
await this.restaurantService.notifyNewOrder(order);
await this.metricsService.increment('orders');

Do:

// OrdersService just announces what happened
this.eventEmitter.emit('order.placed', new OrderPlacedEvent(order));
// Each listener handles their own job separately

Why it matters: As the system grows, OrdersService would otherwise need to import 15 other services. Events keep it clean.

Database Concepts

Migration

Plain English: A versioned script that changes the database structure in a controlled, tracked way.

Think of migrations like Git commits for your database. Each one is numbered, applied once, and never edited after it runs.

Constraint

Plain English: A rule the database itself enforces, no matter what your code does.

Examples:

• NOT NULL — this column must always have a value
• UNIQUE — no two rows can have the same value in this column
• CHECK — value must match a condition (status IN ('pending', 'approved'))
• FOREIGN KEY — this value must exist in another table

Why constraints beat app-level validation: Your code can have bugs. A DBA can run SQL directly. A script can bypass your API. The database cannot be bypassed. Constraints are your last line of defense.

Transaction (Database)

Plain English: A group of database operations that either ALL succeed or ALL fail together.

await sequelize.transaction(async (tx) => {
  const order = await Order.create({ userId, restaurantId, status: 'pending' }, { transaction: tx });
  await OrderItem

Connection Pool

Plain English: A pre-made set of database connections that requests share. Opening a database connection is slow (TCP handshake, authentication). The pool keeps 8–20 connections open and ready.

HTTP & API Concepts

Idempotency

Plain English: Doing the same thing twice has the same result as doing it once.

GET /orders/123 — call it 100 times, you always get the same order. Idempotent. POST /orders — call it twice, you get two orders. NOT idempotent.

In payments, this matters hugely. If a network error causes the QuickBite app to retry a "charge customer" request, you don’t want to charge twice. The solution: Idempotency-Key headers — the server stores the result the first time and returns it on retry without executing again.

REST Verbs

Status Codes That Matter

Operations Concepts

Correlation ID

Plain English: A unique ID attached to every request that follows it through every log line, across every service.

Without it: "find all log entries at 10:23:01.452 and hope nothing else happened that millisecond."

With it: grep cid=7f3a-abc... shows you every log line for exactly that one request.

Health Checks

Two endpoints every backend must have:

• GET /healthz — "Am I alive?" Returns 200 if the process is running.
• GET /readyz — "Am I ready to serve traffic?" Returns 200 only if the DB is reachable.

Security Concepts

CORS (Cross-Origin Resource Sharing)

Plain English: A browser security feature that prevents websites you didn't authorize from calling your API.

If evil.com tries to call api.quickbite.app, the browser checks if api.quickbite.app has allowed evil.com. If not, the browser blocks the request.

SQL Injection — know it cold

// ❌ Vulnerable: user input goes directly into SQL
const result = await sequelize.query(
  `SELECT * FROM users WHERE email = '${email}'`
);
// If email = "x' OR '1'='1", this returns EVERY user
 
// ✅ Safe: parameterized query
const result = await sequelize.query(
  `SELECT * FROM users WHERE email = $1`

Sequelize's model methods (.findAll, .findOne) are parameterized by default. The danger zone is raw SQL via sequelize.query().

One thing to remember