simpleshop_theme/CLAUDE.md

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

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")