# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a React + TypeScript + Vite web application for browsing grocery products, comparing prices, and viewing price trends. The application displays products organized by categories, shows price history charts, and provides product search functionality.

## Development Commands

### Running the Development Server
```bash
npm run dev
```
The dev server runs with `--host` flag to allow external connections. Vite is configured to allow the host `dfmoller-acer-aspire.springbok-cod.ts.net`.

### Building for Production
```bash
npm run build
```
This runs TypeScript compilation (`tsc -b`) followed by Vite build.

### Linting
```bash
npm run lint
```
Or to lint specific directories:
```bash
npx eslint ./src/
```

### Preview Production Build
```bash
npm run preview
```

### Testing
Playwright is installed (`@playwright/test` in devDependencies), but no test configuration or test files exist yet in the repository.

## Architecture

### State Management & Data Fetching

The application uses **Redux Toolkit Query (RTK Query)** for API calls and caching. This is a critical architectural decision:

- **RTK Query API Definition**: `src/redux/api.tsx` defines the API slice using `createApi` with a base URL of `/api`
- **Configured Endpoints**:
  - `getStoreById`, `getGrocerById`, `getGrocerByStoreId`
  - `getCategories`, `getCategoryById`
  - `getProductById`
- **Auto-generated Hooks**: The API exports hooks like `useGetProductByIdQuery`, `useGetCategoriesQuery` that handle loading states, caching, and refetching
- **Store Setup**: `src/redux/store.tsx` configures the Redux store with RTK Query middleware for caching, invalidation, and polling
- **Provider**: The app is wrapped with `ApiProvider` in `src/main.tsx`

**Important for Caching**: To benefit from RTK Query caching, always use `useNavigate()` or `<Link>` from `react-router-dom` for navigation. Other navigation methods may cause full page reloads and bypass the cache.

### API Layer - Two Patterns Coexist

There are **two different patterns** for API calls in this codebase:

1. **RTK Query (Preferred)**: Used in `src/redux/api.tsx` for frequently-accessed resources that benefit from caching (stores, grocers, categories, products)
2. **Direct Fetch API**: Used in `src/api/fetchapi.tsx` for specialized endpoints like:
   - `getCategoryPopulatedById` - categories with product associations
   - `getCategoryProducts` - paginated products in a category
   - `getProductDetailedImage`, `getProductThumbnailImage` - product images
   - `getProductLatestPrices`, `getProductPriceHistory` - price data with flexible query parameters
   - `searchProducts` - product search with pagination

The direct fetch pattern is used where RTK Query caching doesn't provide obvious benefits (e.g., one-off queries with many parameters) or for simpler implementation.

### Routing Structure

Routes defined in `src/App.tsx`:

- `/` - Landing view
- `/deals` - Deals view
- `/search` - Search view
- `/products/:productId` - Product detail view (standalone)
- `/categories/:categoryId` - Subcategory selection view
- `/categories/:categoryId/:subCategoryId` - Product list view
- `/categories/:categoryId/:subCategoryId/:productId` - Product detail view (with category context)

**Note**: The ProductView component (`src/views/ProductView.tsx`) handles two different routing patterns:
1. Via categories: `/categories/:categoryId/:subCategoryId/:productId` - includes breadcrumb navigation through category hierarchy
2. Direct/search: `/products/:productId` - used when accessing from search or direct links

### UI Framework

- **Material-UI (MUI v7)**: All components use `@mui/material` with `@emotion/react` and `@emotion/styled` for styling
- **Layout Pattern**: Many views use a flex layout with `CategoryDrawer` on the left and scrollable content on the right
- **Responsive Grid**: Uses MUI's Grid component with size props (not the older xs/sm/md pattern)

### Key Components

- **Header** (`src/components/Header.tsx`): App-wide navigation bar
- **CategoryDrawer** (`src/components/CategoryDrawer.tsx`): Side navigation for browsing categories
- **ProductCard** (`src/components/ProductCard.tsx`): Reusable product display component
- **BreadCrumbs** (`src/components/BreadCrumbs.tsx`): Navigation breadcrumb trail
- **GrocerPill** (`src/components/GrocerPill.tsx`): Display grocer badge/label

### Data Visualization

- **Recharts** library is used for price trend visualization
- ProductView shows an AreaChart with customizable time ranges (24h, 7d, 30d, 90d, 1y)
- Price data is fetched from the API in descending order (newest first) and reversed for chronological display

### TypeScript Interfaces

All API types are defined in `src/api/fetchapi.tsx`:
- `Grocer`, `Store` - grocery store entities
- `Category` - hierarchical category structure with `parent_id` and `children`
- `CategoryPopulated` - category with associated products
- `CategoryProductAssociation` - links products to categories with similarity scores
- `Product` - product entity
- `ProductsPaginated` - paginated product list response
- `ProductImage` - product image metadata
- `Price` - price record with timestamp
- `PriceHistoryParams` - query parameters for price history API

## Working with the API

The backend API is expected to be available at `/api` (proxied in development). When adding new endpoints:

1. For frequently-accessed resources that benefit from caching, add to RTK Query API in `src/redux/api.tsx`
2. For specialized queries with complex parameters or one-off usage, add direct fetch functions to `src/api/fetchapi.tsx`
3. Always define TypeScript interfaces for request/response types
4. Ensure proper error handling in components using the APIs

## Code Style

- **Line Length**: Maximum 120 characters per line
- **Comments**: Add comments when they provide meaningful value. Briefly state what is being done, but focus on the why. All comments must end with a period.
- **Docstrings**: Add docstrings to functions when the function name itself does not fully indicate what it does or how it should be used.
- **Indentation**: Use 2 spaces consistently
- **React Components**: Prefer functional components with hooks
- **No Emojis**: Never use emojis in comments or documentation

## Known Issues & TODOs

From code comments:
- App.tsx:28-29: Consider consolidating category views - if category has subcategories show subcategories, if it has products show products directly
- ProductView.tsx:60: Add proper error handling for API calls (currently errors are not displayed to users)