AuraScribe API — Explainer

Concepto

AuraScribe es un Virtual Scribe médico construido como API SaaS B2B. Los médicos suben grabaciones de sus consultas; AuraScribe las transcribe con Whisper y genera automáticamente una nota clínica estructurada en formato SOAP usando GPT-4o. El resultado reduce hasta un 40 % la carga administrativa, devolviendo tiempo de atención al paciente.

---

Arquitectura

┌─────────────────────────────────────────────────────────────────┐
│  Cliente (Web / Mobile)                                         │
└────────────────────────┬────────────────────────────────────────┘
                         │ HTTPS  (JWT Bearer)
┌────────────────────────▼────────────────────────────────────────┐
│  Spring Boot 4.0.4 — Java 25 — Virtual Threads                  │
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │ AuthController│  │Consultation  │  │ ClinicalNote /       │  │
│  │ /auth/**     │  │Controller    │  │ User Controllers      │  │
│  └──────┬───────┘  └──────┬───────┘  └──────────┬───────────┘  │
│         │                 │                      │               │
│  ┌──────▼───────┐  ┌──────▼───────┐  ┌──────────▼──────────┐  │
│  │  UserService  │  │Consultation  │  │   JwtService         │  │
│  │  (register/  │  │Service       │  │   (HS256 / JJWT)     │  │
│  │   login)     │  │(upload/list/ │  └─────────────────────┘   │
│  └──────────────┘  │ getNote)     │                             │
│                    └──────┬───────┘                             │
│                           │ @Async (virtual thread)             │
│                    ┌──────▼───────┐                             │
│                    │AiProcessing  │                             │
│                    │Service       │                             │
│                    └──┬───────┬───┘                             │
│                       │       │                                 │
│             Whisper   │       │  GPT-4o                         │
│          ┌────────────▼─┐  ┌──▼────────────────┐               │
│          │ RestClient   │  │ OpenAiChatClient   │               │
│          │ (multipart)  │  │ (@FeignClient)     │               │
│          └──────────────┘  └───────────────────┘               │
│                                                                  │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ PostgreSQL (JPA/Hibernate 6)                             │    │
│  │  users │ consultation_audios │ clinical_notes           │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

Capas

Paquete	Responsabilidad
controller	REST endpoints — validación de input, delegación a service
service	Lógica de negocio, orquestación async, gestión de tokens
repository	Spring Data JPA — derived queries sobre PostgreSQL
%%INLINE3%%	Entidades JPA (%%INLINE4%%, %%INLINE5%%, %%INLINE6%%)
dto	Records inmutables para request/response
client	Feign client OpenAI Chat + RestClient Whisper
%%INLINE9%%	%%INLINE10%%, UserDetailsServiceImpl
%%INLINE12%%	%%INLINE13%%, %%INLINE14%%, %%INLINE15%%, AppProperties

---

Endpoints

Autenticación (público)

Método	Path	Body	Respuesta
POST	%%INLINE17%%	%%INLINE18%%	201 AuthResponse
POST	%%INLINE20%%	%%INLINE21%%	200 AuthResponse

Consultas (requiere JWT)

Método	Path	Body / Params	Respuesta
POST	%%INLINE23%%	%%INLINE24%%	202 ConsultationResponse
GET	%%INLINE26%%	—	200 %%INLINE27%%
GET	%%INLINE28%%	—	200 %%INLINE29%%

Notas Clínicas (requiere JWT)

Método	Path	Respuesta
GET	%%INLINE30%%	200 %%INLINE31%%

Perfil (requiere JWT)

Método	Path	Respuesta
GET	%%INLINE32%%	200 %%INLINE33%%

---

Flujo de Procesamiento Asíncrono

POST /api/v1/consultations
  │
  ├── StorageService.store()        → guarda audio en /tmp/aura-scribe-uploads/
  ├── ConsultationAudioRepository.save()  → estado: UPLOADED (commit)
  └── AiProcessingService.processAsync()  → @Async (virtual thread)
           │
           ├── setStatus(PROCESSING) → save()
           ├── RestClient → OpenAI /v1/audio/transcriptions (Whisper)
           ├── setTranscription() → save()
           ├── OpenAiChatClient → /v1/chat/completions (GPT-4o)
           ├── parseSoapSections() → ClinicalNoteRepository.save()
           └── setStatus(COMPLETED) → save()

---

Modelo de Datos

users

Campo	Tipo	Notas
id	UUID	PK generada automáticamente
email	VARCHAR	UNIQUE, usado como username JWT
password	VARCHAR	BCrypt hash
full_name	VARCHAR	Nombre en notas clínicas
specialty	VARCHAR	Especialidad médica
role	VARCHAR	DOCTOR / ADMIN
enabled	BOOLEAN	Soft-delete / suspensión
created_at	TIMESTAMP	Inmutable

consultation_audios

Campo	Tipo	Notas
id	UUID	PK
user_id	UUID	FK → users
original_filename	VARCHAR	Nombre original del archivo
stored_path	VARCHAR	Ruta absoluta en servidor
status	VARCHAR	UPLOADED/PROCESSING/COMPLETED/FAILED
transcription	TEXT	Resultado de Whisper
created_at	TIMESTAMP
updated_at	TIMESTAMP	Actualizado en cada cambio de estado

clinical_notes

Campo	Tipo	Notas
id	UUID	PK
consultationid	UUID	FK → consultationaudios (1:1)
subjective	TEXT	S — síntomas del paciente
objective	TEXT	O — hallazgos de examen
assessment	TEXT	A — diagnóstico
plan	TEXT	P — plan de tratamiento
raw_content	TEXT	JSON crudo del LLM (auditoría)
created_at	TIMESTAMP

---

Seguridad y Cumplimiento HIPAA

• Transporte: HTTPS requerido en producción (TLS 1.3).
• Autenticación: JWT HMAC-SHA256 con expiración configurable (default 24 h).
• Autorización: Todos los endpoints protegidos; cada consulta valida que el

recurso pertenece al médico autenticado (findByIdAndUserEmail).

• Almacenamiento: Los archivos de audio se guardan en un directorio configurable

(app.storage.upload-dir). En producción usar un volumen cifrado (AES-256) o un bucket con SSE (e.g. AWS S3 + KMS).

• Datos en BD: Configurar %%INLINE39%% a nivel de columna para %%INLINE40%%

y el contenido de clinical_notes en producción.

• Raw content: El campo raw_content preserva el JSON del LLM para auditoría

y re-procesamiento sin llamar de nuevo a la API.

---

Análisis de Negocio

Dimensión	Detalle
Problema	Médicos dedican ~40 % del tiempo a documentación administrativa
Mercado	Clínicas privadas y consultorios (< 20 médicos) sin solución EHR
Diferenciador	Precio accesible vs. enterprise; onboarding < 5 min; API-first
Monetización	Plan Individual (300 min/mes) · Plan Clínica (por usuario/mes)
CAC	Marketing de contenido médico + partnerships con asociaciones
Expansión	Integración bidireccional con EHR (HL7 FHIR); soporte de idiomas

---

Cómo Ejecutar

Pre-requisitos

• Java 25+
• Maven 3.9+
• PostgreSQL 15+ en ejecución
• Clave de API de OpenAI

Configuración (application.yml override o variables de entorno)

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/aurascribe
    username: postgres
    password: postgres
  jpa:
    hibernate:
      ddl-auto: update       # 'validate' en producción con Flyway/Liquibase
  threads:
    virtual:
      enabled: true          # Virtual Threads (Project Loom)

app:
  jwt:
    secret: <BASE64_SECRET_MIN_32_BYTES>
    expiration: 86400
  openai:
    api-key: sk-...
    base-url: https://api.openai.com
    model: gpt-4o
    whisper-model: whisper-1
  storage:
    upload-dir: /var/data/aura-scribe-uploads

Compilar y ejecutar

# Compilar
mvn clean compile

# Ejecutar (requiere PostgreSQL y OpenAI key)
mvn spring-boot:run

# Verificar salud
curl http://localhost:8080/actuator/health

Ejemplo de uso rápido

# 1. Registrar médico
curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"dr@clinic.com","password":"Secret123!","fullName":"Dr. García","specialty":"Internal Medicine"}'

# 2. Login (obtener JWT)
TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"dr@clinic.com","password":"Secret123!"}' | jq -r '.token')

# 3. Subir grabación de consulta
curl -X POST http://localhost:8080/api/v1/consultations \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@consultation.mp3"
# → Devuelve {"id":"<UUID>","status":"UPLOADED",...}

# 4. Verificar estado (polling)
curl http://localhost:8080/api/v1/consultations/<UUID> \
  -H "Authorization: Bearer $TOKEN"
# → {"status":"COMPLETED",...}

# 5. Leer nota SOAP generada
curl http://localhost:8080/api/v1/notes/<UUID> \
  -H "Authorization: Bearer $TOKEN"
# → {"subjective":"...","objective":"...","assessment":"...","plan":"..."}

---

Referencias

• Ambient Clinical Intelligence in Healthcare (YouTube)
• OpenAI Whisper API
• OpenAI Chat Completions API
• Spring Boot 4 Documentation
• JJWT 0.12.x
• HIPAA Security Rule

---

FinOps Analysis para AuraScribe

Resumen de Costos y Rentabilidad

AuraScribe opera con una estructura de costos muy lean en su fase de MVP, aprovechando la eficiencia de los servicios cloud modernos y los LLMs de bajo costo. Con una base inicial de 20 clientes y un precio de suscripción de $25/mes, se proyecta un ingreso mensual de $500.

Los costos operativos mensuales se estiman en aproximadamente $100, lo que resulta en un margen de beneficio del 80%. Este alto margen es un indicador positivo de la viabilidad del modelo de negocio, especialmente dada la naturaleza de bajo costo de las APIs de IA y la infraestructura minimalista necesaria para un MVP.

Desglose de Costos Mensuales:

• APIs de IA (OpenAI Whisper STT y GPT-4o-mini): $65

Speech-to-Text (STT): El mayor componente de costo de la IA es la transcripción de audio. Para un volumen estimado de 500 consultas/mes (20 clientes 25 consultas/cliente), cada una de 20 minutos, se procesarían 10,000 minutos de audio. A $0.006/minuto (OpenAI Whisper), esto suma $60/mes. * Generación de Notas LLM: El procesamiento de los textos transcritos por GPT-4o-mini para generar notas SOAP consume aproximadamente 2.5 millones de tokens LLM al mes (considerando tokens de entrada y salida). A las tarifas actuales de GPT-4o-mini ($0.00015/1K tokens de entrada, $0.0006/1K tokens de salida), esto asciende a alrededor de $5/mes.

• Infraestructura Cloud (AWS): $25

* Cómputo (API Spring Boot): Una instancia t4g.micro de AWS EC2 (basada en ARM Graviton, más eficiente) es suficiente para el MVP, con un costo aproximado de $8/mes. * Base de Datos (PostgreSQL): Una instancia db.t4g.micro de AWS RDS para PostgreSQL, que incluye almacenamiento y IOPS básicos, cuesta alrededor de $15/mes. * Almacenamiento (S3) y Monitoreo (CloudWatch): El almacenamiento de archivos de audio en S3 y los costos básicos de logs y métricas en CloudWatch son mínimos, estimados en $2/mes.

• Otros Costos Operativos: $10

* Incluye gastos como el registro de dominio, servicio de correo electrónico básico y licencias de herramientas menores esenciales para la operación de la micro-startup.

Estrategias de Optimización FinOps Clave:

1. Optimización Agresiva de Prompts: Continuamente refinar los prompts para el LLM para minimizar la verbosidad y asegurar que solo se procese la información esencial. Esto tiene un impacto directo en el costo de tokens.
2. Implementación de Caching: Desarrollar una capa de caché para las notas clínicas. Si los patrones de consulta o las notas estandarizadas se repiten, se pueden servir desde el caché en lugar de generar nuevas llamadas al LLM.
3. Evaluación de Modelos de IA: A medida que la startup crece, se debe evaluar la posibilidad de usar modelos LLM de código abierto auto-hospedados (si la complejidad y el mantenimiento lo justifican) o explorar proveedores con tarifas aún más competitivas para volúmenes muy altos o tareas específicas.
4. Arquitectura Serverless para el Procesamiento de IA: Migrar el worker de procesamiento asíncrono de IA a una función serverless (ej. AWS Lambda o Google Cloud Run). Esto permite pagar solo por el tiempo de cómputo real utilizado, escalando automáticamente a cero cuando no hay trabajos pendientes y reduciendo drásticamente los costos de cómputo para cargas de trabajo intermitentes.
5. Gestión de la Retención de Datos: Establecer políticas claras de retención de datos para las grabaciones de audio. Una vez procesadas y las notas confirmadas, los archivos de audio pueden moverse a almacenamiento de bajo costo (como S3 Glacier) o eliminarse, reduciendo los costos de almacenamiento a largo plazo y mejorando el cumplimiento de la privacidad.
6. Monitoreo y Alertas de Costos: Configurar alertas de presupuesto y paneles de control de costos en la plataforma cloud para detectar gastos inesperados o patrones de uso ineficientes rápidamente. Esto es crucial para mantener la rentabilidad a medida que la operación escala.

Mediante la aplicación proactiva de estas estrategias FinOps, AuraScribe puede mantener un control estricto sobre sus gastos operativos, escalar de manera rentable y maximizar su margen de beneficio mientras crece su base de clientes.