## CRITICAL RULES - ALWAYS FOLLOW

### 1. BACKUP BEFORE ANY CHANGES
**MANDATORY**: Create backup before ANY code changes:
```bash
./create_full_backup.sh
```
- Creates full server backup and pushes to GitHub automatically
- Local copy remains for quick rollback
- Restore if needed: `./restore_full_backup.sh server_backup_YYYYMMDD_HHMMSS`

### 2. GITHUB BACKUPS ARE PERMANENT
- **NEVER DELETE** backups from GitHub repository (hetzner-backup)
- Only local backups can be deleted after successful upload
- GitHub serves as permanent backup archive

### 3. BACKUP TROUBLESHOOTING
If `create_full_backup.sh` fails to push:
- SSH key configured at: `~/.ssh/github_backup`
- Fix "Author identity unknown": `git -c user.email="backup@intelsight.de" -c user.name="Backup System" commit -m "..."`
- Repository: `git@github.com:UserIsMH/hetzner-backup.git`

### 4. BACKUP SCHEDULE
- Manual backups: Before EVERY change using `./create_full_backup.sh`
- Automatic backups: Daily at 3:00 AM via Admin Panel
- Admin Panel backup interface: https://admin-panel-undso.intelsight.de/backups

## SYSTEM OVERVIEW

Production license management system at intelsight.de with:
- **Admin Panel** (Flask): Web interface for customer/license/resource management
- **License Server** (FastAPI): API for license validation and heartbeat monitoring  
- **PostgreSQL**: Database with partitioned tables for performance
- **Nginx**: SSL termination and routing

## KEY FEATURES

### 1. License Management
- **Device Limit**: Each license has a `device_limit` (1-10 devices)
- **Concurrent Sessions**: Each license has a `concurrent_sessions_limit` (max simultaneous users)
- **Constraint**: concurrent_sessions_limit ≤ device_limit
- **Resource Allocation**: Domains, IPv4 addresses, phone numbers per license

### 2. Device Management
- **Single Table**: `device_registrations` stores all device information
- **Device Fields**: `hardware_fingerprint` (unique ID), `device_name`, `device_type`
- **Tracking**: First activation, last seen, active status
- **No automatic termination**: When session limit reached, new sessions are denied

### 3. Authentication & Security
- **API Authentication**: X-API-Key header (format: AF-YYYY-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX)
- **API Key Management**: Admin Panel → "Lizenzserver Administration" → "System-API-Key generieren"
- **2FA Support**: TOTP-based two-factor authentication for admin users
- **Audit Logging**: All changes tracked in audit_log table

### 4. Session Management
- **Heartbeat**: 30-second intervals (configurable)
- **Timeout**: 60 seconds without heartbeat = automatic cleanup
- **Single Device Resume**: Same device can resume existing session
- **Session Token**: UUID v4 for session identification

### 5. Database Structure
- **Partitioned Tables**: license_heartbeats (monthly partitions)
- **Resource Pools**: Centralized management of domains/IPs/phones
- **Session History**: Complete tracking with end reasons
- **Lead CRM**: Institution and contact management system