puffin-app/CLAUDE.md

CLAUDE.md

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

Core Commands

Development

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

npm test           # Run tests with Vitest
npm run lint       # Run ESLint

Docker Operations

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