T1.1: Pre-Installation Decisions Based on Technical Architecture Document

Overview

The Solution Architecture Document (SAD) is the foundational artifact that drives every decision a HealthShare UCR Deployment Specialist makes. Before any software is installed or any configuration is applied, the deployment specialist must thoroughly read, understand, and validate this document. It describes the intended UCR federation topology, the number and placement of each component, and the infrastructure requirements for the deployment.

What the Architecture Document Contains

A typical UCR Solution Architecture Document includes the following sections:

• Executive summary: High-level description of the federation scope, participating organizations, and project goals
• Component topology diagram: Visual representation of all UCR components (Registry, Edge Gateways, Access Gateways, Bus, ODS) and their relationships
• Network architecture: Network segments, firewall zones, VPN tunnels, and connectivity paths between components
• Server sizing and specifications: CPU, memory, disk, and operating system requirements for each server
• Facility inventory: List of healthcare facilities participating in the federation and their source systems
• Security architecture: SSL/TLS requirements, authentication model, certificate authority, and trust relationships
• Integration requirements: Source systems, data feeds, and external application connections
• High availability and disaster recovery: Mirroring, failover, and backup strategies

The Deployment Specialist's Perspective

Unlike the solution architect who creates the document, the deployment specialist interprets it. The specialist must be able to:

• Map each box in a topology diagram to a concrete server, instance, and namespace
• Translate sizing recommendations into actual hardware or virtual machine specifications
• Identify dependencies between components that dictate installation order
• Flag gaps or ambiguities in the document before installation begins
• Validate that the documented architecture is feasible given the available infrastructure

Validating the Architecture Document

Before proceeding with installation, the deployment specialist should verify:

• All servers listed in the document exist and are accessible
• Network connectivity between all component pairs has been confirmed
• License keys have been obtained for every planned instance
• The documented topology matches the customer's operational requirements
• Any assumptions in the document are explicitly confirmed with stakeholders

---

Overview

Component topology diagrams are the most critical part of the architecture document for a deployment specialist. These diagrams show every UCR component in the federation, how they connect, and which facilities they serve. Reading these diagrams accurately is essential for planning the installation sequence and validating infrastructure readiness.

Identifying Components in Topology Diagrams

Each component type appears in the topology diagram with specific characteristics:

• Registry (Hub): Always appears as a single central node. All other components connect to the Registry. It handles MPI, consent, and federation-wide registries. There is never more than one Registry in a federation.
• Edge Gateways: Appear as nodes associated with one or more facilities. Each Edge Gateway stores clinical data in its Edge Cache Repository (ECR). The deployment specialist must identify how many Edge Gateways are needed and which facilities each one serves.
• Access Gateways: Appear as nodes serving clinician-facing applications. They host the Clinical Viewer and query Edge Gateways for patient data. Multiple Access Gateways may be deployed for load distribution or geographic proximity.
• Bus: Appears as an optional integration layer connecting external applications to the federation. Not all deployments include a Bus.
• ODS: Appears as a data aggregation node that receives data from Edge Gateways and provides FHIR-based API access.

Counting Components for Installation Planning

From the topology diagram, the deployment specialist must extract a precise count:

• How many IRIS for Health instances are needed in total
• How many license keys must be obtained
• How many servers or virtual machines must be provisioned
• How many SSL/TLS certificates must be created
• What is the installation order (Registry first, then Edge Gateways, then Access Gateways, etc.)

Identifying the Audit Edge

One Edge Gateway in the topology must be designated as the Audit Edge. The architecture document should specify which Edge Gateway serves this role. If it is not explicitly stated, the deployment specialist must confirm this decision with the solution architect before proceeding.

---

Overview

The architecture document specifies the infrastructure requirements for each UCR component. The deployment specialist must translate these specifications into concrete provisioning requests and verify that the delivered infrastructure meets or exceeds the documented requirements.

Server Specifications by Component Type

Each UCR component type has different resource requirements:

• Registry: Moderate CPU, moderate memory. The MPI engine requires sufficient memory for patient matching algorithms. Storage needs are relatively low since the Registry does not store clinical data.
• Edge Gateway: Variable CPU and memory depending on data volume. Storage requirements can be significant because the ECR stores all clinical data for associated facilities. High-throughput Edge Gateways serving large hospitals require more resources.
• Access Gateway: Moderate CPU, moderate memory. Storage is minimal since data is transient. Memory needs scale with the number of concurrent Clinical Viewer users.
• Bus: Low to moderate resources. Requirements depend on the volume of external application queries.
• ODS: High storage requirements for aggregated clinical data. CPU and memory scale with the volume of data and the complexity of FHIR queries and analytics workloads.

Network Port Requirements

UCR components communicate over specific network ports:

• Port 443 (HTTPS): Web-based communication between components, Management Portal access, Clinical Viewer access
• Port 1972 (SuperServer): InterSystems IRIS superserver port for direct instance communication
• Port 52773 (Web Server): Default IRIS private web server port (development only; production uses external web server on port 443)
• Custom ports: Some deployments use non-standard ports for security purposes; these must be documented

Storage Planning

Storage planning must account for:

• Database storage: Primary databases for each namespace (IRIS.DAT files)
• Journal storage: Write-ahead journal files, ideally on separate physical volumes
• Backup storage: Space for online backups and backup history
• Temp storage: Temporary space for large operations and data transformations
• Growth projections: Storage must accommodate projected data growth over the deployment lifetime

---

Overview

Facility-to-gateway mapping is one of the most consequential pre-installation decisions. It determines how many Edge Gateways to deploy, where to place them, and how to distribute the data collection workload across the federation. The architecture document should provide this mapping, and the deployment specialist must validate it against infrastructure availability and operational requirements.

Factors Driving the Mapping Decision

Several factors influence whether a facility gets a dedicated or shared Edge Gateway:

• Data volume: Facilities generating large volumes of clinical messages (HL7 ADTs, ORUs, MDMs) typically need a dedicated gateway to handle the processing load
• Number of source systems: Facilities with many integrated source systems create more integration complexity, favoring a dedicated gateway
• Regulatory or organizational boundaries: Some organizations require data isolation, mandating separate gateways even for smaller facilities
• Network topology: Facilities on separate networks or behind different firewalls may require their own gateway for connectivity reasons
• Growth expectations: A facility expected to grow significantly should be planned for a dedicated gateway from the start

Shared Edge Gateway Considerations

When multiple facilities share an Edge Gateway:

• Ensure the gateway has sufficient capacity for the combined data volume of all connected facilities
• Plan for the added complexity of managing multiple facility configurations on a single gateway
• Consider the impact on one facility if another facility's data volume spikes unexpectedly
• Document clearly which facilities are served by each shared gateway

Source System Inventory

For each facility, the deployment specialist should verify that the architecture document includes:

• A complete list of source systems that will send data to the Edge Gateway
• The message types and protocols used by each source system (HL7v2, CDA, FHIR, custom)
• Estimated daily message volumes per source system
• Connectivity details (VPN, direct network, point-to-point)

---

Overview

Security is not optional in a UCR deployment. The architecture document defines the security model, and the deployment specialist must understand every security requirement before installation begins. Security configuration touches every component and every communication path in the federation.

SSL/TLS Certificate Planning

Every UCR component must be configured with SSL/TLS for secure communication. The deployment specialist must plan for:

• Certificate Authority (CA): Will the deployment use an internal CA, a commercial CA, or self-signed certificates (development only)?
• Certificate count: One server certificate per IRIS for Health instance, plus any client certificates needed
• Certificate format: InterSystems IRIS for Health requires certificates in specific formats (PEM or DER)
• Certificate lifecycle: Plan for certificate renewal before expiration, including renewal procedures and responsible personnel
• Trust chain: Each component must trust the CA that signed the certificates of every other component it communicates with

Authentication Model

The architecture document specifies how users (clinicians, administrators) will authenticate:

• LDAP/Active Directory integration: Most common in enterprise deployments. IRIS for Health is configured to delegate authentication to the directory service.
• Local authentication: User accounts managed directly within IRIS for Health. Simpler but harder to manage at scale.
• Delegated authentication: Custom authentication logic using ObjectScript classes. Used when specialized authentication requirements exist.
• Multi-factor authentication: May be required by organizational security policies, typically handled at the web server or identity provider layer.

WS-Security and SAML

UCR components use WS-Security for SOAP message-level security:

• SAML assertions carry identity information between components
• The Registry acts as the SAML token issuer for the federation
• Each component must be configured to validate SAML tokens from the Registry
• Proper clock synchronization (NTP) is essential because SAML tokens contain timestamps

---

Overview

Most UCR deployments involve multiple environments that serve different purposes in the software delivery lifecycle. The architecture document should describe each environment, and the deployment specialist must understand how to tailor the installation for each tier.

Environment Tiers

A typical UCR deployment includes:

• Development: Used by developers and integration engineers to build and test data feeds, transformations, and customizations. Single-instance topology with multiple namespaces is acceptable. Minimal security configuration.
• Test/QA: Used for integration testing and quality assurance. Should mirror production topology as closely as possible but may use reduced hardware. Full security configuration with test certificates.
• Staging (Pre-Production): A near-exact replica of production used for final validation before go-live. Same topology, same security, same configuration as production but with anonymized or synthetic data.
• Production: The live environment serving real clinical users with real patient data. Full distributed topology with dedicated instances per component, production SSL/TLS certificates, full high availability, and disaster recovery.

Single-Instance vs Distributed Topology

The key topology difference between environments:

• Single-instance (development/demo): All UCR components run as separate namespaces on one IRIS for Health instance. Advantages include lower infrastructure cost and simpler management. Disadvantages include shared resources, no fault isolation, and performance characteristics that do not reflect production.
• Distributed (staging/production): Each UCR component runs on its own dedicated IRIS for Health instance, typically on separate servers. This provides resource isolation, independent scaling, fault containment, and realistic performance characteristics.

Configuration Tracking

The deployment specialist should maintain a configuration matrix that tracks:

• Instance names and connection details for each environment
• Namespace names and component assignments
• SSL/TLS certificate details per environment
• Network endpoints and port assignments
• Feature flags that differ between environments
• Version numbers and patch levels

---

Overview

Before any installation begins, the deployment specialist must complete a comprehensive pre-installation checklist. This checklist ensures that every prerequisite has been met and that the installation can proceed without interruption. Skipping this step leads to costly delays and rework.

License Key Verification

• Confirm that a valid license key has been obtained for every IRIS for Health instance in the deployment plan
• Verify that each key matches the server hardware or virtual machine it will be installed on
• Check that the key type and capacity are appropriate for the component role (Registry, Edge, Access, Bus, ODS)
• Confirm that all keys have sufficient validity period to cover the deployment timeline and initial production period
• Store license key files securely and maintain a mapping of which key goes to which server

Server Readiness Verification

• All servers or virtual machines are provisioned and powered on
• Operating system is installed and patched to the supported version
• Required system packages and libraries are installed (specific to OS platform)
• Disk volumes are mounted and sized according to the architecture document
• Server clock is synchronized via NTP (critical for SAML token validation and audit timestamps)
• Administrative access is confirmed (SSH for Linux, RDP for Windows)

Network Readiness Verification

• Connectivity has been tested between all component pairs using the documented ports
• Firewall rules are in place allowing HTTPS and SuperServer traffic
• DNS entries are configured for all servers (forward and reverse lookup)
• Load balancers, if specified, are configured and tested
• VPN tunnels, if required for remote facilities, are established and stable

Personnel and Access

• Installation team members are identified and available for the planned installation window
• Each team member has the necessary access credentials for their assigned servers
• Escalation contacts are identified for network, security, and infrastructure issues
• InterSystems support contact information is available for technical issues during installation

Timeline and Communication

• Installation schedule is documented and agreed upon by all stakeholders
• Communication plan is in place for status updates during installation
• Rollback plan is documented in case of critical installation failures
• Post-installation validation steps are defined and assigned to team members

---