# FHIR Configuration Guide

## Current Status

| Component | Status |
|-----------|--------|
| Infrastructure | ✅ Ready |
| CSP Applications | ✅ Created |
| Endpoint | ✅ Port 52773 → IRIS HTTP |
| Synthetic CapabilityStatement | ✅ API Gateway serves `/fhir/metadata` |
| IRIS FHIR Module (Community) | ⭕ Not installed — synthetic endpoint via API Gateway |

> **Note**: The InterSystems IRIS Community Edition does not include `HS.FHIR.Config.Root` or the full FHIR production classes. The API Gateway on port 58080 serves a **synthetic FHIR CapabilityStatement** and proxies `/fhir/*` requests to IRIS.

## Accessing FHIR

### Via API Gateway (Recommended)

```bash
# CapabilityStatement
curl http://localhost:58080/fhir/metadata | jq .

# Resource lookup (returns OperationOutcome if FHIR module not installed)
curl http://localhost:58080/fhir/Patient/101 | jq .
```

The synthetic CapabilityStatement advertises:
- `Patient`, `Claim`, `Coverage`, `Organization`, `Practitioner`
- `CommunicationRequest`, `Task`, `Bundle`, `DocumentReference`
- `RiskAssessment` (predictive models)

### Via IRIS Direct (port 52773)

```bash
curl http://localhost:52773/fhir/r4/metadata
curl http://localhost:52773/fhir/r4/Patient
```

## FHIR Resources Mapped to BRAINSAIT Data

| FHIR Resource | Source System | Description |
|---------------|---------------|-------------|
| `Patient` | HNH + Oracle EHRs | Patient demographics |
| `Encounter` | Hospital systems | Clinical visits |
| `Condition` | Clinical diagnoses | Medical conditions |
| `MedicationRequest` | NPHIES | Prescriptions |
| `Claim` | NPHIES | Insurance claims |
| `Coverage` | NPHIES | Insurance coverage |
| `CarePlan` | Clinical pathways | Treatment plans |
| `Observation` | Labs & vitals | Lab results, vital signs |
| `DiagnosticReport` | Imaging & pathology | Radiology, lab reports |
| `CommunicationRequest` | NPHIES | Claim communication requests |
| `RiskAssessment` | **Predictive Models** | Readmission, denial, ED utilization, interaction, no-show |

## Pulse Agent FHIR Resources

All **19** Pulse agents consume and produce FHIR R4 resources:

### Clinical Agents (12)

| Agent | Primary FHIR Resources |
|-------|----------------------|
| Summary | `Patient`, `Encounter`, `Observation`, `Composition` |
| Prior Auth | `Procedure`, `Claim`, `ClaimResponse`, `Coverage` |
| Gaps in Care | `DiagnosticReport`, `Observation`, `CarePlan` |
| Medication Safety | `MedicationRequest`, `MedicationDispense`, `AllergyIntolerance` |
| Care Plan | `CarePlan`, `Goal`, `ActivityDefinition` |
| Clinical Trials | `ResearchStudy`, `Group`, `Evidence` |
| Readmission Risk | `RiskAssessment`, `Observation`, `Encounter` |
| Triage | `Encounter`, `Observation`, `Condition` |
| Imaging Followup | `ImagingStudy`, `DiagnosticReport`, `ServiceRequest` |
| Lab Explainer | `Observation`, `DiagnosticReport`, `Specimen` |
| NL Query | `Parameters`, `Bundle` |
| SDOH Referral | `ServiceRequest`, `Task`, `Organization` |

### Predictive Models (5)

| Agent | Primary FHIR Resource | Key Fields |
|-------|----------------------|------------|
| Predict Readmission | `RiskAssessment` | `prediction[].probabilityDecimal`, `mitigations[]` |
| Predict PA Denial | `RiskAssessment` | `prediction[].probabilityDecimal`, `riskFactors[]` |
| Predict ED Util | `RiskAssessment` | `predictions[].when.value` (7d + 30d) |
| Predict Interaction | `RiskAssessment` | `predictions[].medications`, `predictions[].risk` |
| Predict No-Show | `RiskAssessment` | `prediction[].probabilityDecimal`, `interventions[]` |

### Integration Agents (2)

| Agent | Primary FHIR Resource |
|-------|----------------------|
| Chat | `Parameters` |
| HF Models | `Parameters` |

## Query Examples

```bash
# FHIR metadata
curl 'http://localhost:58080/fhir/metadata' -H "Accept: application/fhir+json"

# Get patient summary via Pulse
curl "http://localhost:58080/linc/summary?patient=P-5842" | jq .

# Search clinical trials via Pulse
curl "http://localhost:58080/linc/clinical-trials?patient=P-5842" | jq .

# Predictive: readmission risk as RiskAssessment
curl "http://localhost:58080/linc/predict-readmission?patientId=P001" | jq .

# Predictive: drug interactions as RiskAssessment
curl "http://localhost:58080/linc/predict-interaction?patientId=P005&medications=metformin,lisinopril,warfarin,atorvastatin" | jq .
```

## Synthetic CapabilityStatement

The API Gateway serves a synthetic FHIR R4 CapabilityStatement at `/fhir/metadata`:

```json
{
  "resourceType": "CapabilityStatement",
  "status": "active",
  "fhirVersion": "4.0.1",
  "format": ["application/fhir+json"],
  "rest": [{
    "mode": "server",
    "resource": [
      { "type": "Patient", "interaction": [{"code": "read"}, {"code": "search-type"}] },
      { "type": "Claim", "interaction": [{"code": "read"}, {"code": "search-type"}] },
      { "type": "RiskAssessment", "interaction": [{"code": "read"}] },
      { "type": "Coverage", "interaction": [{"code": "read"}, {"code": "search-type"}] },
      { "type": "Organization", "interaction": [{"code": "read"}, {"code": "search-type"}] },
      { "type": "Practitioner", "interaction": [{"code": "read"}, {"code": "search-type"}] }
    ]
  }]
}
```

## Performance Optimization

When FHIR is fully installed:
- **Cache Strategy**: Aggressive, TTL 3600s
- **Connection Pooling**: Max 100, Min Idle 10, Acquire 30s
- **Compression**: GZIP for responses >1KB

## Security

1. **SSL/TLS**: Cloudflare edge terminates SSL for public access
2. **Authentication**: Bearer token + X-API-Key validation on sensitive paths
3. **Rate Limiting**: 100 requests/min per IP (via Python security module)
4. **Audit Logging**: All auth failures logged to JSON audit trail
5. **CORS**: Restricted origins in production

## Reference

- [FHIR R4 Specification](http://hl7.org/fhir/R4/)
- [IRIS FHIR Documentation](https://docs.intersystems.com/latest/csp/docbook/DocBook.UI.Portal.Title.cls?KEY=HSFHIR)
- [RiskAssessment FHIR Resource](https://hl7.org/fhir/R4/riskassessment.html)