Production Integration Architecture

+-------------------+ +--------------------+ +------------------------+ | Pharmacy Mgmt | | EHR / Practice | | Contract Pharmacy | | System (PMS) | | Mgmt System | | Network | | e.g. QS/1 | | e.g. Epic/athena | | e.g. Walgreens, CVS | +--------+----------+ +---------+----------+ +-----------+------------+ | | | | NCPDP D.0 | FHIR R4 | NCPDP / 834 | Claim Data | Patient/Encounter | Claim Referrals v v v +------------------------------------------------------------------------+ | | | 340B ELIGIBILITY PRE-VALIDATION ENGINE | | | | +------------------+ +-------------------+ +---------------------+ | | | Claim Intake | | Rules Engine | | Audit & Reporting | | | | FHIR R4 Parser | | 8 HRSA Rules | | Per-Rule Logging | | | | NDC Lookup | | Duplicate Discount | | HRSA Audit Export | | | +------------------+ | Carve-in/out | | Analytics Dashboard | | | +-------------------+ +---------------------+ | | | | +------------------+ +-------------------+ +---------------------+ | | | Patient Index | | Provider Registry | | Coverage Resolver | | | | MRN Matching | | NPI Validation | | Medicaid FFS Check | | | | Org Registration | | Affiliation Check | | MEF Lookup | | | +------------------+ +-------------------+ +---------------------+ | | | +-----+--------------+--------------+-------------------+----------------+ | | | | v v v v +----------+ +-----------+ +-------------+ +------------------+ | HRSA | | State | | Medicaid | | 340B OPAIS | | OPAIS | | Medicaid | | Exclusion | | Entity | | API | | Agency | | File (MEF) | | Registration DB | | Registry | | Rebate DB | | CMS.gov | | | +----------+ +-----------+ +-------------+ +------------------+

Data Flow: Claim Validation Lifecycle

1. CLAIM RECEIVED 2. DATA ENRICHMENT 3. RULE EXECUTION PMS submits claim Lookup patient MRN Run 8 HRSA rules via NCPDP D.0 Resolve encounter in parallel: or FHIR Verify provider NPI Check coverage R1: Patient Registration R2: Qualifying Encounter 4. DECISION R3: Provider Affiliation ELIGIBLE -> 340B price applied R4: Rx-Encounter Link INELIGIBLE -> WAC/GPO price applied R5: Covered Outpatient Drug REVIEW -> Manual pharmacist review R6: Duplicate Discount (FFS/MCO) R7: Timing Window (30 days) 5. AUDIT TRAIL R8: Active OPA Registration Every decision logged with per-rule reasoning for HRSA audit readiness

The 8 HRSA Eligibility Rules

  • Rule 1: Patient Registration - Patient must be registered at the covered entity (managing_organization_id match)
  • Rule 2: Qualifying Encounter - Must have an AMB (outpatient) encounter at the registered site
  • Rule 3: Provider Affiliation - Prescriber must be employed/contracted by the covered entity
  • Rule 4: Rx-Encounter Link - Prescription must reference a valid encounter
  • Rule 5: Covered Outpatient Drug - Drug must be a covered outpatient drug (not inpatient-only)
  • Rule 6: Duplicate Discount Prevention - Medicaid FFS + carve-in/carve-out + MEF check
  • Rule 7: Timing Validation - Prescription within 30 days of qualifying encounter
  • Rule 8: Active OPA Registration - Organization OPA status must be active with HRSA

Technology Stack

  • API Layer FastAPI Python 3.12 Pydantic v2
  • Data Models FHIR R4 SQLAlchemy 2.0
  • Database SQLite (WAL mode) - production: PostgreSQL
  • Frontend Vanilla JS CSS Custom Properties
  • API Docs OpenAPI 3.0 Swagger UI
  • Deployment Uvicorn systemd

FHIR R4 Resource Mapping

FHIR Resource | 340B Usage | Key Fields -----------------------+--------------------------------------+---------------------------------- Organization | Covered Entity (FQHC, DSH, etc.) | opa_id, opa_status, entity_type Practitioner | Prescribing Provider | npi, organization_id, status Patient | Registered Patient | mrn, managing_organization_id Encounter | Qualifying Visit | class (AMB/IMP), period, org_id MedicationRequest | Prescription Claim | ndc_code, encounter_id, authored_on Coverage | Insurance/Payer | type (FFS/MCO), carve_designation

Production Scaling Considerations

Current Demo

  • SQLite single-file database
  • Synchronous rule execution
  • Single Uvicorn worker
  • In-process validation

Production Path

  • PostgreSQL with read replicas
  • Async rule execution with Celery
  • Horizontal scaling with K8s
  • Redis caching for MEF/OPAIS lookups
  • FHIR Bulk Data API for batch imports
  • HL7 FHIR Subscription for real-time

Contract Pharmacy Flow

Patient visits FQHC FQHC prescribes medication Patient fills at contract pharmacy (qualifying encounter) (linked to encounter) (e.g., Walgreens, CVS) | | | v v v +----------------+ +-----------------+ +-----------------+ | Encounter | | MedicationReq | | Dispensing Event | | class: AMB |---------->| encounter_id |<-------------| NDC, quantity | | org: FQHC | | prescriber: NPI | | claim_id | +----------------+ +-----------------+ +-----------------+ | | v | +------------------+ | | 340B Validator |<--------------------+ | 8 HRSA Rules | | Decision: Y/N/R | +------------------+ | v 340B Price or WAC Price

API Endpoints