c2df13ff79
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>
82 lines
3.1 KiB
Markdown
82 lines
3.1 KiB
Markdown
# 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")`
|