Reports App - Micro-Frontend

OverviewCopy Anchor Link

The Reports app is a dedicated micro-frontend for premium reporting features including:

• Consolidated reports across multiple locations
• Commission tracking and management for doctors/consultants
• Revenue sharing configuration and tracking

Status: ✅ Complete and ready for production

ArchitectureCopy Anchor Link

Micro-Frontend IntegrationCopy Anchor Link

The Reports app follows the same micro-frontend pattern as CMS and Growth apps:

// Shell app lazy loads Reports app
const ReportsApp = lazy(() => import('@kulcare/reports/src/App'))

// Routes in shell
<Route path="/reports/*" element={<ReportsApp />} />

Development-Only Mock DataCopy Anchor Link

The app includes comprehensive mock data for development that is:

• Excluded from production builds using dynamic imports
• Conditionally loaded based on environment variables
• Type-safe with full TypeScript support

// API service with conditional mock loading
export const reportsApi = {
  async getConsolidatedReports(params) {
    if (import.meta.env.DEV && !import.meta.env.VITE_USE_REAL_API) {
      const { mockConsolidatedReports } = await import('./__mocks__/mockReportsData')
      return mockConsolidatedReports(params)
    }
    return apiClient.get('/reports/consolidated', { params })
  }
}

FeaturesCopy Anchor Link

1. DashboardCopy Anchor Link

• Overview of all reporting features
• Quick stats for revenue, commissions, and payouts
• Navigation to specific report sections

2. Consolidated ReportsCopy Anchor Link

• Revenue Analysis: Daily/weekly/monthly revenue trends
• Appointment Metrics: Completion rates, cancellations, no-shows
• Patient Demographics: Age, gender distribution, top conditions
• Location Performance: Comparative analysis across clinics
• Export Options: PDF, Excel, CSV formats

3. Commission TrackingCopy Anchor Link

• Rule Management: Configure commission rules (percentage, tiered, performance-based)
• Calculations: Automated commission calculations with manual adjustments
• Approval Workflow: Multi-step approval process with audit trail
• Payout Processing: Batch payout with multiple payment methods
• Analytics: Commission trends, top earners, role-based analysis

4. Revenue SharingCopy Anchor Link

• Configuration Management: Define stakeholder shares per location
• Automated Distribution: Calculate revenue shares based on configurations
• Payout Tracking: Monitor pending and completed payouts
• Trend Analysis: Revenue trends with growth metrics
• Stakeholder Management: Track individual stakeholder payouts

API ServicesCopy Anchor Link

Reports API (reportsApi)Copy Anchor Link

- getConsolidatedReports(params)
- getSavedReports()
- exportReport(reportId, format)
- generateReport(params)
- deleteReport(reportId)
- getReportTemplates()

Commissions API (commissionsApi)Copy Anchor Link

- getCommissionRules(filters)
- createCommissionRule(ruleData)
- updateCommissionRule(ruleId, updates)
- getCommissionCalculations(params)
- runCommissionCalculation(params)
- approveCommission(calculationId, notes)
- processPayout(calculationIds, paymentMethod)
- getCommissionAnalytics(params)

Revenue API (revenueApi)Copy Anchor Link

- getRevenueSharingConfigs(locationId)
- createRevenueSharingConfig(configData)
- updateRevenueSharingConfig(configId, updates)
- getRevenueSharingCalculations(params)
- getRevenueTrends(params)
- getStakeholderPayouts(params)
- processRevenueSharingPayout(payoutIds, paymentDetails)

Mock Data StructureCopy Anchor Link

Reports Mock DataCopy Anchor Link

• Time series revenue data
• Appointment statistics
• Patient demographics
• Location-wise breakdowns

Commission Mock DataCopy Anchor Link

• Commission rules (percentage, tiered, performance)
• User commission calculations
• Approval workflows
• Payout history

Revenue Mock DataCopy Anchor Link

• Revenue sharing configurations
• Stakeholder distributions
• Payout tracking
• Trend analysis

Environment ConfigurationCopy Anchor Link

# Use real API instead of mocks
VITE_USE_REAL_API=true

# API endpoint
VITE_API_URL=https://api.kulcare.com

DevelopmentCopy Anchor Link

Running StandaloneCopy Anchor Link

cd apps/reports
pnpm dev
# Opens at http://localhost:3004

Running with ShellCopy Anchor Link

pnpm dev
# Access via shell at http://localhost:3000/reports

Building for ProductionCopy Anchor Link

pnpm build --filter=@kulcare/reports

Feature FlagsCopy Anchor Link

The Reports app visibility is controlled by feature flags in the shell:

• ENABLE_CONSOLIDATED_REPORTS
• ENABLE_REVENUE_SHARING
• ENABLE_COMMISSION_TRACKING

Any of these flags being true will enable the Reports app in navigation.

Role-Based AccessCopy Anchor Link

• Admin/Owner: Full access to all features
• Doctor/Consultant: Limited to viewing their own commission data
• Staff: Access based on specific permissions

UI ComponentsCopy Anchor Link

Charts and VisualizationsCopy Anchor Link

• Line charts for trends (Recharts)
• Bar charts for comparisons
• Pie charts for distributions
• Tables with sorting and filtering

Forms and ModalsCopy Anchor Link

• Commission rule configuration
• Revenue sharing setup
• Date range pickers
• Export dialogs

Status IndicatorsCopy Anchor Link

• Badge components for statuses
• Progress indicators for calculations
• Real-time updates for job progress

TestingCopy Anchor Link

Unit TestsCopy Anchor Link

pnpm test --filter=@kulcare/reports

Manual TestingCopy Anchor Link

1. Verify mock data loads in development
2. Confirm mocks are excluded from production build
3. Test all CRUD operations with mock data
4. Verify exports work correctly
5. Test navigation between sections

Production ReadinessCopy Anchor Link

✅ Completed:

• Fully functional UI with all features
• Comprehensive mock data system
• Development-only mock loading
• API service layer ready for integration
• Role-based access controls
• Export functionality
• Responsive design

⏳ Pending (Backend required):

• Real API endpoints implementation
• Authentication integration
• Real-time updates
• File download for exports

V2 Features (Coming Soon)Copy Anchor Link

🚧 Advanced Analytics DashboardCopy Anchor Link

Status: Coming Soon

Enhanced analytics capabilities:

• AI-Powered Insights: Machine learning algorithms to identify trends and anomalies
• Predictive Forecasting: Revenue and patient flow predictions
• Custom KPI Builder: Create and track custom key performance indicators
• Automated Alerts: Smart notifications for significant changes
• Benchmarking: Compare performance against industry standards

🚧 Real-Time ReportingCopy Anchor Link

Status: Coming Soon

Live data streaming and updates:

• WebSocket Integration: Real-time data synchronization
• Live Dashboards: Auto-updating metrics and charts
• Instant Notifications: Push alerts for critical events
• Collaborative Viewing: Multiple users can view reports simultaneously
• Activity Feed: Real-time stream of financial activities

🚧 Custom Report BuilderCopy Anchor Link

Status: Coming Soon

Self-service report creation:

• Drag-and-Drop Designer: Visual report builder interface
• Template Library: Pre-built templates for common reports
• Custom Calculations: Create complex formulas and metrics
• Scheduled Reports: Automated generation and delivery
• Report Sharing: Secure sharing with stakeholders

🚧 Mobile Reports AppCopy Anchor Link

Status: Coming Soon

Native mobile experience:

• iOS and Android Apps: Native applications for better performance
• Offline Mode: Download and view reports without internet
• Touch-Optimized: Gestures for zooming and navigation
• Biometric Security: Face ID/Touch ID authentication
• Push Notifications: Real-time alerts on mobile

🚧 Integration HubCopy Anchor Link

Status: Coming Soon

Third-party integrations:

• QuickBooks Integration: Sync financial data automatically
• Payment Gateways: Stripe, Razorpay, PayPal analytics
• Google Analytics: Website traffic correlation with revenue
• SMS/WhatsApp: Automated report delivery via messaging
• API Marketplace: Connect with any third-party service

🚧 Compliance & AuditCopy Anchor Link

Status: Coming Soon

Enhanced compliance features:

• Regulatory Reports: GST, tax, and compliance reports
• Audit Trail Enhancement: Blockchain-based immutable logs
• Digital Signatures: Legally binding report approvals
• Role-Based Restrictions: Granular permission controls
• Data Retention Policies: Automated archival and purging