Swedish Healthcare Service - Health Condition Description - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Technical Architecture

Architecture

This page describes the technical architecture and integration patterns for the Health Condition Description service domain.

Architectural Overview

System Components

graph TB
    Consumer[Consumer<br/>EMR/Portal]
    Platform[Service Platform<br/>Tjänsteplattform]
    Aggregator[Aggregating Service<br/>National/Regional]
    EI[Engagement Index<br/>Which systems?]
    Source1[Source System 1<br/>Hospital A]
    Source2[Source System 2<br/>Clinic B]
    SourceN[Source System N<br/>Provider X]
    
    Consumer -->|SOAP Request| Platform
    Platform --> Aggregator
    Aggregator -->|Query| EI
    EI -->|HSA-IDs| Aggregator
    Aggregator -->|Parallel Requests| Source1
    Aggregator -->|Parallel Requests| Source2
    Aggregator -->|Parallel Requests| SourceN
    Source1 -->|Response| Aggregator
    Source2 -->|Response| Aggregator
    SourceN -->|Response| Aggregator
    Aggregator -->|Aggregated| Platform
    Platform -->|SOAP Response| Consumer
    
    style Consumer fill:#e1f5ff
    style Aggregator fill:#fff4e1
    style EI fill:#ffe1f5
    style Source1 fill:#e1ffe1
    style Source2 fill:#e1ffe1
    style SourceN fill:#e1ffe1

Direct Access Pattern

graph LR
    Consumer[Consumer<br/>EMR System]
    Platform[Service Platform]
    Source[Source System<br/>Local Provider]
    
    Consumer -->|SOAP Request| Platform
    Platform -->|Route| Source
    Source -->|SOAP Response| Platform
    Platform -->|Return| Consumer
    
    style Consumer fill:#e1f5ff
    style Source fill:#e1ffe1

Component Roles

Consumer (Tjänstekonsument)

The system that requests patient information:

• EMR Systems - Electronic medical record systems
• Patient Portals - Systems for patient access (1177, Journalen, etc.)
• Specialized Applications - Clinical decision support, reporting, etc.

Responsibilities:

• Authenticate users
• Check access permissions (PDL)
• Handle blocking/consent
• Display information appropriately
• Log access (PDL compliance)

Service Platform (Tjänsteplattform)

Infrastructure layer providing:

• Virtual Services - Single endpoint for consumers
• Routing - Directs requests to appropriate producers
• Security - Authentication, authorization
• Monitoring - Performance tracking

Aggregating Service

Consolidates information from multiple source systems:

National Aggregating Service:

• Operated by Inera
• HSA-ID: 5565594230
• Covers all care givers nationally

Regional Aggregating Services:

• Operated by regional authorities
• Own HSA-ID per region
• Covers care givers within region

Functions:

1. Receives consumer request
2. Queries engagement index
3. Identifies relevant source systems
4. Sends parallel requests to source systems
5. Aggregates responses
6. Returns consolidated result

Engagement Index (EI)

Registry of which source systems have information about which patients:

Index Entry Contains:

• Patient identity
• Service domain
• Information categorization
• Source system HSA-ID
• Most recent content timestamp
• Data controller

Benefits:

• Efficient queries (only query relevant systems)
• Change notifications
• Reduces unnecessary requests

Source System (Källsystem)

The authoritative source of patient information:

• Operational Systems - Where information is created/managed
• Examples - Journal systems, radiology systems, lab systems

Responsibilities:

• Store patient information
• Respond to queries
• Update engagement index
• Apply local access controls
• Maintain data quality

Integration Patterns

Pattern 1: Aggregated Query (National)

sequenceDiagram
    participant C as Consumer
    participant A as National Aggregator
    participant EI as Engagement Index
    participant S1 as Source System 1
    participant S2 as Source System 2
    participant S3 as Source System 3
    
    C->>A: GetCareDocumentation<br/>(patientId, timePeriod)
    A->>EI: Query (patientId, service)
    EI-->>A: HSA-IDs [S1, S2, S3]
    
    par Parallel Queries
        A->>S1: GetCareDocumentation
        A->>S2: GetCareDocumentation
        A->>S3: GetCareDocumentation
    end
    
    par Parallel Responses
        S1-->>A: Documents [1-5]
        S2-->>A: Documents [6-12]
        S3-->>A: Documents [13-15]
    end
    
    A->>A: Aggregate, Sort, Deduplicate
    A-->>C: All Documents [1-15]

Use Case: Patient portal needs complete view of patient's care documentation from all care givers nationally.

Benefits:

• Single query returns all data
• Consumer doesn't need to know source systems
• Consistent sorting and deduplication

Considerations:

• Response time depends on slowest source system
• Partial failure possible (some systems unavailable)
• Aggregator must handle timeouts gracefully

Pattern 2: Regional Query

sequenceDiagram
    participant C as Consumer<br/>(Regional EMR)
    participant RA as Regional Aggregator
    participant EI as Regional EI
    participant S1 as Hospital A
    participant S2 as Clinic B
    
    C->>RA: GetDiagnosis<br/>(patientId)
    RA->>EI: Query Regional Index
    EI-->>RA: HSA-IDs [S1, S2]
    
    par Regional Sources
        RA->>S1: GetDiagnosis
        RA->>S2: GetDiagnosis
    end
    
    par Responses
        S1-->>RA: Diagnoses [A-D]
        S2-->>RA: Diagnoses [E-F]
    end
    
    RA-->>C: Regional Diagnoses [A-F]

Use Case: Regional EMR needs diagnosis information from within the region.

Benefits:

• Faster response (fewer source systems, geographic proximity)
• Regional governance control
• Compliance with local data policies

Pattern 3: Direct Query to Source System

sequenceDiagram
    participant C as Consumer<br/>(Local EMR)
    participant P as Service Platform
    participant S as Source System<br/>(Same Organization)
    
    C->>P: GetAlertInformation<br/>(patientId, sourceSystemHSAId)
    P->>S: Route to specified system
    S->>S: Validate access<br/>Execute query
    S-->>P: Alert Information
    P-->>C: Alert Information

Use Case: EMR querying its own backend or known system within organization.

Benefits:

• Fastest response (no aggregation)
• Simplest flow
• Predictable behavior

Requirements:

• Consumer must know source system HSA-ID
• sourceSystemHSAId must match logicalAddress in SOAP header
• Direct network connectivity

Pattern 1: Aggregated Access

Consumer accesses via aggregating service:

[Consumer] 
    ↓ 1. Request (logicalAddress=Aggregator HSA-ID)
[Aggregating Service]
    ↓ 2. Query (Which systems have data?)
[Engagement Index]
    ↓ 3. Response (System A, B, C)
[Aggregating Service]
    ↓ 4. Parallel requests
[System A] [System B] [System C]
    ↓ 5. Responses
[Aggregating Service]
    ↓ 6. Aggregated response
[Consumer]

Use Cases:

• National patient overview
• Regional information access
• Cross-organizational queries

Benefits:

• Single query gets all information
• Automatic discovery of relevant sources
• Transparent to consumer

Pattern 2: Direct System Access

Consumer directly queries specific source system:

[Consumer]
    ↓ 1. Request (logicalAddress=Source System HSA-ID)
[Service Platform]
    ↓ 2. Route to system
[Source System]
    ↓ 3. Response
[Consumer]

Use Cases:

• Following up notification
• Known source system
• Testing/troubleshooting

Requirements:

• Consumer knows source system HSA-ID
• Direct relationship between consumer and producer

Pattern 3: Notification-Driven

Source system notifies about changes:

[Source System]
    ↓ 1. Update (patient data changed)
[Engagement Index]
    ↓ 2. ProcessNotification (to subscribers)
[Consumer]
    ↓ 3. Direct query to source system
[Source System]
    ↓ 4. Updated data
[Consumer]

Benefits:

• Real-time updates
• Efficient (only fetch when changed)
• Reduced polling

Addressing Models

Logical Address

The logicalAddress in SOAP header determines routing:

Source System Identification

When sourceSystemHSAId specified in request:

• Must match logicalAddress in SOAP header
• Bypasses aggregation
• Direct query to that system only

Engagement Index Updates

Update Flow

[Source System]
    ↓ Event occurs (new/modified/deleted data)
    ↓
    ↓ Update EI entry
    ↓
[Engagement Index]
    ↓ Store/update entry
    ↓
    ↓ Notify subscribers (if configured)
    ↓
[Subscribers]

Update Triggers

Source systems must update EI when:

• New patient information created
• Existing information modified
• Information deleted/obsoleted
• Access approval changes (approvedForPatient)
• Information crosses threshold for inclusion

Update Timing

• As soon as event occurs
• Target < 60 minutes maximum delay
• Index must reference immediately available data

Performance Considerations

Response Time Optimization

Strategies:

• Parallel queries to source systems
• Caching at aggregator (when appropriate)
• Partial data retrieval for large datasets
• Efficient database queries at source

Target: < 30 seconds total response time

Scalability

Design Features:

• Horizontal scaling of aggregating services
• Load balancing across source systems
• Engagement index for efficient queries
• Asynchronous processing where possible

Capacity Requirements:

• Minimum 10 concurrent requests per producer
• Handle 2x daily update volume
• 99.5% availability

Engagement Index Efficiency

Benefits:

• Reduces queries to systems without data
• Enables targeted queries
• Supports change notifications
• Provides metadata for smart caching

Security Architecture

Transport Security

TLS/HTTPS:

• All communication encrypted
• Minimum TLS 1.2
• Strong cipher suites

Authentication

WS-Security:

• SAML tokens for user identity
• X.509 certificates for system identity
• Strong authentication in shared networks

Authorization

Multi-Level:

1. System Level - Which systems can call which services
2. User Level - PDL-based access control
3. Data Level - Blocking, consent, approval flags

Audit Logging

All access must be logged:

• Who accessed what information
• When and from where
• For what purpose (PDL)
• Success or failure

Data Flow Patterns

Read-Only Access

This domain provides READ access only:

• No create/update/delete operations
• Data modified only in source systems
• Changes propagate via EI updates

Data Currency

Update Propagation:

1. Change occurs in source system
2. Source system updates EI (< 60 min target)
3. EI may notify subscribers
4. Next query returns updated data

Eventually Consistent:

• Small delay expected between change and visibility
• Not real-time synchronization
• Acceptable for clinical workflows

Partial Data Retrieval

For large datasets:

Consumer          Producer
   │                 │
   │ Request         │
   ├────────────────>│
   │                 │
   │ Response        │
   │ (first batch)   │
   │<────────────────┤
   │                 │
   │ Display batch   │
   │                 │
   │ Request more    │
   ├────────────────>│
   │                 │
   │ Next batch      │
   │<────────────────┤
   │                 │

Rules:

• Consumer decides when to fetch more
• Same search parameters maintained
• Server maintains query context
• Consumer handles deduplication

Error Handling Architecture

Error Types

Technical Errors:

• Network failures
• Timeout
• System unavailability
• Invalid message format

Logical Errors:

• Invalid request parameters
• Access denied
• Data not found
• Business rule violation

Fault Tolerance

Aggregator Behavior:

• Continue if some systems fail
• Include partial results
• Report which systems failed
• Consumer decides how to handle

Retry Strategy:

• No automatic retries at platform level
• Consumer decides retry logic
• Consider user experience

Circuit Breaker Pattern

For source system failures:

• Detect repeated failures
• Temporarily skip failed system
• Periodic retry to check recovery
• Automatic re-inclusion when recovered

Deployment Architecture

National Infrastructure

graph TB
    subgraph National[National Level - Inera]
        NAgg[National Aggregating Service<br/>HSA-ID: 5565594230]
        NEI[National Engagement Index]
        NAgg -.Query.-> NEI
    end
    
    subgraph RegionA[Region A]
        RAggA[Regional Aggregator A]
        REIA[Regional EI]
        SA1[Hospital A1]
        SA2[Clinic A2]
        RAggA -.Query.-> REIA
        RAggA --> SA1
        RAggA --> SA2
    end
    
    subgraph RegionB[Region B]
        RAggB[Regional Aggregator B]
        REIB[Regional EI]
        SB1[Hospital B1]
        SB2[Clinic B2]
        RAggB -.Query.-> REIB
        RAggB --> SB1
        RAggB --> SB2
    end
    
    subgraph RegionC[Region C]
        SC1[Source System C1]
        SC2[Source System C2]
    end
    
    NAgg --> RAggA
    NAgg --> RAggB
    NAgg --> SC1
    NAgg --> SC2
    
    SA1 -->|Update| NEI
    SA2 -->|Update| NEI
    SB1 -->|Update| NEI
    SB2 -->|Update| NEI
    SC1 -->|Update| NEI
    SC2 -->|Update| NEI
    
    style National fill:#e1f5ff
    style RegionA fill:#fff4e1
    style RegionB fill:#fff4e1
    style RegionC fill:#ffe1e1

Regional Infrastructure

┌─────────────────────────────────────┐
│         Regional Level              │
│                                     │
│ Systems  │      │ Systems  │
└──────────┘      └──────────┘

Regional Infrastructure

┌─────────────────────────────────────┐
│         Regional Level              │
│                                     │
│  ┌────────────────────────────┐    │
│  │  Regional Aggregating Svc  │    │
│  └────────────────────────────┘    │
│                                     │
│  ┌────────────────────────────┐    │
│  │  Regional Engagement Index │    │
│  └────────────────────────────┘    │
│                                     │
└──────────────┬──────────────────────┘
               │
     ┌─────────┴─────────┐
     │                   │
┌────▼─────┐      ┌─────▼────┐
│Hospital 1│      │Hospital 2│
│ Systems  │      │ Systems  │
└──────────┘      └──────────┘

Standards Compliance

RIV Technical Framework

Service Orientation:

• Contract-first design
• WSDL-defined interfaces
• SOAP/HTTP transport
• WS-Security

Addressing:

• Logical addressing
• Service catalog
• Dynamic routing

Swedish Healthcare Standards

HSA Integration:

• HSA-ID for identification
• HSA catalog for discovery
• HSA organization structure

PDL Compliance:

• Access control framework
• Logging requirements
• Consent management
• Blocking capabilities

Monitoring and Operations

Health Checks

Each component provides:

• Service availability check
• Performance metrics
• Error rates
• Resource utilization

Metrics

Key Performance Indicators:

• Response time (p50, p95, p99)
• Success rate
• Availability percentage
• Concurrent users
• Data freshness (EI update lag)

Alerting

Alerts triggered on:

• Service unavailability
• Response time degradation
• Error rate increase
• SLA violation
• Security events

Versioning Strategy

API Versioning

Major Versions:

• Breaking changes
• New major version number
• Parallel operation period
• Managed migration

Minor Versions:

• Backward compatible changes
• Same major version
• Automatic adoption

Compatibility

Forward Compatibility:

• Ignore unknown elements
• Extensible structures
• Graceful degradation

Backward Compatibility:

• New optional fields
• Deprecated field support
• Version negotiation

Architecture Decisions

Key Design Choices

Trade-offs

Pull vs Push:

• Chose: Pull-based with notification support
• Trade-off: Not real-time but more reliable

Consistency vs Availability:

• Chose: Availability (eventual consistency)
• Trade-off: Small data lag acceptable

Flexibility vs Performance:

• Chose: Flexible schema with validation
• Trade-off: Runtime validation overhead