# Developer Guide

## Table of Contents
1. [Getting Started](#getting-started)
2. [Project Structure](#project-structure)
3. [Key Features](#key-features)
4. [Development Workflow](#development-workflow)
5. [Testing](#testing)
6. [Deployment](#deployment)

## Getting Started

### Prerequisites
- PHP 8.2+
- Composer
- MySQL 8.0+
- Node.js & NPM (for frontend assets)

### Installation

1. Clone the repository
```bash
git clone <repository-url>
cd ecom_lite
```

2. Install dependencies
```bash
composer install
npm install
```

3. Configure environment
```bash
cp .env.example .env
php artisan key:generate
```

4. Update `.env` with your database credentials and API keys

5. Run migrations
```bash
php artisan migrate
```

6. Seed database (optional)
```bash
php artisan db:seed
```

7. Start development server
```bash
php artisan serve
```

## Project Structure

```
app/
├── Console/Commands/      # Artisan commands
├── Exceptions/            # Custom exceptions
├── Http/
│   ├── Controllers/      # Application controllers
│   │   ├── Admin/        # Admin controllers
│   │   └── Api/          # API controllers
│   ├── Middleware/       # Custom middleware
│   └── Requests/         # Form request validation
├── Models/               # Eloquent models
├── Observers/            # Model observers
├── Providers/            # Service providers
├── Repositories/         # Repository pattern implementations
├── Services/             # Business logic services
└── Helpers/              # Helper functions

database/
├── factories/            # Model factories
├── migrations/           # Database migrations
└── seeders/              # Database seeders

routes/
├── web.php               # Web routes
├── api.php               # API routes
└── console.php           # Scheduled tasks

tests/
├── Unit/                 # Unit tests
└── Feature/              # Feature tests
```

## Key Features

### Stock Reservation System
Prevents race conditions during checkout by reserving stock before payment confirmation.

**Usage:**
```php
$inventoryService = app(InventoryService::class);
$token = $inventoryService->reserve($productId, $quantity);
// ... process payment ...
$inventoryService->confirmReservation($token);
```

### Feature Flags
Enable/disable features dynamically.

**Usage:**
```php
if (feature_enabled('new_checkout_flow')) {
    // New checkout logic
}
```

### A/B Testing
Run experiments to test different variations.

**Usage:**
```php
$abTestService = app(AbTestService::class);
$variant = $abTestService->getVariant('checkout_button_test');
$abTestService->trackEvent('checkout_button_test', 'click');
```

### Repository Pattern
Centralized data access layer.

**Usage:**
```php
$productRepository = app(ProductRepositoryInterface::class);
$products = $productRepository->getFeatured(8);
```

## Development Workflow

### Running Tests
```bash
php artisan test
php artisan test --filter=InventoryServiceTest
```

### Code Style
```bash
./vendor/bin/pint
```

### Database Migrations
```bash
php artisan migrate
php artisan migrate:rollback
php artisan migrate:fresh
```

## Testing

### Unit Tests
Located in `tests/Unit/`. Test individual components in isolation.

### Feature Tests
Located in `tests/Feature/`. Test complete user workflows.

### Running Tests
```bash
# All tests
php artisan test

# Specific test
php artisan test --filter=InventoryServiceTest

# With coverage
php artisan test --coverage
```

## Deployment

### Production Checklist
- [ ] Set `APP_ENV=production`
- [ ] Set `APP_DEBUG=false`
- [ ] Run migrations
- [ ] Clear and cache config
- [ ] Optimize autoloader
- [ ] Set up queue workers
- [ ] Configure scheduled tasks (cron)
- [ ] Set up monitoring

### Commands
```bash
php artisan config:cache
php artisan route:cache
php artisan view:cache
composer install --optimize-autoloader --no-dev
```

## Scheduled Tasks

Configure in `routes/console.php`:
- Stock reservation cleanup: Every 5 minutes
- System health monitoring: Hourly

Add to crontab:
```bash
* * * * * cd /path-to-project && php artisan schedule:run >> /dev/null 2>&1
```