UHI First & Second Search — Architecture Audit

Audit Date: 2026-06-25 Scope: First search (broadcast) and second search (P2P) — FE + BE implementation vs UHI spec v2.0

1. Architecture OverviewCopy Anchor Link

Network RolesCopy Anchor Link

Kulcare operates in both EUA and HSPA roles on the same system. External EUAs can search Kulcare's HSPA, and Kulcare's EUA can search external HSPAs.

Bidirectional CommunicationCopy Anchor Link

Kulcare's backend handles both roles simultaneously:

Kulcare as EUA (initiating):

• /uhi/eua/search — broadcasts search to all HSPAs via Gateway
• /uhi/eua/search/p2p — sends P2P search to specific HSPA
• /uhi/eua/on_search — receives catalog responses from HSPAs
• /uhi/eua/on_init, /on_confirm, etc. — receives booking callbacks from HSPAs

Kulcare as HSPA (responding):

• /uhi/hspa/search — receives searches from ANY EUA (Gateway broadcast or direct P2P)
• /uhi/hspa/on_search — sends catalog to requesting EUA
• /uhi/hspa/init, /confirm, etc. — receives booking requests from EUAs

External EUAs that may search Kulcare's HSPA: eua-nha, aarogyaSetu.eua, etc. External HSPAs that Kulcare's EUA may search: healthSmarttech.hspa, eSushrutLite.hspa, hspa-nha, etc.

First Search (Broadcast) FlowCopy Anchor Link

Patient → Kulcare BE (EUA) → UHI Gateway → All HSPAs (including Kulcare HSPA)
                                                              ↓
                                                    Each HSPA responds
                                                              ↓
Kulcare ← Gateway ← on_search callbacks from all HSPAs
   ↓
Ably → Patient (real-time)

1. Patient fills search form → POST /uhi/eua/search
2. Kulcare BE logs UhiRequest with user_id, sends to Gateway
3. Gateway broadcasts to all registered HSPAs (including Kulcare's own HSPA)
4. Each HSPA logs webhook, builds catalog, sends on_search via Gateway
5. Kulcare receives on_search via Gateway, logs UhiWebhook, publishes to Ably
6. Patient receives real-time updates, then polls /results for complete data

Note: External EUAs (e.g., eua-nha) also send searches to Kulcare's HSPA via Gateway. Kulcare's HSPA receives these at /uhi/hspa/search and responds with its catalog.

Second Search (P2P) FlowCopy Anchor Link

Patient → Kulcare BE (EUA) → External HSPA (direct)
                                         ↓
                              on_search (direct callback)
                                         ↓
                              Kulcare → Ably → Patient

1. Patient selects a provider → navigates to slot selection
2. POST /uhi/eua/search/p2p with provider_uri, transaction_id, intent
3. Kulcare BE logs UhiRequest with user_id, sends directly to HSPA
4. External HSPA responds with time slots
5. Kulcare receives on_search directly, publishes to Ably, patient polls /results

2. Database SchemaCopy Anchor Link

uhi.requests — Outbound API callsCopy Anchor Link

uhi.webhooks — Inbound callbacksCopy Anchor Link

Note: Webhooks are received at two endpoint groups:

• /uhi/eua/on_* — Receives callbacks FROM external HSPAs (they respond to Kulcare's searches)
• /uhi/hspa/* — Receives requests FROM external EUAs (they search Kulcare's catalog)

3. Issues FoundCopy Anchor Link

🔴 CRITICAL — Must FixCopy Anchor Link

Issue 1: Ably Event Field Name MismatchCopy Anchor Link

File: patient/src/hooks/useUhiRealtime.ts

The frontend hook expects total_count but the backend sends total_providers.

// useUhiRealtime.ts — LINE 36
interface UhiSearchCompleteEvent {
  type: 'search_complete'
  transaction_id: string
  total_count: number  // ❌ WRONG — backend sends total_providers
  timestamp: string
}

# backend/domains/uhi/services/realtime_publisher.rb — LINE 47
channel.publish('search_complete', {
  total_providers: total_providers,  // ✓ CORRECT per UHI spec
  ...
})

Impact: UhiSearchCompleteEvent.total_count is always undefined. This could break any FE logic that relies on this field (e.g., showing total provider count).

Fix: Change frontend interface to use total_providers.

Issue 2: source_id Set to Wrong Value in EUA CallbacksCopy Anchor Link

Files:

• backend/domains/uhi/models/uhi_webhook.rb (affects all EUA inbound callbacks)
• backend/domains/uhi/controllers/eua/on_search_controller.rb
• backend/domains/uhi/controllers/eua/on_init_controller.rb
• backend/domains/uhi/controllers/eua/on_confirm_controller.rb
• backend/domains/uhi/controllers/eua/on_status_controller.rb
• backend/domains/uhi/controllers/eua/on_update_controller.rb
• backend/domains/uhi/controllers/eua/on_cancel_controller.rb
• backend/domains/uhi/controllers/eua/on_message_controller.rb

Bug: source_id is being set to context.provider_id (the HSPA that responded), but it should be context.consumer_id (the EUA that initiated the request).

# Current (WRONG)
source_id: payload.dig('context', 'provider_id')  # = "healthSmarttech.hspa"

# Should be
source_id: payload.dig('context', 'consumer_id')  # = "kulcare.eua"

Context fields in callbacks:

• context.consumer_id = "kulcare.eua" (the EUA that sent the original search)
• context.provider_id = "healthSmarttech.hspa" (the HSPA that is responding)

Impact:

• Webhook source_id logs are incorrect — they show the responder instead of the initiator
• Any logic relying on source_id to identify the EUA will break
• The /results endpoint filters by source_id which may not work correctly

Note: HSPA controllers are correct — they correctly use consumer_id as source_id:

# backend/domains/uhi/controllers/hspa/search_controller.rb — CORRECT
source_id: @raw_payload.dig('context', 'consumer_id')  # = "kulcare.eua"

Fix: Update UhiWebhook.log_inbound to use consumer_id first, then update all EUA controllers to pass correct value.

Issue 3: UhiProvider TypeScript Interface Missing items FieldCopy Anchor Link

File: patient/src/features/uhi/types/uhi.types.ts

The UhiProvider interface is missing the items array which is used in P2P search and booking.

// Current — MISSING items
export interface UhiProvider {
  id: string;
  source_id?: string;
  descriptor: { name: string; code?: string };
  categories?: UhiCategory[];
  fulfillments?: UhiFulfillment[];
  // items is used throughout but not defined!
  // items?: UhiItem[];  // MISSING
}

Usage throughout codebase:

• UhiSlotSelectionPage.tsx: provider.items?.find((i) => i.fulfillment_id === slot.id)
• UhiProviderCard.tsx: provider.items?.[0]?.price?.value
• uhiApi.ts P2P search: sends params.items in intent
• search_service.rb: echoes items in P2P payload

Impact: TypeScript errors when accessing items, potential runtime issues.

Fix: Add items?: UhiItem[] to UhiProvider interface.

🟡 FEATURES — ImprovementsCopy Anchor Link

Feature 4: Slot Selection Page — URL Date PersistenceCopy Anchor Link

File: patient/src/features/uhi/pages/UhiSlotSelectionPage.tsx

Currently, when a patient refreshes the slot selection page, the selected date is lost.

Current URL: /uhi/slots?tx={tx}&providerId={id}&sourceId={sourceId}

Requested URL: /uhi/slots?tx={tx}&providerId={id}&sourceId={sourceId}&date={YYYY-MM-DD}

Implementation:

1. Add date query param to URL
2. Read date on mount and use it as initial active date
3. Update URL when user changes date
4. Validate date is within the broadcast search's date_from → date_to range

Feature 5: Slot Selection Page — Date Dropdown Instead of TabsCopy Anchor Link

File: patient/src/features/uhi/components/UhiSlotGrid.tsx

Currently uses 7-day tab selector. Change to a date dropdown picker for better UX when:

• Date range is larger than 7 days
• Patient wants to navigate to a specific date

Feature 6: Slot Selection Page — Date Range ValidationCopy Anchor Link

File: patient/src/features/uhi/pages/UhiSlotSelectionPage.tsx

The date range shown in the slot grid should be limited to the original broadcast search's date range (date_from → date_to).

Currently:

• P2P search always sends 7 days or the selected date
• No validation that selected date is within broadcast search window

Requested behavior:

1. Store broadcast search date range in URL or state
2. Validate selected date is within range
3. Show message if date is outside range
4. Disable date picker options outside range

4. Correctly Implemented ✅Copy Anchor Link

First Search (Broadcast)Copy Anchor Link

Second Search (P2P)Copy Anchor Link

on_search Response (First & Second)Copy Anchor Link

HSPA Code (Receiving Searches)Copy Anchor Link

Kulcare's HSPA receives searches from ANY EUA including kulcare.eua, eua-nha, aarogyaSetu.eua, etc.

Real-Time (Ably)Copy Anchor Link

EUA Code (Receiving from External HSPAs)Copy Anchor Link

Kulcare's EUA endpoints (/uhi/eua/on_*) receive callbacks from ANY HSPA including kulcare.hspa, healthSmarttech.hspa, eSushrutLite.hspa, hspa-nha, etc.

OtherCopy Anchor Link

5. Action Items SummaryCopy Anchor Link

6. Reference DocumentationCopy Anchor Link

• UHI Spec: docs/guides/uhi/UHI Physical Consultation - Onboarding Document_v2.0.docx.txt
• Architecture Doc: docs/guides/uhi/search-flow-architecture.md