# CLAUDE.md

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

## Project Overview

German-language MLM/direct-sales e-commerce platform for organic/natural products ("Gruene Seele" / Green Soul). Partners/distributors get personal whitelabel shops, earn commissions through a multi-level hierarchy, and manage orders, invoices, and promotions.

**Stack:** PHP 8.4, Laravel 11 (using Laravel 10 directory structure), Bootstrap 4, jQuery, Laravel Mix (webpack), MySQL, Laravel Passport (API auth).

## Common Commands

```bash
# Tests (Pest v2, uses SQLite in-memory)
php artisan test                                    # run all tests
php artisan test tests/Feature/ExampleTest.php      # run single file
php artisan test --filter=testName                  # filter by name

# Code formatting (Laravel Pint)
vendor/bin/pint --dirty                             # format changed files only
vendor/bin/pint                                     # format all files
composer format                                     # alias for pint

# Frontend (Laravel Mix, NOT Vite)
npm run dev                                         # development build
npm run prod                                        # production build
npm run watch                                       # watch mode

# Artisan - always pass --no-interaction
php artisan make:model Name --no-interaction
php artisan make:test --pest Name --no-interaction
```

## Architecture

### Multi-Domain Routing (`routes/web.php`)
Three separate domain groups, each with distinct middleware:
- **Main domain** (`config('app.domain')`) - admin panel + user dashboard
- **Promo domain** (`config('app.promo_domain')`) - public promotion/microsite pages
- **Shop domain** (`config('app.shop_domain')`) - public whitelabel shop

### Admin Access Levels (middleware in `app/Http/Middleware/`)
- `CopyReader` - admin >= 1 (product/content management)
- `Admin` - admin >= 7 (sales, customers, promotions)
- `SuperAdmin` - admin >= 8 (users, shipping, settings)
- `SysAdmin` - admin >= 9 (system tools, imports)

### Key Service Layer
- **`app/Services/Yard.php`** + `app/Services/Yard/` - Custom shopping cart (extends forked Gloudemans Cart in `packages/digital-bird/shoppingcart/`). Handles shipping, tax, margins, commissions.
- **`app/Services/Invoice.php`** - Invoice and cancellation invoice PDF generation (uses DomPDF)
- **`app/Services/PaymentReminderService.php`** - Payment reminder logic with status progression
- **`app/Services/Credit.php`** - User credit/balance management
- **`app/Services/Stats/`** - Sales statistics

### Repository Pattern
Business logic uses repositories in `app/Repositories/` (e.g., `CheckoutRepository`, `InvoiceRepository`, `CustomerRepository`). Controllers delegate to repositories and services.

### Local Packages
`packages/digital-bird/shoppingcart/` - Forked `gloudemans/shoppingcart`, autoloaded via composer PSR-4 as `Gloudemans\Shoppingcart\`.

### Cron Jobs (`app/Console/Kernel.php`)
- `payments:accounts` - Checks user account expiry, sends reminders (statuses 31/33/34/35), deactivates expired accounts
- `payments:reminders` - Sends payment reminders for open invoices

### API (`routes/api.php`)
No versioning. Passport-authenticated endpoints for WordPress integration (`/api/wp/*`) and auth (`/api/auth/*`).

### Global Helpers
`app/helpers.php` (autoloaded) - URL helpers, formatting delegates to `App\Services\Util`.

### PDF Generation
- `app/Libraries/InvoicePDF.php`, `ContractPDF.php` - FPDF/FPDI based
- `app/Services/Invoice.php` - DomPDF based (Blade templates in `resources/views/pdf/`)

## Important Conventions

- This project uses **Laravel 10 directory structure** on Laravel 11. Do NOT migrate to Laravel 11 structure.
  - Middleware registration: `app/Http/Kernel.php`
  - Exception handling: `app/Exceptions/Handler.php`
  - Schedule: `app/Console/Kernel.php`
- Default auth guard is `user` (not `web`), configured in `config/auth.php`
- User model is `App\User` (not `App\Models\User`)
- Views are Blade templates with Bootstrap 4 + jQuery DataTables
- Always run `vendor/bin/pint --dirty` before finalizing changes
- Countries supported: DE, FR, CH, NL (with reverse charge VAT handling)