src/
├── routes/           # Couche HTTP — parsing requête, formatage réponse
│   └── users.routes.js
├── controllers/       # Orchestration — appelle les services, ne contient PAS de logique métier
│   └── users.controller.js
├── services/           # Logique métier pure, indépendante d'Express
│   └── users.service.js
├── repositories/        # Accès aux données, seule couche qui connaît le SQL/l'ORM
│   └── users.repository.js
└── container.js          # Câblage des dépendances

// repositories/users.repository.js — SEULE couche qui parle à la base de données
export class UsersRepository {
  constructor(pool) {
    this.pool = pool;
  }

  async findById(id) {
    const { rows } = await this.pool.query("SELECT * FROM users WHERE id = $1", [id]);
    return rows[0] ?? null;
  }

  async create(data) {
    const { rows } = await this.pool.query(
      "INSERT INTO users (name, email) VALUES ($1, $2) RETURNING *",
      [data.name, data.email]
    );
    return rows[0];
  }
}

// services/users.service.js — logique métier, ne connaît PAS Express ni SQL
export class UsersService {
  constructor(usersRepository, emailService) {
    this.usersRepository = usersRepository;
    this.emailService = emailService;
  }

  async registerUser({ name, email }) {
    const existing = await this.usersRepository.findByEmail(email);
    if (existing) {
      throw new ValidationError({ email: "Déjà utilisé" });
    }

    const user = await this.usersRepository.create({ name, email });
    await this.emailService.sendWelcomeEmail(user.email); // testable indépendamment via un mock

    return user;
  }
}

// controllers/users.controller.js — traduit HTTP <-> appels au service
export class UsersController {
  constructor(usersService) {
    this.usersService = usersService;
  }

  register = async (req, res, next) => {
    try {
      const user = await this.usersService.registerUser(req.body);
      res.status(201).json(user);
    } catch (err) {
      next(err);
    }
  };
}

// container.js — composition root : le SEUL endroit où tout est câblé ensemble
import { pool } from "./db.js";
import { UsersRepository } from "./repositories/users.repository.js";
import { EmailService } from "./services/email.service.js";
import { UsersService } from "./services/users.service.js";
import { UsersController } from "./controllers/users.controller.js";

const usersRepository = new UsersRepository(pool);
const emailService = new EmailService(process.env.SMTP_URL);
const usersService = new UsersService(usersRepository, emailService);
export const usersController = new UsersController(usersService);

// tests/users.service.test.js — le bénéfice concret : tester la logique métier SANS DB réelle
import { describe, it, expect, vi } from "vitest";
import { UsersService } from "../src/services/users.service.js";

describe("UsersService.registerUser", () => {
  it("rejette un email déjà utilisé", async () => {
    const fakeRepo = {
      findByEmail: vi.fn().mockResolvedValue({ id: 1, email: "a@a.com" }),
      create: vi.fn(),
    };
    const fakeEmailService = { sendWelcomeEmail: vi.fn() };
    const service = new UsersService(fakeRepo, fakeEmailService);

    await expect(service.registerUser({ email: "a@a.com" })).rejects.toThrow();
    expect(fakeRepo.create).not.toHaveBeenCalled();
  });
});