> ## Documentation Index
> Fetch the complete documentation index at: https://omniloy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="EHR/HIS System">
    The host application embeds the **SofIA SDK Web Component**, providing configuration and patient context.
  </Step>

  <Step title="Communication Channels">
    The SDK communicates through two channels: the **SofIA REST API** for AI processing, and **WebSocket** connections for real-time transcription.
  </Step>

  <Step title="Backend Processing">
    The REST API routes requests through the **Cognitive Framework** for report generation, while the **Transcription Engine** processes audio streams.
  </Step>

  <Step title="Results Delivery">
    Generated reports and transcriptions flow back through the SDK to the host **EHR/HIS** application.
  </Step>
</Steps>

## 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:

```javascript theme={null}
// 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

<Steps>
  <Step title="User interaction">
    The healthcare professional interacts via chat (text) or voice (microphone button). Audio is captured through the browser's MediaStream API.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

### 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

<Steps>
  <Step title="Audio Capture">
    The browser's **Microphone** provides a **MediaStream** via the MediaStream API.
  </Step>

  <Step title="Audio Processing">
    The stream passes through an **AudioContext** for processing, then is sent over a **WebSocket** connection.
  </Step>

  <Step title="Transcription">
    The **Transcription Engine** converts the audio into **real-time text** segments.
  </Step>

  <Step title="Display">
    Transcribed text is displayed in the **SofIA SDK Chat** interface.
  </Step>
</Steps>

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](/sofia/en/platform/security-compliance)
2. [Configure required properties](/sofia/en/sdk/required-properties)
3. [Design clinical data schemas](/sofia/en/sdk/templates)
4. [Integrate in your framework](/sofia/en/sdk/vanilla)