# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is **Mi Gatito Regalón**, a customized e-commerce store built on top of [Bagisto](https://bagisto.com) — a Laravel 10 + Vue.js open-source e-commerce framework. The store uses Bagisto's default theme with UI customizations primarily in the Shop package.

### Business context

The store sells **personalized gifts** (not flowers): personalized breakfasts and gift packages where the key differentiator is custom photography printed or attached to the gift. The two biggest sales campaigns — with significant traffic spikes — are **Valentine's Day** and **Mother's Day**. Avoid deploying risky changes close to those dates.

Primary customer archetype: **women aged 25–40** with a partner (boyfriend/husband). Secondary: men buying for their partner or mother. The storefront tone should be warm and emotional, and UX decisions should favor simplicity for non-technical users.

---

## Commands

### PHP / Laravel

```bash
php artisan serve                        # Start development server
php artisan migrate                      # Run migrations
php artisan cache:clear && php artisan config:clear && php artisan view:clear
php artisan bagisto:install              # Full installation (runs migrations + seeders)
```

### Frontend — Shop theme (storefront)

```bash
cd packages/Webkul/Shop
npm install
npm run dev      # Watch mode (hot: public/shop-default-vite.hot)
npm run build    # Build to public/themes/shop/default/build/
```

### Frontend — Admin theme

```bash
cd packages/Webkul/Admin
npm install
npm run dev      # Watch mode (hot: public/admin-default-vite.hot)
npm run build    # Build to public/themes/admin/default/build/
```

### Linting

```bash
./vendor/bin/pint              # Fix all files (Laravel preset)
./vendor/bin/pint --test       # Check only, no write
```

### Tests

```bash
php artisan test                                              # All suites
php artisan test --testsuite="Shop Feature Test"             # Shop only
php artisan test --testsuite="Admin Feature Test"            # Admin only
php artisan test --testsuite="Core Unit Test"                # Core only
php artisan test --testsuite="DataGrid Unit Test"            # DataGrid only
php artisan test --filter=SomeTestClass                      # Single test class
```

Tests live under `packages/Webkul/{Package}/tests/`. The framework uses **Pest** (on top of PHPUnit).

---

## Architecture

### Module system

All business logic lives in `packages/Webkul/` as self-contained modules. Modules are registered via **Konekt Concord** in `config/concord.php`. Each module exposes its own `ModuleServiceProvider` which bootstraps routes, views, migrations, and translations. The load order is defined in that config file.

Key packages:
| Package | Role |
|---|---|
| `Core` | Global helpers, channels, currencies, locales, ElasticSearch facade |
| `Theme` | Theme resolution, `@bagistoVite` Blade directive, `ThemeViewFinder` |
| `Shop` | Storefront controllers, Blade views, Vue components, routes |
| `Admin` | Back-office controllers, Blade views, Vue components, routes |
| `Product` | Product types (Simple, Configurable, Bundle, Grouped, Downloadable, Virtual), repositories, models |
| `DataGrid` | Abstract `DataGrid` class used by both Admin and Shop for table listings |
| `MagicAI` | AI content generation via OpenAI or Ollama |
| `DataTransfer` | Import/export (CSV samples in `storage/app/public/data-transfer/samples/`) |

### Theme / asset pipeline

The `Theme` package intercepts Laravel's view finder (`ThemeViewFinder`) so views are resolved from the active theme path before falling back to the package views. This means you can override any package view by placing a file at the equivalent path under `resources/themes/` without touching the package itself.

Assets are compiled per-theme with separate Vite configs:
- Shop: `packages/Webkul/Shop/vite.config.js` → outputs to `public/themes/shop/default/build/`
- Admin: `packages/Webkul/Admin/vite.config.js` → outputs to `public/themes/admin/default/build/`

The root `vite.config.js` is for the core app (`resources/css/app.css`, `resources/js/app.js`) and is not used for theme assets.

### Blade component namespacing

Shop anonymous components are registered under the `shop::` namespace:

```blade
<x-shop::layouts />
<x-shop::media.images.lazy />
<x-shop::carousel />   {{-- packages/Webkul/Shop/src/Resources/views/components/carousel/index.blade.php --}}
```

### Repository pattern

All DB access goes through repositories (in `src/Repositories/`) that extend the `prettus/l5-repository` base. Controllers and services inject repositories, not models directly.

### Custom storefront CSS

Store-specific styles live in `packages/Webkul/Shop/src/Resources/assets/css/custom.css`. This file is compiled as a separate Vite entry point (`custom.css`) alongside `app.css`. The brand color is `rgb(255 152 0)` (orange). Responsive breakpoints used: 525 / 700 / 1022 / 1024 / 1180 / 1220 / 1240 / 1440 / 1520 / 1700px.

### Carousel component

The home-page image slider is a Vue component rendered via `<v-carousel>` inside `packages/Webkul/Shop/src/Resources/views/components/carousel/index.blade.php`. It drives slide height via a reactive `sliderHeight` / `sliderHeightImage` computed from the viewport and uses `will-change-transform` + `transition-transform` for smooth animation.

---

## Pint rules

The project uses the `laravel` Pint preset with one override (`pint.json`): `=>` operators are **aligned** (not single-space).