# Caron-L'Écuyer - Technical Documentation

> Créateur de cuillères et d'os musicaux en bois / Designer of wooden musical spoons and bones

## Project Overview

Caron-L'Écuyer is an e-commerce website for a Quebec artisan specializing in handcrafted wooden musical instruments (spoons and bones). The site is bilingual (French/English) and processes payments through Stripe.

## Architecture

### Tech Stack
- **Framework**: Next.js 15.5.5 (App Router, Turbopack)
- **Language**: TypeScript
- **Styling**: Tailwind CSS
- **i18n**: next-intl (French/English)
- **Database**: Supabase (PostgreSQL)
- **Payments**: Stripe Checkout
- **Email**: Resend
- **Error Monitoring**: Sentry

### Project Structure

```
src/
├── app/
│   ├── [locale]/           # Localized pages (fr/en)
│   │   ├── page.tsx        # Home page
│   │   ├── produits/       # Products listing
│   │   ├── produit/[slug]/ # Product detail pages
│   │   ├── checkout/       # Checkout flow
│   │   ├── contact/        # Contact page
│   │   └── ...
│   ├── api/
│   │   ├── checkout/       # Stripe checkout session + webhooks
│   │   └── contact/        # Contact form endpoint
│   ├── sitemap.ts          # Dynamic sitemap generation
│   └── robots.ts           # Robots.txt configuration
├── components/
│   ├── home/               # Home page components
│   ├── layout/             # Header, Footer, Container
│   ├── cart/               # Cart sidebar
│   ├── checkout/           # Checkout components
│   └── product/            # Product display components
├── context/
│   └── CartContext.tsx     # Shopping cart state
├── lib/
│   ├── supabase/           # Supabase clients (server/client)
│   ├── stripe.ts           # Stripe configuration
│   └── products.ts         # Product data fetching
├── i18n/                   # Internationalization setup
└── emails/                 # Email templates (React Email)
```

## Database Schema

### Products Table: `caronlecuyer_products`
- `id` (UUID) - Primary key
- `slug` (TEXT) - URL-friendly identifier
- `name_fr`, `name_en` (TEXT) - Bilingual names
- `description_fr`, `description_en` (TEXT) - Bilingual descriptions
- `price` (DECIMAL) - Price in CAD
- `category` (TEXT) - 'spoons' or 'bones'
- `images` (JSONB) - Array of image URLs
- `in_stock` (BOOLEAN) - Availability
- `featured` (BOOLEAN) - Show on homepage

### Variants Table: `caronlecuyer_product_variants`
- `id` (UUID) - Primary key
- `product_id` (UUID) - Foreign key to products
- `name_fr`, `name_en` (TEXT) - Variant names
- `options` (JSONB) - Variant options (size, wood type, etc.)
- `price_modifier` (DECIMAL) - Price adjustment
- `in_stock` (BOOLEAN) - Variant availability

### Orders Table: `caronlecuyer_orders`
- `id` (UUID) - Primary key
- `stripe_checkout_session_id` (TEXT) - Stripe reference
- `stripe_payment_intent_id` (TEXT) - Payment reference
- `status` (TEXT) - Order status
- `customer_email`, `customer_name` (TEXT) - Customer info
- `shipping_*` (TEXT) - Shipping address fields
- `subtotal_cents`, `shipping_cents`, `total_cents` (INTEGER) - Amounts in cents
- `currency` (TEXT) - 'CAD'
- `locale` (TEXT) - 'fr' or 'en'

### Order Items Table: `caronlecuyer_order_items`
- `id` (UUID) - Primary key
- `order_id` (UUID) - Foreign key to orders
- `product_id`, `variant_id` (TEXT) - Product references
- `name_fr`, `name_en` (TEXT) - Item names at time of purchase
- `options` (JSONB) - Selected options
- `unit_price_cents` (INTEGER) - Price per unit
- `quantity` (INTEGER) - Quantity ordered
- `line_total_cents` (INTEGER) - Line total

## API Endpoints

### POST /api/checkout/create-session
Creates a Stripe Checkout Session for the cart.

Request body:
```json
{
  "items": [{ "productId": "uuid", "variantId": "uuid", "quantity": 1 }],
  "shipping": { "name": "", "email": "", "address": {...} },
  "locale": "fr"
}
```

### POST /api/checkout/webhook
Handles Stripe webhook events (checkout.session.completed).
Creates order in database, sends confirmation emails.

### POST /api/contact
Handles contact form submissions via Resend.

## Internationalization

Routes are prefixed with locale: `/fr/...` or `/en/...`
Default locale: French (`fr`)

Translation files: `messages/fr.json`, `messages/en.json`

## Environment Variables

```
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=
RESEND_API_KEY=
OWNER_EMAIL=
NEXT_PUBLIC_SENTRY_DSN=
SENTRY_TRACES_SAMPLE_RATE=0.1
```

## Products

### Musical Spoons (Cuillères)
Traditional wooden spoons for folk music percussion. Sizes range from standard to extra-large. Wood types include maple, cherry, walnut, and birch.

### Musical Bones (Os)
Rhythm bones carved from hardwood. Used by striking together in pairs to create percussive rhythms.

## Contact

Website: https://www.caronlecuyer.com
Region: Quebec, Canada