HH/docs/COMMAND_CENTER_IMPLEMENTATION.md

# PX360 Command Center - Implementation Guide

## Overview

The PX360 Command Center is a comprehensive, unified dashboard that consolidates all analytics, KPIs, and metrics from across the PX360 system into a single, powerful command center interface. This document provides detailed information about the implementation, features, and usage of the Command Center.

## Features

### 1. Unified KPI Display
- **Complaints KPIs**: Total complaints, open complaints, overdue complaints, resolved complaints
- **Actions KPIs**: Total actions, overdue actions
- **Surveys KPIs**: Average survey score, negative surveys
- **Trend Indicators**: Visual indicators showing percentage changes vs. previous period

### 2. Interactive Charts (ApexCharts)
All charts use ApexCharts library for modern, responsive, and interactive visualizations:

- **Complaints Trend**: Line/Area chart showing complaint volume over time
- **Complaints by Category**: Donut chart showing distribution across categories
- **Survey Satisfaction Trend**: Line chart showing satisfaction scores over time
- **Survey Distribution**: Donut chart showing positive/neutral/negative split
- **Department Performance**: Bar chart ranking departments by performance
- **Physician Leaderboard**: Bar chart showing top-performing physicians

### 3. Advanced Filtering System
Users can filter data by:
- **Date Range**: Preset options (7 days, 30 days, 90 days, this month, last month, quarter, year) or custom range
- **Hospital**: Filter by specific hospital (role-based access control)
- **Department**: Filter by specific department
- **KPI Category**: Filter by category (complaints, surveys, actions, physicians)

### 4. Data Tables
- **Overdue Complaints Table**: Shows all overdue complaints with quick action links
- **Physician Leaderboard Table**: Detailed ranking with ratings, survey counts, and sentiment breakdown

### 5. Export Functionality
- **Excel Export**: Download dashboard data in Excel (.xlsx) format
- **PDF Export**: Generate professional PDF reports with all KPIs and data
- Both exports respect current filter settings

## Architecture

### Backend Components

#### 1. UnifiedAnalyticsService (`apps/analytics/services/analytics_service.py`)

A comprehensive service class that handles all data aggregation and KPI calculations.

**Key Methods:**
```python
class UnifiedAnalyticsService:
    @staticmethod
    def get_all_kpis(user, date_range, hospital_id, department_id, ...)
        """Returns all KPIs based on filters"""
        
    @staticmethod
    def get_chart_data(user, chart_type, date_range, ...)
        """Returns chart data for specific chart type"""
        
    @staticmethod
    def get_date_range_filter(date_range, custom_start, custom_end)
        """Returns (start_date, end_date) tuple"""
        
    @staticmethod
    def get_complaints_trend(user, start_date, end_date, ...)
        """Returns complaints trend chart data"""
        
    @staticmethod
    def get_complaints_by_category(user, start_date, end_date, ...)
        """Returns complaints by category chart data"""
        
    # ... additional chart data methods
```

#### 2. ExportService (`apps/analytics/services/export_service.py`)

Handles Excel and PDF export generation.

**Key Methods:**
```python
class ExportService:
    @staticmethod
    def prepare_dashboard_data(user, kpis, charts, tables)
        """Prepares data structure for export"""
        
    @staticmethod
    def export_to_excel(data)
        """Generates Excel file and returns HttpResponse"""
        
    @staticmethod
    def export_to_pdf(data)
        """Generates PDF file and returns HttpResponse"""
```

#### 3. UI Views (`apps/analytics/ui_views.py`)

Django views for rendering the dashboard and handling API requests.

**Key Views:**
```python
@login_required
def command_center(request)
    """Main dashboard view - renders the HTML template"""
    
@login_required
def command_center_api(request)
    """API endpoint - returns JSON data for dynamic updates"""
    
@login_required
def export_command_center(request, export_format)
    """Handles Excel and PDF export requests"""
```

### Frontend Components

#### 1. Command Center Template (`templates/analytics/command_center.html`)

The main dashboard template includes:
- Filter panel with collapsible form
- KPI cards with trend indicators
- Chart containers for ApexCharts
- Data tables with sorting and actions
- Loading overlay
- JavaScript for dynamic updates

#### 2. JavaScript Functionality

**Key JavaScript Functions:**
```javascript
// Global state
let charts = {};
let currentFilters = { ... };

// Core functions
loadDashboardData()              // Loads all dashboard data via AJAX
updateKPIs(kpis)                 // Updates KPI cards
updateCharts(chartData)          // Renders/updates ApexCharts
renderChart(elementId, chartData, chartType)  // Renders individual chart
updateTables(tableData)          // Updates data tables

// Filter functions
handleDateRangeChange()          // Shows/hides custom date range
updateFilters()                  // Updates currentFilters object
resetFilters()                   // Resets all filters to defaults

// Export functions
exportDashboard(format)          // Initiates Excel/PDF export
```

## URL Structure

```
/analytics/command-center/                    # Main dashboard
/analytics/api/command-center/                # API endpoint for data
/analytics/api/command-center/export/excel/   # Excel export
/analytics/api/command-center/export/pdf/     # PDF export
```

## Data Flow

### 1. Initial Page Load
```
User Request → command_center view
    ↓
Render template with initial filters and KPIs
    ↓
Return HTML to browser
    ↓
JavaScript loads data via AJAX
    ↓
command_center_api returns JSON
    ↓
Dashboard updates with data
```

### 2. Filter Change
```
User applies filter
    ↓
JavaScript updates currentFilters
    ↓
loadDashboardData() called
    ↓
AJAX request to command_center_api with filters
    ↓
Backend aggregates data based on filters
    ↓
JSON response with kpis, charts, tables
    ↓
JavaScript updates UI components
```

### 3. Export Request
```
User clicks Export → Excel/PDF
    ↓
exportDashboard(format) called
    ↓
AJAX request to export_command_center
    ↓
ExportService generates file
    ↓
Browser downloads file
```

## Role-Based Access Control

The Command Center respects user roles:

### PX Admin
- Can view data across all hospitals
- Can filter by any hospital or department
- Full access to all KPIs and charts

### Hospital Manager
- Can only view data for their hospital
- Hospital filter pre-selected to their hospital
- Can filter by departments within their hospital

### Department Manager
- Can only view data for their department
- Hospital and department filters pre-selected
- Limited to department-specific KPIs

## Chart Configurations

### 1. Line Charts (Trend Data)
```javascript
{
    chart: { type: 'line', height: 350, toolbar: { show: true } },
    stroke: { curve: 'smooth', width: 3 },
    fill: { type: 'gradient', gradient: { ... } },
    xaxis: { categories: [...] },
    yaxis: { min: 0, forceNiceScale: true }
}
```

### 2. Donut Charts (Distribution Data)
```javascript
{
    chart: { type: 'donut', height: 350 },
    labels: [...],
    dataLabels: { enabled: true },
    legend: { position: 'bottom' }
}
```

### 3. Bar Charts (Ranking Data)
```javascript
{
    chart: { type: 'bar', height: 350 },
    plotOptions: { bar: { horizontal: true } },
    xaxis: { categories: [...] }
}
```

## Export Formats

### Excel Export (.xlsx)
- Contains separate sheets for:
  - Executive Summary (KPIs)
  - Detailed Charts Data
  - Overdue Complaints List
  - Physician Leaderboard
- Formatted with proper headers and styling
- Includes timestamp and filter information

### PDF Export (.pdf)
- Professional report format
- Executive summary with key KPIs
- **Charts rendered as high-quality images using Matplotlib**:
  - Line charts with markers and trend lines
  - Bar charts with value labels
  - Donut/Pie charts with percentage labels
  - Professional styling and colors
  - 150 DPI resolution for print quality
- Data tables with proper formatting
- Includes report metadata (date, filters applied)

## Performance Optimizations

1. **Database Query Optimization**
   - Uses select_related() and prefetch_related() for efficient queries
   - Aggregates data at database level where possible
   - Limits result sets for tables (20-100 rows)

2. **Caching**
   - Consider adding Redis caching for frequently accessed data
   - Cache chart data for common filter combinations

3. **AJAX Loading**
   - Initial page load shows skeleton with filters
   - Data loads asynchronously via AJAX
   - Prevents page timeout on large datasets

4. **Pagination**
   - Table results are paginated
   - Chart data limits to top N items (e.g., top 10 departments)

## Dependencies

### Required Python Packages
```txt
openpyxl>=3.1.0      # Excel export
reportlab>=4.0.0     # PDF export
Pillow>=10.0.0       # Image processing for PDF
matplotlib>=3.8.0     # Chart image generation for PDF export
```

### Required JavaScript Libraries
```html
<!-- Already included in base.html -->
<script src="https://cdn.jsdelivr.net/npm/apexcharts@3.45.1/dist/apexcharts.min.js"></script>
```

## Customization Guide

### Adding a New KPI

1. **Add KPI calculation in UnifiedAnalyticsService:**
```python
@staticmethod
def get_all_kpis(user, date_range, ...):
    kpis = {
        # existing KPIs
        'new_kpi': self._calculate_new_kpi(user, date_range, ...),
    }
    return kpis
```

2. **Add KPI card to template:**
```html
<div class="col-md-3">
    <div class="card kpi-card">
        <div class="card-body">
            <div class="text-xs font-weight-bold text-primary text-uppercase mb-1">
                {% trans "New KPI" %}
            </div>
            <div class="kpi-value text-primary" id="newKpi">0</div>
        </div>
    </div>
</div>
```

3. **Update JavaScript:**
```javascript
function updateKPIs(kpis) {
    // existing updates
    document.getElementById('newKpi').textContent = kpis.new_kpi || 0;
}
```

### Adding a New Chart

1. **Add chart data method in UnifiedAnalyticsService:**
```python
@staticmethod
def get_new_chart(user, start_date, end_date, hospital_id, department_id):
    # Query and aggregate data
    return {
        'series': [...],
        'labels': [...],
        'chart_type': 'bar',  # or 'line', 'donut', etc.
        'metadata': {...}
    }
```

2. **Add chart method call:**
```python
charts = {}
for chart_type in chart_types + ['new_chart']:
    charts[chart_type] = UnifiedAnalyticsService.get_chart_data(
        user=user, chart_type=chart_type, ...
    )
```

3. **Add chart container to template:**
```html
<div class="col-lg-6">
    <div class="card">
        <div class="card-header">
            <h6 class="m-0 font-weight-bold">{% trans "New Chart" %}</h6>
        </div>
        <div class="card-body">
            <div class="chart-container" id="newChart"></div>
        </div>
    </div>
</div>
```

## Troubleshooting

### Issue: Charts not rendering
**Solution:**
- Check browser console for JavaScript errors
- Verify ApexCharts library is loaded (base.html)
- Ensure chart data is properly formatted (check API response)

### Issue: Filters not working
**Solution:**
- Verify filter parameters are being sent in AJAX request
- Check backend is processing filters correctly
- Ensure date parsing is working for custom ranges

### Issue: Export fails
**Solution:**
- Verify openpyxl and reportlab are installed
- Check file permissions for temporary directories
- Review export service logs for errors

### Issue: Slow page load
**Solution:**
- Add database indexes on frequently queried fields
- Implement caching for common filter combinations
- Consider pagination for large datasets

## Security Considerations

1. **Authentication**: All views require `@login_required` decorator
2. **Authorization**: Role-based filtering applied at model level
3. **SQL Injection**: Uses Django ORM parameterized queries
4. **XSS Protection**: Template auto-escaping enabled
5. **CSRF Protection**: Django CSRF middleware enabled

## Future Enhancements

1. **Real-time Updates**: WebSocket integration for live data
2. **Advanced Analytics**: Predictive analytics and AI insights
3. **Custom Dashboards**: User-defined dashboard layouts
4. **Scheduled Reports**: Automated email reports on schedule
5. **Drill-down Capability**: Click on chart to view detailed data
6. **Comparison Mode**: Compare multiple time periods side-by-side
7. **KPI Thresholds**: Alert system when KPIs exceed thresholds
8. **Annotations**: Add notes to specific data points

## Support and Maintenance

For issues, questions, or feature requests:
- Check this documentation first
- Review the codebase implementation
- Consult with the development team
- Create detailed bug reports with steps to reproduce

## Version History

- **v1.1.0** (2026-01-05): Enhanced PDF export with chart images
  - Added Matplotlib integration for generating actual chart images in PDF
  - Charts now render as visual graphics instead of text data
  - Improved PDF readability and professionalism
  - Fallback to text representation if image generation fails

- **v1.0.0** (2024-01-05): Initial implementation
  - Unified KPI dashboard
  - Interactive ApexCharts
  - Advanced filtering
  - Excel/PDF export
  - Role-based access control