Radiology Service — Application Logic
Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · 03 platform-services · 02 DDD
1. Use Cases
Commands
| Use case | Command | Actor |
|---|---|---|
| Register PACS endpoint | RegisterPacsEndpointCommand | Radiology admin |
| Register imaging study from order | RegisterImagingStudyCommand | System (order event) / integration |
| Sync study metadata from PACS | SyncStudyMetadataCommand | System (scheduled / webhook) |
| Ingest radiology report | IngestRadiologyReportCommand | System (HL7 ORU / API) / radiologist |
| Sign radiology report | SignRadiologyReportCommand | Radiologist |
| Amend radiology report | AmendRadiologyReportCommand | Radiologist |
| Generate viewer launch token | GenerateViewerLaunchTokenCommand | Clinician (viewer launch request) |
| Flag critical finding | FlagCriticalFindingCommand | System (automated) / Radiologist |
Queries
| Use case | Query | Returns |
|---|---|---|
| Get studies for patient | GetPatientImagingStudiesQuery | Paginated ImagingStudyRef list |
| Get study detail | GetImagingStudyDetailQuery | Study + PACS metadata + report list |
| Get radiologist worklist | GetRadiologistWorklistQuery | Studies pending reporting |
| Get report | GetRadiologyReportQuery | Report with version history |
| Search PACS endpoints | GetPacsEndpointsQuery | Tenant/facility endpoint list |
2. Orchestration Flows
2.1 Order → Study Registration Flow
2.2 Report Lifecycle Flow
2.3 Viewer Launch Flow
3. Ports
| Port | Direction | Adapter |
|---|---|---|
IOrdersPort | Inbound | NATS inbox consumer for clinical.orders.placed |
IDicomWebPort | Outbound | HTTP adapter → PACS DICOMweb (QIDO-RS/WADO-RS) |
IFhirPort | Outbound | HTTP adapter → interop-service FHIR gateway |
IEventPublisher | Outbound | NATS JetStream publisher |
IRadiologyRepository | Outbound | Drizzle ORM → PostgreSQL |
IAbacPort | Outbound | access-policy-service for viewer launch authorization |
IAuditPort | Outbound | NATS event → audit-service |
4. Outbox Pattern
All domain events are written atomically with state changes. FHIR ImagingStudy resource creation is similarly queued in the outbox and published to the FHIR gateway on success.
5. Error Handling
| Scenario | Strategy |
|---|---|
| PACS QIDO-RS returns 503 | Retry with exponential backoff (max 3); study remains in registered state; alert if PACS unreachable > 5 min |
| Viewer launch ABAC denial | Return 403 with RAD_ACCESS_DENIED; log audit event |
| Report ingestion with no matching study | Store as unlinked_report with patient ID + study UID; raise admin alert |
| Duplicate ORU study notification | Dedup by (tenant_id, pacs_study_uid); idempotent upsert |
| Amendment without prior final | Return RAD_REPORT_NOT_FINAL 409 |