node-express-boilerplate / rules

---
description: Architecture overview and file-structure rules for every new resource
globs: ["src/**/*.ts"]
alwaysApply: true
---

# Layered Architecture

Routes → Controllers → Services → Repositories → Prisma (PostgreSQL).

Every new resource requires exactly these five files, in this order:

| File | Purpose |
|------|---------|
| `src/validations/<name>.validation.ts` | Zod v4 schemas + `RequestHandler` exports |
| `src/repository/<name>.repository.ts` | `I<Name>Repository` interface + class extending `BaseRepository` |
| `src/services/<name>.service.ts` | `I<Name>Service` interface + class |
| `src/controllers/<name>.controller.ts` | `I<Name>Controller` interface + class extending `BaseController` |
| `src/routes/<name>.route.ts` | class extending `BaseRoute`, exports router instance |

After creating those files:
1. Register repository, service, and controller in `src/container/index.ts` following the existing init pattern.
2. Mount the route in `src/app.ts` at `/api/v1/<name>`.
3. Export all interfaces and classes from the barrel files (`src/repository/index.ts`, `src/services/index.ts`, `src/controllers/index.ts`).

# DI Container

`Container` (singleton in `src/container/index.ts`) is the only place where `new Repository/Service/Controller()` is called. Access instances in routes via `this.container.get<Name>Controller()`.

# Entry Points

- `src/index.ts` — binds the port only (import `app` in tests without binding)
- `src/app.ts` — all middleware and route mounting