# 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