# CLAUDE.md

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

## Commands

```bash
# Local development (via artisan)
php artisan serve                     # Start dev server (port 8000)
php artisan migrate                   # Run pending migrations
php artisan migrate:rollback          # Roll back last batch
php artisan db:seed                   # Run seeders
php artisan tinker                    # Interactive REPL

# Docker
docker-compose up -d                  # Start app + MySQL
docker-compose exec app bash          # Shell into app container

# Testing (PHPUnit)
php artisan test                      # Run all tests
php artisan test --filter=TestName    # Run a single test
./vendor/bin/phpunit tests/Unit/ExampleTest.php  # Run a specific file

# Dependencies
composer install                      # Install PHP dependencies
composer require vendor/package       # Add a package
```

## Architecture

This is a **Laravel 8 RESTful API** for a multi-tenant POS/e-commerce platform. All API consumers authenticate via **Laravel Sanctum** tokens.

### Route Organization

Routes are modularized by domain in [`app/Providers/RouteServiceProvider.php`](app/Providers/RouteServiceProvider.php). Each domain has its own route file under `routes/`:

| Prefix | Domain |
|--------|--------|
| `/api/` | Auth (login, register) |
| `/api/business/` | Multi-tenant business management |
| `/api/product/`, `/api/category/` | Product catalog |
| `/api/order/`, `/api/item_order/` | Order lifecycle |
| `/api/shopify/`, `/api/woo/` | E-commerce platform sync |
| `/api/forza/`, `/api/caex/`, `/api/reach/` | Shipping/logistics providers |
| `/api/webhooks/` | Inbound webhook receivers |
| `/api/twilio/` | SMS notifications |
| `/api/report/`, `/api/logs/` | Reporting & audit |

### Key Layers

- **Controllers** (`app/Http/Controllers/`) — thin controllers that delegate to services or use Eloquent directly. No business logic in controllers beyond HTTP input/output handling.
- **Models** (`app/Models/`) — 40 Eloquent models. Multi-tenancy is enforced via `business_id` scoping on most models.
- **Services** (`app/services/`) — `ShopifyService` and `WebhookService` encapsulate integration logic.
- **Adapters** (`app/Apps/Adapters/`) — normalizes third-party API responses into internal structures.
- **Middleware** (`app/Http/Middleware/`) — 17 middleware classes; authentication is handled via Sanctum's `auth:sanctum` guard.

### External Integrations

| Integration | Purpose | Key Classes |
|------------|---------|-------------|
| Shopify | Store sync & webhooks | `ShopifyController`, `ShopifyService` |
| WooCommerce | Store sync | `WooCommerceController`, `automattic/woocommerce` package |
| Twilio | SMS notifications | `TwilioController`, `twilio/sdk` |
| Pusher | Real-time events | Configured in `config/broadcasting.php` |
| Forza / CAEX / Reach | Shipping/logistics | Dedicated controllers + webhook receivers |

### Database

MySQL via Eloquent ORM. Migrations are in `database/migrations/`. Models use soft deletes (`SoftDeletes` trait) for safe deletion. Relationships follow Laravel conventions (e.g., `Order` hasMany `Order_item`).

### Docker

`docker-compose.yml` defines two services: `app` (PHP 8.2-Apache on port 8000) and `db` (MySQL 5.7). The `.env` file configures DB credentials for local development.