# CLAUDE.md

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

## Core Commands

### Development
```bash
npm run dev        # Start Vite dev server at localhost:5173
npm run build      # Build production bundle to dist/
npm run preview    # Preview production build locally
```

### Testing & Quality
```bash
npm test           # Run tests with Vitest
npm run lint       # Run ESLint
```

### Docker Operations
```bash
docker compose up -d      # Start containerized app on port 3800
docker compose down       # Stop containers
docker compose build      # Build Docker images
```

## Architecture Overview

### Application Type
React + TypeScript SPA for carbon offsetting calculations for yachts, built with Vite. Features both desktop and mobile-specific routes with Progressive Web App (PWA) support.

### Key Architectural Patterns

**Component Structure**: The app uses a single-page architecture with client-side routing managed through state in `App.tsx`. Navigation changes `currentPage` state rather than using React Router.

**Mobile App Route**: Special `/mobile-app` route renders `MobileCalculator` component exclusively, bypassing the standard layout. This is detected via `window.location.pathname` and managed through `isMobileApp` state.

**Data Flow**:
- Vessel data flows from `App.tsx` → Calculator components → `OffsetOrder`
- Carbon calculations happen in `utils/carbonCalculator.ts`
- API calls go through dedicated clients in `src/api/`

### API Integration

**Wren Climate API** (`src/api/wrenClient.ts`):
- Base URL: `https://www.wren.co/api`
- Requires Bearer token authentication via `VITE_WREN_API_TOKEN`
- Handles portfolio fetching and offset order creation
- Implements retry logic and fallback to default portfolio

**AIS Client** (`src/api/aisClient.ts`):
- Fetches vessel data by IMO number
- Currently uses mock data in development

**Formspree Integration**:
- Contact forms use `VITE_FORMSPREE_CONTACT_ID` and `VITE_FORMSPREE_OFFSET_ID`
- Handled in `Contact.tsx` and offset order components

### State Management
- Local component state via React hooks
- No global state management library
- Form state managed locally within components
- Calculator results passed via props to OffsetOrder components

### Styling Approach
- Tailwind CSS for utility-first styling
- Custom glass morphism effects via `index.css`
- Framer Motion for animations
- Responsive design with mobile-first approach

### Component Responsibilities

**Core Components**:
- `TripCalculator.tsx`: Desktop carbon calculator with trip details form
- `MobileCalculator.tsx`: Mobile-optimized calculator with step-by-step flow
- `OffsetOrder.tsx` / `MobileOffsetOrder.tsx`: Handles offset purchase flow
- `Home.tsx`: Landing page with hero section and navigation
- `Contact.tsx`: Contact form integration

**Calculation Logic** (`utils/carbonCalculator.ts`):
- Implements DEFRA emission factors
- Calculates based on distance, speed, engine power
- Returns tons of CO2 and monetary amounts

### Environment Configuration
Required environment variables in `.env`:
```
VITE_WREN_API_TOKEN=         # Wren API authentication
VITE_FORMSPREE_CONTACT_ID=   # Contact form endpoint
VITE_FORMSPREE_OFFSET_ID=    # Offset order form endpoint
```

### Testing Strategy
- Unit tests using Vitest and React Testing Library
- Test files in `__tests__` directories
- Run with `npm test`

### Build & Deployment
- Production builds output to `dist/`
- Docker deployment uses Nginx to serve static files on port 3800
- Host Nginx reverse proxy configuration available in `nginx-host.conf`
- PWA manifest and service worker for mobile app installation