# Local Sync Agent - Setup & Deployment Guide

## Overview

The **Local Sync Agent** is a Python application that runs on a machine with access to your local biometric devices. It periodically fetches user data from the cloud ADMS and syncs it to all local devices on your network.

This solves the firewall/remote device problem by:
- ✅ Running on a local machine with direct LAN access to devices
- ✅ Pulling data from cloud ADMS via HTTPS (outbound only, no firewall issues)
- ✅ Syncing to devices via HTTP/UDP on local network (no firewall blocking)
- ✅ Running continuously in background with automatic retries
- ✅ Reporting sync status back to cloud

---

## Architecture

```
┌─────────────────────────────────┐
│   CLOUD ADMS (DigitalOcean)    │
│   - User Database               │
│   - REST API (/api/sync/...)   │
└──────────────┬──────────────────┘
               │
               │ HTTPS (Outbound)
               │ Fetches users every 10 min
               │
┌──────────────▼──────────────────┐
│  LOCAL SYNC AGENT               │
│  (Runs on local PC/server)       │
│  - Fetches users from cloud      │
│  - Discovers local devices       │
│  - Syncs users to devices        │
│  - Reports status back           │
└──────────────┬──────────────────┘
               │
               │ HTTP (Local LAN)
               │ Port 4370 or 80
               │
       ┌───────┼───────┐
       │       │       │
   ┌───▼──┐ ┌─▼───┐ ┌─▼───┐
   │Dev 1 │ │Dev 2│ │Dev 3│
   └──────┘ └─────┘ └─────┘
```

---

## Prerequisites

### On Cloud Server (ADMS)
- Laravel app running with new API endpoints (already installed)
- API routes in `/routes/api.php` (already configured)

### On Local Machine (Where Sync Agent Runs)
- Python 3.8 or higher
- Network access to:
  - Cloud ADMS via HTTPS (for pulling users)
  - Local devices via HTTP/UDP (for syncing users)
- Can be any machine on the network (Windows, Mac, Linux)

### On Devices
- Connected to same network as sync agent
- HTTP server running (usually on port 80 or 4370)
- User database (will be synced)

---

## Installation

### Step 1: Install Python Dependencies

```bash
cd /var/www/html/adms/adms-server

# Create virtual environment (optional but recommended)
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
```

### Step 2: Create Configuration File

```bash
# Generate config template
python3 sync_agent.py --create-config

# This creates: sync_agent_config.json
```

### Step 3: Edit Configuration

```bash
nano sync_agent_config.json  # or use your editor
```

**Configuration template:**
```json
{
  "cloud_url": "https://your-adms.cloud.com",
  "sync_interval_minutes": 10,
  "device_timeout_seconds": 30,
  "max_retries": 3,
  "devices": [
    "192.168.1.100",
    "192.168.1.101",
    "192.168.1.102"
  ],
  "auto_discover": true,
  "network_prefix": "192.168.1",
  "port": 4370
}
```

**Configuration Options:**
- `cloud_url` - Your ADMS cloud URL (required)
- `sync_interval_minutes` - How often to sync (default: 10)
- `device_timeout_seconds` - Timeout for device connection (default: 30)
- `max_retries` - Retry attempts on failure (default: 3)
- `devices` - List of device IPs (if empty, will auto-discover)
- `auto_discover` - Enable auto-discovery (default: true)
- `network_prefix` - Network range for discovery (e.g., "192.168.1")
- `port` - Device port for sync (default: 4370)

### Step 4: Test Configuration

```bash
# Test sync to specific device
python3 sync_agent.py --device 192.168.1.100

# Expected output:
# 🧪 Testing sync to 192.168.1.100...
# ✅ Success: Successfully synced 50 users
```

---

## Running the Agent

### Option 1: Direct Run (Testing)

```bash
python3 sync_agent.py
```

**Output:**
```
2024-06-01 10:00:00 [INFO] 🚀 Starting sync agent
2024-06-01 10:00:00 [INFO]    Cloud URL: https://your-adms.cloud.com
2024-06-01 10:00:00 [INFO]    Sync interval: 10 minutes
2024-06-01 10:00:00 [INFO]    Device timeout: 30s
2024-06-01 10:00:00 [INFO] 🔄 Running initial sync cycle...
2024-06-01 10:00:01 [INFO] ════════════════════════════════════════════════════════════════════════════════════
2024-06-01 10:00:01 [INFO] 🔄 STARTING SYNC CYCLE
2024-06-01 10:00:01 [INFO] ════════════════════════════════════════════════════════════════════════════════════
2024-06-01 10:00:02 [INFO] 📥 Fetched 50 users from cloud
2024-06-01 10:00:02 [INFO] 📡 Syncing to 3 device(s)
2024-06-01 10:00:02 [INFO] 
2024-06-01 10:00:02 [INFO]    Syncing to 192.168.1.100...
2024-06-01 10:00:03 [INFO]    ✅ Successfully synced 50 users
2024-06-01 10:00:03 [INFO]    📤 Reported sync status to cloud
2024-06-01 10:00:04 [INFO] ✨ SYNC CYCLE COMPLETE
2024-06-01 10:00:04 [INFO]    ✅ Successful: 3
2024-06-01 10:00:04 [INFO]    ❌ Failed: 0
2024-06-01 10:00:04 [INFO]    ⏱️  Duration: 2.5s
2024-06-01 10:00:04 [INFO] ✅ Sync agent running. Press Ctrl+C to stop.
```

### Option 2: Run as Background Service

#### On Linux/Mac (systemd)

**Create service file:**
```bash
sudo nano /etc/systemd/system/adms-sync-agent.service
```

**Add this content:**
```ini
[Unit]
Description=ADMS Local Sync Agent
After=network.target
Wants=network-online.target

[Service]
Type=simple
User=sync_user
WorkingDirectory=/home/sync_user/adms-sync-agent
ExecStart=/usr/bin/python3 /home/sync_user/adms-sync-agent/sync_agent.py
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
```

**Install and start:**
```bash
sudo systemctl daemon-reload
sudo systemctl enable adms-sync-agent
sudo systemctl start adms-sync-agent

# Check status
sudo systemctl status adms-sync-agent

# View logs
sudo journalctl -u adms-sync-agent -f
```

#### On Windows (Task Scheduler)

1. Open Task Scheduler
2. Create Basic Task
3. Name: "ADMS Sync Agent"
4. Trigger: At system startup (or On a schedule - every 10 min)
5. Action:
   - Program: `C:\Python39\python.exe`
   - Arguments: `C:\path\to\sync_agent.py`
   - Start in: `C:\path\to\`
6. Enable "Run with highest privileges"

#### On Windows (Background Script)

```batch
@echo off
REM adms-sync-agent.bat
cd C:\path\to\adms-sync-agent
python sync_agent.py
```

Run at startup:
1. Save as `adms-sync-agent.bat`
2. Create shortcut in `C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Startup`

---

## Monitoring

### Check Logs

```bash
# Real-time logs
tail -f logs/sync_agent_2024-06-01.log

# View last sync
tail -20 logs/sync_agent_2024-06-01.log

# Search for errors
grep ERROR logs/sync_agent_2024-06-01.log
```

### Cloud Dashboard

Go to your ADMS web interface:
1. Navigate to **Device Sync Status** page
2. Check "Last Sync" column for each device
3. Status should show recent timestamp (within sync interval)
4. Progress bar should show 100% synced

### API Endpoint

Check agent health:
```bash
curl https://your-adms.cloud.com/api/sync/health

# Response:
# {
#   "success": true,
#   "status": "healthy",
#   "timestamp": "2024-06-01T10:30:00.000Z"
# }
```

---

## Cloud API Endpoints (Reference)

The sync agent uses these endpoints:

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/api/sync/users` | GET | Fetch all active users |
| `/api/sync/devices` | GET | Fetch all active devices |
| `/api/sync/status` | GET | Get current sync status |
| `/api/sync/report` | POST | Report sync completion |
| `/api/sync/config` | GET | Get sync configuration |
| `/api/sync/health` | GET | Health check |

---

## Troubleshooting

### Agent Won't Start

**Error: "No module named 'requests'"**
```bash
# Solution: Install dependencies
pip install -r requirements.txt
```

**Error: "ADMS_CLOUD_URL not configured"**
```bash
# Solution: Set cloud URL
export ADMS_CLOUD_URL=https://your-adms.cloud.com
python3 sync_agent.py

# Or edit sync_agent_config.json
nano sync_agent_config.json
```

### Can't Connect to Cloud

**Error: "Cloud API is unreachable"**
```bash
# Solution: Check cloud URL and network connectivity
curl https://your-adms.cloud.com/api/sync/health

# Check if HTTPS certificate is valid
# May need to add certificate if self-signed
```

### Can't Sync to Devices

**Error: "Cannot connect to device"**
```bash
# Solution: Check device connectivity
ping 192.168.1.100

# Check if device port is open
curl -v http://192.168.1.100:4370/iclock/cdata

# Check device firewall
```

**Error: "Device timeout"**
```bash
# Solution: Increase timeout in config
# Edit sync_agent_config.json and increase device_timeout_seconds
"device_timeout_seconds": 60
```

### No Devices Found

**Error: Auto-discovery finds 0 devices**
```bash
# Solution: Manually specify devices in config
{
  "devices": [
    "192.168.1.100",
    "192.168.1.101"
  ],
  "auto_discover": false
}
```

### Users Not Syncing

1. **Check cloud users:** Verify users exist in ADMS and are marked as `is_active = 1`
2. **Check device:** Verify device shows in sync status dashboard
3. **Check logs:** Look for sync cycle output and errors
4. **Manual test:** `python3 sync_agent.py --device 192.168.1.100`
5. **Check device directly:** Go to device web UI and check user database

---

## Configuration Examples

### Example 1: Single Location, Auto-Discovery

```json
{
  "cloud_url": "https://your-adms.cloud.com",
  "sync_interval_minutes": 10,
  "auto_discover": true,
  "network_prefix": "192.168.1"
}
```

### Example 2: Multiple Locations, Manual Devices

```json
{
  "cloud_url": "https://your-adms.cloud.com",
  "sync_interval_minutes": 5,
  "devices": [
    "192.168.1.100",
    "192.168.1.101",
    "10.0.0.50",
    "10.0.0.51"
  ],
  "auto_discover": false
}
```

### Example 3: Slow Network, High Timeout

```json
{
  "cloud_url": "https://your-adms.cloud.com",
  "sync_interval_minutes": 20,
  "device_timeout_seconds": 60,
  "max_retries": 5,
  "auto_discover": true
}
```

---

## Performance

### Typical Sync Time
- Cloud API fetch: 1-2 seconds
- Per device sync: 2-5 seconds
- Report back: 1 second
- **Total for 3 devices:** ~10 seconds

### Network Usage
- Users data: ~5-10 KB (per 100 users)
- Per sync cycle: ~100 KB (including reports)
- **Daily (6 cycles):** ~600 KB

### Resource Usage
- RAM: ~50-100 MB
- CPU: Minimal (only active during sync)
- Disk: ~10 MB for logs

---

## Maintenance

### Update Dependencies

```bash
pip install --upgrade -r requirements.txt
```

### Clean Logs

```bash
# Remove old logs (keep last 7 days)
find logs/ -name "*.log" -mtime +7 -delete
```

### Monitor Disk Space

```bash
# Check log directory size
du -sh logs/
```

---

## Support & Debug

### Enable Debug Logging

Edit sync_agent.py, line 55:
```python
logging.basicConfig(
    level=logging.DEBUG,  # Change from INFO to DEBUG
```

### Test Cloud Connectivity

```bash
python3 sync_agent.py --device 192.168.1.100
```

### Manual API Test

```bash
# Test cloud API
curl -X GET https://your-adms.cloud.com/api/sync/users
curl -X GET https://your-adms.cloud.com/api/sync/devices
```

### View Agent Uptime

```bash
ps aux | grep sync_agent.py
```

---

## Security Notes

- ✅ Uses HTTPS for cloud communication
- ✅ No credentials stored in agent (API pulls public data)
- ✅ Local network only for device sync
- ✅ Consider firewall rules for local network
- ⚠️ Use HTTPS-only cloud URLs in production
- ⚠️ Restrict network access to sync agent machine

---

## Next Steps

1. **Install** on local machine with device network access
2. **Configure** with your cloud URL and device IPs
3. **Test** with `--device` option
4. **Deploy** as background service
5. **Monitor** via dashboard and logs
6. **Verify** users appear on devices

All done! The sync agent will now automatically sync users from cloud to your local devices! 🎉