Hetzner-Backup/SYSTEM_DOCUMENTATION.md

V2-Docker System Documentation

Overview

V2-Docker is a comprehensive system featuring a License Server, Admin Panel, Lead Management, and Monitoring Stack. 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

Services

1. License Service - Core license validation
2. Analytics Service - Usage statistics and reporting
3. Admin API Service - Administrative operations
4. Notification Service - Email/webhook notifications
5. Backup Service - Automated backups

Communication

• REST APIs for external communication
• Message queuing for internal communication
• Event-driven architecture for real-time updates

Database Schema

Core Tables

• licenses - License definitions
• license_activations - Active installations
• license_heartbeats - Usage tracking (partitioned monthly)
• license_usage_stats - Aggregated statistics
• license_features - Feature flags
• license_limits - Usage limits

Partitioning Strategy

• Monthly partitions for license_heartbeats
• Automatic partition creation
• 90-day retention policy

Security Concepts

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

Implementation Status (June 19, 2025)

Completed

• Basic license server functionality
• Admin Panel integration
• Monitoring dashboard
• Docker services configuration
• JWT secret management
• Basic API endpoints

In Progress

• Analytics service
• Advanced monitoring
• Backup automation
• Performance optimization

Lead Management System

Architecture

• Modular Architecture: Clean separation of concerns
• Service Layer Pattern: Business logic isolation
• Repository Pattern: Data access abstraction
• RESTful API Design: Standard HTTP methods

Data Model

• Institutions: Core entity for organizations
• Contact Persons: Multiple contacts per institution
• Notes System: Versioned notes with timestamps
• Future-proof Design: JSONB fields for extensibility

Features

1. Institution management (CRUD operations)
2. Contact person management
3. Advanced search and filtering
4. Export functionality
5. Activity tracking
6. Note versioning

Monitoring Stack

Components

• Prometheus: Metrics collection
• Grafana: Visualization (port 3001)
• Alertmanager: Alert management (port 9093)
• Node Exporter: System metrics
• Postgres Exporter: Database metrics
• cAdvisor: Container metrics

Dashboards

1. System Overview
2. License Server Metrics
3. Database Performance
4. Container Resources
5. Admin Panel Usage

Alert Rules

• High CPU usage (>80%)
• High memory usage (>90%)
• Database connection issues
• License server downtime
• Disk space warnings

Admin Panel Integration

Features

• License management interface
• Customer creation and editing
• License monitoring dashboard
• Real-time statistics
• Alert notifications

Technical Details

• Flask-based web application
• PostgreSQL database
• Bootstrap UI framework
• AJAX for real-time updates
• Responsive design

Deployment Configuration

Docker Services

• v2_db: PostgreSQL database
• v2_adminpanel: Admin interface
• v2_nginx: Reverse proxy
• v2_lizenzserver: License server
• prometheus: Metrics collection
• grafana: Monitoring dashboards

Environment Variables

• JWT_SECRET: Authentication key
• DATABASE_URL: PostgreSQL connection
• API_KEY: Service authentication
• MONITORING_ENABLED: Feature flag

Network Configuration

• Internal network for service communication
• External access through Nginx
• SSL/TLS termination at proxy level

Testing Strategy

Unit Tests

• Service layer logic
• API endpoint validation
• Database operations

Integration Tests

• Service communication
• Database transactions
• API workflows

Performance Tests

• Load testing
• Stress testing
• Scalability verification

Future Roadmap

Phase 1: Core Completion

• Finish analytics service
• Complete backup automation
• Implement all monitoring dashboards

Phase 2: Advanced Features

• Machine learning for usage prediction
• Advanced reporting
• Multi-tenant support

Phase 3: Enterprise Features

• High availability setup
• Disaster recovery
• Advanced security features