Healthcare IPA/MSO Analytics Platform

Executive Summary

This document outlines JAB's approach to designing and building an enterprise-grade analytics dashboard for a regional IPA/MSO. The platform will replace fragmented, manual reporting workflows with a unified system capable of ingesting data from SQL queries, Excel spreadsheets, and CSV files — then automatically generating interactive, HIPAA-compliant dashboards focused on financial KPIs.

Phase 1 delivers a fully functional shell: responsive layout, auto-report generation framework, financial KPI dashboard structure, API integration layer, and complete documentation for IT review. Every technology decision is auditable, every dependency is sourced, and the architecture is built for healthcare compliance from day one.

The Challenge

The client — a regional IPA/MSO managing capitated contracts across multiple health plans — faces a familiar but critical problem: financial visibility is too slow, too manual, and too fragmented to support strategic decision-making.

Capitation revenue, claims data, provider performance metrics, and risk scores live in disconnected systems: legacy SQL databases, Excel workbooks passed between departments, and CSV exports from clearinghouses. Finance teams spend 40+ hours per month manually assembling reports. By the time leadership reviews the numbers, they're already weeks stale.

The consequences are real: MLR deviations go undetected, provider cost outliers persist, and capitation rate negotiations happen without current data. The organization needs a single platform that consolidates data from any source and delivers real-time, role-based analytics — built to healthcare compliance standards from the start.

Our Approach

We're building this in layers — starting with a robust, compliance-ready foundation and progressively adding intelligence. Phase 1 delivers the architecture, layout, data ingestion framework, and KPI structure. Subsequent phases layer in AI-assisted analysis, predictive modeling, and expanded data source integrations.

Design Principles

Compliance-first architecture. HIPAA readiness isn't a future enhancement — it's baked into every decision from data handling to access control to audit logging. No PII touches the frontend. No shortcuts on encryption.

Auditable dependencies. Every module in the project is traceable to its source, vetted for vulnerabilities, and documented with rationale. IT can review the full dependency chain before a single line of code ships to production.

Healthcare-native KPIs. This isn't a generic dashboard tool with healthcare data bolted on. The financial metrics — capitation PMPM, MLR, claims incurred, risk score trends — are first-class citizens in the data model and the UI.

Progressive intelligence. The shell is built to support AI-assisted analysis from day one. Schema detection, chart type recommendation, and anomaly alerting are all architected into the data flow — even before the ML models are trained.

Technology Stack

Every technology choice is validated against our module sourcing standards: open source, actively maintained, healthcare-proven, and zero high-severity vulnerabilities. The complete stack:

Frontend Framework

UI Components & Visualization

State & Data Management

Auto-Report Generation Engine

The core differentiator of this platform: upload data, get a dashboard. No manual configuration, no drag-and-drop widget placement, no BI tool training. The system detects what you have and recommends how to see it.

SQL Query Path

Users paste a raw SQL query into the platform. The backend executes it with full sanitization, returns the result set, and the frontend analyzes the schema: identifying measures vs. dimensions, detecting aggregation levels, and recommending grouping strategies. The system distinguishes between detail-level data (suited for tables and drill-downs) and summary data (suited for KPI cards and trend charts).

Excel / CSV Path

Users upload a file. The parsing layer auto-detects headers (row 1 vs. named ranges), infers column data types (date, currency, percentage, text), suggests pivot structures, and handles files up to 100k+ rows with memory-efficient streaming. No server round-trip required for initial parsing — it happens in the browser.

AI Suggestion Layer

Based on data cardinality, type distribution, and detected patterns, the engine recommends visualization types: time-series data gets line charts, categorical breakdowns get bar charts, single-value KPIs get summary cards. Users can accept, modify, or override every recommendation. All dashboard configurations are saved as reusable JSON templates.

Financial KPI Framework

The dashboard is purpose-built for IPA/MSO financial management. These aren't generic metrics — they're the specific numbers that drive capitated healthcare economics.

Dashboard Layout

KPI summary cards anchor the top of the view — revenue, claims, MLR, and profitability at a glance. Below: trend charts showing monthly and quarterly comparisons. Provider drill-down tables allow ranking and filtering. Automated alerts surface when MLR deviates beyond the 5% threshold, flagging potential issues before they become problems.

Security & Compliance

Healthcare data demands the highest standard of protection. This architecture is designed for HIPAA compliance — not as a future enhancement, but as a foundational constraint that shapes every technical decision.

Data Handling

• Zero PII storage in the frontend — no localStorage, no sessionStorage, no client state
• All sensitive data (member IDs, claims) transmitted over TLS only
• Audit logging for every data access event — who accessed what, when
• Data retention policies aligned with HIPAA and state regulations
• Encryption at rest and in transit for all sensitive fields

Access Control

• Role-based dashboard visibility: admin, analyst, provider
• Field-level masking for sensitive metrics (risk scores, cost data)
• Enterprise SSO ready — architecture supports Azure AD, Okta integration
• Compliance reporting trail for all data access
• Session management with automatic timeout

Accessibility

• WCAG 2.1 AA compliance throughout the application
• Full keyboard navigation — no mouse-dependent interactions
• Screen reader support — all charts include descriptive alt text
• Healthcare-appropriate color schemes — no red/green for colorblind users
• Mobile responsive layout (enhancement, not primary target)

Performance Targets

The platform must be fast enough that users don't wait — and scalable enough that it doesn't degrade as data volumes grow. These are our contracted performance benchmarks:

Backend Expectations

Phase 1 Deliverables

Phase 1 is the foundation. Everything that follows — AI analysis, predictive modeling, expanded integrations — builds on what we deliver here.

IT Approval Criteria

This project is designed to pass IT review on the first submission. Every item below is addressed in the Phase 1 deliverable:

• All dependencies traceable to npmjs.com or GitHub with documented rationale
• Zero high or critical CVEs across the entire dependency tree
• TypeScript strict mode — no "any" types anywhere in the codebase
• HIPAA-ready architecture with audit logging hooks in place
• No hardcoded secrets, credentials, or API keys
• CI/CD pipeline ready with GitHub Actions template
• Full MODULE_MANIFEST.md for compliance review
• WCAG 2.1 AA accessibility compliance
• Architecture documentation with deployment checklist
• Security & compliance checklist signed off