> ## 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.
# Arquitectura
> Arquitectura técnica de la plataforma SofIA
SofIA se implementa como un sistema distribuido que combina un SDK front-end (Web Component) con servicios back-end especializados. La plataforma utiliza streaming seguro para comunicaciones en tiempo real y un framework cognitivo basado en agentes especializados para el procesamiento de información clínica.
## Arquitectura del Sistema
La aplicación host integra el **SofIA SDK Web Component**, proporcionando configuración y contexto del paciente.
El SDK se comunica a través de dos canales: la **SofIA REST API** para procesamiento de IA, y conexiones **WebSocket** para transcripción en tiempo real.
La REST API enruta las solicitudes a través del **Framework Cognitivo** para generación de reportes, mientras el **Motor de Transcripción** procesa los flujos de audio.
Los reportes generados y las transcripciones fluyen de vuelta a través del SDK hacia la aplicación **EHR/HIS** host.
## Arquitectura del SDK
El SofIA SDK es un **Web Component** (``) construido con React y TypeScript, envuelto mediante `@r2wc/react-to-web-component`. Utiliza **Shadow DOM** para encapsulación completa de estilos, asegurando que los estilos del SDK nunca entren en conflicto con la aplicación host.
### Jerarquía de Providers
El componente utiliza internamente una arquitectura de providers por capas. Cada provider gestiona un dominio específico de la funcionalidad del SDK:
Los providers se envuelven unos a otros en este orden (más externo a más interno):
**ApiConfigProvider → SettingsProvider → I18nProvider → TranscriptorProvider → LangGraphProvider → ProcessingThreadsProvider → ThreadProvider → MessageImagesProvider → StreamProvider → ToastProvider → App**
| Provider | Responsabilidad |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **ApiConfigProvider** | Almacena credenciales de API (`apikey`, `baseurl`), la URL del transcriber resuelta, visibilidad del widget y estado de configuración de plantillas |
| **SettingsProvider** | Gestiona preferencias del usuario, selección de idioma, ID de plantilla y campos de plantilla |
| **I18nProvider** | Internacionalización — resuelve cadenas de UI basándose en el idioma activo (`es`, `en`) |
| **TranscriptorProvider** | Estado de grabación de audio, sesiones de transcripción y gestión de transcripciones en tiempo real |
| **LangGraphProvider** | Datos de sesión (paciente, doctor), estado de reportes, gestión de hilos e interacción con IA |
| **ProcessingThreadsProvider** | Gestiona hilos de procesamiento en segundo plano para generación de reportes |
| **ThreadProvider** | Ciclo de vida de hilos de chat — crear, cambiar y cachear conversaciones |
| **MessageImagesProvider** | Maneja imágenes adjuntas en mensajes del chat |
| **StreamProvider** | Conexión de streaming LangGraph para respuestas de IA en tiempo real |
| **ToastProvider** | Sistema de notificaciones de UI |
### Registro del Web Component
El SDK se registra automáticamente como elemento personalizado al cargarse:
```javascript theme={null}
// Registro automático al cargar
customElements.define('sofia-sdk', SofiaSDK);
```
El wrapper de Web Component mapea atributos HTML a props de React con conversión automática de tipos:
| Tipo de Atributo | Ejemplos | Conversión |
| ---------------- | ------------------------------ | ----------------------- |
| `string` | `apikey`, `baseurl`, `userid` | Paso directo |
| `boolean` | `isopen`, `debug` | String → Boolean |
| `json` | `patientdata`, `template` | JSON.parse automático |
| `function` | `handle-report`, `set-is-open` | Vinculación de callback |
## Flujo de Datos
### Chat y Generación de Reportes
El profesional sanitario interactúa mediante chat (texto) o voz (botón de micrófono). El audio se captura a través de la API MediaStream del navegador.
El audio se transmite por streaming a través de una conexión WebSocket al servicio de transcripción (la URL se resuelve desde la API de settings), que devuelve segmentos de texto en tiempo real. El SDK soporta múltiples motores de transcripción.
Los mensajes del chat (escritos o transcritos) se envían a la API REST de SofIA (`baseurl`), que los enruta a través del framework cognitivo usando streaming LangGraph para entrega de respuestas en tiempo real.
Cuando se proporcionan `template` y `templateid`, aparece el botón de generar. Al hacer clic, la IA utiliza el esquema JSON Schema de la plantilla para estructurar datos clínicos de la conversación en un reporte formateado.
El reporte generado se entrega a la aplicación host mediante el callback `handle-report`, permitiendo al EHR/HIS procesar, mostrar o almacenar los datos estructurados.
### Resolución de Plantillas
El SDK resuelve la configuración de plantillas con compatibilidad hacia atrás:
```
prop template (preferido) → prop toolsargs (fallback deprecado) → sin plantilla (modo solo chat)
```
La generación de reportes solo se habilita cuando se proporcionan **tanto** `templateid` como una plantilla válida. En caso contrario, el SDK opera en modo solo chat automáticamente.
## Framework Cognitivo
El núcleo de procesamiento de SofIA se basa en un sistema de agentes especializados que colaboran para generar documentación clínica precisa:
* **Motor de razonamiento**: Modelo de lenguaje especializado en dominio médico que coordina las operaciones de los agentes
* **Agente de documentación**: Genera notas clínicas estructuradas siguiendo plantillas JSON Schema predefinidas
* **Agentes de codificación**: Especializados en sistemas de clasificación médica (SNOMED CT, CIE-10, LOINC)
* **Agente de validación**: Verifica la coherencia clínica y reduce errores mediante validación cruzada
## Sistema de Transcripción
La pila de transcripción está optimizada para el procesamiento de audio médico:
* **Captura de audio**: API MediaStream del navegador → AudioContext → Streaming WebSocket
* **Transcriptor en tiempo real**: Proporciona retroalimentación inmediata durante las consultas
* **Motor de transcripción médica**: Especializado en terminología y contexto clínico específico
* **Sistema de traducción**: Soporte nativo para múltiples idiomas
* **Separación de interlocutores**: Identificación automática de médico y paciente
* **Normalización terminológica**: Corrección y estandarización de términos médicos
### Pipeline de Audio
El **Micrófono** del navegador proporciona un **MediaStream** a través de la API MediaStream.
El stream pasa por un **AudioContext** para procesamiento, luego se envía a través de una conexión **WebSocket**.
El **Motor de Transcripción** convierte el audio en segmentos de **texto en tiempo real**.
El texto transcrito se muestra en la interfaz del **SofIA SDK Chat**.
La grabación de audio utiliza un **patrón de sesión singleton** — solo una sesión de grabación puede estar activa en cualquier momento en toda la aplicación, previniendo conflictos con múltiples instancias de micrófono.
## Arquitectura de Seguridad
* **Encapsulación Shadow DOM**: Los estilos y DOM del SDK están aislados de la aplicación host
* **HTTPS/WSS requerido**: Todas las comunicaciones usan protocolos cifrados
* **Enmascaramiento de PII**: Los identificadores de paciente y doctor se enmascaran automáticamente en logs de debug para cumplimiento HIPAA/GDPR
* **Almacenamiento local cifrado**: Los datos de sesión se cifran usando la clave API como semilla
* **Sin persistencia de datos**: Los datos clínicos no se almacenan localmente más allá de la sesión activa
## Próximos Pasos
1. [Detalles de seguridad y cumplimiento](/sofia/es/platform/security-compliance)
2. [Configurar propiedades requeridas](/sofia/es/sdk/required-properties)
3. [Diseñar esquemas de datos clínicos](/sofia/es/sdk/templates)
4. [Integrar en tu framework](/sofia/es/sdk/vanilla)