CalejoControl/DASHBOARD.md

# Calejo Control Adapter - Interactive Dashboard

## Overview

The Calejo Control Adapter Dashboard is a web-based interface that provides convenient configuration management, system monitoring, and operational controls for the Calejo Control Adapter system.

## Features

### 🖥️ Dashboard Interface

- **Tab-based Navigation**: Easy access to different system areas
- **Real-time Status Monitoring**: Live system status with color-coded indicators
- **Configuration Management**: Web-based configuration editor
- **System Logs**: Real-time log viewing
- **System Actions**: One-click operations for common tasks

### 📊 Status Monitoring

- **Application Status**: Overall system health
- **Database Status**: PostgreSQL connection status
- **Protocol Status**: OPC UA and Modbus server status
- **REST API Status**: API endpoint availability
- **Monitoring Status**: Health monitor and metrics collection

### ⚙️ Configuration Management

- **Database Configuration**: Connection settings for PostgreSQL
- **Protocol Configuration**: Enable/disable OPC UA and Modbus servers
- **REST API Configuration**: API host, port, and CORS settings
- **Monitoring Configuration**: Health monitor port settings
- **Validation**: Real-time configuration validation

### 📝 System Logs

- **Real-time Log Viewing**: Latest system logs with timestamps
- **Log Levels**: Color-coded log entries (INFO, WARNING, ERROR)
- **Auto-refresh**: Automatic log updates

### 🔧 System Actions

- **System Restart**: Controlled system restart
- **Backup Creation**: Manual backup initiation
- **Health Checks**: On-demand health status checks
- **Metrics Viewing**: Direct access to Prometheus metrics

## Accessing the Dashboard

### URL
```
http://localhost:8080/dashboard
```

or

```
http://localhost:8080/
```

### Default Ports
- **Dashboard**: 8080 (same as REST API)
- **Health Monitor**: 9090
- **Prometheus**: 9091
- **Grafana**: 3000

## Dashboard Tabs

### 1. Status Tab
- Real-time system status overview
- Color-coded status indicators
- Auto-refresh every 30 seconds
- Manual refresh button

### 2. Configuration Tab
- **Database Section**:
  - Host, port, database name
  - Username and password
- **Protocol Section**:
  - OPC UA server enable/disable
  - OPC UA port configuration
  - Modbus server enable/disable
  - Modbus port configuration
- **REST API Section**:
  - API host and port
  - CORS enable/disable
- **Monitoring Section**:
  - Health monitor port
- **Action Buttons**:
  - Load Current: Load current configuration
  - Save Configuration: Apply new settings
  - Validate: Check configuration validity

### 3. Logs Tab
- Real-time system log display
- Log level filtering (INFO, WARNING, ERROR)
- Timestamp information
- Manual refresh button

### 4. Actions Tab
- **System Operations**:
  - Restart System (requires confirmation)
  - Create Backup
- **Health Checks**:
  - Run Health Check
  - View Metrics (opens in new tab)

## API Endpoints

The dashboard uses the following REST API endpoints:

### Configuration Management
- `GET /api/v1/dashboard/config` - Get current configuration
- `POST /api/v1/dashboard/config` - Update configuration

### System Status
- `GET /api/v1/dashboard/status` - Get system status

### System Actions
- `POST /api/v1/dashboard/restart` - Restart system
- `GET /api/v1/dashboard/backup` - Create backup
- `GET /api/v1/dashboard/logs` - Get system logs

### Health Monitoring
- `GET /health` - Basic health check
- `GET /api/v1/health/detailed` - Detailed health status
- `GET /metrics` - Prometheus metrics

## Security Features

### Authentication
- JWT token-based authentication
- Role-based access control
- Secure credential handling

### Input Validation
- Server-side configuration validation
- Port range validation (1-65535)
- Required field validation
- Security warnings for default credentials

### Security Warnings
- Default JWT secret key detection
- Default API key detection
- Default database password detection

## Browser Compatibility

- **Chrome**: 70+
- **Firefox**: 65+
- **Safari**: 12+
- **Edge**: 79+

## Mobile Support

- Responsive design for mobile devices
- Touch-friendly interface
- Optimized for tablets and smartphones

## Development

### Frontend Technologies
- **HTML5**: Semantic markup
- **CSS3**: Modern styling with Flexbox/Grid
- **JavaScript**: Vanilla JS (no frameworks)
- **Fetch API**: Modern HTTP requests

### Backend Technologies
- **FastAPI**: REST API framework
- **Pydantic**: Data validation
- **Jinja2**: HTML templating

### File Structure
```
src/dashboard/
├── api.py           # Dashboard API endpoints
├── templates.py     # HTML templates
├── router.py        # Main dashboard router
static/
└── dashboard.js     # Frontend JavaScript
```

## Configuration Validation

The dashboard performs comprehensive validation:

### Required Fields
- Database host
- Database name
- Database user
- All port numbers

### Port Validation
- All ports must be between 1 and 65535
- No duplicate port assignments

### Security Validation
- Default credential detection
- Password strength recommendations

## Error Handling

### User-Friendly Messages
- Clear error descriptions
- Actionable suggestions
- Context-specific help

### Graceful Degradation
- API failure handling
- Network error recovery
- Partial data display

## Performance

### Optimizations
- Client-side caching
- Efficient DOM updates
- Minimal API calls
- Compressed responses

### Monitoring
- Performance metrics
- Error rate tracking
- User interaction analytics

## Troubleshooting

### Common Issues

1. **Dashboard Not Loading**
   - Check if REST API is running
   - Verify port 8080 is accessible
   - Check browser console for errors

2. **Configuration Not Saving**
   - Verify all required fields are filled
   - Check port numbers are valid
   - Look for validation errors

3. **Status Not Updating**
   - Check network connectivity
   - Verify health monitor is running
   - Check browser console for API errors

### Debug Mode
Enable debug mode by opening browser developer tools and checking:
- Network tab for API calls
- Console for JavaScript errors
- Application tab for storage

## Integration with Monitoring Stack

The dashboard integrates with the existing monitoring infrastructure:

- **Prometheus**: Metrics collection
- **Grafana**: Advanced dashboards
- **Health Monitor**: System health checks
- **Alert Manager**: Notification system

## Backup and Restore

Dashboard configuration changes can be backed up using:

```bash
# Manual backup
./scripts/backup.sh

# Restore from backup
./scripts/restore.sh BACKUP_ID
```

## Security Best Practices

1. **Change Default Credentials**
   - Update JWT secret key
   - Change API keys
   - Use strong database passwords

2. **Network Security**
   - Use HTTPS in production
   - Restrict dashboard access
   - Implement firewall rules

3. **Access Control**
   - Use role-based permissions
   - Regular credential rotation
   - Audit log monitoring

## Support

For dashboard-related issues:

1. **Documentation**: Check this guide and API documentation
2. **Logs**: Review system logs for errors
3. **Community**: Check project forums
4. **Support**: Contact support@calejo-control.com

---

**Dashboard Version**: 1.0
**Last Updated**: 2024-01-01
**Compatibility**: Calejo Control Adapter 2.0+