@heudia/referral-management

Referral dashboard, queue, and analytics MFA package — Lit web components backed by Firebase. Replaces the PaaS Angular dashboard at paas/amc/src/app/dashboard for the referral surface.

Out of scope: the Referral Action Center (deferred — AMC Insights Care Plan handles care management for now) and the referral submission forms (those live in packages/components/{self,clinical}-referral-form).

Screens

Each screen is a single custom element mounted by the host app on its own route.

| Element | Purpose | | --- | --- | | <rm-action-center> | Network + your-organization KPI tiles | | <rm-review-referrals> | Clinical inbound queue, send-to-service-group, stacked bar chart | | <rm-new-self-directed> | Self-directed queue with date-window filters | | <rm-new-clinical> | Clinical inbound — spec gap, phase 6 | | <rm-manage-referrals> | Active referrals table with program filters + activity chart | | <rm-referral-history> | Closed/expired view, stacked bar + activity chart |

Architecture

src/
  models/      shared types — Referral, KpiTile, TimeWindow, UserRole, RecordLock
  services/    backend-agnostic interfaces (IReferralService, IAnalyticsService,
               IAuthService, ILockService) + in-memory mock implementations
  state/       Lit reactive controllers (phase 2+)
  elements/    custom elements (phase 3+)

The host app constructs concrete service instances and injects them — Lit elements never import Firebase directly.

Firebase custom claims contract

FirebaseAuthService reads the user's identity and authorization scope from Firebase ID-token custom claims. The host app's Cloud Function (or Admin SDK call) must set claims in this shape — anything else is treated as an unauthenticated user.

interface ReferralAuthClaims {
  roles: Array<'network-admin' | 'org-admin' | 'org-user'>;
  primaryOrg: {
    uuid: string;
    name: string;
    serviceGroupIds?: string[];
  };
  additionalOrgs?: Array<{
    uuid: string;
    name: string;
    serviceGroupIds?: string[];
  }>;
}

Notes:

• Unknown role strings are silently dropped; the user ends up with no roles rather than failing closed (use requireAuth({ roles: [...] }) to enforce).
• primaryOrg is required — a user with no primary org cannot use this dashboard.
• additionalOrgs is optional and enables multi-org users to switch context via setActiveOrg(uuid).
• A user with network-admin passes every canActOn(orgUuid) check.

Phased delivery

1. Scaffold (this phase) — package wired up, types locked, mock services.
2. Auth + org scope — Firebase Auth wrapper, custom-claims-based role checks, reactive currentUser / currentOrg controllers.
3. Shared widgets — rm-kpi-tile, rm-referrals-over-time-chart, rm-activity-chart, rm-referral-table.
4. Action Center + Review Referrals — first KPI-heavy screens.
5. Self-Directed + Manage — queue UX, assign popover, record locking, program filter chips.
6. History + New Clinical — closed-state view + clinical inbound.

Reference

Requirements: docs/referral/analytics/paas-referral-analytics.md PaaS source being ported: paas/amc/src/app/dashboard