# SimpleShop

A beautiful, customisable e-commerce storefront built with Phoenix LiveView. Designed for print-on-demand sellers who want professional shops without design expertise.

## Features

### The Shop
A complete storefront with all the pages you need:
- **Home** - Hero banner, category navigation, featured products, testimonials
- **Products** - Grid layout with hover effects and filtering
- **Product Detail** - Image gallery, variants, reviews, related products
- **Cart** - Full shopping cart with order summary
- **Checkout** - Stripe-hosted checkout with order confirmation
- **About** - Rich content with your brand story
- **Contact** - Contact form with business details
- **Error pages** - Themed 404/500 pages

### Theme Editor (`/admin/theme`)
Customise your shop's look without touching code:
- **8 curated presets** - Gallery, Studio, Boutique, Bold, Playful, Minimal, Night, Classic
- **Real-time preview** - See changes instantly across all page types
- **Comprehensive customisation**:
  - Mood (Neutral, Warm, Cool, Dark)
  - Typography (Clean, Editorial, Modern, Classic, Friendly, Minimal)
  - Shape (Sharp, Soft, Round, Pill)
  - Density (Compact, Balanced, Spacious)
  - Accent colours with automatic contrast
  - Layout options (grid columns, header style, width)
  - Feature toggles (announcement bar, sticky header, etc.)
- **Logo upload** with optional SVG recolouring
- **Header image** with zoom and position controls

### Technical Highlights
- CSS custom properties for instant theme switching
- Three-layer CSS architecture (primitives → attributes → semantic)
- ETS-based CSS caching for performance
- SQLite database with BLOB storage for images
- Shared PageTemplates between preview and live shop

## Getting Started

### Prerequisites
- Elixir 1.17+
- Erlang 27+
- Node.js 20+ (for assets)

### Setup

```bash
# Clone the repository
git clone <repo-url>
cd simpleshop_theme

# Install dependencies
mix setup

# Start the server
mix phx.server
```

Visit:
- **Shop**: http://localhost:4000
- **Theme Editor**: http://localhost:4000/admin/theme

### Running Tests

```bash
mix test
```

## Project Structure

```
lib/
├── simpleshop_theme/           # Core business logic
│   ├── settings.ex             # Theme settings context
│   ├── settings/
│   │   └── theme_settings.ex   # Theme settings schema
│   ├── media.ex                # Image upload handling
│   └── theme/
│       ├── css_generator.ex    # Generates CSS from settings
│       ├── css_cache.ex        # ETS cache for generated CSS
│       ├── presets.ex          # 8 theme presets
│       └── preview_data.ex     # Mock data for previews
│
├── simpleshop_theme_web/       # Web layer
│   ├── components/
│   │   ├── layouts/            # App and shop layouts
│   │   ├── page_templates/     # Shared page templates (*.heex)
│   │   ├── page_templates.ex   # PageTemplates module
│   │   └── shop_components.ex  # Reusable shop UI components
│   ├── live/
│   │   ├── theme_live/         # Theme editor LiveView
│   │   └── shop_live/          # Public shop LiveViews
│   └── controllers/
│       └── error_html.ex       # Themed error pages

assets/css/
├── app.css                     # Main stylesheet
├── theme-layer1-primitives.css # Design tokens
├── theme-layer2-attributes.css # Theme-specific values
└── theme-layer3-semantic.css   # Component styles
```

## Routes

| Path | Description |
|------|-------------|
| `/` | Shop home page |
| `/collections/all` | All products |
| `/collections/:slug` | Category collection (filterable) |
| `/products/:id` | Product detail page |
| `/cart` | Shopping cart |
| `/checkout` | Create Stripe session (POST) |
| `/checkout/success` | Order confirmation |
| `/webhooks/stripe` | Stripe webhook endpoint |
| `/about` | About page |
| `/contact` | Contact page |
| `/admin/theme` | Theme editor (requires auth) |
| `/dev/errors/404` | Preview 404 page (dev only) |
| `/dev/errors/500` | Preview 500 page (dev only) |

## Stripe Checkout

SimpleShop uses [Stripe Checkout](https://stripe.com/docs/payments/checkout) (hosted payment page) for secure payment processing.

### Setup

1. Create a [Stripe account](https://dashboard.stripe.com/register)
2. Get your API keys from the [Stripe Dashboard](https://dashboard.stripe.com/test/apikeys)
3. Set environment variables:

```bash
export STRIPE_SECRET_KEY="sk_test_..."
export STRIPE_WEBHOOK_SECRET="whsec_..."
```

### Local webhook testing

Use the [Stripe CLI](https://stripe.com/docs/stripe-cli) to forward webhooks to your local server:

```bash
stripe listen --forward-to localhost:4000/webhooks/stripe
```

The CLI will print a webhook signing secret — use that as `STRIPE_WEBHOOK_SECRET`.

### Test cards

| Number | Result |
|--------|--------|
| `4242 4242 4242 4242` | Successful payment |
| `4000 0000 0000 0002` | Declined |
| `4000 0025 0000 3155` | Requires 3D Secure |

Use any future expiry date and any 3-digit CVC.

## Generating Mockups

The project includes a Printify integration for generating product mockups. This is useful for creating sample product images from Unsplash artwork.

### Prerequisites

1. A Printify account with API access
2. Set the `PRINTIFY_API_TOKEN` environment variable

### Usage

```bash
# Generate all mockups (saves to priv/static/mockups/)
export PRINTIFY_API_TOKEN="your-token"
mix generate_mockups

# Generate mockups and delete products from Printify afterwards
mix generate_mockups --cleanup

# Search for available blueprints
mix generate_mockups --search "poster"

# List all blueprints
mix generate_mockups --list-blueprints
```

Product definitions are in `lib/simpleshop_theme/printify/mockup_generator.ex`.

## Documentation

- [ROADMAP.md](ROADMAP.md) - Future features and improvements
- [docs/plans/](docs/plans/) - Feature plans
- [docs/research/](docs/research/) - Design research and guidelines

## Design Philosophy

1. **"One theme, infinite variations"** - Rather than multiple themes, one solid foundation with curated customisation
2. **Constrained creativity** - Limit choices to prevent poor design outcomes
3. **No professional photography required** - Works with product mockups
4. **Mobile-first** - All features work on touch devices
5. **Ethical design** - No dark patterns or fake urgency

## License

AGPL-3.0
