Copilot instructions

1---
2applyTo: 'src/**/*.{tsx,ts}'
3---
4# Code Architecture & Reusability Guidelines
5 
6## CRITICAL ARCHITECTURE RULES
7 
8### NEVER CREATE:
9- Components over 300 lines
10- Duplicate logic across components
11- Inline API calls in UI components
12- Mixed concerns (UI + business logic + API)
13- Copy-pasted code blocks
14 
15### ALWAYS CREATE:
16- Single-responsibility components (20-100 lines)
17- Custom hooks for reusable logic
18- Service layer for API calls
19- Shared types in `lib/types.ts`
20- Composition patterns from smaller components
21 
22## Component Composition Over Monoliths
23 
24**NEVER create large, monolithic components that handle multiple concerns:**
25**Avoid**: Single components or page that exceed 300 lines or handle multiple responsibilities
26**Avoid**: Pages that contain all logic inline instead of using smaller components
27**Avoid**: Components that mix UI rendering, business logic, and API calls
28 
29**ALWAYS break down complex functionality into smaller, reusable pieces:**
30**Create**: Focused components with single responsibilities (20-100 lines)
31**Create**: Composition patterns using multiple small components 
32**Create**: Custom hooks for reusable logic extraction
33**Create**: Separate layers for data fetching, business logic, and presentation
34 
35## Component Organization Strategy
36 
37### 1. Feature-Based Organization
38```tsx
39// Wrong: Everything in one file
40const Dashboard = () => {
41  // 300+ lines of mixed logic
42  return <div>{/* massive JSX */}</div>
43}
44 
45// ✅ Correct: Composed from focused components
46const Dashboard = () => (
47  <DashboardLayout>
48    <DashboardHeader />
49    <DashboardStats />
50    <DashboardCharts />
51    <DashboardActivity />
52  </DashboardLayout>
53)
54```
55 
56### 2. Reusable Component Patterns
57```tsx
58// ✅ Base components for consistent UI patterns
59const Card = ({ children, className, ...props }) => (
60  <div className={cn("rounded-lg border bg-card", className)} {...props}>
61    {children}
62  </div>
63)
64 
65// ✅ Composite components for complex patterns  
66const StatsCard = ({ title, value, change, icon: Icon }) => (
67  <Card className="p-6">
68    <div className="flex items-center justify-between">
69      <div>
70        <p className="text-sm text-muted-foreground">{title}</p>
71        <p className="text-2xl font-bold">{value}</p>
72        <p className="text-sm text-green-600">{change}</p>
73      </div>
74      <Icon className="h-8 w-8 text-muted-foreground" />
75    </div>
76  </Card>
77)
78```
79 
80### 3. Logic Extraction Patterns
81```tsx
82// ✅ Custom hooks for reusable stateful logic
83const useLocalStorage = (key: string, initialValue: any) => {
84  const [storedValue, setStoredValue] = useState(() => {
85    try {
86      const item = window.localStorage.getItem(key)
87      return item ? JSON.parse(item) : initialValue
88    } catch (error) {
89      return initialValue
90    }
91  })
92 
93  const setValue = (value: any) => {
94    try {
95      setStoredValue(value)
96      window.localStorage.setItem(key, JSON.stringify(value))
97    } catch (error) {
98      console.error(error)
99    }
100  }
101 
102  return [storedValue, setValue]
103}
104 
105// ✅ Service layer for API interactions
106export const userService = {
107  async getUser(id: string) {
108    const response = await fetch(`/api/users/${id}`)
109    return response.json()
110  },
111  
112  async updateUser(id: string, data: Partial<User>) {
113    const response = await fetch(`/api/users/${id}`, {
114      method: 'PATCH',
115      headers: { 'Content-Type': 'application/json' },
116      body: JSON.stringify(data)
117    })
118    return response.json()
119  }
120}
121```
122 
123## File Organization Best Practices
124 
125### 1. Component File Structure
126```tsx
127// ComponentName/index.ts - Export barrel
128export { ComponentName } from './ComponentName'
129export type { ComponentNameProps } from './ComponentName'
130 
131// ComponentName/ComponentName.tsx - Main component
132interface ComponentNameProps {
133  // Props definition
134}
135 
136export const ComponentName = ({ ...props }: ComponentNameProps) => {
137  // Component implementation
138}
139 
140// ComponentName/ComponentName.stories.tsx - Storybook stories (if used)
141// ComponentName/ComponentName.test.tsx - Tests (if used)
142```
143 
144### 2. Shared Type Definitions
145```tsx
146// lib/types.ts - Shared application types
147export interface User {
148  id: string
149  email: string
150  name: string
151  avatar?: string
152}
153 
154export interface ApiResponse<T> {
155  data: T
156  message: string
157  success: boolean
158}
159 
160export type Theme = 'light' | 'dark' | 'system'
161export type UserRole = 'admin' | 'user' | 'guest'
162```
163 
164### 3. Utility Function Organization
165```tsx
166// lib/utils.ts - General utilities (keep existing cn function)
167export function cn(...inputs: ClassValue[]) {
168  return twMerge(clsx(inputs))
169}
170 
171export function formatDate(date: Date | string, format?: string): string {
172  // Date formatting utility
173}
174 
175export function debounce<T extends (...args: any[]) => any>(
176  func: T,
177  wait: number
178): (...args: Parameters<T>) => void {
179  // Debounce utility
180}
181 
182// lib/constants.ts - Application constants
183export const API_ENDPOINTS = {
184  USERS: '/api/users',
185  POSTS: '/api/posts',
186  AUTH: '/api/auth'
187} as const
188 
189export const QUERY_KEYS = {
190  USERS: 'users',
191  POSTS: 'posts',
192  USER_PROFILE: 'user-profile'
193} as const
194```
195 
196## Custom Hook Patterns for Reusability
197 
198### 1. Data Fetching Hooks
199```tsx
200// hooks/useUsers.ts
201export const useUsers = () => {
202  return useQuery({
203    queryKey: [QUERY_KEYS.USERS],
204    queryFn: () => userService.getAllUsers()
205  })
206}
207 
208export const useUser = (id: string) => {
209  return useQuery({
210    queryKey: [QUERY_KEYS.USERS, id],
211    queryFn: () => userService.getUser(id),
212    enabled: !!id
213  })
214}
215```
216 
217### 2. Form Handling Hooks
218```tsx
219// hooks/useUserForm.ts
220export const useUserForm = (initialData?: Partial<User>) => {
221  const form = useForm<UserFormData>({
222    resolver: zodResolver(userSchema),
223    defaultValues: {
224      name: initialData?.name || '',
225      email: initialData?.email || '',
226      // ... other fields
227    }
228  })
229 
230  const { mutate: saveUser, isPending } = useMutation({
231    mutationFn: userService.updateUser,
232    onSuccess: () => {
233      toast.success('User updated successfully')
234    }
235  })
236 
237  return { form, saveUser, isPending }
238}
239```
240 
241### 3. UI State Hooks
242```tsx
243// hooks/useDisclosure.ts
244export const useDisclosure = (initialState = false) => {
245  const [isOpen, setIsOpen] = useState(initialState)
246  
247  const open = useCallback(() => setIsOpen(true), [])
248  const close = useCallback(() => setIsOpen(false), [])
249  const toggle = useCallback(() => setIsOpen(prev => !prev), [])
250  
251  return { isOpen, open, close, toggle }
252}
253```
254 
255## Validation Schema Reusability
256 
257### 1. Shared Zod Schemas
258```tsx
259// lib/validations/common.ts
260export const emailSchema = z.string().email('Invalid email address')
261export const phoneSchema = z.string().regex(/^\+?[\d\s-()]+$/, 'Invalid phone number')
262 
263// lib/validations/user.ts
264export const userSchema = z.object({
265  name: z.string().min(2, 'Name must be at least 2 characters'),
266  email: emailSchema,
267  phone: phoneSchema.optional(),
268  role: z.enum(['admin', 'user', 'guest'])
269})
270 
271export type UserFormData = z.infer<typeof userSchema>
272```
273 
274## Component Composition Patterns
275 
276### 1. Compound Components
277```tsx
278// components/common/DataTable/DataTable.tsx
279const DataTable = ({ children }: { children: React.ReactNode }) => (
280  <div className="border rounded-lg overflow-hidden">
281    {children}
282  </div>
283)
284 
285const DataTableHeader = ({ children }: { children: React.ReactNode }) => (
286  <div className="bg-muted p-4 border-b">
287    {children}
288  </div>
289)
290 
291const DataTableBody = ({ children }: { children: React.ReactNode }) => (
292  <div className="divide-y">
293    {children}
294  </div>
295)
296 
297// Usage: Flexible composition
298<DataTable>
299  <DataTableHeader>
300    <h3>Users</h3>
301  </DataTableHeader>
302  <DataTableBody>
303    {users.map(user => <UserRow key={user.id} user={user} />)}
304  </DataTableBody>
305</DataTable>
306```
307 
308### 2. Render Props Pattern
309```tsx
310// components/common/DataLoader.tsx
311interface DataLoaderProps<T> {
312  data: T[] | undefined
313  isLoading: boolean
314  error: Error | null
315  children: (data: T[]) => React.ReactNode
316  loadingComponent?: React.ReactNode
317  errorComponent?: (error: Error) => React.ReactNode
318  emptyComponent?: React.ReactNode
319}
320 
321export const DataLoader = <T,>({
322  data,
323  isLoading,
324  error,
325  children,
326  loadingComponent = <div>Loading...</div>,
327  errorComponent = (err) => <div>Error: {err.message}</div>,
328  emptyComponent = <div>No data found</div>
329}: DataLoaderProps<T>) => {
330  if (isLoading) return <>{loadingComponent}</>
331  if (error) return <>{errorComponent(error)}</>
332  if (!data || data.length === 0) return <>{emptyComponent}</>
333  return <>{children(data)}</>
334}
335```
336 
337## CRITICAL RULES FOR CODE ORGANIZATION
338 
3391. **Single Responsibility**: Each component should have one clear purpose
3402. **Composition Over Inheritance**: Build complex UIs by combining simple components
3413. **Extract Logic**: Move reusable logic into custom hooks, not copy-paste
3424. **Shared Types**: Define interfaces once, import everywhere
3435. **Service Layer**: Keep API calls separate from UI components
3446. **Consistent Patterns**: Use the same patterns across the entire application
3457. **Import Organization**: Group imports by type (React, libraries, local)
346 
347## Project Structure
348```
349/
350├── src/
351│   ├── components/
352│   │   ├── ui/              # shadcn/ui components (pre-built)
353│   │   ├── common/          # Reusable components (Header, Footer, Layout)
354│   │   ├── forms/           # Form-specific components
355│   │   └── features/        # Feature-specific component groups
356│   ├── hooks/               # Custom React hooks (reusable logic)
357│   ├── integrations/
358│   │   └── supabase/        # Supabase client configuration
359│   │       ├── client.ts    # Supabase client instance
360│   │       └── types.ts     # Auto-generated database types
361│   ├── lib/
362│   │   ├── utils.ts         # General utility functions
363│   │   ├── constants.ts     # App constants and enums
364│   │   ├── types.ts         # Shared TypeScript types
365│   │   └── validations/     # Zod schemas and form validations
366│   ├── pages/               # Route components (composition only)
367│   ├── services/            # API calls and external service integrations
368│   ├── context/             # React context providers
369│   ├── App.tsx              # Main app component with routing
370│   ├── main.tsx             # Entry point
371│   └── index.css            # Global styles
372├── supabase/                # Supabase local development
373│   ├── config.toml          # Supabase CLI configuration
374│   └── migrations/          # Database migrations (auto-generated)
375├── public/                  # Static assets
376├── package.json             # Dependencies and scripts
377├── vite.config.ts           # Vite configuration (@ → ./src, port 8080)
378├── tailwind.config.ts       # Tailwind configuration (dark mode support)
379├── components.json          # shadcn/ui configuration
380└── tsconfig.json            # TypeScript configuration
381```