From c2df13ff7909ebcfe4bc73ac5d4532826c67633e Mon Sep 17 00:00:00 2001
From: jamey <jamey@server.jamey.stream>
Date: Sat, 31 Jan 2026 09:58:36 +0000
Subject: [PATCH] docs: add CLAUDE.md for Claude Code guidance

Provides essential commands, architecture overview, and coding guidelines
for AI assistants working in this codebase.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 CLAUDE.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..604daa9
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,81 @@
+# 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")`