DICOM File Support -- Phase 1¶

Status: Proposed Author: SD Created: 2026-04-10 GitHub Issue: #147 Branch: feat/dicom-support

1. Overview and Motivation¶

What¶

Accept DICOM (.dcm/.dicom) medical imaging files in the Curaway upload flow, extract structured metadata (body part, modality, study date, laterality, patient demographics), parse DICOM-SR (Structured Reports) for radiology findings, de-identify patient PII from headers before provider forwarding, auto-match imaging metadata against procedure requirements, and render a thumbnail preview in the EHR drawer.

Why¶

• Patients have DICOM files. Radiology departments frequently provide imaging on CD/USB as DICOM, not PDF. Patients currently cannot upload these -- they must convert to PDF first, losing structured metadata.
• Structured metadata > OCR. DICOM headers contain machine-readable body part, modality, study date, and laterality. This is 100% accurate data that the OCR + LLM pipeline would otherwise have to infer from free text with lower confidence.
• DICOM-SR carries radiology findings. Structured Reports embedded in DICOM files contain the radiologist's findings, measurements, and impressions in a parseable format -- no OCR needed.
• Procedure requirement matching. Auto-matching BodyPartExamined=KNEE + Modality=MR against a TKR procedure's "Knee MRI" requirement is deterministic and instant.
• De-identification is mandatory. DICOM headers contain patient name, DOB, and medical record numbers. These must be stripped before forwarding to international providers (GDPR + HIPAA Safe Harbor).
• Cross-border value. Patients traveling from US/UK/UAE to India/Turkey/Thailand often carry imaging on disc. Supporting DICOM directly removes a friction point in the onboarding flow.

What This Is Not¶

• Not a full PACS viewer. No windowing, level adjustment, or multi-frame cine playback.
• Not multi-file DICOM series handling (Phase 2).
• Not DICOM networking (C-STORE, C-FIND, WADO-RS) -- that is post-Series A.
• Not DICOM-RT (radiation therapy) support.

2. Architecture Decisions¶

Where dicom_parser.py Fits¶

New service at app/services/dicom_parser.py -- sits alongside document_processing.py in the services layer. It is a pure utility module: takes bytes in, returns structured dict out. No DB access, no side effects.

Upload flow (existing)
  |
  v
document_service.confirm_upload()
  |
  +-- file_type == "dicom" ?
  |     |
  |     YES --> dicom_parser.parse_dicom(file_bytes)
  |     |         returns: {metadata, sr_findings, thumbnail_bytes, deidentified_bytes}
  |     |
  |     +-- Store deidentified_bytes to R2 (overwrite original)
  |     +-- Store thumbnail to R2 ({storage_key}_thumb.png)
  |     +-- Save metadata + sr_findings to doc.extracted_data
  |     +-- Skip OCR, go straight to run_post_ocr_pipeline() with extracted text from SR
  |     |
  |     NO --> existing OCR pipeline (unchanged)
  |
  v
run_post_ocr_pipeline()  <-- receives SR text or metadata-derived text
  |
  v
Clinical Context Agent --> FHIR resources --> requirement matching --> EHR rebuild

Key Design Choices¶

3. Implementation Checklist¶

Tier 1: Opus (Architecture, Clinical Logic, Security)¶

• [ ] O1: app/services/dicom_parser.py -- core parser module [NEW FILE]
• parse_dicom(file_bytes: bytes) -> DicomParseResult -- main entry point
• extract_metadata(ds: pydicom.Dataset) -> dict -- pull structured tags
• extract_sr_findings(ds: pydicom.Dataset) -> list[SRFinding] -- walk SR content tree
• deidentify(ds: pydicom.Dataset) -> pydicom.Dataset -- strip PII tags per Safe Harbor
• generate_thumbnail(ds: pydicom.Dataset) -> bytes | None -- pixel data to PNG

• build_text_representation(metadata: dict, findings: list) -> str -- synthesize text for Clinical Context Agent

• [ ] O2: De-identification tag list and logic [IN dicom_parser.py]

• Implement Safe Harbor tag stripping (see Section 6)
• Replace stripped values with safe placeholders (e.g., "DEIDENTIFIED")
• Preserve all clinical tags (BodyPartExamined, Modality, StudyDate, etc.)
• Write to new Dataset, never modify-in-place on the input

• Log deidentification event to audit table (tag count stripped, no PII values)

• [ ] O3: DICOM-SR parsing logic [IN dicom_parser.py]

• Walk ContentSequence recursively
• Extract TEXT, NUM, CODE, PNAME, DATE, TIME, UIDREF, COMPOSITE value types
• Map SR concept names to clinical meaning (see Section 7)

• Return structured findings list

• [ ] O4: Wire into document_processing.py [MODIFY]

• Add DICOM branch in the processing pipeline
• Skip OCR for DICOM files
• Pass SR text + metadata-derived text to run_post_ocr_pipeline()

• Set ocr_method = "dicom_metadata" for DICOM files

• [ ] O5: Wire into attachment_handler.py [MODIFY]

• Add DICOM detection in process_attachments()
• When file_type == "dicom", skip inline OCR, use extracted_data directly

• Set report_type = "imaging" for Clinical Context Agent

• [ ] O6: Auto-match body part + modality against procedure requirements [MODIFY requirement_matcher.py]

• New function: match_dicom_metadata_to_requirements(metadata, proc_reqs) -> list[dict]
• Match BodyPartExamined + Modality against requirement descriptions

• Higher confidence than LLM matching (deterministic, 0.95+ confidence)

• [ ] O7: FHIR ImagingStudy resource generation [MODIFY clinical_context.py prompts]

• When DICOM metadata is available, generate FHIR ImagingStudy (not just Condition/Observation)
• Map modality, body part, study date, accession number to ImagingStudy fields
• Store via fhir_service.create_fhir_resource()

Tier 2: Sonnet (Mechanical Implementation, Config, Tests)¶

• [ ] S1: Update config/guardrails.yaml [MODIFY]
• Add .dcm, .dicom to frontend.allowed_extensions
• Add application/dicom to backend.allowed_mime_types (already present, verify)

• Add DICOM-specific medical keywords: dicom, modality, body part, series

• [ ] S2: Update app/services/file_validator.py [MODIFY]

• Add .dcm, .dicom to extension validation
• Add application/dicom MIME type mapping

• DICOM files skip medical keyword check (metadata provides clinical context natively)

• [ ] S3: Update presign endpoint [MODIFY app/routers/documents.py]

• Accept .dcm/.dicom extensions in presign request validation

• Set file_type = "dicom" in DocumentReference creation

• [ ] S4: Update confirm_upload flow [MODIFY app/services/document_service.py]

• Detect DICOM file type
• Call dicom_parser.parse_dicom() instead of queuing OCR
• Store deidentified bytes back to R2
• Store thumbnail to R2
• Populate extracted_data with DICOM metadata
• Set document_category = "imaging" automatically

• Queue run_post_ocr_pipeline() with SR text

• [ ] S5: Update QStash OCR callback [MODIFY app/routers/internal.py]

• In process_ocr(), detect DICOM file type before starting OCR tiers
• If DICOM: call dicom_parser.parse_dicom(), skip all OCR tiers

• Feed results into run_post_ocr_pipeline() as normal

• [ ] S6: Pydantic schemas for DICOM data [NEW FILE app/schemas/dicom.py]

• DicomMetadata -- body_part, modality, study_date, laterality, etc.
• SRFinding -- concept_name, value_type, value, unit, finding_type

• DicomParseResult -- metadata, sr_findings, thumbnail_key, text_representation, deidentification_summary

• [ ] S7: Frontend -- accept DICOM file types [MODIFY ConversationApp.tsx]

• Update accept= attribute: add .dcm,.dicom
• Update frontend file validation (extension list)

• Add DICOM icon/badge for file attachment cards

• [ ] S8: Frontend -- DICOM thumbnail preview [MODIFY EHR drawer components]

• When document has thumbnail_key in extracted_data, fetch and display
• Fallback to generic imaging icon when no thumbnail available

• 256x256 max, grayscale, with body part + modality label overlay

• [ ] S9: Flagsmith feature flag [CONFIG]

• Create dicom_support_enabled flag in Flagsmith
• Gate all DICOM-specific code paths behind this flag

• Default: OFF until integration testing passes

• [ ] S10: Add pydicom and Pillow to requirements [MODIFY requirements.txt]

• pydicom>=2.4.0,<3.0
• Pillow>=10.0.0,<11.0 (likely already present for other image handling)

4. File-by-File Changes¶

New Files¶

Modified Files¶

5. Data Model¶

extracted_data JSONB Schema for DICOM Documents¶

When a DICOM file is processed, document_references.extracted_data will contain:

{
  "source_type": "dicom",
  "dicom_metadata": {
    "modality": "MR",
    "modality_description": "Magnetic Resonance",
    "body_part_examined": "KNEE",
    "laterality": "L",
    "study_date": "2026-03-15",
    "study_description": "MRI LEFT KNEE WITHOUT CONTRAST",
    "series_description": "SAG PD FAT SAT",
    "institution_name": "DEIDENTIFIED",
    "referring_physician": "DEIDENTIFIED",
    "accession_number": "DEIDENTIFIED",
    "manufacturer": "SIEMENS",
    "station_name": "MRC35273",
    "slice_thickness": 3.0,
    "pixel_spacing": [0.35, 0.35],
    "rows": 512,
    "columns": 512,
    "bits_allocated": 16,
    "photometric_interpretation": "MONOCHROME2",
    "number_of_frames": 1
  },
  "sr_findings": [
    {
      "concept_name": "Finding",
      "value_type": "TEXT",
      "value": "Moderate tricompartmental osteoarthritis with near-complete loss of medial compartment cartilage",
      "finding_type": "impression"
    },
    {
      "concept_name": "Measurement",
      "value_type": "NUM",
      "value": 2.3,
      "unit": "mm",
      "finding_type": "measurement",
      "measurement_site": "Medial meniscus tear"
    }
  ],
  "thumbnail_key": "tenant-001/patient-abc/doc-xyz_thumb.png",
  "deidentification_summary": {
    "tags_stripped": 18,
    "tags_preserved": 45,
    "method": "safe_harbor_v1"
  },
  "analysis_status": "completed",
  "extracted_entities": [],
  "observations": [],
  "matched_requirements": []
}

FHIR Mapping¶

FHIR ImagingStudy resource will be created with status: "available" and linked to the patient via subject reference. SR findings feed into the existing Clinical Context Agent flow, which generates Condition and Observation resources.

6. De-Identification: Safe Harbor DICOM Tag Stripping¶

Tags to Strip (DICOM PS3.15 Table E.1-1, Safe Harbor subset)¶

These tags contain direct patient identifiers and must be removed or replaced with "DEIDENTIFIED" before storage or forwarding.

Tags to Preserve (Clinical Value)¶

All of these stay intact -- they carry clinical meaning without identifying the patient:

• Modality (0008,0060)
• BodyPartExamined (0018,0015)
• StudyDate (0008,0020) -- Note: study date is preserved because knowing when the imaging was done is critical for procedure requirement matching (validity windows). Date alone does not identify a patient under Safe Harbor.
• StudyDescription (0008,1030)
• SeriesDescription (0008,103E)
• Laterality (0020,0060)
• ImageLaterality (0020,0062)
• All pixel data tags
• All acquisition parameter tags (SliceThickness, PixelSpacing, etc.)
• Manufacturer, StationName, SoftwareVersions

Implementation Notes¶

• Use pydicom's Dataset.walk() to traverse all sequences (including nested SR content)
• After stripping, call ds.save_as() to produce clean bytes
• Generate new UIDs using pydicom.uid.generate_uid() (maintains DICOM validity)
• Log an audit event: {"event_type": "DICOM_DEIDENTIFIED", "tags_stripped": N, "document_id": "..."}
• Never log the stripped values themselves

7. DICOM-SR Parsing¶

Supported SR Template Types (Phase 1)¶

SR Content Tree Traversal¶

DICOM-SR stores findings as a tree of Content Items. Each item has a ValueType and a ConceptNameCodeSequence. The parser walks this tree recursively:

ContentSequence
  +-- Container: "Imaging Report"
       +-- Container: "Findings"
       |    +-- TEXT: "Moderate tricompartmental osteoarthritis..."
       |    +-- NUM: 2.3 mm (meniscus tear measurement)
       |    +-- CODE: SNOMED 396230008 (osteoarthritis)
       +-- Container: "Impression"
            +-- TEXT: "Near-complete loss of medial compartment cartilage"

Value Type Handling¶

Finding Classification¶

SR findings are classified into types for downstream processing:

Fallback for Non-SR DICOM¶

Most DICOM files patients upload will be image instances, not SR. When no SR content is found: 1. Build text from metadata: "{Modality} of {BodyPartExamined}, {Laterality}, Study Date: {StudyDate}. {StudyDescription}" 2. Pass this text to Clinical Context Agent as report_type="imaging" 3. The agent will not extract diagnoses from metadata alone (correct behavior -- a knee MRI file does not contain findings, the radiology report does)

8. Frontend Changes¶

File Input¶

ConversationApp.tsx -- update the accept attribute:

Current:  accept=".pdf,.jpg,.jpeg,.png,.doc,.docx"
New:      accept=".pdf,.jpg,.jpeg,.png,.doc,.docx,.dcm,.dicom"

Frontend File Validation¶

Update the client-side extension check to include .dcm and .dicom. DICOM files can be large (50-200MB for multi-frame), but Phase 1 only supports single-frame files. Keep the 20MB limit for now; revisit in Phase 2 for series support.

File Attachment Card¶

When file_type === "dicom", show: - A medical imaging icon (Lucide ScanLine or FileImage) instead of the generic file icon - Badge: "DICOM" in teal - After processing: body part + modality label (e.g., "MR - Left Knee")

EHR Drawer / Documents Tab¶

When a document has extracted_data.thumbnail_key: - Fetch thumbnail via presigned URL - Display as a small preview (128x128) in the document row - Click to expand to 256x256 in a lightbox - Overlay: modality + body part + study date

When no thumbnail (e.g., DICOM-SR without pixel data): - Show generic imaging icon - Display metadata summary: modality, body part, study date

9. Testing Plan¶

Unit Tests (tests/test_dicom_parser.py)¶

Integration Tests (tests/test_dicom_pipeline.py)¶

Test Fixtures¶

Create synthetic DICOM files using pydicom (no real patient data):

# tests/conftest.py
import pydicom
from pydicom.dataset import Dataset, FileDataset
from pydicom.uid import generate_uid

@pytest.fixture
def sample_dicom_bytes():
    ds = Dataset()
    ds.PatientName = "TEST^PATIENT"
    ds.PatientID = "TEST123"
    ds.Modality = "MR"
    ds.BodyPartExamined = "KNEE"
    ds.Laterality = "L"
    ds.StudyDate = "20260315"
    ds.StudyDescription = "MRI LEFT KNEE W/O CONTRAST"
    ds.BitsAllocated = 16
    ds.Rows = 64
    ds.Columns = 64
    ds.PixelData = b'\x00' * (64 * 64 * 2)
    # ... set required DICOM file meta
    # Return bytes via BytesIO

10. Risks and Mitigations¶

11. Dependencies¶

Python Packages¶

Optional (Not Required for Phase 1)¶

No New Infrastructure¶

• No new database tables (uses existing document_references.extracted_data JSONB)
• No new R2 buckets (thumbnails stored alongside documents)
• No new services or containers
• No new external API calls

Appendix A: DICOM Modality Codes to Procedure Requirement Mapping¶

Appendix B: Body Part to Procedure Code Mapping¶

These mappings are used by the deterministic matcher in match_dicom_metadata_to_requirements() and will be stored in config/dicom_mappings.yaml for configurability.