# Biometric Logs Cloud-to-Local Mirror Architecture

## Overview
Mirror biometric logs from cloud API to local server with real-time webhook processing, local database persistence, and fallback polling.

---

## Architecture

### Components

1. **Cloud API** → sends biometric log events
2. **Webhook Receiver** → `/api/webhooks/biometric-logs` endpoint
3. **Job Queue** → Async processing with Laravel Queue
4. **Local Database** → Persistent storage in `biometric_logs` table
5. **Sync Service** → Handles validation, transformation, storage
6. **Dashboard Integration** → View synced logs in Filament

---

## Implementation Strategy

### Phase 1: Database & Models

Create migration and model for local biometric logs storage:

```bash
php artisan make:model BiometricLog -m
php artisan make:migration create_biometric_logs_table
```

### Phase 2: Webhook Endpoint

Create dedicated controller to receive cloud API events:

```bash
php artisan make:controller Api/BiometricLogWebhookController
```

### Phase 3: Queue Job

Create async job to process logs without blocking webhook response:

```bash
php artisan make:job ProcessBiometricLogSync
```

### Phase 4: Sync Service

Create service layer to handle business logic:

```bash
php artisan make:provider BiometricLogServiceProvider
```

### Phase 5: Filament Integration

Create Filament resource to view/manage synced logs:

```bash
php artisan make:filament-resource BiometricLog
```

---

## Data Flow

```
┌─────────────────────┐
│   Cloud API         │
│ (External Service)  │
└──────────┬──────────┘
           │
           │ POST (webhook)
           ↓
┌─────────────────────────────────────┐
│ POST /api/webhooks/biometric-logs   │
│ (WebhookController)                 │
└──────────┬──────────────────────────┘
           │
           │ Validate signature
           │ Queue job
           ↓
┌─────────────────────┐
│  Queue Job          │
│ ProcessBiometricLog │
└──────────┬──────────┘
           │
           │ Transform & Validate
           │ Check for duplicates
           ↓
┌──────────────────────────┐
│ Local Database           │
│ biometric_logs table     │
└──────────┬───────────────┘
           │
           ↓
┌──────────────────────────┐
│ Filament UI Dashboard    │
│ View/Export logs         │
└──────────────────────────┘
```

---

## Security Considerations

1. **Webhook Signature Verification**: Validate HMAC-SHA256 signatures from cloud API
2. **Rate Limiting**: Prevent abuse with middleware throttling
3. **Access Control**: Protect webhook endpoint with API key or IP whitelist
4. **Data Encryption**: Encrypt biometric data at rest (if sensitive)
5. **Idempotency**: Use transaction IDs to prevent duplicate processing

---

## Configuration

Add to `.env`:

```env
BIOMETRIC_CLOUD_API_KEY=your_api_key_here
BIOMETRIC_WEBHOOK_SECRET=your_webhook_secret_here
BIOMETRIC_API_ENDPOINT=https://cloud-api.example.com
BIOMETRIC_SYNC_ENABLED=true
BIOMETRIC_LOG_RETENTION_DAYS=90
```

---

## File Structure

```
app/
├── Models/
│   └── BiometricLog.php
├── Http/
│   └── Controllers/
│       └── Api/
│           └── BiometricLogWebhookController.php
├── Jobs/
│   └── ProcessBiometricLogSync.php
├── Services/
│   └── BiometricLogSyncService.php
├── Filament/
│   └── Resources/
│       └── BiometricLogResource.php
└── Events/
    └── BiometricLogSynced.php

database/
├── migrations/
│   └── YYYY_MM_DD_HHMMSS_create_biometric_logs_table.php
└── seeders/
    └── BiometricLogSeeder.php

routes/
└── api.php (webhook routes)
```

---

## Key Features

✅ Real-time webhook processing  
✅ Async queue handling  
✅ Duplicate prevention  
✅ Error logging & retry logic  
✅ Webhook signature validation  
✅ Local database persistence  
✅ Filament UI integration  
✅ Configurable log retention  
✅ Fallback polling mechanism  
✅ Event dispatching for extensibility  

---

## Next Steps

1. Create migration and model
2. Create webhook controller with signature verification
3. Create queue job with business logic
4. Create sync service
5. Add routes and middleware
6. Create Filament resource
7. Set up monitoring & logging
8. Test with webhook simulator