Provider Network

What this module does

Fertility agencies work with a network of external professionals: IVF clinics, reproductive attorneys, escrow agencies, genetic counselors, and psychologists. This module manages:

• Building and maintaining the agency’s provider network
• Assigning providers to specific cases
• Giving providers a limited portal where they can view case information
• Controlling what case data is shared with each provider

Business value

Providers need access to specific case information to do their jobs — a clinic needs to see test results; an attorney needs to see match details. But providers should not see everything about every case. This module gives agencies fine-grained control over what gets shared with whom.

Key files

• Directoryorchid/

  • Directorymodels/

    • provider.py 23 KB — Provider, CaseProvider, CaseProviderExternal, ProviderUser, CaseProviderExternalMatchsheet, ProviderNote, 12 total classes
    • clinic.py Clinic, ClinicContact, ClinicDocument
  • Directoryviews/

    • admin_providers.py 25 KB — provider management admin UI
    • provider.py 7 KB — provider portal UI (/provider)
    • provider_network.py provider network overview UI
  • Directoryapi/

    • providernetwork.py 31 KB — provider network API
    • external_pn.py 67 KB — external provider network API
    • provider_auth.py 2 KB — provider token auth API
  • Directoryutils/

    • providernetwork.py 5 KB — provider network utilities
    • providernetwork_wrapper.py 5 KB — provider network wrapper

Three overlapping concepts

Understanding the provider model requires distinguishing three related but different concepts:

graph TD
    Provider["Provider\n(an organization:\nIVF Clinic, Attorney, etc.)"]
    ProviderUser["ProviderUser\n(a person at that organization\nwho has a login)"]
    CaseProvider["CaseProvider\n(assignment: this Provider\nis working on this Case)"]

    Provider --> ProviderUser
    CaseProvider --> Provider
    CaseProvider --> Case

Model	What it represents
Provider	An external organization (the clinic itself)
ProviderUser	A specific person at that organization who has portal access
CaseProvider	The assignment linking a Provider to a specific Case

All three must exist for a provider to see a case. A Provider without a ProviderUser cannot log in. A ProviderUser without a CaseProvider assignment cannot see any cases.

Provider portal

External providers access Orchid at /provider/. The portal is completely separate from the admin and user portals.

What providers can see in the portal:

• Cases where they have a CaseProvider assignment
• Documents and match sheets that the agency has explicitly shared
• Case notes marked as shareable with the provider

What providers cannot see:

• Any case they are not assigned to
• Internal agency notes
• Other providers’ assignments
• Financial information not explicitly shared

CaseProviderExternal — API-based providers

Some providers access case data through the external API rather than the portal. CaseProviderExternal tracks these integrations. Key models:

• CaseProviderExternal — the external provider assignment
• CaseProviderExternalDocument — documents shared via the external API
• CaseProviderExternalMatchsheet — match sheets shared externally
• CaseProviderExternalMatchsheetShare / CaseProviderExternalMatchsheetList — sharing history

Clinic portal subdomains

CLINIC_PORTAL_SUBDOMAINS in orchid/views/admin_providers.py is a hardcoded list of subdomains that get the clinic portal — a special variant of the provider portal with clinic-specific features.

Adding a new clinic portal requires a code change

The clinic portal subdomain list is hardcoded in Python, not stored in the database. To add a new subdomain to the clinic portal, you must add it to CLINIC_PORTAL_SUBDOMAINS in admin_providers.py and deploy.

Provider auth

Provider authentication uses a token-based system (GurgleToken or provider-specific tokens) rather than the session-based system used by admins and users. The /api/provider-auth endpoint handles token validation.

Gotchas

Three required records

A common support issue: a provider says “I can’t see my case.” The checklist: (1) Does a Provider record exist? (2) Does a ProviderUser record exist linked to that Provider? (3) Does a CaseProvider record exist linking that Provider to the Case? All three are required.

CaseProviderExternal is different from CaseProvider

CaseProvider = portal access. CaseProviderExternal = API-based access. They are different models for different provider types. Don’t confuse them when debugging provider access issues.