# CLAUDE.md

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

## Project Overview

**CleanSerp** is a Shopify embedded app for SEO management. It provides a configurable rules engine that applies `noindex`/`nofollow` meta directives and canonical tags to Shopify storefront pages. The UI labels are in French (French market focus).

**Stack**: Remix v2 + Vite 6, React 18, Polaris v12, Prisma + PostgreSQL (Neon), Shopify App Remix v3, TypeScript

## Development Commands

```bash
pnpm install                  # Install dependencies
pnpm run dev                  # Start dev server (shopify app dev, press P to open)
pnpm run build                # Production build (remix vite:build)
pnpm run start                # Production server (remix-serve)
pnpm run setup                # DB setup (prisma generate && prisma migrate deploy)
pnpm run lint                 # ESLint with cache
pnpm run deploy               # Deploy to Shopify
pnpm run graphql-codegen      # Generate GraphQL types from Shopify Admin API
pnpm prisma studio            # Browse database visually
```

## Architecture

### Core Flow

```
Shop installs app
  → shop-lifecycle.server.ts creates Shop + initializes all ShopRules in DB
  → Dashboard (app._index.tsx) displays rules by category tabs
  → Merchant toggles rules on/off, enters custom values
  → On save: rules persisted to DB, then metafield-sync pushes config as JSON
    to Shopify app metafields (namespace: cs_x9k2m)
  → Theme extension reads metafields to inject <meta name="robots"> and canonical tags
```

### Key Files

| File | Purpose |
|------|---------|
| `app/lib/rules.ts` | All SEO rule definitions — 4 categories (Security, Duplicate Content, Technical, Custom), ~15 rules with priority, robotsValue, hasCanonical flag |
| `app/lib/metafield-sync.server.ts` | Syncs enabled rules to Shopify via GraphQL `metafieldsSet` mutation on `CurrentAppInstallation` |
| `app/lib/shop-lifecycle.server.ts` | Shop install/uninstall logic, default rule initialization |
| `app/routes/app._index.tsx` | Main dashboard — rule toggles organized by category tabs, save triggers DB + metafield sync |
| `app/shopify.server.ts` | Shopify app config (OAuth, API version January25, Prisma session storage) |
| `prisma/schema.prisma` | DB schema: Session, Shop, ShopRule (unique on `[shopId, ruleKey]`, cascade delete) |
| `shopify.app.toml` | App config: scopes `read_themes`, webhooks, embedded=true |
| `extensions/cleanserp-seo/` | Theme extension: `blocks/seo-injection.liquid` injects robots/canonical tags in storefront |

### Patterns

- **Remix loader/action** for all data fetching and mutations
- **Prisma upsert** for idempotent shop/rule creation
- **Metafield namespace** `cs_x9k2m` with keys `rules` (JSON) and `active` (boolean)
- All data scoped by `shopId` (Shopify shop domain as primary key)
- **Embedded app**: runs in Shopify Admin iframe — use `Link` from `@remix-run/react` or Polaris, never raw `<a>` tags. Use `redirect` from `authenticate.admin`, not from `@remix-run/node`

## Database

- PostgreSQL on Neon (project: `cold-field-63734010`, org: `elevaseo`)
- Connection string in `.env` (`DATABASE_URL`)
- After schema changes: `pnpm run setup`
- `ShopRule` has unique constraint on `[shopId, ruleKey]` with cascade delete from Shop

## Known Issues & Refactoring

This project was originally built with Gemini and needs significant refactoring. Full specifications and requirements are in `documentation/CleanSerp - app seo kalys/`.

**Critical bugs:**
- Theme extension generates multiple `<meta name="robots">` tags — Google only reads the first one. Must generate a single merged tag placed FIRST in `<head>`
- No character limits on custom CSV fields (handles, paths, parameters) — 10/20 max needed

**Missing features:**
- Billing/subscription system (required for Shopify App Store submission)
- Complete theme extension implementation
- README.md is still default Shopify template boilerplate

**Key documentation files:**
- `documentation/.../Autres/Ce que j_attends de la Nouvelle version (Important).docx` — requirements for the new version
- `documentation/.../Cahier des charges/cahier-des-charges-cleanserp-v2.0.5.docx` — latest specifications
- `documentation/.../UX UI/` — interface designs and assets