# Face Verification Proxy Implementation

## Architecture

```
Client → Laravel API → Python Face Engine
         (API Key)     (Internal Key)
```

## Components

### 1. Controller
**File:** `app/Http/Controllers/Api/Face/VerifyController.php`
- Validates request payload
- Delegates to FaceEngineService
- Returns response to client

### 2. Service
**File:** `app/Services/FaceEngineService.php`
- Handles HTTP communication with Python engine
- Manages internal authentication
- Handles connection errors

### 3. Route
**File:** `routes/api.php`
```php
Route::prefix('face')->middleware('api.key')->group(function () {
    Route::post('verify', VerifyController::class);
});
```

## Request Flow

1. **Client Request**
   ```bash
   POST /api/face/verify
   Headers: X-API-KEY: face_xxx
   Body: {"reference_id": "user_123", "image": "base64..."}
   ```

2. **Middleware Validation**
   - Validates client API key
   - Checks client is active
   - Rejects if invalid (401)

3. **Controller Validation**
   - Validates `reference_id` (required, string)
   - Validates `image` (required, string)
   - Rejects if invalid (422)

4. **Service Proxy**
   ```php
   POST {FACE_ENGINE_URL}/face/verify
   Headers: X-API-KEY: {FACE_ENGINE_API_KEY}
   Body: {"reference_id": "user_123", "image": "base64..."}
   ```

5. **Response Forwarding**
   - Returns Python response unchanged
   - Preserves status code
   - Preserves JSON body

## Error Handling

### 401 Unauthorized (Middleware)
```json
{
  "error": "API key required"
}
```

### 422 Validation Error (Controller)
```json
{
  "message": "The image field is required.",
  "errors": {
    "image": ["The image field is required."]
  }
}
```

### 503 Service Unavailable (Service)
```json
{
  "error": "Face engine unavailable"
}
```

### Python Errors (Forwarded)
Status and body forwarded as-is from Python service.

## Configuration

**Environment Variables:**
```env
FACE_ENGINE_URL=http://127.0.0.1:8000
FACE_ENGINE_API_KEY=your_internal_key
```

**Config File:** `config/services.php`
```php
'face' => [
    'url' => env('FACE_ENGINE_URL', 'http://127.0.0.1:8000'),
    'key' => env('FACE_ENGINE_API_KEY'),
],
```

## Security

✅ **Protected:**
- Client API key validated by middleware
- Internal key never exposed to clients
- Face images not logged or stored

❌ **Never:**
- Log face image data
- Store face images in Laravel
- Expose `FACE_ENGINE_API_KEY` to clients

## Testing

```bash
# 1. Create client
curl -X POST http://localhost:8000/api/admin/clients \
  -H "Content-Type: application/json" \
  -d '{"name":"Test Client"}'

# 2. Verify face
curl -X POST http://localhost:8000/api/face/verify \
  -H "X-API-KEY: face_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_id": "user_123",
    "image": "base64_encoded_image"
  }'
```

## Code Quality

- ✅ Service-based architecture
- ✅ Dependency injection
- ✅ Clean separation of concerns
- ✅ Proper error handling
- ✅ No business logic in controller
- ✅ Production-ready