ff1bc483b9
Stripe-hosted Checkout integration with full order lifecycle: - stripity_stripe ~> 3.2 with sandbox/prod config via env vars - Order and OrderItem schemas with price snapshots at purchase time - CheckoutController creates pending order then redirects to Stripe - StripeWebhookController verifies signatures and confirms payment - Success page with real-time PubSub updates from webhook - Shop flash messages for checkout error feedback - Cart cleared after successful payment Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
203 lines
6.4 KiB
Markdown
203 lines
6.4 KiB
Markdown
# 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
|