# CLAUDE.md

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

## Project Overview

This is a Gatsby.js website for ABC Guêpes, a wasp and hornet nest removal service in France. The site is a professional services business website with location-based pages for various French municipalities in the Seine-et-Marne (77), Essonne (91), and Val-de-Marne (94) departments.

## Development Commands

### Core Commands
- `npm run develop` or `npm start` - Start development server
- `npm run dev` - Start development server with HTTPS (uses yarn internally)
- `npm run build` - Build for production (includes clean)
- `npm run serve` - Serve production build locally
- `npm run clean` - Clean Gatsby cache
- `npm run test` - Clean, build, and serve (equivalent to deployment test)

### Fast Development Commands (Performance)
- `npm run dev-fast` - Start development server WITHOUT location pages (much faster)
- `npm run dev-fast-https` - Start development server with HTTPS WITHOUT location pages
- **Use these for development** to avoid building hundreds of location pages during development

### Additional Commands
- `npm run cleandev` - Clean cache and start development with HTTPS
- `npm run mobile` - Start development server accessible on local network
- `npm run format` - Format code with Prettier
- `npm run deploy` - Clean and build for production

### Location Pages Management Commands
- `npm run hide-location-pages` - Temporarily move location pages to `.temp-location-pages/` for faster development
- `npm run restore-location-pages` - Restore location pages before building for production
- `npm run pages-status` - Check current status of location pages
- **Important**: Location pages must be restored before running `npm run build` or `npm run deploy`

### Code Quality Commands
- `npm run lint` - Run ESLint on source files
- `npm run lint:fix` - Run ESLint with auto-fix
- `npm run format:check` - Check code formatting with Prettier

## Architecture

### Technology Stack
- **Framework**: Gatsby.js v5.14.5
- **Styling**: Styled Components with global styles
- **Layout**: Reflexbox for responsive grid system
- **Images**: Gatsby Image (gatsby-plugin-image) with optimized loading
- **SEO**: React Helmet for meta tags, sitemaps, robots.txt
- **Analytics**: Google Analytics (gtag) and Google Tag Manager
- **Contact Forms**: EmailJS for contact form functionality

### Key Components Structure
- `src/components/layout.js` - Main layout wrapper with global styles and navbar
- `src/components/GlobalStyles.js` - Global CSS-in-JS styles
- `src/components/Navigation/` - Navigation components (Navbar, Logo, etc.)
- `src/components/P/` - Text components (Gras, Pcenter, Prouge, etc.)
- `src/components/Heading/` - Heading components
- `src/components/Footer/` - Footer components
- `src/pages/` - Gatsby pages including hundreds of location-specific pages

### Page Structure
- Main pages: index, contact, blog, pricing pages (zones-tarifaires), galleries
- Hundreds of location-specific pages following the pattern: `nid-guepes-frelons-[location-name]-[postal-code].js`
- Each location page is a minimal wrapper that uses Smart components for content generation
- Location pages support both single-city and multi-city formats (e.g., multiple municipalities sharing a postal code)

### Styling Approach
- Uses styled-components for component-level styling
- Global styles defined in `GlobalStyles.js`
- Responsive design with Reflexbox grid system
- Color scheme: Red (#e6332a) for headings, light background (#F6F7FD)

### Data Sources
- Static content and images from `src/images/`
- GraphQL queries for site metadata
- No external CMS or database dependencies

## Development Notes

### Image Handling
- Images are optimized using Gatsby Image with multiple formats (AUTO, WEBP, AVIF)
- Zoom functionality implemented with react-medium-image-zoom
- Static images stored in `src/images/`

### SEO Configuration
- Comprehensive SEO setup with canonical URLs, sitemaps, and robots.txt
- Location-specific meta descriptions for each municipality page
- Advanced sitemap generation for all pages

### Code Quality
- ESLint configured with Airbnb rules
- Prettier for code formatting
- gatsby-plugin-prettier-eslint for automatic formatting during development

### Performance Features
- Gatsby's static site generation for fast loading
- Image optimization and lazy loading
- Offline plugin for PWA capabilities
- Google Analytics and Tag Manager integration

## Important Files

### Configuration Files
- `gatsby-config.js` - Main Gatsby configuration with plugins, SEO settings, and site metadata
- `package.json` - Dependencies and npm scripts
- `vercel.json` - Deployment configuration for Vercel hosting (build command, headers, caching)

### Core Components
- `src/components/layout.js` - Main layout wrapper with global styles and navbar
- `src/components/GlobalStyles.js` - Global CSS-in-JS styles and theme configuration
- `src/components/seo.js` - SEO component with React Helmet configuration
- `src/pages/index.js` - Homepage with comprehensive business information

### Smart Components (Critical Architecture)
- `src/components/SmartLocalContent.js` - Generates all location page content dynamically
- `src/components/SmartLocalSeo.js` / `SmartLocalSeoOptimized.js` - Generates SEO metadata for location pages

### Data Layer
- `src/data/locationData.js` - Centralized location database with city and department data
- `src/utils/contentVariations.js` - Content variation system to ensure unique content per page

### Scripts
- `scripts/manage-location-pages.js` - Performance script to hide/restore location pages during development
- `scripts/migrate-pages.js` - Page migration utility script

## Location-Based Pages Architecture

This project contains hundreds of location-specific pages for French municipalities, following a consistent pattern:

### Page Structure
- Pages are named `nid-guepes-frelons-[location-name]-[postal-code].js`
- Each page targets specific municipalities in Seine-et-Marne (77), Essonne (91), Val-de-Marne (94), and some Yonne (89) departments
- URL structure: `/nid-guepes-frelons-[location-name]-[postal-code]`
- All pages follow a minimal template structure that delegates content generation to Smart components

### Smart Components System
The site uses a data-driven approach with "Smart" components that dynamically generate content:

- **`SmartLocalSeo`** (`src/components/SmartLocalSeoOptimized.js`) - Generates SEO metadata dynamically
  - Parses the filename to extract city name and postal code
  - Creates location-specific meta descriptions and title tags
  - Uses `parseFileName()` utility to handle multi-city pages

- **`SmartLocalContent`** (`src/components/SmartLocalContent.js`) - Generates all page content dynamically
  - Pulls data from `src/data/locationData.js` if available, otherwise creates default data
  - Uses content variation utilities from `src/utils/contentVariations.js` to ensure unique content per page
  - Generates location-specific H1 tags, problem descriptions, intervention types, and local context
  - Handles both single-city and multi-city pages automatically
  - Creates sections for: wasps/hornets, processionary caterpillars, and pest control

### Data Layer
- **`src/data/locationData.js`** - Central location database
  - Contains detailed data for specific cities (coordinates, neighborhoods, notable places, local problems)
  - Includes department-level data (77, 91, 94, 89, 75)
  - Exports utility functions: `getLocationData()`, `getDepartmentData()`, `parseFileName()`, `createDefaultLocationData()`
  - Falls back to generated default data for cities not explicitly defined

- **`src/utils/contentVariations.js`** - Content variation system
  - Generates unique content variations to avoid duplicate content across hundreds of pages
  - Functions include: `generateUniqueIntro()`, `generateProblemContext()`, `generateInterventionContext()`, etc.
  - Uses deterministic variation based on city name to ensure consistency

### Development Performance
Because there are hundreds of location pages, building all of them during development is slow:
- Use `npm run dev-fast` or `npm run dev-fast-https` to hide location pages during development
- The `scripts/manage-location-pages.js` script temporarily moves pages to `.temp-location-pages/`
- Main pages (index, contact, blog, pricing) remain available for development
- **Always run `npm run restore-location-pages` before production builds**

## Component Organization

### Text Components (`src/components/P/`)
- `Gras.js` - Bold text component
- `Pcenter.js` - Centered paragraph component
- `Prouge.js` - Red text component
- `SpanRouge.js` - Red span component
- Various text styling components following French naming conventions

### Navigation Components (`src/components/Navigation/`)
- `Navbar.js` - Main navigation bar
- `Logo.js` - Logo component
- `NavbarLinks.js` - Navigation links component

### Form Components
- Contact forms use EmailJS for serverless form handling
- No backend server required for contact functionality

## Development Workflow

### Making Changes
1. **For development**: Use `npm run dev-fast` or `npm run dev-fast-https` for fast startup (hides location pages)
2. Use `npm run develop` or `npm run dev` if you need to work on location pages specifically
3. Run `npm run lint` before committing to ensure code quality
4. Use `npm run format` to format code according to project standards

### Creating New Location Pages
To create new location pages:
1. Add location data to `src/data/locationData.js` (optional - falls back to defaults if not present)
2. Create a new page file: `src/pages/nid-guepes-frelons-[city-name]-[postal-code].js`
3. Use the minimal template structure (see existing pages like `nid-guepes-frelons-creteil-94000.js`)
4. The Smart components will automatically generate content based on the filename

### Working with Smart Components
- **Do not hardcode content** in location page files - use Smart components instead
- Modify `SmartLocalContent.js` to change content structure for all location pages
- Update `src/data/locationData.js` to add/modify specific city data
- Edit `src/utils/contentVariations.js` to adjust content variation logic

### Testing Changes
- `npm run test` - Full build and serve test (mimics deployment)
- `npm run build` - Production build only (automatically restores location pages)
- `npm run serve` - Serve existing build locally

### Deployment
- Site is configured for Vercel deployment with configuration in `vercel.json`
- `npm run deploy` - Clean and build for production (automatically restores location pages)
- Automatic deployment via Git integration
- **Note**: Build and deploy scripts automatically run `manage-location-pages.js restore` to ensure all pages are included

## Key Architectural Patterns

### Data-Driven Content Generation
This project uses a unique architecture to manage hundreds of location pages efficiently:

1. **Centralized Data**: All location information is stored in `src/data/locationData.js` rather than hardcoded in individual pages
2. **Smart Components**: Content generation logic lives in reusable Smart components, not in page files
3. **Filename Parsing**: The `parseFileName()` utility extracts city names and postal codes from filenames
4. **Content Variations**: The content variation system ensures each page has unique content to avoid SEO penalties
5. **Fallback System**: Pages without explicit data in `locationData.js` use generated defaults

### Benefits of This Architecture
- **Maintainability**: Changes to content structure only require editing Smart components, not hundreds of individual pages
- **Scalability**: New location pages can be created with just a few lines of boilerplate code
- **SEO**: Each page has unique, contextually-relevant content despite being template-driven
- **Performance**: Location pages can be hidden during development without losing functionality

### When Modifying Location Pages
- To change **structure or layout**: Edit `SmartLocalContent.js` or `SmartLocalSeo.js`
- To change **specific city data**: Edit `src/data/locationData.js`
- To adjust **content variations**: Edit `src/utils/contentVariations.js`
- To create **new pages**: Create a minimal page file using the existing template pattern