Cursor rule

1---
2description: Service layer architecture, API patterns, and data management with TanStack Query
3globs: ["src/lib/**/*.ts", "src/services/**/*.ts", "src/hooks/use*.ts"]
4alwaysApply: false
5---
6 
7# Service Layer & Data Management Rules
8 
9## Service Layer Organization
10 
11### File Structure
12```
13src/lib/
14├── utils.ts          # General utilities (keep cn function)
15├── types.ts          # Shared TypeScript interfaces
16├── constants.ts      # App-wide constants
17├── validations/      # Zod schemas
18│   ├── user.ts
19│   ├── product.ts
20│   └── common.ts
21└── services/         # API service layer
22    ├── api.ts        # Base API client
23    ├── userService.ts
24    └── productService.ts
25```
26 
27### Service Layer Pattern
28```tsx
29// services/userService.ts
30export const userService = {
31  async getAll(): Promise<User[]> {
32    const response = await fetch('/api/users')
33    if (!response.ok) throw new Error('Failed to fetch users')
34    return response.json()
35  },
36  
37  async getById(id: string): Promise<User> {
38    const response = await fetch(`/api/users/${id}`)
39    if (!response.ok) throw new Error('Failed to fetch user')
40    return response.json()
41  },
42  
43  async create(data: CreateUserData): Promise<User> {
44    const response = await fetch('/api/users', {
45      method: 'POST',
46      headers: { 'Content-Type': 'application/json' },
47      body: JSON.stringify(data)
48    })
49    if (!response.ok) throw new Error('Failed to create user')
50    return response.json()
51  },
52  
53  async update(id: string, data: Partial<User>): Promise<User> {
54    const response = await fetch(`/api/users/${id}`, {
55      method: 'PATCH',
56      headers: { 'Content-Type': 'application/json' },
57      body: JSON.stringify(data)
58    })
59    if (!response.ok) throw new Error('Failed to update user')
60    return response.json()
61  }
62}
63```
64 
65### Shared Types (lib/types.ts)
66```tsx
67export interface User {
68  id: string
69  email: string
70  name: string
71  avatar?: string
72  role: UserRole
73  createdAt: string
74  updatedAt: string
75}
76 
77export interface ApiResponse<T> {
78  data: T
79  message: string
80  success: boolean
81  meta?: {
82    total: number
83    page: number
84    limit: number
85  }
86}
87 
88export type UserRole = 'admin' | 'user' | 'guest'
89export type Theme = 'light' | 'dark' | 'system'
90export type LoadingState = 'idle' | 'loading' | 'success' | 'error'
91```
92 
93### Constants (lib/constants.ts)
94```tsx
95export const API_ENDPOINTS = {
96  USERS: '/api/users',
97  PRODUCTS: '/api/products',
98  AUTH: '/api/auth',
99} as const
100 
101export const QUERY_KEYS = {
102  USERS: 'users',
103  PRODUCTS: 'products',
104  USER_PROFILE: 'user-profile',
105} as const
106 
107export const ROUTES = {
108  HOME: '/',
109  DASHBOARD: '/dashboard',
110  USERS: '/users',
111  PROFILE: '/profile',
112} as const
113```
114 
115### Validation Schemas
116```tsx
117// lib/validations/common.ts
118export const emailSchema = z.string().email('Invalid email address')
119export const phoneSchema = z.string().regex(/^\+?[\d\s-()]+$/, 'Invalid phone number')
120 
121// lib/validations/user.ts
122export const userSchema = z.object({
123  name: z.string().min(2, 'Name must be at least 2 characters'),
124  email: emailSchema,
125  phone: phoneSchema.optional(),
126  role: z.enum(['admin', 'user', 'guest'])
127})
128 
129export const createUserSchema = userSchema.omit({ role: true })
130export const updateUserSchema = userSchema.partial()
131 
132export type UserFormData = z.infer<typeof userSchema>
133export type CreateUserData = z.infer<typeof createUserSchema>
134export type UpdateUserData = z.infer<typeof updateUserSchema>
135```
136 
137## TanStack Query Integration
138 
139### Query Hooks Pattern
140```tsx
141// hooks/useUsers.ts
142export const useUsers = (params?: UserQueryParams) => {
143  return useQuery({
144    queryKey: [QUERY_KEYS.USERS, params],
145    queryFn: () => userService.getAll(params),
146    staleTime: 5 * 60 * 1000, // 5 minutes
147  })
148}
149 
150export const useUser = (id: string) => {
151  return useQuery({
152    queryKey: [QUERY_KEYS.USERS, id],
153    queryFn: () => userService.getById(id),
154    enabled: !!id,
155  })
156}
157```
158 
159### Mutation Hooks Pattern
160```tsx
161// hooks/useUserMutations.ts
162export const useCreateUser = () => {
163  const queryClient = useQueryClient()
164  
165  return useMutation({
166    mutationFn: userService.create,
167    onSuccess: () => {
168      queryClient.invalidateQueries({ queryKey: [QUERY_KEYS.USERS] })
169      toast.success('User created successfully')
170    },
171    onError: (error) => {
172      toast.error(error.message)
173    }
174  })
175}
176```
177 
178## NEVER in Components
179- Direct API calls (`fetch`, `axios` inline)
180- Business logic mixed with UI
181- Hardcoded API URLs
182- Duplicate validation schemas
183 
184## ALWAYS Use
185- Service layer for all API calls
186- Shared types for consistent interfaces
187- Custom hooks for data fetching
188- Centralized constants for URLs and keys
189