Skip to content

CLAUDE.md

Latest commit

 

History

History
142 lines (105 loc) · 6.54 KB

CLAUDE.md

File metadata and controls

142 lines (105 loc) · 6.54 KB

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

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

npm run build

This runs TypeScript compilation (tsc -b) followed by Vite build.

Linting

npm run lint

Or to lint specific directories:

npx eslint ./src/

Preview Production Build

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)