docs: add DTO location and naming conventions to knowledge base (#26478)

* docs: add DTO location and naming conventions to knowledge base Co-Authored-By: eunjae@cal.com <hey@eunjae.dev> * docs: clarify DTO location rules for new features vs refactored code Co-Authored-By: eunjae@cal.com <hey@eunjae.dev> * docs: simplify DTO location - all DTOs go in packages/lib/dto/ Co-Authored-By: eunjae@cal.com <hey@eunjae.dev> --------- Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
2026-01-06 15:02:55 -03:00
parent eacfcd15a4
commit 6fa525812c
1 changed files with 22 additions and 0 deletions
@@ -420,6 +420,28 @@ export interface BookingDTO {
 }
 ```

+### DTO Location and Naming
+
+**Location**: All DTOs go in `packages/lib/dto/`
+
+**Naming conventions**:
+- Base entity: `{Entity}Dto` (e.g., `BookingDto`)
+- With relations: `{Entity}With{Relations}Dto` (e.g., `BookingWithAttendeesDto`)
+- For specific projections: `{Entity}For{Purpose}Dto` (e.g., `BookingForConfirmationDto`)
+- Avoid: `{Entity}Dto2`, `{Entity}DtoForHandler`, or other use-case-specific names
+
+**Enum/union pattern** – use string literal unions to stay ORM-agnostic:
+
+```typescript
+// ✅ Good - ORM-agnostic string literal union
+export type BookingStatusDto = "CANCELLED" | "ACCEPTED" | "REJECTED" | "PENDING";
+
+// ❌ Bad - importing Prisma enum
+import { BookingStatus } from "@calcom/prisma/client";
+```
+
+**Type safety** – never use `as any` in DTO mapping functions. If types don't align, fix the mapping explicitly.
+
 ### Prisma boundaries

 - **Allowed**: `packages/prisma`, repository implementations (`packages/features/**/repositories/*Repository.ts`), and low-level data access infrastructure.