Craze-Data-check/AGENTS.md

# AGENTS.md - Developer Guidelines for Craze-Data-check

## Build, Lint, and Test Commands

### Development
```bash
npm run dev              # Start dev server on port 3000
npm run build            # Production build
npm run preview          # Preview production build
npm run clean            # Remove dist folder
```

### Linting & Type Checking
```bash
npm run lint             # TypeScript type check only (tsc --noEmit)
```

Note: This project does not have a separate test framework configured. To add tests, consider installing Vitest or Jest.

---

## Code Style Guidelines

### General Principles
- Use TypeScript for all new code
- Prefer functional components with hooks over class components
- Keep components focused and modular
- Use meaningful variable and function names

### Imports

**Order (top to bottom):**
1. React imports (`react`)
2. External libraries (`lucide-react`, `xlsx`, etc.)
3. Internal components (`./components/...`)
4. Internal lib/utils (`./lib/...`)
5. Types (`./types`)

```typescript
import React, { useState, useMemo } from 'react';
import { Search, Filter, Edit2 } from 'lucide-react';
import { ExcelRow, COLUMNS } from '../types';
import { cn } from '../lib/utils';
```

### TypeScript Conventions

- Use explicit types for props and function parameters
- Use `any` sparingly; prefer union types or interfaces
- Define column indices in a centralized `COLUMNS` object (see `src/types.ts`)

```typescript
// Good
interface ProductDescriptionsProps {
  data: ExcelRow[];
  onEdit: (index: number) => void;
}

// Good - centralized constants
export const COLUMNS = {
  ARTICLE_NO: 0,
  ARTICLE_NAME: 2,
  LINE: 7,
};
```

### Naming Conventions

| Element | Convention | Example |
|---------|------------|---------|
| Components | PascalCase | `ProductDescriptions`, `MatrixView` |
| Functions | camelCase | `handleFileUpload`, `formatCellValue` |
| Variables | camelCase | `activeModule`, `paginatedData` |
| Constants | UPPER_SNAKE_CASE | `ARTICLE_NO`, `MAX_UPLOAD_SIZE` |
| Interfaces | PascalCase | `AppState`, `ExcelRow` |
| Types | PascalCase | `TabType`, `SortDirection` |

### React Patterns

- Destructure props in function signature
- Use `useMemo` for expensive computations
- Use `useCallback` for event handlers passed to child components
- Keep `useState` calls at the top of component

```typescript
export function ProductDescriptions({ data, onEdit }: ProductDescriptionsProps) {
  const [activeTab, setActiveTab] = useState<TabType>('all');
  const [search, setSearch] = useState('');

  const filteredData = useMemo(() => {
    // expensive computation
  }, [data, activeTab, search]);
}
```

### Error Handling

- Use TypeScript's type system for runtime safety
- Use optional chaining (`?.`) and nullish coalescing (`??`)
- Validate file uploads with proper type checks

```typescript
const file = e.target.files?.[0];
if (!file) return;

// Validate Excel data
if (data.length > 0) {
  const rawHeaders = data[0];
  const rawRows = data.slice(1);
}
```

### UI/Styling

- Use Tailwind CSS for all styling
- Use `cn()` utility from `lib/utils` for conditional classes
- Follow existing color scheme (slate, blue, green, red for status)
- Use `lucide-react` for icons
- Keep responsive design in mind

```typescript
import { cn } from '../lib/utils';

<button
  className={cn(
    "px-4 py-2 rounded-md text-sm font-medium",
    isActive 
      ? "bg-blue-600 text-white" 
      : "bg-slate-800 text-slate-400"
  )}
>
```

### File Organization

```
src/
├── components/       # React components
│   ├── Sidebar.tsx
│   ├── MatrixView.tsx
│   └── ...
├── lib/             # Utilities and helpers
│   ├── utils.ts     # cn(), helpers
│   ├── auth.ts      # Authentication
│   └── supabase.ts  # Database operations
├── services/        # External API integrations
│   ├── gemini.ts
│   └── anthropic.ts
├── types.ts         # TypeScript types and constants
├── App.tsx          # Main application
└── main.tsx         # Entry point
```

### Data Processing

- When processing Excel data, handle both string and number types
- Use centralized column index constants
- Format numbers consistently (2 decimal places for prices/weights)
- Handle Excel date serial numbers properly (convert to readable dates)

```typescript
// Handle date columns from Excel
if (header.includes('date') || header.includes('launch')) {
  if (typeof val === 'number' && val >= 25569 && val <= 60000) {
    const excelEpoch = new Date(1899, 11, 30);
    const date = new Date(excelEpoch.getTime() + val * 86400000);
    return date.toLocaleDateString('en-GB');
  }
}
```

### Git Workflow

- Make small, focused commits
- Write clear commit messages describing what changed
- Push to main to trigger Vercel deployment automatically

### Running Single Components

When testing or developing specific features:
```bash
npm run dev    # Start dev server - access at http://localhost:3000
```

### Environment Variables

- Use `.env` file for local development
- Never commit secrets - use Vercel dashboard for production env vars

Required environment variables (production):
- `VITE_SUPABASE_URL`
- `VITE_SUPABASE_ANON_KEY`
- `VITE_GEMINI_API_KEY`
- `VITE_ANTHROPIC_API_KEY`