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

# 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)

4.2 KiB Raw Blame History