Network & Publish-Subscribe Guide

Overview

CareFrame's Network module enables secure, real-time sharing of research data between different CareFrame instances using a publish-subscribe (pub/sub) architecture. This allows research teams to collaborate across institutional boundaries while maintaining data integrity and access control.

Key Concepts

• Host Mode: Your CareFrame instance acts as a server, allowing others to connect
• Client Mode: Your CareFrame connects to another instance's server
• Topics: Channels for organizing different types of research information
• Publish: Send data to a specific topic
• Subscribe: Receive data from specific topics
• WebSockets: Technology enabling real-time bidirectional communication

Interface Components

The Network section consists of:

1. Mode Selection

   • Host Mode (server)
   • Client Mode (connects to other servers)

2. Server Control

   • Start/Stop server
   • Port configuration
   • Server status indicator

3. Connection Management

   • Host connection (IP and port)
   • Topic subscription controls
   • Connection status indicator

4. Message Publishing

   • Message composition area
   • Topic selection
   • Publish button

5. Message Display

   • Subscribed message view
   • Connected clients list
   • Server output log

Basic Workflows

Setting Up a Host Server

1. Select Host Mode
2. Set the desired port number (default: 8889)
3. Click Start Server
4. Wait for server status to change to "Ready"
5. Click Connect to establish a WebSocket connection to your own server
6. The connected clients list will show your connection

Connecting to Another Host

1. Select Client Mode
2. Enter the host's IP address
3. Enter the host's port number
4. Click Connect to Host
5. Wait for the WebSocket status to indicate "Connected"

Publishing Data to a Topic

1. Enter a topic name in the Topic field (e.g., "study_results", "protocol_updates")
2. Compose your message in JSON format:

   {
     "topic": "study_results",
     "data": "Results from Trial A show p<0.05",
     "context": "hypertension_study"
   }
   

3. Click Publish Message
4. Verify in the server output that the message was published

Subscribing to Topics

1. Enter the topic name in the Topic field
2. Click Subscribe
3. Messages published to this topic will appear in the Subscribed Messages area
4. To stop receiving updates, click Unsubscribe

Advanced Features

System Topics

CareFrame includes special system topics:

• system: Provides server status updates and notifications
• client_list: Updates when clients connect or disconnect
• evidence: Used for sharing blockchain-validated evidence
• protocol: Used for protocol updates and reviews

Automated Subscriptions

When connected to a server, your instance can automatically:

1. Subscribe to the system topic with:

   Subscribe → system
   

2. Subscribe to evidence updates with:

   Subscribe → evidence
   

Evidence Sharing

To share blockchain-validated evidence:

1. First validate evidence in the Evidence Blockchain section
2. Navigate to Network
3. Set the topic to "evidence"
4. In the message area, reference the blockchain evidence ID:

   {
     "topic": "evidence", 
     "data": {"evidence_id": "e12345", "study_id": "s789"},
     "context": "multicenter_validation"
   }
   

5. Click Publish Message

Integration with Other Modules

Research Planning Integration

Share research plans with collaborators:

1. Create a plan in the Research Planning module
2. Export the plan to JSON
3. In the Network module, publish to the "research_plans" topic
4. Collaborators subscribed to this topic receive the plan

Protocol Sharing

Distribute protocols to research partners:

1. Finalize a protocol in the Protocol section
2. In the Network module, publish to the "protocols" topic
3. Include protocol ID and version information in the message

Literature Evidence Distribution

Share literature findings:

1. Collect evidence in the Literature Search module
2. In the Network module, publish to the "literature_evidence" topic
3. Include paper references and evidence strength ratings

Security Considerations

• Network Visibility: By default, servers are only visible on your local network
• Authentication: Currently uses simple connection management; consider VPN for public networks
• Data Validation: Always validate received data before incorporating into studies
• Firewall Configuration: Ensure port forwarding is set up for external connections
• Topic Access Control: Use specific topic names and context fields to limit data exposure

Example Use Cases

Multi-center Research Collaboration

1. Establish a central CareFrame host at the lead institution
2. Partner institutions connect in client mode
3. Define topic naming conventions (e.g., "center1_results", "center2_results")
4. Each center publishes their results to their designated topic
5. All centers subscribe to a common "aggregated_results" topic
6. The lead center validates and publishes combined results

Real-time Protocol Updates

1. Start a host server at the protocol management site
2. All research sites connect as clients
3. Subscribe to the "protocol_updates" topic
4. When protocols change, publish updates with version tracking
5. All sites receive immediate notification of protocol changes

Troubleshooting

• Connection Issues: Verify IP address and port number; check firewalls
• Message Not Received: Confirm topic spelling matches exactly
• Server Won't Start: Check if port is already in use by another application
• Client List Empty: Ensure WebSocket connection is established after server starts
• Message Format Errors: Verify JSON syntax in the message body

Next Steps

After setting up your network:

• Define a topic taxonomy for your research collaboration
• Create documentation for your team on topic usage conventions
• Set up automated clients for continuous data collection
• Connect with the Evidence Blockchain to share validated findings