System Architecture¶

Full Dependency Map¶

Legend

:blue_square: Internal business function · :orange_square: External service (blackbox)

graph LR
    VerifyInsuranceCoverage(["InsurancePayer / VerifyInsuranceCoverage"]):::service
    FetchPatientRecord(["EHR / FetchPatientRecord"]):::service
    CheckFormulary(["Pharmacy / CheckFormulary"]):::service
    SubmitPriorAuth(["InsurancePayer / SubmitPriorAuth"]):::service
    CheckClinicalGuidelines(["ClinicalDB / CheckClinicalGuidelines"]):::service
    check_eligibility["check_eligibility"]:::func
    estimate_patient_cost["estimate_patient_cost"]:::func
    evaluate_prior_auth["evaluate_prior_auth"]:::func
    check_eligibility -->|.call| FetchPatientRecord
    check_eligibility -->|.call| VerifyInsuranceCoverage
    estimate_patient_cost --> check_eligibility
    evaluate_prior_auth -->|.call| FetchPatientRecord
    evaluate_prior_auth -->|.call| VerifyInsuranceCoverage
    evaluate_prior_auth -->|.call| CheckClinicalGuidelines
    evaluate_prior_auth -->|.call| SubmitPriorAuth

    classDef service fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#e65100
    classDef func fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#1565c0

Focus: Prior Authorization Workflow¶

Legend

:green_square: evaluate_prior_auth — entry point · :blue_square: Internal business function · :orange_square: External service (blackbox)

graph LR
    evaluate_prior_auth["evaluate_prior_auth"]:::entry
    CheckClinicalGuidelines(["ClinicalDB / CheckClinicalGuidelines"]):::service
    FetchPatientRecord(["EHR / FetchPatientRecord"]):::service
    SubmitPriorAuth(["InsurancePayer / SubmitPriorAuth"]):::service
    VerifyInsuranceCoverage(["InsurancePayer / VerifyInsuranceCoverage"]):::service
    evaluate_prior_auth -->|.call| FetchPatientRecord
    evaluate_prior_auth -->|.call| VerifyInsuranceCoverage
    evaluate_prior_auth -->|.call| CheckClinicalGuidelines
    evaluate_prior_auth -->|.call| SubmitPriorAuth

    classDef service fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#e65100
    classDef func fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#1565c0
    classDef entry fill:#e8f5e9,stroke:#2e7d32,stroke-width:3px,color:#2e7d32

Focus: Cost Estimation¶

Legend

:green_square: estimate_patient_cost — entry point · :blue_square: Internal business function · :orange_square: External service (blackbox)

graph LR
    estimate_patient_cost["estimate_patient_cost"]:::entry
    FetchPatientRecord(["EHR / FetchPatientRecord"]):::service
    VerifyInsuranceCoverage(["InsurancePayer / VerifyInsuranceCoverage"]):::service
    check_eligibility["check_eligibility"]:::func
    check_eligibility -->|.call| FetchPatientRecord
    check_eligibility -->|.call| VerifyInsuranceCoverage
    estimate_patient_cost --> check_eligibility

    classDef service fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#e65100
    classDef func fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#1565c0
    classDef entry fill:#e8f5e9,stroke:#2e7d32,stroke-width:3px,color:#2e7d32

Eligibility Decision Flow¶

flowchart TD
    A[Patient Request] --> B[Fetch Patient Record]
    B --> C[Verify Insurance]
    C -->|Active| D{Service Covered?}
    C -->|Inactive| E[NOT ELIGIBLE]
    D -->|Yes| F[Calculate Cost]
    D -->|No| G[NOT COVERED]
    F --> H{Deductible Met?}
    H -->|Yes| I[Patient pays copay only]
    H -->|No| J[Patient pays deductible + copay]

    style E fill:#ffcdd2,stroke:#c62828,color:#b71c1c
    style G fill:#ffcdd2,stroke:#c62828,color:#b71c1c
    style I fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20
    style J fill:#fff3e0,stroke:#e65100,color:#bf360c

Prior Authorization Sequence¶

@startuml
actor Provider
participant "Eligibility System" as sys
participant "EHR" as ehr
participant "Insurance Payer" as ins
participant "Clinical DB" as cdb

Provider -> sys : evaluate_prior_auth(patient_id, procedure)

sys -> ehr : FetchPatientRecord(patient_id)
ehr --> sys : {age, conditions, member_id}

sys -> ins : VerifyInsuranceCoverage(member_id, procedure)
ins --> sys : {active, plan, covered_services}

alt Insurance not active
    sys --> Provider : DENIED: Insurance not active
else
    sys -> cdb : CheckClinicalGuidelines(procedure, conditions)
    cdb --> sys : {medically_necessary, guideline}

    alt Not medically necessary
        sys --> Provider : DENIED: Not medically necessary
    else
        sys -> ins : SubmitPriorAuth(request)
        ins --> sys : {auth_id, status: "approved"}
        sys --> Provider : APPROVED: auth_id
    end
end
@enduml

PlantUML Source

@startuml
actor Provider
participant "Eligibility System" as sys
participant "EHR" as ehr
participant "Insurance Payer" as ins
participant "Clinical DB" as cdb

Provider -> sys : evaluate_prior_auth(patient_id, procedure)

sys -> ehr : FetchPatientRecord(patient_id)
ehr --> sys : {age, conditions, member_id}

sys -> ins : VerifyInsuranceCoverage(member_id, procedure)
ins --> sys : {active, plan, covered_services}

alt Insurance not active
    sys --> Provider : DENIED: Insurance not active
else
    sys -> cdb : CheckClinicalGuidelines(procedure, conditions)
    cdb --> sys : {medically_necessary, guideline}

    alt Not medically necessary
        sys --> Provider : DENIED: Not medically necessary
    else
        sys -> ins : SubmitPriorAuth(request)
        ins --> sys : {auth_id, status: "approved"}
        sys --> Provider : APPROVED: auth_id
    end
end
@enduml

External Services¶

EHR (Electronic Health Records)¶

class FetchPatientRecord(ExternalService):
    """Retrieve patient demographics and medical history (Blackbox)."""

    component_name = "EHR"

    def execute(self, patient_id: str) -> PatientRecord:
        pass  # type: ignore[return-value]

    def mock(self, patient_id: str) -> MockResponse:
        return MockResponse(data=PatientRecord(
            patient_id=patient_id,
            age=45,
            conditions=["hypertension", "diabetes_type2"],
            member_id="INS-001234",
        ))

Insurance Payer¶

class VerifyInsuranceCoverage(ExternalService):
    """Real-time eligibility check with the insurance payer (Blackbox)."""

    component_name = "InsurancePayer"

    def execute(self, member_id: str, service_code: str) -> InsuranceCoverage:
        pass  # type: ignore[return-value]

    def mock(self, member_id: str, service_code: str) -> MockResponse:
        return MockResponse(data=InsuranceCoverage(
            active=True,
            plan="PPO Gold",
            copay=25.0,
            deductible_remaining=500.0,
            out_of_pocket_max=3000.0,
            covered_services=["preventive", "diagnostic", "surgical"],
        ))

    def mock_error(self, member_id: str, service_code: str) -> MockErrorResponse:
        return MockErrorResponse(
            error_code="MEMBER_NOT_FOUND",
            error_message="Member ID not found in payer system.",
            http_code=404,
        )

Pharmacy / Formulary¶

class CheckFormulary(ExternalService):
    """Check whether a medication is covered by the patient's plan (Blackbox)."""

    component_name = "Pharmacy"

    def execute(self, plan_id: str, medication_code: str) -> FormularyInfo:
        pass  # type: ignore[return-value]

    def mock(self, plan_id: str, medication_code: str) -> MockResponse:
        return MockResponse(data=FormularyInfo(
            covered=True,
            tier=2,
            requires_prior_auth=False,
            generic_available=True,
        ))

Clinical Guidelines¶

class CheckClinicalGuidelines(ExternalService):
    """Check clinical necessity against evidence-based guidelines (Blackbox)."""

    component_name = "ClinicalDB"

    def execute(self, procedure_code: str, conditions: list) -> ClinicalGuideline:
        pass  # type: ignore[return-value]

    def mock(self, procedure_code: str, conditions: list) -> MockResponse:
        return MockResponse(data=ClinicalGuideline(
            medically_necessary=True,
            guideline="AHA-2023-HBP-MGMT",
            evidence_level="A",
            notes="Recommended for patients with uncontrolled hypertension",
        ))