Chapter 1 — Architecture Patterns

The why

A codebase without architecture is a garage without shelves — everything works until you need to find the 10mm socket at 2 AM.

Core concepts

MVC: The Pattern You Already Know (Maybe Wrong)

MVC — Model, View, Controller — is the grandparent of web frameworks. Rails, Laravel, Django, and ASP.NET MVC all trace back to Trygve Reenskaug's 1979 paper. But in backend APIs (where the "View" is JSON), the pattern often degrades into something unrecognizable.

The original contract:

• Model: Business data + business rules. A User model knows that email must be unique and passwords must be hashed. It does NOT know about HTTP status codes.
• View: Presentation logic. In an API, this is response serialization — converting a User object into { "id": 1, "name": "Sharma" } and omitting the password_hash.
• Controller: The traffic cop. It parses the request, calls the right model methods, picks the right view, and sends the response. It should be thin — 5–10 lines ideally.

The anti-pattern you'll see everywhere:

// DO NOT DO THIS
router.post('/users', async (req, res) => {
  const { email, password, name } = req.body;
 
  //

This 30-line controller does validation, business logic, database access, email sending, AND response formatting. When you need to create a user from a background job, CLI script, or another service — you can't. The logic is trapped inside an HTTP handler.

Clean Architecture: Uncle Bob's Dependency Inversion

Robert C. Martin's "Clean Architecture" (2012) introduced a rule that changes everything: dependencies point inward. The outer layers (HTTP, databases, frameworks) depend on the inner layers (business rules, entities). Never the reverse.

┌──────────────────────────────────────────┐
│          Frameworks & Drivers             │
│  Express routes, PostgreSQL, Redis, S3    │
│  ┌────────────────────────────────────┐   │
│  │      Interface Adapters            │   │
│  │  Controllers, Repositories, DTOs   │   │
│  │  ┌──────────────────────────────┐  │   │
│  │  │    Application / Use Cases   │  │   │
│  │  │  CreateUser, ProcessPayment  │  │   │
│  │  │  ┌────────────────────────┐  │  │   │
│  │  │  │      Domain / Entities │  │  │   │
│  │  │  │  User, Order, Payment  │  │  │   │
│  │  │  └────────────────────────┘  │  │   │
│  │  └──────────────────────────────┘  │   │
│  └────────────────────────────────────┘   │
└──────────────────────────────────────────┘

Here's how to structure an Express app in Clean Architecture:

src/
├── domain/                  # Innermost layer — zero dependencies
│   ├── entities/
│   │   └── User.ts          # Plain TS class/interface, no ORM decorators
│   ├── value-objects/
│   │   └── Email.ts
│   └── errors/
│       └── ValidationError.ts
├── application/             # Use cases — depends ONLY on domain
│   ├── use-cases/
│   │   ├── CreateUser.ts
│   │   └── GetUserProfile.ts
│   └── ports/               # Interfaces that outer layers implement
│       ├── IUserRepository.ts
│       ├── IEmailService.ts
│       └── IHashService.ts
├── infrastructure/          # Outer layer — implements ports
│   ├── persistence/
│   │   └── PostgresUserRepository.ts
│   ├── services/
│   │   ├── BcryptHashService.ts
│   │   └── ResendEmailService.ts
│   └── config/
│       └── database.ts
└── presentation/            # HTTP concerns only
    ├── controllers/
    │   └── UserController.ts
    ├── middleware/
    │   └── errorHandler.ts
    └── routes/
        └── userRoutes.ts

The CreateUser use case — pure business logic, no HTTP, no database driver:

import { User } from '../../domain/entities/User';
import { Email } from '../../domain/value-objects/Email';
import { IUserRepository } from '../ports/IUserRepository';
import { IHashService } from '../ports/IHashService';
import

The controller becomes a thin adapter:

import { Request, Response } from 'express';
import { CreateUser } from '../../application/use-cases/CreateUser';
 
export class UserController {
  constructor(private createUser: CreateUser) {}
 
  async register(

Hexagonal Architecture (Ports & Adapters)

Alistair Cockburn's Hexagonal Architecture (2005) is Clean Architecture's spiritual predecessor. The core idea: your application is a hexagon. Each face is a "port" — an interface that the outside world connects to via "adapters."

• Primary (driving) adapters call INTO your app: HTTP controllers, CLI commands, test runners, message queue consumers.
• Secondary (driven) adapters are called BY your app: PostgreSQL, Redis, S3, Stripe API, SendGrid.

         ┌─── HTTP Controller (primary adapter)
         │
    ┌────▼────┐      ┌─────────────┐
    │  PORT   │◄─────┤  Use Case   │
    │  (in)   │      │  (pure TS)  │
    └─────────┘      └──────┬──────┘
                            │
    ┌─────────┐      ┌──────▼──────┐
    │  PORT   │──────►  Adapter    │──► PostgreSQL
    │  (out)  │      │  (repo)     │
    └─────────┘      └─────────────┘

Hexagonal architecture uses the same ports/interfaces pattern as Clean Architecture but emphasizes testability above all: you can drive your entire application from a test harness by plugging test adapters into the ports.

Feature-Based vs Layer-Based Folder Structure

This is a practical, non-academic decision you make on Day 1 of a project. It affects every import statement for the life of the codebase.

Layer-based (group by technical role):

src/
├── controllers/
│   ├── UserController.ts
│   ├── OrderController.ts
│   └── ProductController.ts
├── services/
│   ├── UserService.ts
│   ├── OrderService.ts
│   └── ProductService.ts
├── repositories/
│   ├── UserRepository.ts
│   └── ...
└── models/
    └── ...

Feature-based (group by business capability):

src/
├── features/
│   ├── users/
│   │   ├── UserController.ts
│   │   ├── UserService.ts
│   │   ├── UserRepository.ts
│   │   ├── User.test.ts
│   │   └── types.ts
│   ├── orders/
│   │   ├── OrderController.ts
│   │   ├── OrderService.ts
│   │   ├── OrderRepository.ts
│   │   └── ...
│   └── products/
│       └── ...
├── shared/
│   ├── database.ts
│   ├── errors.ts
│   └── middleware/
└── config/
    └── index.ts

Shopify uses feature-based organization in their Rails monolith ("component-based Rails"). Each business domain — orders/, products/, payments/ — is a self-contained module with its own models, controllers, views, and tests. When a developer picks up a "cart checkout" ticket, they work inside app/components/checkout/ for 90% of their changes.

When NOT to Use Clean Architecture

Clean Architecture adds 3x the files of a simple Express app. For these scenarios, it's overkill:

Real-world example: How Shopify organizes their Rails monolith

Shopify's core application is a Ruby on Rails monolith that processes over $200 billion in GMV annually. With 5,000+ engineers contributing to the same codebase, folder structure isn't academic — it's how they prevent merge conflicts and ship 40+ deploys per day.

In 2017, Shopify adopted component-based Rails — their term for feature-based organization. Before this, their app/models/ folder had over 800 files. No single developer understood the full model graph. Changing Order could silently break Refund, Fulfillment, or GiftCard.

Their solution: each business domain becomes a "component" with an explicit public API. A component declares what it exports (models, services, libraries) and what it depends on. The payments component can depend on orders but not vice versa — cyclic dependencies are caught at CI time.

Key lessons from Shopify's architecture journey:

1. Explicit boundaries. Every component has a public/ folder — only files in public/ can be imported by other components. Everything else is private by convention.
2. Dependency tracking. They built tooling that visualizes the component dependency graph. PRs that introduce new dependencies trigger review from the owning team.
3. Incremental migration. They didn't rewrite 800 models. They moved one component at a time, starting with the most isolated ones (billing, analytics) and ending with the tangled core (orders, products).
4. Test speed as a forcing function. Component tests that don't cross boundaries run in < 2 seconds. Tests that cross boundaries require explicit setup and run slower — this friction naturally pushes engineers toward proper isolation.

You don't need a monolith the size of Shopify's to benefit from feature-based organization. The principle scales down: if your src/ folder has 30+ files, organize them by what they DO, not by what they ARE.

Common mistakes

Production notes

• Dependency injection without a framework. Use manual constructor injection for < 20 classes. Switch to tsyringe or inversify only when the wiring code exceeds 100 lines. DI frameworks add magic that makes stack traces harder to read.
• Barrel files with caution. index.ts re-exports are convenient but can cause circular imports. Use explicit imports (from './entities/User') until you're confident in your dependency graph.
• Error codes over error messages. Use USER_ALREADY_EXISTS (machine-readable, i18n-ready) rather than "A user with this email already exists" (hard to switch languages, hard to match in frontend logic).
• One database transaction per use case. If CreateOrder touches orders, order_items, and inventory, wrap all three in one transaction. Partial commits in a use case are a data integrity nightmare.
• Architecture Decision Records (ADRs). When you choose Clean Architecture over MVC, write a 1-page ADR explaining WHY. In 18 months when someone questions it, you'll have the context.

Performance notes

• Dependency injection is not a performance concern. Instantiating classes is sub-microsecond. The bottleneck is always I/O (database, network, disk). Don't avoid Clean Architecture because of "performance" — measure first.
• Repository pattern can N+1. If GetOrders calls orderRepo.findById() in a loop, you've hidden the N+1 behind an abstraction. Repository methods should accept batch operations: findByIds(ids: string[]).
• Use case granularity matters. One use case per HTTP endpoint is a good starting heuristic. Don't create GetUserByIdUseCase AND GetUserByEmailUseCase — parameterize.
• Cold starts in serverless. If you're on AWS Lambda, Clean Architecture's 15+ file imports per request add to cold start. Bundle with esbuild and tree-shake unused code. In practice, the difference is < 50ms.

Security notes

• Port interfaces prevent leakage. A IUserRepository interface forces you to think about what data leaves the domain layer. You won't accidentally return password_hash in a query because the domain entity simply doesn't have that field.
• Input validation at the boundary. Validate in the controller (HTTP layer), NOT in the use case. The use case receives already-validated data. This means a malicious request is rejected before it reaches business logic.
• Authorization is a cross-cutting concern. Don't scatter if (user.role !== 'admin') across use cases. Use middleware or decorators at the controller level. The use case should receive a pre-authorized context.
• Secrets never in domain code. process.env.DATABASE_URL belongs in infrastructure/config/, not in domain/entities/User.ts. The domain layer should be importable without any environment setup.

Exercises

Beginner

1. Refactor a fat controller. Take the routes/users.ts fat controller example from this chapter. Extract the business logic into a CreateUser use case and rewrite the controller to be ≤ 10 lines. Write one unit test for the use case with mock dependencies.

2. Folder reorganization. Given a flat Express app with 12 route files in routes/, 8 "helper" files in utils/, and raw SQL in every route — design a feature-based folder structure. Draw the tree and explain which files go where.

Intermediate

1. Port & Adapter implementation. Implement the IUserRepository port with two adapters: PostgresUserRepository (real DB) and InMemoryUserRepository (for tests). Make the CreateUser use case work with both without changing a single line of the use case.

2. Circular dependency breaker. Design two features — Orders and Users — where Orders needs user data but Users must NOT import from Orders. Implement the dependency inversion: both depend on a shared interface. Show the import graph.

Advanced

1. Multi-transport application. Your CreateOrder use case currently runs via HTTP. Add a second "primary adapter": a RabbitMQ consumer that calls the same use case when an order.created message arrives. The use case itself must not change.

2. Architecture Decision Record. Write a 1-page ADR for a hypothetical e-commerce startup choosing between MVC (Rails-style) and Clean Architecture (NestJS-style). Include context, decision, consequences, and when they'd revisit the decision.

Interview questions

Beginner

Q1: What is MVC and what does each letter actually do?

Answer: Model manages data and business rules (validation, relationships). View handles presentation — in APIs, this means JSON serialization and response formatting. Controller is the traffic director — it receives the HTTP request, delegates to models/services, and returns a response. The key insight: the model should never know about HTTP status codes or response headers.

Q2: What is the difference between layer-based and feature-based folder structure?

Answer: Layer-based groups files by technical role (controllers/, services/, models/). Feature-based groups by business domain (users/, orders/, payments/). Layer-based is simpler for < 10 features; feature-based scales better because a developer working on "orders" touches files in one folder, not four.

Q3: What problem does the dependency inversion principle solve in backend architecture?

Answer: It prevents high-level business logic from depending on low-level implementation details. Without it, changing from PostgreSQL to MongoDB means rewriting every use case. With it, you write one new repository adapter and the use cases stay untouched. It also makes testing trivial — inject mocks instead of real databases.

Senior

Q4: When would you choose Clean Architecture for a greenfield project, and when would you explicitly avoid it?

Answer: I'd choose it when: (a) the domain has complex business rules that will evolve independently of the framework, (b) there are 3+ developers who need clear module boundaries, (c) the application will live 3+ years and likely swap infrastructure (database, message queue, cloud provider). I'd avoid it for: (a) an MVP that needs validation in 2 weeks, (b) a single-purpose serverless function, (c) a team unfamiliar with the pattern (the learning curve will slow delivery more than the architecture will help). The real answer: I'd start MVC and extract Clean Architecture patterns as the pain appears — fat controllers, untestable logic, duplicated validation.

Q5: How do you enforce architectural boundaries in a TypeScript codebase without a framework like NestJS?

Answer: Three techniques: (1) ESLint import/no-restricted-paths — prevent domain/ from importing from infrastructure/. (2) Dependency-cruiser (dpdm or madge) in CI to detect circular dependencies. (3) Barrel file discipline — each layer exports only through an index.ts that explicitly lists public symbols; anything not exported is private by convention. Bonus: TypeScript paths in tsconfig.json can create import aliases (@domain, @application) that make violations visually obvious in code review.

Q6: Shopify moved to component-based Rails. What's one architectural pattern they use that a 5-person Express team should adopt?

Answer: Explicit public APIs per module — every feature folder has a public.ts (or index.ts) that exports only what other features need. Everything else is private. In TypeScript, you can enforce this with barrel files and a lint rule. This prevents the "everything depends on everything" spaghetti that happens when any file can import any other file. A 5-person team benefits because code review can focus on public API changes — internal refactors of a feature don't risk breaking other features.

Summary

Architecture patterns aren't about writing more code — they're about writing code that survives team growth, requirement changes, and the developer who inherits it 2 years later. MVC gives you a starting point. Clean Architecture and Hexagonal Architecture add the dependency inversion that makes business logic testable and infrastructure swappable. Feature-based folder organization keeps related code together, matching how humans think about features ("I'm working on orders") rather than technical layers ("I'm working on controllers"). The key is pragmatism: start simple, extract patterns when you feel the friction, and never let the architecture become more important than the product it serves.

Quick recall

• MVC: Model = business logic, View = presentation, Controller = thin traffic cop (≤ 15 lines)
• Clean Architecture: dependencies point inward; domain has zero imports from frameworks
• Hexagonal / Ports & Adapters: same idea, emphasis on testability via swappable adapters
• Feature-based folders: users/, orders/, payments/ — group by what code DOES
• Layer-based folders: controllers/, services/, repositories/ — group by what code IS
• Fat controller anti-pattern: business logic trapped in HTTP handlers, can't reuse
• Dependency inversion: CreateUser depends on IUserRepository (interface), not PostgresUserRepository (concrete)
• Port = interface (abstraction), Adapter = implementation (concrete class that fulfills the interface)
• Primary adapters drive the app (HTTP, CLI, tests); secondary adapters are driven by the app (DB, email, cache)
• Shopify: component-based Rails, explicit public APIs per domain, dependency tracking at CI time

Quiz

1. In Clean Architecture, which layer should have zero dependencies on external frameworks? Answer: The domain/entities layer.

2. What is the maximum recommended line count for a well-structured controller method? Answer: 15 lines.

3. A feature-based folder puts UserController, UserService, and UserRepository in which folder? Answer: features/users/ (or users/).

4. What is the "fat controller" anti-pattern? Answer: Controllers that contain business logic, validation, database access, and side effects — making the logic impossible to reuse outside HTTP.

5. In Hexagonal Architecture, an HTTP controller is a ______ adapter, and a PostgreSQL repository is a ______ adapter. Answer: Primary (driving), Secondary (driven).

6. Why does Shopify use component-based organization in their Rails monolith? Answer: To scope changes to a single domain folder, reduce merge conflicts, and make dependency violations visible at CI time.

7. You're building a 2-week MVP for a hackathon. Should you use Clean Architecture? Why or why not? Answer: No — the abstraction overhead (3x files, interface definitions) slows delivery. Start MVC and refactor if the project survives past the hackathon.