# CLAUDE.md

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

## Project Overview

EAR (Editura Academiei Romane) is a Laravel 11-based e-commerce platform for a Romanian publishing house. The application handles product catalogs, orders, customer management, and integrates with payment providers and shipping services.

**Key Technologies:**
- **Backend:** PHP 8.3, Laravel 11.9, Livewire 3.0
- **Frontend:** AlpineJS, TailwindCSS 3.4, jQuery, Laravel Mix 6
- **Database:** MariaDB
- **Third-party integrations:** FanCourier (shipping), Netopia (payments), Stripe

## Development Commands

### Backend (PHP/Laravel)

```bash
# Install PHP dependencies
composer install

# Run database migrations
php artisan migrate

# Refresh migrations (WARNING: drops all tables)
php artisan migrate:refresh

# Seed database
php artisan db:seed

# Generate application key
php artisan key:generate

# Clear caches
php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear

# Run development server
php artisan serve
# Access at https://ear.test or http://localhost:8000

# Run tests (using PHPUnit)
vendor/bin/phpunit
# Or via artisan
php artisan test

# Run specific test suite
vendor/bin/phpunit --testsuite=Feature
vendor/bin/phpunit --testsuite=Unit

# Code formatting (Laravel Pint)
./vendor/bin/pint

# Debug tools
php artisan telescope:install  # Laravel Telescope (already included)
```

### Frontend (JavaScript/CSS)

```bash
# Install JavaScript dependencies
npm install

# Development build (watch mode)
npm run dev
# Or
npm run watch

# Production build
npm run build
# Or
npm run production

# Build with image optimization
npm run optimize

# Hot reload development (with BrowserSync)
npm run hot
```

## Architecture Overview

### Route Organization

The application uses **multi-guard authentication** with separate route files:

- **`routes/web.php`** - Public frontend routes (product listings, cart, checkout)
- **`routes/admin.php`** - Admin panel routes (protected by `auth:admin` middleware)
- **`routes/customer.php`** - Customer dashboard routes (order history, wishlist, profile)
- **`routes/api.php`** - API endpoints
- **`routes/console.php`** - Artisan console commands

### Authentication Guards

Three separate authentication systems:
- **`web`** - Default user authentication
- **`admin`** - Admin panel authentication (separate login at `env('APP_ADMIN_URL')`)
- **`customer`** - Customer portal authentication

Corresponding models: `User`, `AdminLogin`, `CustomerLogin`

### Application Layers

**Controllers (`app/Http/Controllers/`):**
- `Frontend/` - Public-facing controllers (product catalog, cart, checkout, news, events)
- `Backend/` - Admin panel controllers (products, orders, customers, settings)
- `Customer/` - Customer dashboard controllers (wishlist, orders, profile)
- `Auth/` - Authentication controllers

**Livewire Components (`app/Livewire/`):**
Primary UI interaction layer using Livewire 3.0 for reactive components:
- Search components (product search, category search, domain search)
- Checkout flow (`Checkout.php`)
- Admin components (`AdminProduct.php`, `AdminPeriodicProduct.php`)
- Dynamic forms (`AddressForm.php`, `SelectAddress.php`)

**Services (`app/Services/`):**
Business logic layer:
- `ProductService.php` - Product operations and catalog management
- `FanCourierService.php` - Shipping integration
- `CacheService.php` - Cache management
- `EloquentOptimizationService.php` - Database query optimization
- `Monitoring/` - Application monitoring services

**Repositories (`app/Repositories/`):**
Data access layer using Repository pattern:
- `Eloquent/BaseRepository.php` - Base repository with common CRUD operations
- `Eloquent/ProductRepository.php` - Product-specific data access
- `Eloquent/OrderRepository.php` - Order data access
- `Eloquent/UserRepository.php` - User data access
- `Interfaces/` - Repository contracts

**Models (`app/Models/`):**
Key domain models:
- E-commerce: `Product`, `Category`, `Brand`, `Order`, `OrderItem`, `Transaction`, `Coupon`
- Customer data: `Customer`, `BillingProfile`, `Wishlist`
- Content: `News`, `Event`, `Announcement`, `Slider`, `Page`
- Catalog organization: `Domain` (product domains), `Attribute`, `AttributeValue`

### Key Features

**Multi-language Support:**
Uses Spatie's laravel-translatable package. Many models have translatable fields (check model `$translatable` property).

**Product Types:**
- Regular products (books, publications)
- Periodic publications (journals, magazines) - handled separately with `PeriodicProduct` model

**Asset Pipeline:**
- Laravel Mix compiles: `resources/js/app.js`, `resources/css/app.css` (Tailwind), SCSS files
- Production builds use versioning for cache busting
- BrowserSync configured for local development (proxy on `localhost:8000`)
- Vendor assets (TinyMCE) copied to `public/assets/vendor/`

**Helper Functions:**
Custom helpers available globally via `app/Helpers/helpers.php` (autoloaded in composer.json)

## Environment Configuration

Copy `.env.example` to `.env` and configure:

**Required variables:**
- `APP_KEY` - Generate with `php artisan key:generate`
- `APP_ADMIN_URL` - Custom admin panel URL path (security through obscurity)
- `DB_*` - Database credentials
- `SHOP_COMPANY_EMAIL`, `SHOP_COMPANY_NAME` - Shop information
- Payment gateways (Netopia, Stripe credentials)
- FanCourier API credentials for shipping

**Multiple environments:**
- `.env.example` - Template
- `.env.staging` - Staging configuration
- `.env.main` - Production configuration

## Docker Deployment

Docker setup available for staging/production:

```bash
# Automated deployment
./deploy-staging.sh

# Manual deployment
docker-compose up -d
docker-compose exec app php artisan migrate
docker-compose exec app php artisan key:generate
```

See `DOCKER_README.md` for detailed Docker deployment instructions.

## Testing

Test structure (PHPUnit):
- `tests/Feature/` - Feature tests
- `tests/Unit/` - Unit tests

Test database: SQLite in-memory (configured in `phpunit.xml`)

## Important Patterns

**Permission System:**
Uses Spatie Laravel Permission package for role-based access control. Check user permissions in admin controllers.

**File Uploads:**
Uses Intervention Image (v3.7) and Spatie Image Optimizer for image processing.

**Auditing:**
Laravel Auditing package tracks model changes (check models with `Auditable` trait).

**Excel Import/Export:**
Maatwebsite Excel package for data import/export operations (see `app/Exports/`, `app/Imports/`).

**Queue System:**
Queue driver: database (check `.env` `QUEUE_CONNECTION=database`)
Jobs in `app/Jobs/`

## Code Organization Tips

- **DTOs:** `app/DTOs/` contains Data Transfer Objects for structured data passing
- **Actions:** `app/Actions/` for single-responsibility action classes
- **Policies:** `app/Policies/` for authorization logic
- **Events/Listeners:** `app/Events/` and `app/Listeners/` for event-driven features
- **Custom Rules:** `app/Rules/` for validation rules
- **View Composers:** `app/View/` for sharing data with views

## Development Tools

**Laravel Telescope:** Enabled in development for debugging (access at `/telescope`)
**Laravel Debugbar:** Available in dev environment (via barryvdh/laravel-debugbar)
**Laravel Dusk:** Browser testing support

## Frontend Asset Locations

- `resources/css/frontend/` - Frontend SCSS
- `resources/css/admin/` - Admin panel SCSS
- `resources/css/shared/` - Shared styles
- `resources/js/` - JavaScript files
- `resources/views/` - Blade templates
- `public/assets/` - Compiled assets (gitignored, built by Mix)