docs: Update contributors-guide (#22734)

* Update contributors-guide.mdx

* Update contributors-guide.mdx

* update cursor rule

* update CONTRIBUTING.md

* update CONTRIBUTING.md

---------

Co-authored-by: Eunjae Lee <hey@eunjae.dev>

.cursor/rules/review.mdc

@@ -1,5 +1,13 @@
 # Review Instructions
 
+## File Naming Conventions
+
+- **Repository Files**: Must include `Repository` suffix, prefix with technology if applicable (e.g., `PrismaAppRepository.ts`), use PascalCase matching exported class
+- **Service Files**: Must include `Service` suffix, use PascalCase matching exported class, avoid generic names (e.g., `MembershipService.ts`)
+- **New files**: Avoid dot-suffixes like `.service.ts` or `.repository.ts`; reserve `.test.ts`, `.spec.ts`, `.types.ts` for their specific purposes
+
+## Code Quality
+
 - Prefer early returns. It is recommended to throw/return early so we can ensure null-checks and prevent further nesting.
 - Prefer Composition over Prop Drilling. Instead of relying on prop drilling, let's try to take advantage of react children feature.
 - For Prisma queries:

CONTRIBUTING.md

@@ -95,6 +95,57 @@ Write with the future in mind. If there are trade-offs, edge cases, or temporary
   </tr>
 </table>
 
+## File Naming Conventions
+
+To ensure consistency and make files easy to fuzzy-find, we follow the naming conventions below for **services**, **repositories**, and other class-based files.
+
+### Repository Files
+
+- Repository class files must include the `Repository` suffix.
+- If the repository is backed by a specific technology (e.g. Prisma), prefix the filename and class name with it.
+- File name must match the exported class exactly (PascalCase).
+
+**Pattern:**
+
+`Prisma<Entity>Repository.ts`
+
+**Examples:**
+
+```ts
+// File: PrismaAppRepository.ts
+export class PrismaAppRepository { ... }
+
+// File: PrismaMembershipRepository.ts
+export class PrismaMembershipRepository { ... }
+```
+
+This avoids ambiguous filenames like app.ts and improves discoverability in editors.
+
+### Service Files
+
+- Service class files must include the Service suffix.
+- File name should be in PascalCase, matching the exported class.
+- Keep naming specific — avoid generic names like AppService.ts.
+
+**Pattern:**
+
+`<Entity>Service.ts`
+
+**Examples:**
+
+```ts
+// File: MembershipService.ts
+export class MembershipService { ... }
+
+// File: HashedLinkService.ts
+export class HashedLinkService { ... }
+```
+
+**Note:**
+
+- New files must avoid dot-suffixes like .service.ts or .repository.ts; these will be migrated from the existing codebase progressively.
+- We still reserve suffixes such as .test.ts, .spec.ts, and .types.ts for their respective use cases.
+
 ## Developing
 
 [See README](https://github.com/calcom/cal.com#development)

docs/developing/open-source-contribution/contributors-guide.mdx

@@ -44,6 +44,60 @@ You can look at [turbo.json](https://github.com/calcom/cal.com/blob/main/turbo.j
 - The public API related codebase can be found in the [/apps/api](https://github.com/calcom/cal.com/tree/main/apps/api) folder from the root.
 - The Cal.ai related codebase can be found in the [/apps/ai](https://github.com/calcom/cal.com/tree/main/apps/ai) folder from the root
 
+## File Naming Conventions
+
+To ensure consistency and make files easy to fuzzy-find, we follow the naming conventions below for **services**, **repositories**, and other class-based files.
+
+### Repository Files
+
+- Repository class files must include the `Repository` suffix.
+- If the repository is backed by a specific technology (e.g. Prisma), prefix the filename and class name with it.
+- File name must match the exported class exactly (PascalCase).
+
+**Pattern:**
+
+Prisma<Entity>Repository.ts
+
+**Examples:**
+
+```ts
+// File: PrismaAppRepository.ts
+export class PrismaAppRepository { ... }
+
+// File: PrismaMembershipRepository.ts
+export class PrismaMembershipRepository { ... }
+```
+
+
+This avoids ambiguous filenames like app.ts and improves discoverability in editors.
+
+### Service Files
+Service class files must include the Service suffix.
+
+File name should be in PascalCase, matching the exported class.
+
+Keep naming specific — avoid generic names like AppService.ts.
+
+**Pattern:**
+
+<Entity>Service.ts
+
+**Examples:**
+
+```ts
+// File: MembershipService.ts
+export class MembershipService { ... }
+
+// File: HashedLinkService.ts
+export class HashedLinkService { ... }
+```
+
+
+<Note>
+New files must avoid dot-suffixes like .service.ts or .repository.ts; these will be migrated from the existing codebase progressively.  
+We still reserve suffixes such as .test.ts, .spec.ts, and .types.ts for their respective use cases.
+</Note>
+
 ## How we use TRPC at cal.com
 
 Cal.com makes use of the TRPC calls for CRUD operations on the database by utilizing the [useQuery()](https://trpc.io/docs/client/react/useQuery) & [useMutation()](https://trpc.io/docs/client/react/useMutation) hooks. These are essentially wrappers around @tanstack/react-query and you can learn more about them here, respectively: [queries](https://tanstack.com/query/v4/docs/react/guides/queries), [mutations](https://tanstack.com/query/v4/docs/react/guides/mutations).