Multi-Tenancy Phase 1 — Provider Flow Implementation Spec¶

Patient completes intake → Consent given → Coordinator forwards case
    ↓
CaseShare created (copy mode, provider_snapshot redaction)
    ↓
Provider receives notification → Opens case in Provider Portal
    ↓
Views redacted patient data (pseudonymized, no PII)
    ↓
Submits quote (cost breakdown, timeline, notes)
    ↓
Quote appears in patient's match results for comparison

# app/models/provider_quote.py

class QuoteStatus(str, Enum):
    SUBMITTED = "submitted"
    EXPIRED = "expired"       # Set by query-time check: WHERE expires_at < NOW()
    ACCEPTED = "accepted"     # Patient selected this provider
    REJECTED = "rejected"     # Patient selected a different provider

class ProviderQuote(Base, UUIDPrimaryKeyMixin, TenantScopedMixin, TimestampMixin):
    """A provider's cost quote for a forwarded case."""

    __tablename__ = "provider_quotes"

    case_share_id: Mapped[str] = mapped_column(
        String(36), ForeignKey("case_shares.id"), nullable=False, index=True
    )
    provider_id: Mapped[str] = mapped_column(
        String(36), ForeignKey("providers.id"), nullable=False, index=True
    )

    # Cost breakdown (all in smallest currency unit)
    procedure_cost: Mapped[int] = mapped_column(Integer, nullable=False)
    currency: Mapped[str] = mapped_column(String(3), nullable=False, default="USD")

    # Itemized components (JSONB for flexibility)
    cost_breakdown: Mapped[dict] = mapped_column(FlexibleJSON, nullable=False, default=dict)
    # {
    #   "hospital_stay_nights": 5,
    #   "hospital_stay_cost": 150000,
    #   "implants_cost": 50000,
    #   "anesthesia_cost": 15000,
    #   "follow_up_visits": 2,
    #   "follow_up_cost": 20000,
    #   "other_items": [{"label": "...", "cost": ...}]
    # }

    total_cost: Mapped[int] = mapped_column(Integer, nullable=False)
    # Sum of procedure_cost + all breakdown items

    # Timeline
    estimated_start_date: Mapped[date | None] = mapped_column(Date, nullable=True)
    estimated_duration_days: Mapped[int | None] = mapped_column(Integer, nullable=True)
    validity_days: Mapped[int] = mapped_column(Integer, nullable=False, default=30)
    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)

    # Status
    status: Mapped[str] = mapped_column(String(20), nullable=False, default="submitted")
    notes: Mapped[str | None] = mapped_column(Text, nullable=True)

    # Who submitted
    submitted_by: Mapped[str] = mapped_column(String(255), nullable=False)
    # Clerk user ID of the provider staff member

class CaseForwardingService:

    async def forward_case_to_providers(
        self, db: AsyncSession, *,
        case_id: str,
        tenant_id: str,
        provider_tenant_ids: list[str],
        forwarded_by: str,  # coordinator's clerk user ID
        message: str | None = None,
    ) -> list[CaseShare]:
        """Forward a case to one or more provider tenants.

        IMPORTANT: Case must be in risk_cleared state. The state machine
        enforces consent_given → risk_review_pending → risk_cleared →
        providers_notified. Forwarding from consent_given is NOT allowed
        (risk review is mandatory per ADR-0018).

        This is ORCHESTRATION-LAYER code (like case_orchestrator.py), not
        a domain service. It coordinates across domains: case state, shares,
        redaction, notifications. Place in app/services/orchestration/.

        1. Validate case is in risk_cleared state
        2. Load case + EHR + patient data
        3. For each provider:
           a. Apply provider_snapshot redaction → RedactedCaseData
           b. Create CaseShare (copy mode, 30-day expiry)
           c. Store serialized RedactedCaseData in case_share.redacted_snapshot
           d. Send notification to provider
        4. Advance case state to providers_notified (via CaseLifecycleService)
        5. Return created shares
        """

    async def get_forwarded_case(
        self, db: AsyncSession, *,
        case_share_id: str,
        provider_tenant_id: str,
    ) -> RedactedCaseData:
        """Get redacted case data for a provider.

        Deserializes RedactedCaseData from the stored snapshot.
        Provider never queries the live patient data.
        """

# In case_shares table, add:
redacted_snapshot: Mapped[dict | None] = mapped_column(FlexibleJSON, nullable=True)

ALTER TABLE case_shares ADD COLUMN redacted_snapshot JSONB;

# Case inbox
GET  /api/v1/provider/cases
  → List all case_shares for the provider's tenant
  → Returns: case_number, procedure, age, status, forwarded_at, expires_at

# Case detail (redacted)
GET  /api/v1/provider/cases/{case_share_id}
  → Returns redacted_snapshot from CaseShare
  → Updates provider_status: RECEIVED → REVIEWING (first access)

# Submit quote
POST /api/v1/provider/cases/{case_share_id}/quote
  Body: { procedure_cost, currency, cost_breakdown, estimated_start_date,
          validity_days, notes }
  → Creates ProviderQuote, updates provider_status → QUOTED
  → Notifies coordinator

# Decline case
POST /api/v1/provider/cases/{case_share_id}/decline
  Body: { reason }
  → Updates provider_status → REJECTED
  → Notifies coordinator

# Request info (coordinator-initiated, provider sees result)
GET  /api/v1/provider/cases/{case_share_id}/info-requests
  → List pending info requests from coordinator

@router.get("/provider/cases")
@require_permission("case:read:forwarded")
async def list_provider_cases(...):

async def create_provider_tenant(
    provider_id: str,
    provider_name: str,
    admin_email: str,
) -> Tenant:
    """Create a Clerk organization and Curaway tenant for a provider."""

    # 1. Create Clerk org
    clerk_org = await clerk_client.organizations.create(
        name=provider_name,
        slug=slugify(provider_name),
    )

    # 2. Create Curaway tenant
    tenant = Tenant(
        name=provider_name,
        slug=slugify(provider_name),
        clerk_org_id=clerk_org.id,
        contact_email=admin_email,
        country_code=provider.country_code,
    )

    # 3. Invite admin
    await clerk_client.organizations.invite_member(
        org_id=clerk_org.id,
        email=admin_email,
        role="admin",
    )

    return tenant

provider_clerk_integration:
  default: false
  description: "Enable Clerk multi-org for provider tenants. When false, provider tenants are created without Clerk org."

apps/provider-app/              (existing scaffold)
  src/
    App.tsx                     (Clerk provider + router)
    pages/
      CaseInbox.tsx             (list of forwarded cases)
      CaseDetail.tsx            (redacted case viewer)
      QuoteBuilder.tsx          (cost breakdown form)
    components/
      CaseCard.tsx              (inbox card)
      RedactedEHRViewer.tsx     (shared-web EHR with redaction)
      QuoteForm.tsx             (cost breakdown form fields)
      ProviderNav.tsx           (sidebar navigation)
    services/
      providerApi.ts            (API client for provider endpoints)
    lib/
      provider-auth.ts          (Clerk provider context)

┌──────────────────────────────────────────────┐
│ Acibadem Maslak Hospital, Istanbul           │
│                                              │
│ Hospital Match    86%                        │
│ Your Readiness    78%                        │
│ Overall Fit       72%                        │
│                                              │
│ QUOTE RECEIVED                               │
│ Procedure         $6,500                     │
│ Hospital (5 nights) $1,500                   │
│ Follow-up (2 visits) $350                    │
│ ──────────────────────                       │
│ Total             $8,350                     │
│ Valid until May 18                            │
│                                              │
│ [Select This Provider]                       │
└──────────────────────────────────────────────┘

GET /api/v1/cases/{case_id}/quotes
  → Returns all quotes for the patient's case (from all providers)
  → Each quote includes provider name, total, breakdown, validity
  → No provider contact info until selection

Week 1: Backend foundation
  Day 1-2: ProviderQuote model + migration + repository
  Day 3-4: CaseForwardingService + redacted_snapshot column
  Day 5:   Provider API endpoints (inbox, detail, quote, decline)

Week 2: Auth + notifications
  Day 1-2: Clerk multi-org wiring (provider tenant creation)
  Day 3:   Provider notification service (email + webhook)
  Day 4-5: Feature flags + integration tests

Week 3: Provider portal frontend
  Day 1:   Provider app auth (Clerk) + routing + API client
  Day 2-3: CaseInbox + CaseDetail pages
  Day 4-5: QuoteBuilder form + submission

Week 4: Patient side + polish
  Day 1-2: Patient quote comparison view
  Day 3:   Provider selection flow (select → notify)
  Day 4-5: Integration testing + design review

xxxx_01_add_provider_quotes.py    → provider_quotes table + RLS
xxxx_02_add_redacted_snapshot.py  → redacted_snapshot column on case_shares

# In provider_quote_repository.py
def _with_expiry_status(self, query):
    """Quotes past expires_at are treated as EXPIRED regardless of DB status."""
    return query  # Status resolved in the service layer, not the query

# In provider API response serialization:
effective_status = quote.status
if quote.expires_at and quote.expires_at < datetime.now(timezone.utc):
    effective_status = "expired"