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:

@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:

{
  "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

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

4. View Function

Location: apps/organizations/ui_views.py

@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:

<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:

// 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

// 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/