express-prisma-pattern

Express + Prisma — house pattern

Manual Clean Architecture, not a framework's DI container: every layer is a plain TS interface, wired by hand in a factory function. Confirmed by reading real code in dream-book-api and simple-management-api (independent codebases, different Prisma majors, same controller/usecase/repository/factory shape) — the shell below is non-negotiable, do not invent a NestJS-style module system on top of it. The two repos diverge on where zod validation runs (see rule 4) — that's the one confirmed exception to "same shape", not an oversight.

Per-feature structure

src/
├── controllers/<domain>/<action>-controller.ts   # implements Controller. Parses HttpRequest, calls the usecase, returns HttpResponse via helpers. Never imports Prisma.
├── usecases/<domain>/<action>-usecase.ts         # Business logic. execute(...). Depends on the repository INTERFACE, injected via constructor.
├── interfaces/
│   ├── controllers/controller.ts                  # shared Controller contract
│   ├── http/http-request.ts, http-response.ts     # shared request/response shape
│   └── repositories/<domain>-repository.ts        # repository contract + domain types
├── repository/<domain>/<domain>-repository.ts    # Prisma<Domain>Repository implements <Domain>Repository
└── main/factories/<domain>-factory.ts             # make<Action>Controller(): wires repository → usecase → controller by hand

The shell (non-negotiable)

// interfaces/controllers/controller.ts
export interface Controller<T = any> {
  handle(request: HttpRequest): Promise<HttpResponse<T>>;
}

// controllers/area/area-controllers.ts
export class ListAreasController implements Controller {
  constructor(private readonly usecase: ListAreasUsecase) {}
  async handle(_request: HttpRequest): Promise<HttpResponse<AreaComContagem[]>> {
    return ok(await this.usecase.execute());
  }
}

// main/factories/area-factory.ts — manual composition root, no DI container
const repository = new PrismaAreaRepository();
export const makeListAreasController = (): ListAreasController =>
  new ListAreasController(new ListAreasUsecase(repository));