Architecture

Technical architecture of the SofIA platform

SofIA is implemented as a distributed system that combines a front-end SDK (Web Component) with specialized back-end services. The platform uses secure streaming for real-time communications and a cognitive framework based on specialized agents for clinical information processing.

System Architecture

1. EHR/HIS System

   The host application embeds the SofIA SDK Web Component, providing configuration and patient context.

2. Communication Channels

   The SDK communicates through two channels: the SofIA REST API for AI processing, and WebSocket connections for real-time transcription.

3. Backend Processing

   The REST API routes requests through the Cognitive Framework for report generation, while the Transcription Engine processes audio streams.

4. Results Delivery

   Generated reports and transcriptions flow back through the SDK to the host EHR/HIS application.

SDK Architecture

The SofIA SDK is a Web Component (<sofia-sdk>) built with React and TypeScript, wrapped using @r2wc/react-to-web-component. It uses Shadow DOM for complete style encapsulation, ensuring the SDK’s styles never conflict with the host application.

Provider Hierarchy

The component internally uses a layered provider architecture. Each provider manages a specific domain of the SDK’s functionality:

The providers wrap each other in this order (outermost to innermost):

ApiConfigProvider → SettingsProvider → I18nProvider → TranscriptorProvider → LangGraphProvider → ProcessingThreadsProvider → ThreadProvider → MessageImagesProvider → StreamProvider → ToastProvider → App

Provider	Responsibility
ApiConfigProvider	Stores API credentials (apikey, baseurl), the resolved transcriber URL, widget visibility, and template configuration state
SettingsProvider	Manages user preferences, language selection, template ID, and template fields
I18nProvider	Internationalization — resolves UI strings based on the active language (es, en)
TranscriptorProvider	Audio recording state, transcription sessions, and real-time transcript management
LangGraphProvider	Session data (patient, doctor), report state, thread management, and AI interaction context
ProcessingThreadsProvider	Manages background processing threads for report generation
ThreadProvider	Chat thread lifecycle — creating, switching, and caching conversation threads
MessageImagesProvider	Handles image attachments within chat messages
StreamProvider	LangGraph streaming connection for real-time AI responses
ToastProvider	UI notification system

Web Component Registration

The SDK registers itself as a custom element when loaded:

// Automatic registration on load
customElements.define('sofia-sdk', SofiaSDK);

The Web Component wrapper maps HTML attributes to React props with automatic type conversion:

Attribute Type	Examples	Conversion
string	apikey, baseurl, userid	Direct pass-through
boolean	isopen, debug	String → Boolean
json	patientdata, template	JSON.parse automatically
function	handle-report, set-is-open	Callback binding

Data Flow

Chat and Report Generation

1. User interaction

   The healthcare professional interacts via chat (text) or voice (microphone button). Audio is captured through the browser’s MediaStream API.

2. Transcription

   Audio streams through a WebSocket connection to the transcription service (the URL is resolved from the settings API), which returns real-time text segments. The SDK supports multiple transcription engines.

3. AI Processing

   Chat messages (typed or transcribed) are sent to the SofIA REST API (baseurl), which routes them through the cognitive framework using LangGraph streaming for real-time response delivery.

4. Report Generation

   When template and templateid are provided, the generate button appears. On click, the AI uses the JSON Schema template to structure clinical data from the conversation into a formatted report.

5. Report Delivery

   The generated report is delivered to the host application via the handle-report callback, allowing the EHR/HIS to process, display, or store the structured data.

Template Resolution

The SDK resolves template configuration with backward compatibility:

template prop (preferred) → toolsargs prop (deprecated fallback) → no template (chat-only mode)

Report generation is only enabled when both templateid and a valid template are provided. Otherwise, the SDK operates in chat-only mode automatically.

Cognitive Framework

The SofIA processing core is based on a system of specialized agents that collaborate to generate accurate clinical documentation:

• Reasoning engine: Language model specialized in medical domain that coordinates agent operations
• Documentation agent: Generates structured clinical notes following predefined JSON Schema templates
• Coding agents: Specialized in medical classification systems (SNOMED CT, ICD-10, LOINC)
• Validation agent: Verifies clinical coherence and reduces errors through cross-validation

Transcription System

The transcription stack is optimized for medical audio processing:

• Audio capture: Browser MediaStream API → AudioContext → WebSocket streaming
• Real-time transcriptor: Provides immediate feedback during consultations
• Medical transcription engine: Specialized in clinical terminology and specific context
• Translation system: Native support for multiple languages
• Speaker separation: Automatic identification of doctor and patient
• Terminological normalization: Correction and standardization of medical terms

Audio Pipeline

1. Audio Capture

   The browser’s Microphone provides a MediaStream via the MediaStream API.

2. Audio Processing

   The stream passes through an AudioContext for processing, then is sent over a WebSocket connection.

3. Transcription

   The Transcription Engine converts the audio into real-time text segments.

4. Display

   Transcribed text is displayed in the SofIA SDK Chat interface.

The audio recording uses a singleton session pattern — only one recording session can be active at any time across the entire application, preventing conflicts with multiple microphone instances.

Security Architecture

• Shadow DOM encapsulation: SDK styles and DOM are isolated from the host application
• HTTPS/WSS required: All communications use encrypted protocols
• PII masking: Patient and doctor identifiers are automatically masked in debug logs for HIPAA/GDPR compliance
• Encrypted local storage: Session data is encrypted using the API key as seed
• No data persistence: Clinical data is not stored locally beyond the active session

Next Steps

1. Security and compliance details
2. Configure required properties
3. Design clinical data schemas
4. Integrate in your framework