v2-Docker/SYSTEM_DOCUMENTATION.md

# V2-Docker System Documentation

## WICHTIGER HINWEIS FÜR ZUKÜNFTIGE ENTWICKLUNG

**DIESE SERVICES WERDEN NICHT VERWENDET:**
- ❌ Redis - NICHT BENÖTIGT für <100 Kunden
- ❌ RabbitMQ - NICHT BENÖTIGT für <100 Kunden  
- ❌ Prometheus - NICHT BENÖTIGT
- ❌ Grafana - NICHT BENÖTIGT
- ❌ Alertmanager - NICHT BENÖTIGT
- ❌ Externe Monitoring-Tools - NICHT BENÖTIGT

**Das System verwendet NUR:**
- ✅ PostgreSQL für alle Datenspeicherung
- ✅ Integrierte Überwachung im Admin Panel
- ✅ Direkte Datenbankverbindungen ohne Cache
- ✅ Synchrone Verarbeitung ohne Message Queue

## Overview

V2-Docker is a streamlined system featuring a License Server, Admin Panel, and Lead Management with integrated monitoring. This document consolidates all architecture and implementation details.

## License Server Architecture

### Core Principles
- Designed to avoid refactoring
- Microservices architecture
- Hardware-based license binding
- Offline grace period support (7 days)
- Version control with update enforcement

### Core Functionalities

#### 1. License Validation
- Real-time license verification
- Hardware binding (MAC address, CPU ID, system UUID)
- Version compatibility checks
- Usage limit enforcement

#### 2. Activation Management
- Initial activation with hardware fingerprint
- Multi-activation support
- Deactivation capabilities
- Transfer between systems

#### 3. Usage Monitoring
- Active user tracking
- Feature usage statistics
- Heartbeat monitoring (15-minute intervals)
- Historical data analysis

### Microservices Architecture

#### Aktive Services
1. **License Server** (`v2_lizenzserver`) - Core license validation
   - Vollständig implementiert
   - API-Endpunkte für Aktivierung, Verifizierung, Info
   - Läuft auf internem Port über Nginx

2. **Admin Panel** (`v2_adminpanel`) - Web-basierte Verwaltung
   - Vollständig implementiert auf Port 80
   - Customer, License, Resource Management
   - Integrierte Backup-Funktionalität
   - Lead Management System

#### Infrastructure Services
- **PostgreSQL** - Main database
- **Redis** - Caching
- **RabbitMQ** - Message queue
- **Nginx** - Reverse proxy

*Note: Analytics, Admin API, and Auth services exist in code but are currently inactive.*

#### Communication
- REST APIs für externe Kommunikation
- Redis für Caching
- RabbitMQ für asynchrone Verarbeitung (vorbereitet)

### Database Schema
See `v2_adminpanel/init.sql` for complete schema.
Key feature: Monthly partitioned `license_heartbeats` table.

### Security Concepts
- JWT-based authentication
- API key management
- Rate limiting (100 requests/minute)
- Hardware fingerprint validation
- Encrypted communication

### Implementation Status (June 22, 2025)

#### Completed
- ✅ License Server mit vollständigen API-Endpunkten
  - POST /api/license/activate
  - POST /api/license/verify  
  - GET /api/license/info/{license_key}
  - POST /api/license/session/start - Session-Initialisierung
  - POST /api/license/session/heartbeat - Keep-alive
  - POST /api/license/session/end - Session-Beendigung
  - POST /api/version/check
  - GET /api/version/latest
- ✅ Admin Panel mit voller Funktionalität
  - Customer Management mit erweiterten Features
  - License Management mit Resource Allocation
  - Resource Pool Management (Domains, IPs, Telefonnummern)
  - Session Management mit Live-Monitor
  - Lead Management System (vollständiges CRM)
  - Batch Operations für Bulk-Aktionen
  - Export/Import Funktionalität
  - Device Registration und Management
  - API Key Management (System-wide)
- ✅ Monitoring Stack (Prometheus, Grafana, Alertmanager)
  - Integriertes Monitoring Dashboard
  - Vorkonfigurierte Dashboards
  - Alert Rules für kritische Metriken
- ✅ Docker Services Konfiguration
- ✅ JWT/API Key Management
- ✅ Backup-System (integriert im Admin Panel)
- ✅ 2FA-Authentifizierung
- ✅ Audit Logging mit Request IDs
- ✅ Rate Limiting (konfigurierbar)
- ✅ Single-Session Enforcement (Account Forger)
- ✅ Partitionierte Datenbank für Heartbeats

#### Code vorhanden aber nicht aktiviert
- ⏸️ Analytics Service (auskommentiert)
- ⏸️ Admin API Service (auskommentiert)  
- ⏸️ Auth Service (auskommentiert)

#### Geplant
- 📋 Notification Service
- 📋 Erweiterte Analytics
- 📋 Machine Learning Integration

## Lead Management System

### Status
**Vollständig implementiert** als Teil des Admin Panels unter `/leads/`

### Update June 22, 2025 - 20:26
- **Neuer Navbar-Eintrag**: "Lead Management" über "Ressourcen Pool"
- **Lead Management Dashboard** unter `/leads/management` mit:
  - Übersicht Statistiken (Institutionen, Kontakte, Benutzer-Attribution)
  - Aktivitätsfeed zeigt wer was hinzugefügt/bearbeitet hat
  - Schnellaktionen (Institution hinzufügen, alle anzeigen, exportieren)
  - Geteilte Informationsansicht zwischen rac00n und w@rh@mm3r

### Architecture
- **Modular Architecture**: Clean separation of concerns
- **Service Layer Pattern**: Business logic in `leads/services.py`
- **Repository Pattern**: Data access in `leads/repositories.py`
- **Blueprint Integration**: Routes in `leads/routes.py`

### Data Model (implementiert)
```
lead_institutions
├── lead_contacts (1:n)
│   └── lead_contact_details (1:n) - Telefon/E-Mail
└── lead_notes (1:n) - Versionierte Notizen
```

### Implementierte Features
1. ✅ Institution Management (CRUD)
2. ✅ Contact Person Management mit mehreren Telefon/E-Mail
3. ✅ Notes mit vollständiger Versionierung
4. ✅ Flexible Kontaktdetails (beliebig viele pro Person)
5. ✅ Audit Trail Integration
6. ✅ Service/Repository Pattern für Clean Code
7. ✅ JSONB Felder für zukünftige Erweiterungen

### API Endpoints
- GET /leads/ - Institutionen-Übersicht
- GET /leads/institutions - Institutionen-Liste
- POST /leads/institutions - Neue Institution
- GET /leads/institutions/{id} - Institution Details
- PUT /leads/institutions/{id} - Institution bearbeiten
- DELETE /leads/institutions/{id} - Institution löschen
- GET /leads/contacts/{id} - Kontakt Details
- POST /leads/contacts/{id}/details - Kontaktdetail hinzufügen
- PUT /leads/contacts/{id}/details/{detail_id} - Detail bearbeiten
- POST /leads/contacts/{id}/notes - Notiz hinzufügen

## Admin Panel

### Implementierte Features
1. **Authentication & Security**
   - ✅ Login mit 2FA-Unterstützung
   - ✅ Session Management
   - ✅ Rate Limiting
   - ✅ IP-Blocking bei fehlgeschlagenen Logins
   - ✅ Audit Logging aller Aktionen

2. **Customer Management**
   - ✅ CRUD-Operationen für Kunden
   - ✅ Kundensuche mit Autocomplete
   - ✅ Kunden-Lizenz-Übersicht
   - ✅ Quick Stats pro Kunde

3. **License Management**
   - ✅ Lizenzerstellung (Einzel und Batch)
   - ✅ Lizenzbearbeitung und -löschung
   - ✅ Bulk-Operationen (Aktivieren/Deaktivieren)
   - ✅ Device Management mit Hardware IDs
   - ✅ Resource Allocation (Domains, IPs, Telefonnummern)
   - ✅ Quick Edit Funktionalität
   - ✅ Session Management und Monitoring
   - ✅ Lizenz-Konfiguration für Account Forger

4. **Monitoring & Analytics**
   - ✅ Dashboard mit Live-Statistiken
   - ✅ Lizenzserver-Monitoring
   - ✅ Session-Überwachung mit Live-Updates
   - ✅ Resource Pool Monitoring
   - ✅ Integriertes Monitoring Dashboard (/monitoring)
   - ✅ Prometheus/Grafana Integration
   - ✅ Alert Management

5. **System Administration**
   - ✅ Backup & Restore (manuell und geplant)
   - ✅ Export-Funktionen (CSV, JSON)
   - ✅ Audit Log Viewer mit Filterung
   - ✅ Blocked IPs Management
   - ✅ Feature Flags Konfiguration
   - ✅ API Key Generation und Management
   - ✅ Lizenzserver Administration
   - ✅ Session-Terminierung durch Admins

### Technical Stack
- Backend: Flask 3.0.3, PostgreSQL
- Frontend: Bootstrap 5.3, jQuery
- Security: bcrypt, pyotp (2FA), JWT

## Deployment Configuration

### Docker Services

#### Aktive Services
- `db`: PostgreSQL database (Port 5432)
- `admin-panel`: Admin interface (interner Port 5000)
- `nginx-proxy`: Reverse proxy (Ports 80, 443)
- `license-server`: License server (interner Port 8443)

#### NICHT VERWENDETE Services (DO NOT USE)
- ❌ `redis`: Redis cache - NICHT BENÖTIGT für <100 Kunden
- ❌ `rabbitmq`: Message queue - NICHT BENÖTIGT für <100 Kunden
- ❌ External monitoring (Prometheus, Grafana, Alertmanager) - NICHT BENÖTIGT
- ❌ `monitoring/docker-compose.monitoring.yml` - NICHT VERWENDEN

**WICHTIG**: Das System verwendet KEINE externen Monitoring-Tools, Redis oder RabbitMQ. Die eingebaute Überwachung im Admin Panel ist ausreichend für <100 Kunden.

### Environment Configuration
Required: DATABASE_URL, SECRET_KEY, JWT_SECRET
NOT Required: REDIS_HOST, RABBITMQ_HOST (diese NICHT konfigurieren)
See docker-compose.yaml for all environment variables.


## Current Status
System is production-ready with all core features implemented:
- ✅ License management with session enforcement
- ✅ Lead management CRM
- ✅ Resource pool management
- ✅ Integrierte Überwachung (Admin Panel)
- ✅ Backup and audit systems