Arquitectura de RheumAI

Mapa del sistema

flowchart TB
  UI["Preact web app"] --> API["Elysia API"]
  EXT["Cliente externo"] --> API
  STUDY["BiobadamexAI study harness"] --> SR["Ruta stateless de estudio"]

  API --> ACCESS["Auth · rate limits · x402 opcional"]
  ACCESS --> SETUP["Conversación y estado"]
  SETUP --> PLAN["PLANNING"]
  PLAN --> TOOLS["Herramientas clínicas y fuentes"]
  TOOLS --> RET["DAG / RAG / grafo"]
  RET --> REPLY["REPLY o HYPOTHESIS"]
  REPLY --> ORVS["ORVS + control PMID"]
  ORVS --> ETH["Revisión ética"]
  ETH --> UI

  SR --> PLAN2["PLANNING con límite de herramientas"]
  PLAN2 --> TOOLS2["Herramientas permitidas"]
  TOOLS2 --> REPLY2["REPLY"]
  REPLY2 --> STUDY

  SETUP --> DB[("Supabase")]
  TOOLS --> OBJ[("Storage S3 compatible")]
  TOOLS --> LIT["PubMed · Semantic Scholar · OpenScholar · conocimiento local"]

Componentes

Cliente web

La interfaz Preact gestiona sesiones, autenticación, carga de archivos, envío de mensajes, citas y estados de pago. El backend sirve el bundle y usa una ruta fallback para la aplicación de una sola página.

API Elysia

src/index.ts monta las rutas de autenticación, configuración, chat, investigación profunda, comunidad, búsqueda, criptografía y estudio. También sirve la aplicación web y expone endpoints de salud.

Estado y persistencia

El chat normal crea usuarios, conversaciones, mensajes y estado en Supabase. Los archivos pueden ir a un proveedor S3 compatible y su texto analizado se agrega al estado del turno. Esto significa que /api/chat no es stateless.

La ruta de estudio usa UUID nulos y omite identificadores de mensaje y estado. Sus escrituras quedan desactivadas por diseño. Acepta texto desidentificado, puede fijar un proveedor/modelo y devuelve atribución, herramientas usadas, latencia y uso de tokens.

Planificador y herramientas

El registro descubre carpetas bajo src/tools/ y carga los index.ts habilitados. Variables TOOL_<NOMBRE>_ENABLED pueden activar o desactivar una herramienta. El planificador decide qué fuentes consultar y cuál acción principal ejecutar.

Familias relevantes:

Evidencia: PubMed, Semantic Scholar, OpenScholar, conocimiento local y grafo.
Clínica: razonamiento clínico, interpretación de laboratorio, resumen para aseguradora y protocolos.
Síntesis: REPLY, HYPOTHESIS, reflexión y revisión ética.
Infraestructura: archivos, análisis de datos, almacenamiento y servicios x402.

Que una carpeta exista no garantiza que cargue. La carga es dinámica, registra errores y continúa con las herramientas disponibles.

Recuperación y ranking

El flujo puede combinar recuperación por embeddings, grafo local y búsqueda semántica. Después, DAG-RETRIEVAL reordena documentos para acercar la evidencia a la consulta. Si no hay contexto útil, algunos modos regresan a una respuesta directa del modelo.

Modelos

La biblioteca de LLM expone una interfaz común para varios proveedores. resilientChatCompletion implementa fallbacks. En el estudio, un contexto fijado puede obligar a que todos los saltos observables usen un mismo proveedor y modelo, con fallback deshabilitado.

Dos flujos que no deben confundirse

Aspecto	Chat normal	Ruta de estudio
Endpoint	`/api/chat`	`/v1/study/rheumaai-reply`
Persistencia	Sí	No, por diseño
Archivos	Sí	Solo texto de nota
Sesión	Conversación persistente	Una solicitud aislada
Auth	Sesión, cliente o x402 según configuración	Bearer dedicado; cerrado si falta la clave
Herramientas	Las elegidas por el planificador	Allowlist y techo de costo
ORVS posterior a la respuesta	Sí en el flujo normal; modos explícitos disponibles	No hay una llamada ORVS final explícita en esta ruta
Resultado	Respuesta conversacional	Respuesta, atribución y telemetría del turno

Dependencias externas

Supabase para conversaciones, mensajes, estados y búsquedas.
Storage S3 compatible para archivos cuando está configurado.
Proveedores LLM configurables.
PubMed, Semantic Scholar, OpenScholar y corpus local para evidencia.
Servicios médicos x402 opcionales.
Railway y el dominio rheumai.xyz según la configuración del repositorio.