services · git:20250727.a15289d · 2025-07-27 · sha256 05535de64c0a8081
services git:20250727.a15289dA
Immutable. This exact content never changes and is served at /api/v1/blob/05535de64c0a8081.
---
description: Service layer architecture, API patterns, and data management with TanStack Query
globs: ["src/lib/**/*.ts", "src/services/**/*.ts", "src/hooks/use*.ts"]
alwaysApply: false
---
# Service Layer & Data Management Rules
## Service Layer Organization
### File Structure
```
src/lib/
├── utils.ts # General utilities (keep cn function)
├── types.ts # Shared TypeScript interfaces
├── constants.ts # App-wide constants
├── validations/ # Zod schemas
│ ├── user.ts
│ ├── product.ts
│ └── common.ts
└── services/ # API service layer
├── api.ts # Base API client
├── userService.ts
└── productService.ts
```
### Service Layer Pattern
```tsx
// services/userService.ts
export const userService = {
async getAll(): Promise<User[]> {
const response = await fetch('/api/users')
if (!response.ok) throw new Error('Failed to fetch users')
return response.json()
},
async getById(id: string): Promise<User> {
const response = await fetch(`/api/users/${id}`)
if (!response.ok) throw new Error('Failed to fetch user')
return response.json()
},
async create(data: CreateUserData): Promise<User> {
const response = await fetch('/api/users', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(data)
})
if (!response.ok) throw new Error('Failed to create user')
return response.json()
},
async update(id: string, data: Partial<User>): Promise<User> {
const response = await fetch(`/api/users/${id}`, {
method: 'PATCH',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(data)
})
if (!response.ok) throw new Error('Failed to update user')
return response.json()
}
}
```
### Shared Types (lib/types.ts)
```tsx
export interface User {
id: string
email: string
name: string
avatar?: string
role: UserRole
createdAt: string
updatedAt: string
}
export interface ApiResponse<T> {
data: T
message: string
success: boolean
meta?: {
total: number
page: number
limit: number
}
}
export type UserRole = 'admin' | 'user' | 'guest'
export type Theme = 'light' | 'dark' | 'system'
export type LoadingState = 'idle' | 'loading' | 'success' | 'error'
```
### Constants (lib/constants.ts)
```tsx
export const API_ENDPOINTS = {
USERS: '/api/users',
PRODUCTS: '/api/products',
AUTH: '/api/auth',
} as const
export const QUERY_KEYS = {
USERS: 'users',
PRODUCTS: 'products',
USER_PROFILE: 'user-profile',
} as const
export const ROUTES = {
HOME: '/',
DASHBOARD: '/dashboard',
USERS: '/users',
PROFILE: '/profile',
} as const
```
### Validation Schemas
```tsx
// lib/validations/common.ts
export const emailSchema = z.string().email('Invalid email address')
export const phoneSchema = z.string().regex(/^\+?[\d\s-()]+$/, 'Invalid phone number')
// lib/validations/user.ts
export const userSchema = z.object({
name: z.string().min(2, 'Name must be at least 2 characters'),
email: emailSchema,
phone: phoneSchema.optional(),
role: z.enum(['admin', 'user', 'guest'])
})
export const createUserSchema = userSchema.omit({ role: true })
export const updateUserSchema = userSchema.partial()
export type UserFormData = z.infer<typeof userSchema>
export type CreateUserData = z.infer<typeof createUserSchema>
export type UpdateUserData = z.infer<typeof updateUserSchema>
```
## TanStack Query Integration
### Query Hooks Pattern
```tsx
// hooks/useUsers.ts
export const useUsers = (params?: UserQueryParams) => {
return useQuery({
queryKey: [QUERY_KEYS.USERS, params],
queryFn: () => userService.getAll(params),
staleTime: 5 * 60 * 1000, // 5 minutes
})
}
export const useUser = (id: string) => {
return useQuery({
queryKey: [QUERY_KEYS.USERS, id],
queryFn: () => userService.getById(id),
enabled: !!id,
})
}
```
### Mutation Hooks Pattern
```tsx
// hooks/useUserMutations.ts
export const useCreateUser = () => {
const queryClient = useQueryClient()
return useMutation({
mutationFn: userService.create,
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: [QUERY_KEYS.USERS] })
toast.success('User created successfully')
},
onError: (error) => {
toast.error(error.message)
}
})
}
```
## ❌ NEVER in Components
- Direct API calls (`fetch`, `axios` inline)
- Business logic mixed with UI
- Hardcoded API URLs
- Duplicate validation schemas
## ✅ ALWAYS Use
- Service layer for all API calls
- Shared types for consistent interfaces
- Custom hooks for data fetching
- Centralized constants for URLs and keys