Cursor rule

1---
2description: Guidelines for Service Layer
3globs: 
4alwaysApply: false
5---
6# Guidelines for Service Layer
7 
8## Purpose and Overview
9The service layer is responsible for orchestrating business logic and coordinating data access operations. It sits between the UI (components, hooks) and the data access layer, providing a clear separation of concerns. Services should handle:
10 
111. Orchestration of multiple data operations
122. Business logic implementation
133. Data transformation and validation
144. Error handling and logging
15 
16## Structure and Organization
17 
18### Service Layer Module Structure
19```
20src/
21├── services/                       # Shared service layer module
22│   └── [entity]
23        └── [operation-entity-name].ts  # Shared service implementations
24└── features/
25    └── [feature-name]/
26        └── _services/              # Feature-specific services
27            └── [operation-entity-name].ts  # Feature-specific service implementations
28```
29 
30## Naming Conventions
31 
32### Functions
33- `[operation][Entity]Service`: For service functions (e.g., `getFeatureFlagService`, `createUserService`)
34 
35### Types
36- `[Operation][Entity]ServiceArgs`: Arguments for service functions
37- `[Operation][Entity]ServiceDependencies`: Dependencies for service functions
38- `[Operation][Entity]ServiceResult`: Return type for service functions (if needed)
39 
40## Implementation Guidelines
41 
42### Service Layer
43- Services should receive data access functions as dependencies
44- Dependencies should be injected with default values
45- Services should be pure functions that don't manage state
46- Services should handle error cases and transformations
47- Services should be testable by allowing dependency injection
48 
49### Example Service Function
50```typescript
51import { getUserData } from '@/data/users/get-user';
52import { getFeatureFlagData } from '@/data/feature-flags/get-feature-flag';
53import { type DbClient } from '@/db/create-db-client';
54import { type Session } from '@/types/auth';
55 
56export type GetFeatureFlagServiceDependencies = {
57  getUserData: typeof getUserData;
58  getFeatureFlagData: typeof getFeatureFlagData;
59};
60 
61export type GetFeatureFlagServiceArgs = {
62  dbClient: DbClient;
63  payload: { session: Session };
64  dependencies?: GetFeatureFlagServiceDependencies;
65};
66 
67export async function getFeatureFlagService({
68  dbClient,
69  payload,
70  dependencies = {
71    getUserData,
72    getFeatureFlagData,
73  },
74}: GetFeatureFlagServiceArgs) {
75  const userData = await dependencies.getUserData({
76    dbClient,
77    id: payload.session.id,
78  });
79 
80  const featureFlagData = await dependencies.getFeatureFlagData({
81    dbClient,
82    role: userData.role,
83  });
84 
85  return featureFlagData;
86}
87```
88 
89## When to Use Service Layer
90 
91Services should be used when:
92 
931. You need to coordinate multiple data access operations
942. There is complex business logic to implement
953. You need to transform or validate data before returning it
964. You need to handle specific error cases or implement retry logic
975. You want to make the code more testable through dependency injection
98 
99If an operation is simple and only involves a single data access call with minimal transformation, it might not need a service layer.