# CLAUDE.md

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

## Project Overview

This is the Salamanda POS/ERP System API - a comprehensive retail and inventory management system built with Laravel Lumen 8.0. It provides RESTful JSON APIs for point-of-sale operations, inventory management, supply chain, financial tracking, and multi-store support.

## Essential Commands

### Development Setup
```bash
composer install                      # Install PHP dependencies
cp .env.example .env                 # Create environment file
php artisan key:generate             # Generate app key
php artisan jwt:secret               # Generate JWT secret
php artisan migrate --seed           # Setup database with sample data
php artisan storage:link             # Create storage symlink
```

### Daily Development
```bash
php artisan serve                    # Start development server (port 8000)
php artisan migrate                  # Run new migrations
php artisan db:seed --class=SpecificSeeder  # Run specific seeder
php artisan cache:clear             # Clear all caches
php artisan config:clear            # Clear config cache
```

### Testing
```bash
./vendor/bin/phpunit                # Run all tests
./vendor/bin/phpunit tests/SpecificTest.php  # Run specific test
./vendor/bin/phpunit --filter testMethodName  # Run specific test method
```

### Email Template Development
```bash
cd maizzle_email
npm install                         # First time setup
npm run dev                         # Development server with hot reload
npm run build                       # Build production emails
```

## Architecture Overview

### Core Structure
- **Framework**: Laravel Lumen (micro-framework optimized for APIs)
- **Pattern**: MVC with Eloquent ORM
- **Authentication**: JWT tokens via tymon/jwt-auth
- **API Format**: RESTful JSON responses

### Key Directories
- `app/Http/Controllers/` - API endpoint controllers
- `app/` - Eloquent models (one per database table)
- `database/migrations/` - Database schema versions
- `routes/api.php` - API route definitions
- `maizzle_email/` - Email template system (separate build process)

### Database Design
The system uses a relational database with these core entity groups:
- **Sales Flow**: Sales → Invoices → Payment Methods
- **Inventory**: Items → Stocks → Warehouses → Transfers
- **Supply Chain**: Suppliers → Supplies → Received Supplies
- **Financial**: Accounts → Deposits/Withdrawals → Payments
- **Multi-tenant**: Stores → Users → Sessions

### Critical Relationships
- Items can have variants, modifiers, and taxes
- Sales contain invoices, which contain items with quantities
- Stocks track inventory per item per warehouse
- Sessions track POS terminal shifts with cash management
- Customers can have credit accounts and purchase on credit

## Common Development Tasks

### Adding a New API Endpoint
1. Create/update controller in `app/Http/Controllers/`
2. Add route in `routes/api.php`
3. Create/update model if needed
4. Add validation rules in controller method
5. Return JSON response using `response()->json()`

### Database Changes
1. Create migration: `php artisan make:migration create_tablename_table`
2. Define schema in the migration file
3. Run: `php artisan migrate`
4. Create model: `php artisan make:model ModelName`
5. Define relationships in the model

### Working with Tickets (POS Transactions)
Tickets are draft sales that can be transferred between POS terminals:
- Create ticket → Add items → Apply discounts/taxes → Convert to sale
- Tickets support modifiers (e.g., pizza toppings) and variants (e.g., sizes)
- Use TicketController for all ticket operations

### Report Generation
Reports use Blade templates with CSS for PDF generation:
- Templates in `resources/views/reports/`
- Use dompdf for PDF conversion
- Include letterhead partial when needed
- Export to Excel using Laravel Excel package

## Testing Approach

- Feature tests for API endpoints
- Unit tests for business logic
- Use database transactions for test isolation
- Mock external services (email, SMS)
- Test data factories in `database/factories/`

## Environment Configuration

Key `.env` variables:
```
DB_CONNECTION=mysql
DB_DATABASE=salamanda_pos
JWT_SECRET=<generate-with-artisan>
MAIL_MAILER=smtp
RECEIPT_PRINTER_IP=<if-using-network-printer>
```

## API Authentication Flow

1. Login via `/api/auth/login` with email/password
2. Receive JWT token in response
3. Include token in Authorization header: `Bearer <token>`
4. Token expires after 60 minutes by default
5. Refresh via `/api/auth/refresh`

## Performance Considerations

- Use eager loading to prevent N+1 queries: `with(['relation'])`
- Paginate large result sets using `paginate()`
- Cache frequently accessed data (stores, settings)
- Optimize item search with indexed columns
- Use database transactions for multi-table operations