Skip to content

Provider Portal — Design Brief

Status: Approved — ready for /impeccable craft Companion spec: multi-tenancy-phase1-provider-flow-impl.md Target app: apps/provider-app/ (port 8082)

1. Feature Summary

A Linear-style professional tool for hospital patient coordinators to receive forwarded medical travel cases, review redacted patient records, and submit cost quotes within a 48-hour SLA. Desktop-primary, urgency-driven, with a contextual AI chat assistant that will evolve into the primary interface over time.

2. Primary User Action

Triage and respond to the most urgent case. Speed to quote = competitive advantage (first-mover advantage, provider doesn't know about competitors).

3. Users

  • Primary: Hospital international patient coordinator (dedicated role, 5-15 cases/day)
  • Secondary: Surgeon/department head (reviews clinical details, may act on cases)
  • Context: Desktop in hospital office, professional, familiar with clinical terminology
  • State of mind: Efficient, task-oriented, time-pressured (48hr SLA)

4. Design Direction

Linear-inspired: minimal chrome, keyboard-navigable, urgency-first.

  • Not warm — professional tool. Confidence and speed over reassurance.
  • Teal #008B8B used sparingly (actions, active states). Deep Ocean #004D4D for nav.
  • Data is the hero, not the UI. Dense tables, not card grids.
  • Personality: precise, capable, fast. "Instrument panel" not "dashboard."
  • No completion rings, no layer summaries — providers don't care about patient journey progress.

5. Layout Strategy

┌─────────────────────────────────────────────────────┐
│ [Nav]  Case Inbox                    [Search] [?]   │
├──────┬──────────────────────────────────────────────┤
│      │                                              │
│ Nav  │  Main content (single-column flow)           │
│ 56px │  inbox → case detail → quote (inline)        │
│      │                                              │
│      ├──────────────────────────────────────────────┤
│      │  AI Assistant (280px, collapsible right)     │
│      │  "Ask about this case..."                    │
└──────┴──────────────────────────────────────────────┘

Visual hierarchy: Urgency → Procedure + Age → Deadline → Status → Actions

6. Key States

State User sees User feels
Empty inbox "No cases yet" Informed
Cases pending Urgency-sorted, deadline countdown Clear priority
Case detail Redacted EHR, clinical data Sufficient to assess
Quote draft Procedure-specific line items Structured
Quote submitted Confirmation inline Done
Case expired Grayed, "Expired" badge Clear
Case selected Green "Selected" Rewarding
SLA warning Amber "5h remaining" Urgent, not panicked
AI assistant open Right panel, case context Helpful

7. Interaction Model

  • Inbox: Urgency sort, ↑/↓ navigate, Enter open, D decline, Q quote
  • Case Detail: Full page, EHR inline (not drawer), sticky action bar
  • Quote Builder: Inline below case detail, dynamic line items, Cmd+Enter submit
  • AI Assistant: Cmd+K toggle, answers case questions, suggests pricing from history
  • Multi-staff: View simultaneously, optimistic lock on quote edit

8. Quote Builder

  • Procedure-specific templates from backend config + blank start option
  • Dynamic line items per procedure type
  • Auto-calculated total (server-validated)
  • "Add line item" for custom items
  • Seed data needed for demo/showcase

9. Notifications

  • Email (QStash → SendGrid) for new cases
  • In-app push for urgent cases
  • Webhook for providers with integration
  • spatial-design.md — table density, data hierarchy
  • interaction-design.md — forms, keyboard nav, inline actions
  • typography.md — data-dense type scale
  • motion-design.md — Linear-style page transitions
  • ux-writing.md — professional tone, SLA copy

11. Open Questions

  1. Procedure → line item template mapping: backend seed data structure TBD
  2. Quote revision policy: one update within 48h, then locked
  3. Currency conversion display: provider currency + USD estimate