Skip to content

feat: Enhance Admin Panel Camp Funnel Chart

Title: Enhance Admin Panel Analytics Chart Description: Improve visualization and interactivity of the patient journey funnel chart in the admin analytics dashboard

Problem Statement

The current CampFunnelChart component in the admin analytics page (/admin/analytics) provides a basic funnel visualization of patient flow through medical camp stages. However, there are several limitations:

  • Limited interactivity: Users cannot drill down into specific stages to see patient details
  • Static visualization: No way to filter or compare data across different time periods or camp sessions
  • No export options: Cannot export the funnel data for presentations or reports

This affects admin users who need comprehensive insights into camp operations to make data-driven decisions about resource allocation and process improvements.

Proposed Solution

Enhance the CampFunnelChart component with:

  1. Interactive drill-down: Click on any stage to see list of patients in that stage
  2. Time-based filtering: Filter data by date range or specific camp session
  3. Bottleneck detection: Highlight stages with significant drop-offs
  4. Export functionality: Export chart as PNG/CSV for reporting
  5. Comparison view: Compare metrics across different camp dates
  6. Real-time updates: Improve WebSocket integration for live data

Test-Driven Development

Acceptance Criteria (Given-When-Then)

Primary User Flow

Scenario 1: View funnel chart with real-time data

Given admin user is on the analytics dashboard (/admin/analytics)
  And a medical camp is selected from the dropdown
 When the page loads
 Then the funnel chart should display all 9 patient journey stages
  And show accurate patient counts for each stage
  And update automatically via WebSocket every 5 seconds

Scenario 2: Drill down into funnel stage

Given admin user is viewing the funnel chart
 When user clicks on a specific stage (e.g., "Consultation")
 Then a dialog/modal should display showing list of patients in that stage
  And include patient name, book number, and time in stage

Alternative Flows

Scenario 3: Export funnel data

Given admin user is viewing the funnel chart
 When user clicks the export button
 Then a CSV file should be downloaded with all stage data
  And include: stage name, patient count, percentage, timestamps

Edge Cases

Scenario 4: Empty state - no patients registered

Given a medical camp has no registered patients
 When admin views the funnel chart
 Then display empty state message: "No patient data available for this camp yet"
  And show a dashed outline of the funnel structure

Scenario 5: Loading state

Given admin selects a new camp from the dropdown
 When data is being fetched
 Then show skeleton loading animation for all 9 stages
  And display loading spinner in the center

Scenario 6: Error state - API failure

Given the analytics API returns an error
 When admin attempts to view funnel chart
 Then display error alert: "Failed to load funnel data. Please try again."
  And show a retry button

Technical Specification

Files to Create/Modify

File Path Action Purpose
src/components/CampFunnelChart.tsx Modify Add drill-down, export, and comparison features
src/pages/admin/CampAnalyticsPage.tsx Modify Add filter controls and export buttons
src/lib/api.ts Modify Add new API endpoints for stage details
src/types/api.ts Modify Add types for drill-down data
src/utils/funnel.ts Create Utility functions for funnel calculations

API Requirements

Endpoint Method Request Body Response Status
/api/v1/analytics/funnel/{camp_id}/stage/{stage_name} GET - Patient[] [ ] Needs Backend
/api/v1/analytics/funnel/export POST { camp_id, format } Blob [ ] Needs Backend

API Types to Add:

interface FunnelStageDetail {
  stage_name: string;
  patients: {
    id: string;
    book_no: number;
    name: string;
    entered_at: string;
    time_in_stage_minutes: number;
  }[];
  total_count: number;
}

interface FunnelExportData {
  camp_id: number;
  camp_date: string;
  stages: {
    name: string;
    count: number;
    percentage: number;
  }[];
  generated_at: string;
}

UI/UX Specification

Design Requirements

  • Layout: Horizontal scrollable funnel on desktop, vertical stacked on mobile
  • Colors: Use existing slate color scheme from current implementation
  • Hover states: Show tooltip with detailed stats on hover
  • Click interactions: Cursor pointer on clickable stages
  • Animations: Smooth transitions when data updates (300ms ease-in-out)
  • Accessibility: All interactive elements keyboard navigable

Responsive Behavior

Viewport Behavior
Mobile (<576px) Vertical stacked bars, full-width
Tablet (576px-991px) Horizontal scroll, 2 columns for stats
Desktop (≥992px) Full horizontal funnel, 4-column stats grid

Accessibility Requirements

  • Semantic HTML elements used
  • ARIA labels for interactive elements (to add)
  • Keyboard navigation supported (to add focus states)
  • Focus states visible (to enhance)
  • Screen reader compatible (to test)
  • Color contrast meets WCAG standards
  • Error messages linked to inputs (to add)

i18n Requirements

All user-facing strings must be externalized:

String Key Default Value (English) Context
analytics.funnel.title Patient Journey Funnel Chart header
analytics.funnel.stage.registration Registration Stage name
analytics.funnel.stage.doctorAssignment Doctor Assignment Stage name
analytics.funnel.stage.vitals Vitals Collection Stage name
analytics.funnel.stage.kyp Know Your Patient Stage name
analytics.funnel.stage.waiting Waiting for Doctor Stage name
analytics.funnel.stage.consultation Consultation Stage name
analytics.funnel.stage.prescription Prescription Stage name
analytics.funnel.stage.medicineVerify Medicine Verification Stage name
analytics.funnel.stage.counseling Counseling Stage name
analytics.funnel.export Export Data Button label
analytics.funnel.viewPatients View Patients Button label
analytics.funnel.emptyState No patient data available for this camp yet Empty state
analytics.funnel.loading Loading funnel data... Loading state

Definition of Done

Development

  • All acceptance criteria (Given-When-Then) pass
  • All test cases executed and passing
  • Unit tests written with minimum 80% coverage
  • Integration tests written (if applicable)
  • Code follows project conventions
  • No TypeScript errors or any types
  • No ESLint/Prettier errors
  • No console.log() or debugger statements

Testing

  • Manual testing completed on all browsers
  • Responsive testing on mobile, tablet, desktop
  • Accessibility testing completed
  • Performance testing (no significant slowdowns)
  • Cross-browser testing (Chrome, Firefox, Safari, Edge)

Documentation

  • README.md updated (if setup changed)
  • .env.example updated (if new env vars needed)
  • Feature documented for end users (if applicable)

Code Review

  • Code reviewed and approved by at least 1 team member
  • Product owner approved (if applicable)

Additional Context

Open Questions

  1. Should the drill-down show patient PHI (Protected Health Information)? Consider privacy implications
  2. What is the maximum number of patients to display in drill-down? Consider pagination
  3. Should real-time updates be toggled on/off by user preference?

Related Issues

References

  • Current implementation: src/components/CampFunnelChart.tsx
  • API documentation: /api/v1/analytics/camp/{camp_id}
  • Figma designs: (link to be added)