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

# 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

# Run tests using Pest
./vendor/bin/pest

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

Code Quality

# Format code using Laravel Pint
./vendor/bin/pint
composer run format

Asset Compilation

# 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

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

# 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