.cursorrules

# .cursorrules

## Core Principles

1. **Team Workflow**:
   - Only work on assigned features
   - Don't modify unrelated code
   - Ask team before making cross-feature changes
   - Write clean, readable, maintainable code

2. **Supabase-First Development**:
   - Always use Supabase features over custom implementations
   - Leverage built-in functionality:
     - Auth: Use Supabase Auth for all authentication/authorization
     - Database: Use PostgreSQL features and RLS policies
     - Real-time: Use Supabase's real-time subscriptions
     - Edge Functions: Use Supabase Edge Functions for serverless logic
     - Storage: Use Supabase Storage for file handling
   - Before implementing custom solutions:
     - Check Supabase documentation for existing features
     - Consult team about Supabase capabilities
     - Document why Supabase features weren't suitable (if custom solution needed)

3. **Architecture Overview**:

   ```plaintext
   AutoCRM/
   ├── src/                 # Application source
   │   ├── features/        # Feature modules
   │   │   ├── shared/         # Shared utilities
   │   │   │   ├── components/ # Shared components
   │   │   │   ├── styles/     # Global styles
   │   │   │   │   ├── components/  # Component styles
   │   │   │   │   ├── themes/      # Theme definitions
   │   │   │   │   └── global/      # Global styles
   │   │   │   └── utils/     # Shared utilities
   │   │   └── types/         # Global types
   │   ├── core/          # Base implementations
   │   │   ├── supabase/  # Supabase integration
   │   │   ├── api/       # API clients
   │   │   └── config/    # App configuration
   │   └── types/         # Global types
   ├── supabase/          # Supabase configuration
   │   ├── migrations/    # Database migrations
   │   │   └── [timestamp]_name.sql
   │   ├── functions/     # Edge Functions
   │   │   └── [function-name]/
   │   │       ├── index.ts
   │   │       └── schema.ts
   │   ├── seed.sql      # Seed data
   │   └── config.toml   # Supabase config
   ├── public/           # Static assets
   ├── dist/            # Build output
   └── .env.*           # Environment files
       ├── .env.example
       ├── .env.development
       └── .env.production
   ```

## Feature Organization

1. **Feature Module Structure**:

   ```plaintext
   feature-name/
   ├── components/        # UI Components
   │   ├── FeatureComponent.tsx
   │   └── index.ts      # Barrel export
   ├── services/         # Business Logic
   │   ├── FeatureService.ts
   │   └── index.ts
   ├── hooks/            # Custom Hooks
   │   ├── useFeature.ts
   │   └── index.ts
   ├── store/            # State Management
   │   ├── feature.store.ts
   │   └── index.ts
   ├── types/            # Feature Types
   │   ├── feature.types.ts
   │   └── index.ts
   ├── __tests__/        # Tests
   │   ├── components/
   │   ├── hooks/
   │   └── services/
   ├── __mocks__/        # Test mocks
   └── index.ts          # Public API
   ```

2. **Feature Boundaries**:
   - Self-contained modules
   - Clear public API through index.ts
   - Cross-feature communication via stores only
   - Feature-specific types in feature directory

## Naming & Type System

1. **File Naming**:
   - Components: PascalCase.tsx (UserProfile.tsx)
   - Services: PascalCase + 'Service'.ts (UserService.ts)
   - Hooks: camelCase + 'use' prefix (useAuth.ts)
   - Types: PascalCase + '.types.ts' (User.types.ts)
   - Tests: Original + '.test.ts' (UserService.test.ts)
   - Directories: kebab-case (user-management/)

2. **Type Organization**:
   - Global: `@/types/`

     ```typescript
     database.types.ts  # Supabase schema
     supabase.types.ts  # Client types
     common.types.ts    # Shared utilities
     ```

   - Feature: `@/features/[feature]/types/`

     ```typescript
     state.types.ts    # Store types
     models.types.ts   # Domain models
     api.types.ts      # API types
     ```

3. **Database Naming**:
   - Tables: plural_snake_case (user_profiles)
   - Columns: singular_snake_case (first_name)
   - Keys: table_name_id (user_id)
   - Indexes: idx_table_column (idx_users_email)

## Import & Path System

1. **Path Aliases**:

   ```typescript
   // vite.config.ts
   resolve: {
     alias: {
       '@': '/src',
       '@features': '/src/features',
       '@shared': '/src/shared',
       '@core': '/src/core',
       '@types': '/src/types'
     }
   }
   ```

2. **Import Organization**:

   ```typescript
   // External packages
   import React from 'react'
   import { useQuery } from '@tanstack/react-query'

   // Core & shared
   import { Button } from '@/shared/components'
   import { BaseService } from '@/core/base'

   // Feature imports
   import { UserProfile } from '@/features/user-management'

   // Types
   import type { User } from '@/types/models'
   ```

3. **Import Rules**:
   - Use absolute imports with @/ prefix
   - Import from feature's public API
   - No deep imports into other features
   - Group imports by category

## State Management

1. **Store Pattern**:

   ```typescript
   interface FeatureState {
     data: Data[]
     loading: boolean
     error: Error | null
   }

   interface FeatureActions {
     fetch: () => Promise<void>
     reset: () => void
   }
   ```

2. **State Organization**:
   - Feature state in feature/store
   - Global state in core/store
   - Local state with React hooks
   - Cross-feature state via events

## Technical Integration

1. **Supabase Integration**:
   - Database:

     ```sql
     -- migrations/[timestamp]_create_users.sql
     create table public.users (
       id uuid references auth.users primary key,
       created_at timestamptz default now(),
       updated_at timestamptz default now()
     );

     -- Enable RLS
     alter table public.users enable row level security;

     -- Create policies
     create policy "Users can view own data" on public.users
       for select using (auth.uid() = id);
     ```

   - Edge Functions:

     ```typescript
     // functions/process-data/index.ts
     import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
     import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'

     serve(async (req) => {
       const supabase = createClient(
         Deno.env.get('SUPABASE_URL') ?? '',
         Deno.env.get('SUPABASE_ANON_KEY') ?? ''
       )
       // Implementation
     })
     ```

   - Client Setup:

     ```typescript
     // src/lib/supabase.ts
     import { createClient } from '@supabase/supabase-js'
     import type { Database } from '@/types/database.types'

     export const supabase = createClient<Database>(
       import.meta.env.VITE_SUPABASE_URL,
       import.meta.env.VITE_SUPABASE_ANON_KEYw
     )
     ```

   - Real-time Subscriptions:

     ```typescript
     // In components/features
     const subscription = supabase
       .channel('table_db_changes')
       .on(
         'postgres_changes',
         { event: '*', schema: 'public', table: 'table_name' },
         (payload) => {
           // Handle change
         }
       )
       .subscribe()
     ```

   - Error Handling Pattern:

     ```typescript
     try {
       const { data, error } = await supabase.from('table').select()
       if (error) throw error
     } catch (error) {
       logger.error('Operation failed', { error })
     }
     ```

   - Security:
     - RLS policies for all tables
     - Edge Functions for sensitive operations
     - Proper auth token handling
     - Regular security audits

2. **React Patterns**:
   - Functional components
   - Error boundaries
   - Suspense for loading
   - React Query for data

3. **UI Component System**:
   - Use shadcn components as primary UI building blocks
   - Only use direct TailwindCSS when shadcn components don't exist
   - Extend shadcn components instead of creating new patterns
   - Example shadcn usage:
     ```typescript
     import { Button } from "@/components/ui/button"
     import { Input } from "@/components/ui/input"
     
     function LoginForm() {
       return (
         <form>
           <Input type="email" placeholder="Email" />
           <Button type="submit">Login</Button>
         </form>
       )
     }
     ```
   - TailwindCSS for custom styling only:
     ```typescript
     const styles = {
       customLayout: 'grid grid-cols-[1fr_2fr]', // No shadcn equivalent
       specialText: 'font-mono tracking-tight' // Custom typography
     }
     ```

## Quality Assurance

1. **Testing Structure**:

   ```plaintext
   feature/
   ├── __tests__/
   │   ├── components/
   │   └── services/
   └── __fixtures__/
   ```

2. **Error Handling**:
   - Error boundaries
   - Toast notifications
   - Logging system
   - Monitoring setup

3. **Performance**:
   - Component memoization
   - Query caching
   - Bundle optimization
   - Load time monitoring

4. **Accessibility**:
   - ARIA attributes
   - Keyboard navigation
   - Screen reader support
   - Contrast validation

## Version Control

1. **Git Workflow**:

   ```plaintext
   type(scope): concise summary

   - Detailed change 1
   - Detailed change 2
   ```

2. **Branch Structure**:
   - feature/feature-name
   - fix/issue-description
   - release/version

## Configuration

1. **Environment**:

   ```plaintext
   VITE_SUPABASE_URL=url
   VITE_SUPABASE_ANON_KEY=key
   VITE_ENABLE_FEATURE_X=true
   ```

2. **Feature Flags**:
   - Runtime controls
   - Environment-based
   - Feature toggles