mivita/CLAUDE.md

# CLAUDE.md

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

## Project Overview

This is a Laravel 11 business e-commerce application called "mivita.care" that handles multi-level marketing structures, product sales, payments, and DHL shipping integration. The application supports multi-tenancy through domain resolution and includes comprehensive business analytics and commission calculations.

## Development Commands

### Core Laravel Commands
```bash
# Run development server
php artisan serve

# Run scheduled tasks
php artisan schedule:run

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

# Generate IDE helper files
php artisan ide-helper:generate
php artisan ide-helper:models
php artisan ide-helper:meta

# Database migrations
php artisan migrate
php artisan migrate:rollback
```

### Testing
```bash
# Run tests using Pest
./vendor/bin/pest

# Run specific test
./vendor/bin/pest --filter=TestName
```

### Code Quality
```bash
# Format code using Laravel Pint
./vendor/bin/pint
composer run format
```

### Asset Compilation
```bash
# Install node dependencies
npm install

# Development build
npm run dev
npm run watch

# Production build
npm run production

# Asset postinstall (rebuilds node-sass)
npm run postinstall
```

### Business-Specific Commands
```bash
# Business structure calculations (optimized version - recommended)
php artisan business:store-optimized {month} {year}
php artisan business:store-optimized {month} {year} --clear

# Legacy business structure command
php artisan business:store {month} {year}

# Clear business data
php artisan business:clear-data {month} {year}
php artisan business:clear-data {month} {year} --force

# User management
php artisan user:cleanup
php artisan user:make_abo_order

# Payment processing
php artisan payments:check-accounts

# Level reports (new feature)
php artisan business:level-reports {month} {year}

# Test account management
php artisan business:test-account
```

## Architecture Overview

### Multi-Level Marketing Structure
- **TreeCalcBot/TreeCalcBotOptimized**: Core business logic for calculating commission structures and multi-level hierarchies
- **BusinessPlan Services**: Handle commission calculations, sales volumes, and business structure management
- **BusinessController/BusinessControllerOptimized**: Handle business administration and analytics

### Domain Architecture
- **Multi-tenant setup** using domain resolution
- **DomainService**: Manages domain-specific configurations and routing
- **DomainResolver Middleware**: Routes requests based on domain

### Key Service Classes
- **Payment Services**: Handle various payment methods (Payone, credit systems, invoices)
- **DHL Integration**: Complete shipping solution with label generation and tracking
- **Shopping Cart Systems**: Multiple cart implementations (AboOrderCart, HomepartyCart, ShopApiOrderCart)
- **User Management**: Comprehensive user hierarchy and team management

### Database Structure
- Business users with hierarchical relationships
- Product catalog with categories and ingredients
- Order and payment tracking
- Commission and sales volume calculations
- Multi-domain configurations

### Custom Packages
- **Gloudemans\Shoppingcart**: Custom shopping cart implementation
- **Acme\Dhl**: DHL shipping integration package
- **Alban\LaravelCollectiveSpatieHtmlParser**: HTML parsing utilities

## Scheduled Tasks (Cron Jobs)
The application runs several daily scheduled tasks (defined in `app/Console/Kernel.php`):
- `02:00` - Payment account checks (`payments:check-accounts`)
- `03:00` - Business structure optimization (`store-optimized 0 0`)
- `03:30` - User cleanup (`user:cleanup`)
- `04:00` - Automated subscription orders (`user:make_abo_order`)

## Important File Locations
- **Business Commands**: `app/Console/Commands/Business*.php`
- **Service Classes**: `app/Services/` (extensive service layer)
- **Controllers**: `app/Http/Controllers/` (40+ controllers)
- **Custom Packages**: `packages/` directory
- **Dev Documentation**: `dev/code/Services/*.md` (contains optimization guides)

## Development Notes

### Business Optimization Features
- Use `TreeCalcBotOptimized` for all new business calculation features
- Memory monitoring and automatic garbage collection built into optimized commands  
- Comprehensive error handling with graceful degradation
- Performance logging and monitoring capabilities

### DHL Shipping Integration
- Full DHL API integration with both Developer API and Business Customer API support
- Automatic label generation and tracking
- Sandbox/production mode switching
- Complete shipping workflow integration

### Multi-Domain Support
- Each domain can have different configurations
- Domain-specific routing and middleware
- Subdomain management through console commands

### Asset Management
- Laravel Mix for asset compilation  
- Appwork theme integration with Bootstrap 4
- Vendor assets management with SASS compilation
- Custom node-sass rebuild process for compatibility

## Docker Development Environment
The project uses Laravel Sail with Docker Compose:
```bash
# Start services
docker-compose up -d

# Execute artisan commands in container
./vendor/bin/sail artisan [command]

# Access container shell
./vendor/bin/sail shell
```

### Services:
- **laravel.test**: Main application (Traefik-enabled with SSL)
- **horizon**: Laravel Horizon queue worker
- **mysql**: MySQL 8.0 database server
- **redis**: Redis cache/session store  
- **mailpit**: Email testing interface (accessible at mivita-mail.test)

### Domain Configuration:
- Main domain: `mivita.test`
- Wildcard subdomain support: `*.mivita.test`
- Mail interface: `mivita-mail.test`
- Uses Traefik reverse proxy with SSL