# CLAUDE.md

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

## Project Overview

SimpleShop is a customisable e-commerce storefront for print-on-demand sellers, built with Phoenix 1.8 + LiveView 1.1 on Elixir/Erlang. Uses SQLite with BLOB storage for images. Licensed under AGPL-3.0.

## Common Commands

```bash
mix setup              # Install deps, create DB, run migrations, build assets
mix phx.server         # Start dev server at localhost:4000
mix test               # Run all tests
mix test path/to.exs   # Run specific test file
mix test --failed      # Re-run failed tests
mix precommit          # REQUIRED before committing: compile --warning-as-errors, format, test
```

## Architecture

### Core Contexts (lib/simpleshop_theme/)

- **Settings** - Theme configuration persistence as JSON
- **Theme** - CSS generation, ETS caching, 8 presets (Gallery, Studio, Boutique, etc.)
- **Products** - Product/variant data synced from Printify
- **Media/Images** - Image uploads and optimization pipeline (Oban jobs)
- **Providers** - Abstraction layer for POD providers (Printify integration)

### Web Layer (lib/simpleshop_theme_web/)

- **live/** - LiveViews for shop pages and theme editor
- **components/page_templates/** - Shared templates between preview and live shop
- **components/shop_components.ex** - Reusable shop UI components

### Three-Layer CSS Architecture

1. **Primitives** (layer1) - Design tokens as CSS custom properties
2. **Attributes** (layer2) - Theme-specific design rules
3. **Semantic** (layer3) - Component styles

Theme switching is instant via CSS custom property injection (no reload).

### Key Routes

| Path | Purpose |
|------|---------|
| `/` | Shop home |
| `/collections/:slug` | Product collection (filtering) |
| `/products/:id` | Product detail |
| `/admin/theme` | Theme editor (auth required) |

## Phoenix 1.8 Guidelines

- **Always** wrap LiveView templates with `<Layouts.app flash={@flash} ...>`
- Use `@current_scope.user` in templates, never `@current_user`
- Use `to_form/2` for all form handling, access via `@form[:field]`
- Use `<.input>` component from core_components.ex
- Use `<.icon name="hero-x-mark">` for icons, not Heroicons modules
- Place routes in correct `live_session` scope (`:current_user` or `:require_authenticated_user`)

## Elixir/Ecto Guidelines

- Use `:req` library for HTTP requests (not httpoison, tesla, httpc)
- Use streams for collections: `stream(socket, :items, items)`
- Lists don't support index access (`list[i]`), use `Enum.at/2`
- Access changeset fields with `Ecto.Changeset.get_field/2`, not `changeset[:field]`
- Preload associations in queries when needed in templates

## HEEx Template Guidelines

- Use `{...}` for interpolation in attributes, `<%= %>` for block constructs in bodies
- Class lists require bracket syntax: `class={["base", @cond && "extra"]}`
- Use `<%!-- comment --%>` for template comments
- Never use `else if` or `elsif` - use `cond` or `case`

## LiveView Testing

- Use `element/2`, `has_element/2` - never test raw HTML
- Reference DOM IDs from templates in tests
- Debug with LazyHTML: `LazyHTML.filter(document, "selector")`