HH/docs/D3_HIERARCHY_INTEGRATION.md

# D3.js Staff Hierarchy Visualization Integration

## Overview

This document describes the integration of D3.js for interactive staff hierarchy visualization in the PX360 system. The D3.js implementation provides a modern, interactive alternative to the HTML-based hierarchy view.

## What Was Implemented

### 1. D3.js Data API (`/organizations/api/staff/hierarchy/`)

**Location:** `apps/organizations/views.py` - `StaffViewSet.hierarchy()` action

Provides REST API endpoint that returns staff hierarchy data in D3-compatible JSON format:

```python
@action(detail=False, methods=['get'])
def hierarchy(self, request):
    """Get staff hierarchy as D3-compatible JSON."""
```

**Features:**
- Returns hierarchical tree structure
- Supports filtering by hospital and department
- Includes search functionality
- Provides statistics (total staff, top managers)
- Calculates team sizes for each manager

**Response Format:**
```json
{
  "hierarchy": [
    {
      "id": "staff_id",
      "name": "Staff Name",
      "employee_id": "EMP123",
      "job_title": "Manager",
      "hospital": "Hospital Name",
      "department": "Department Name",
      "status": "active",
      "staff_type": "type",
      "team_size": 5,
      "children": [...]
    }
  ],
  "statistics": {
    "total_staff": 100,
    "top_managers": 3
  }
}
```

### 2. D3.js Visualization Template

**Location:** `templates/organizations/staff_hierarchy_d3.html`

Complete interactive visualization template with:

**Features:**
- **Three Layout Options:**
  - Horizontal tree (default)
  - Vertical tree
  - Radial layout

- **Interactive Controls:**
  - Search staff by name or ID
  - Expand/collapse nodes
  - Expand all / Collapse all buttons
  - Zoom and pan support
  - Reset view button

- **Node Sizing Options:**
  - Fixed size
  - Size by team size
  - Size by hierarchy level

- **Statistics Display:**
  - Total staff count
  - Number of top managers
  - Average hierarchy depth

- **Interactions:**
  - Single click: Expand/collapse children
  - Double click: Navigate to staff detail page
  - Hover: Show tooltip with staff information
  - Search: Auto-navigate and highlight found staff

### 3. URL Routing

**Location:** `apps/organizations/urls.py`

```python
path('staff/hierarchy/d3/', ui_views.staff_hierarchy_d3, name='staff_hierarchy_d3'),
```

### 4. View Function

**Location:** `apps/organizations/ui_views.py`

```python
@login_required
def staff_hierarchy_d3(request):
    """Staff hierarchy D3 visualization view"""
```

### 5. D3.js Library Integration

**Location:** `templates/layouts/base.html`

Added D3.js v7.9.0 CDN:
```html
<script src="https://cdn.jsdelivr.net/npm/d3@7.9.0/dist/d3.min.js"></script>
```

## Accessing the D3 Visualization

### URL
```
/organizations/staff/hierarchy/d3/
```

### Navigation
From the sidebar or staff list page, users can access both:
- **HTML-based Hierarchy:** `/organizations/staff/hierarchy/`
- **D3 Interactive Hierarchy:** `/organizations/staff/hierarchy/d3/`

## D3.js vs HTML-Based Hierarchy

### HTML-Based Hierarchy (Original)

**Advantages:**
- Simple, static display
- Good for printing
- No JavaScript required
- SEO friendly
- Easy to customize with CSS

**Disadvantages:**
- Limited interactivity
- Manual expand/collapse requires page reload
- No zoom/pan capabilities
- Search is server-side only
- Fixed layout

### D3.js Interactive Hierarchy (New)

**Advantages:**
- **Rich Interactivity:**
  - Click to expand/collapse
  - Smooth animations
  - Zoom and pan
  - Real-time search

- **Multiple Layouts:**
  - Horizontal tree
  - Vertical tree
  - Radial/circular layout

- **Dynamic Visualization:**
  - Node sizing by team size or level
  - Tooltips with detailed info
  - Visual hierarchy indicators

- **Better UX:**
  - Client-side filtering
  - Instant feedback
  - Keyboard shortcuts
  - Responsive design

**Disadvantages:**
- Requires JavaScript
- Longer initial load time
- More complex to maintain
- Not printable by default

## Features Comparison

| Feature | HTML | D3.js |
|---------|------|--------|
| Expand/Collapse | Server-side (reload) | Client-side (instant) |
| Search | Server-side (reload) | Client-side (instant) |
| Zoom/Pan | ❌ | ✅ |
| Multiple Layouts | ❌ | ✅ (3 layouts) |
| Node Sizing | Fixed | Variable |
| Animations | ❌ | ✅ |
| Tooltips | ❌ | ✅ |
| Keyboard Support | Limited | Full |
| Printing | ✅ | Limited |
| Mobile Friendly | Basic | Enhanced |
| Performance | Good (small datasets) | Good (all sizes) |

## User Guide

### Basic Navigation

1. **View the Hierarchy:**
   - Navigate to `/organizations/staff/hierarchy/d3/`
   - Chart loads with top-level managers visible
   - Other staff collapsed by default

2. **Expand/Collapse:**
   - Click any node to toggle its children
   - Use "Expand All" to show entire organization
   - Use "Collapse All" to show only top managers

3. **Zoom & Pan:**
   - Mouse wheel: Zoom in/out
   - Click & drag: Pan around the chart
   - "Reset View" button: Return to default position

4. **Search Staff:**
   - Type in search box
   - Press Enter
   - Chart auto-navigates to found staff
   - Found node is highlighted in red

5. **Change Layout:**
   - Select from dropdown: Horizontal, Vertical, or Radial
   - Chart instantly reorganizes

6. **Adjust Node Sizes:**
   - Select from dropdown: Fixed, Team Size, or Level
   - Visual representation updates immediately

### Viewing Staff Details

- **Double-click** on any node to view full staff details
- Opens `/organizations/staff/{id}/` page

## Technical Details

### Data Flow

```
User Request
    ↓
staff_hierarchy_d3 view
    ↓
Render D3 template
    ↓
JavaScript fetches /organizations/api/staff/hierarchy/
    ↓
StaffViewSet.hierarchy() action
    ↓
Query database (filter by user permissions)
    ↓
Build hierarchy tree
    ↓
Return JSON
    ↓
D3.js renders interactive visualization
```

### Performance Considerations

- **Data Fetching:** Single API call retrieves entire hierarchy
- **Client-Side Processing:** All filtering/search happens in browser
- **Optimizations:**
  - Django `select_related` for efficient queries
  - Cached hierarchy calculations
  - Efficient D3 updates (only changed nodes)

### Browser Compatibility

- **Supported:** Chrome, Firefox, Safari, Edge (latest versions)
- **Required:** JavaScript enabled
- **Recommended:** 1920x1080 or higher resolution

## Customization

### Changing Colors

Edit in `templates/organizations/staff_hierarchy_d3.html`:

```javascript
// Node colors
.style("fill", d => d._children ? "var(--hh-primary)" : "var(--hh-success)")
.style("stroke", "var(--hh-primary)")

// Link color
.style("stroke", "#ccc")
```

### Adjusting Layout Spacing

```javascript
// Horizontal spacing
nodeSize([50, 200])  // [height, width]

// Depth spacing
d.y = d.depth * 200;  // pixels per level
```

### Adding Custom Data Fields

1. Update `StaffViewSet.hierarchy()` to include field
2. Update template to display field in tooltip or label
3. Re-render chart

## Future Enhancements

### Potential Additions

1. **Export Options:**
   - Export as PNG/SVG
   - Export as PDF
   - Print-friendly version

2. **Advanced Filtering:**
   - Filter by staff type
   - Filter by status
   - Multi-criteria filters

3. **Additional Visualizations:**
   - Sunburst chart
   - Treemap
   - Force-directed graph

4. **Collaboration Features:**
   - Shareable links
   - Embed in reports
   - Compare hierarchies (time-based)

5. **Analytics:**
   - Hierarchy depth analysis
   - Span of control metrics
   - Bottleneck identification

## Troubleshooting

### Chart Not Loading

**Problem:** Blank screen or "Failed to load hierarchy data" error

**Solutions:**
1. Check browser console for JavaScript errors
2. Verify API endpoint is accessible: `/organizations/api/staff/hierarchy/`
3. Check user has permission to view staff
4. Ensure D3.js CDN is reachable

### Search Not Working

**Problem:** Search doesn't find staff or doesn't navigate

**Solutions:**
1. Verify staff exist in hierarchy
2. Check browser console for errors
3. Ensure staff have valid names/IDs
4. Try full name instead of partial

### Performance Issues

**Problem:** Chart is slow or unresponsive

**Solutions:**
1. Reduce initial node count (collapse deeper levels)
2. Use "Fixed Size" instead of "Team Size"
3. Check network connection for data fetch
4. Consider server-side pagination for very large datasets

## Support

For issues or questions:
1. Check browser console for JavaScript errors
2. Review Django logs for API errors
3. Test with different browsers
4. Contact development team with screenshots and error details

## References

- **D3.js Documentation:** https://d3js.org/
- **D3 Tree Layout:** https://github.com/d3/d3-hierarchy/tree
- **API Endpoint:** `/organizations/api/staff/hierarchy/`
- **Original HTML View:** `/organizations/staff/hierarchy/`