ClarityNote AI — API Explainer

Concepto

ClarityNote AI es un SaaS vertical B2B para terapeutas y psicólogos. Automatiza las tareas administrativas más costosas en tiempo: redacción de notas clínicas, extracción de diagnósticos y generación de planes de tratamiento.

El flujo central:

Terapeuta → sube audio de sesión → IA transcribe → GPT-4o genera nota SOAP
          → extrae códigos ICD-10/DSM-5 → sugiere plan de tratamiento

---

Arquitectura

┌─────────────────────────────────────────────────────────────┐
│                     Spring Boot 4.0.4 / Java 25             │
│                                                             │
│  AuthController   PatientController   SessionController     │
│  ClinicalNoteController                                     │
│       │                 │                   │               │
│  AuthService      PatientService      SessionService        │
│                                       AudioProcessingService│
│                                       ClinicalNoteService   │
│       │                 │                   │               │
│  UserRepository  PatientRepository  SessionAudioRepository  │
│                          ClinicalNoteRepository             │
│                                                             │
│  ── Security ────────────────────────────────────────────── │
│  JwtAuthenticationFilter → JwtService → BCrypt              │
│                                                             │
│  ── AI Integration ──────────────────────────────────────── │
│  OpenAiChatClient (Feign) → api.openai.com                  │
│                                                             │
│  ── Persistence ─────────────────────────────────────────── │
│  Spring Data JPA → PostgreSQL                               │
└─────────────────────────────────────────────────────────────┘

Capas

Capa	Paquete	Responsabilidad
Controller	controller/	HTTP ↔ DTO mapping
Service	service/	Lógica de negocio y orquestación
Repository	repository/	Spring Data JPA
Model	model/	Entidades JPA (Jakarta Persistence)
DTO	dto/	Java 25 Records — transporte inmutable
Security	security/	JWT filter + UserDetailsService
Client	client/	Feign declarativo → OpenAI

Virtual Threads (Java 25)

AudioProcessingService.submitAsync() ejecuta cada pipeline de procesamiento en un virtual thread (Executors.newVirtualThreadPerTaskExecutor()). La petición HTTP retorna en 202 Accepted inmediatamente mientras Whisper + GPT-4o corren en segundo plano.

---

Entidades de Dominio

User          — cuenta de terapeuta (implements UserDetails)
Patient       — paciente vinculado a un terapeuta
SessionAudio  — archivo de audio subido + estado del job (PENDING/PROCESSING/COMPLETED/FAILED)
ClinicalNote  — nota SOAP/DAP generada por IA para una sesión

---

Endpoints REST

Auth (público)

Método	Path	Body	Respuesta
%%INLINE10%%	%%INLINE11%%	%%INLINE12%%	%%INLINE13%% (JWT)
%%INLINE14%%	%%INLINE15%%	%%INLINE16%%	%%INLINE17%% (JWT)

Pacientes (JWT requerido)

Método	Path	Descripción
%%INLINE18%%	%%INLINE19%%	Listar pacientes del terapeuta
%%INLINE20%%	%%INLINE21%%	Detalle de un paciente
%%INLINE22%%	%%INLINE23%%	Crear paciente
%%INLINE24%%	%%INLINE25%%	Actualizar paciente
%%INLINE26%%	%%INLINE27%%	Eliminar paciente

Sesiones de Audio (JWT requerido)

Método	Path	Descripción
%%INLINE28%%	%%INLINE29%%	Subir audio → inicia pipeline IA async
%%INLINE30%%	%%INLINE31%%	Consultar estado del job
%%INLINE32%%	%%INLINE33%%	Listar sesiones de un paciente

Notas Clínicas (JWT requerido)

Método	Path	Descripción
%%INLINE34%%	%%INLINE35%%	Nota SOAP generada para la sesión
%%INLINE36%%	%%INLINE37%%	Todas las notas + códigos ICD-10/DSM-5
%%INLINE38%%	%%INLINE39%%	Borrador plan de tratamiento IA

---

MVP Features Implementadas

Feature	Implementación
Transcripción de audio	AudioProcessingService.transcribe() → OpenAI Whisper (o GPT-4o mock)
Notas SOAP/DAP	AudioProcessingService.generateSoapNote() → prompt estructurado GPT-4o
Extracción ICD-10/DSM-5	Campo %%INLINE42%% en %%INLINE43%%, visible en /notes
Planes de tratamiento	ClinicalNoteService.generateTreatmentPlan() → agrega notas + GPT-4o

---

Análisis de Negocio

Problema: terapeutas pierden 20-30% de tiempo en documentación administrativa.

Propuesta de valor: reducir ese tiempo a < 5 minutos por sesión mediante generación automática de notas SOAP conformes con los estándares ICD-10/DSM-5.

Monetización: freemium SaaS.

• Free: 3 sesiones/mes
• Pro ($49/mes/terapeuta): sesiones ilimitadas + almacenamiento seguro + exportación EHR
• Clinic ($199/mes): multi-terapeuta + analytics + integración seguro

TAM estimado: ~200 000 terapeutas independientes sólo en EE.UU. × $49/mes = ~$118M ARR potencial.

Referencia: Klarify (YC)

---

Cómo Ejecutar

Requisitos

• Java 25
• Maven 3.9+
• PostgreSQL 15+ (o Docker)

Configuración

Añadir a application.yml (o variables de entorno):

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/claritynote
    username: postgres
    password: postgres
  jpa:
    hibernate:
      ddl-auto: update
    show-sql: false

app:
  jwt:
    secret: <base64-encoded-256bit-key>
    expiration-ms: 86400000   # 24 h

openai:
  base-url: https://api.openai.com
  api-key: sk-...

Compilar

mvn clean compile

Ejecutar

mvn spring-boot:run

Ejemplo rápido

# 1. Registrar terapeuta
curl -X POST http://localhost:8080/api/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"dr@example.com","password":"Secret123","fullName":"Dr. Ana López"}'

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

# 3. Crear paciente
curl -X POST http://localhost:8080/api/patients \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"firstName":"Carlos","lastName":"García","dateOfBirth":"1985-03-15"}'

# 4. Subir audio de sesión (id=1)
curl -X POST "http://localhost:8080/api/sessions/upload?patientId=1" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@session.mp3"

# 5. Consultar estado (esperar COMPLETED)
curl http://localhost:8080/api/sessions/1 -H "Authorization: Bearer $TOKEN"

# 6. Obtener nota SOAP generada
curl http://localhost:8080/api/sessions/1/note -H "Authorization: Bearer $TOKEN"

# 7. Obtener plan de tratamiento
curl http://localhost:8080/api/patients/1/treatment-plan -H "Authorization: Bearer $TOKEN"

---

Seguridad

• Autenticación: JWT firmado con HMAC-SHA256 (JJWT 0.12.6)
• Autorización: cada endpoint valida que el recurso pertenece al terapeuta autenticado
• Contraseñas: BCrypt (factor 10)
• Sesiones: completamente stateless — no hay estado de sesión en servidor
• HIPAA: en producción, añadir cifrado AES-256 en reposo, audit log y BAA con AWS/GCP

---

Generado por Forge-AI · Spring Boot 4.0.4 · Java 25

---

FinOps Analysis para ClarityNote AI

Estimación de Costos y Margen de Beneficio

Para una micro-startup como ClarityNote AI, la gestión de costos operativos es crucial para la sostenibilidad y el crecimiento. A continuación, se detalla una estimación de costos y el margen de beneficio inicial basado en las especificaciones del MVP y un volumen de uso proyectado.

Supuestos Clave de Uso Mensual:

• Usuarios pagos: 20 terapeutas.
• Usuarios freemium: 50 terapeutas.
• Sesiones promedio: 20 sesiones/mes por usuario pago, 3 sesiones/mes por usuario freemium.

Total de sesiones procesadas: (20 20) + (50 * 3) = 400 + 150 = 550 sesiones/mes.

• Duración promedio de audio: 50 minutos por sesión.
• Tokens LLM por sesión: ~3000 tokens de entrada (transcripción resumida + prompt) y ~950 tokens de salida (nota SOAP + plan de tratamiento amortizado).

Desglose de Costos Operativos Mensuales Estimados:

1. Costos de APIs de IA (OpenAI):

* Transcripción de Audio (Whisper API): 27,500 minutos de audio (550 sesiones 50 min/sesión) * $0.006/minuto = $165.00 * Generación/Análisis LLM (GPT-4o-mini): Tokens de Entrada: 550 sesiones 3000 tokens/sesión = 1,650,000 tokens (1.65M) Costo Input: 1.65M $0.15/1M tokens = $0.2475 Tokens de Salida: 550 sesiones 950 tokens/sesión = 522,500 tokens (0.5225M) Costo Output: 0.5225M $0.60/1M tokens = $0.3135 * Costo Total LLM: ~$0.56 (redondeado a $1.00 para el desglose, dada su insignificancia frente a Whisper). * Total APIs de IA: ~$166.00

1. Costos de Infraestructura Cloud (AWS Baseline):

* Cómputo (Spring Boot API): AWS EC2 t3.small (2 vCPU, 2 GiB RAM): ~$18.00 * Base de Datos (PostgreSQL): AWS RDS db.t3.micro (2 vCPU, 1 GiB RAM, 20GB almacenamiento): ~$18.00 Almacenamiento de Audio (S3): ~27.5 GB $0.023/GB + solicitudes: ~$1.00 * Networking y Otros (CloudWatch, Data Transfer): ~$3.00 * Total Infraestructura: ~$40.00

Costo Operativo Mensual Total Estimado: $166 (APIs IA) + $40 (Infraestructura) = $206.00

Estimación de Ingresos Mensuales

• Modelo de Monetización: SaaS B2B con plan de suscripción mensual de $25 por terapeuta.

Ingreso Mensual Estimado: 20 clientes pagos $25/cliente = $500.00

Margen de Beneficio

• Beneficio Bruto: $500 (Ingresos) - $206 (Costos) = $294

Margen de Beneficio: (($294 / $500) 100) = 58.8% (redondeado a 59%)

Este margen del 59% es saludable para una startup, especialmente considerando el bajo volumen inicial. Sin embargo, es vital implementar principios de FinOps desde el principio para mantener y mejorar este margen a medida que la startup escala.

Estrategias FinOps para Optimización de Costos

Las siguientes optimizaciones son cruciales para ClarityNote AI:

1. Optimización de Cómputo para Procesamiento Asíncrono:

* Serverless (AWS Lambda/GCP Cloud Functions): Migrar el flujo de procesamiento de audio y llamadas a LLM a funciones serverless. Esto eliminará la necesidad de una instancia EC2 24/7 para el procesamiento de fondo, pagando solo por el tiempo de ejecución real, lo cual es ideal para cargas de trabajo asíncronas y esporádicas. * Contenedores (AWS Fargate/GKE Autopilot): Si se requiere más control o persistencia de procesos, considerar plataformas de contenedores serverless que abstraen la gestión de la infraestructura subyacente y optimizan el uso de recursos.

1. Gestión Inteligente del Almacenamiento de Audio:

* Políticas de Ciclo de Vida en S3: Configurar reglas para mover automáticamente los archivos de audio más antiguos (ej. después de 30 o 60 días) a clases de almacenamiento más baratas como S3 Infrequent Access o S3 Glacier Deep Archive, reduciendo significativamente los costos a largo plazo. * Compresión de Audio: Evaluar la posibilidad de comprimir las grabaciones de audio después de la transcripción para reducir el espacio de almacenamiento requerido, manteniendo la calidad suficiente para futuras referencias.

1. Estrategias Avanzadas para el Uso de LLMs:

* Prompt Engineering Avanzado: Invertir tiempo en refinar los prompts para ser lo más concisos posible, minimizando los tokens de entrada, y diseñando el formato de salida para ser eficiente en tokens. * Caching de Respuestas: Implementar un sistema de caché para respuestas LLM que sean predecibles o se repitan con frecuencia (ej. formatos de notas estandarizados, listas de códigos de diagnóstico comunes). Esto reducirá las llamadas redundantes a la API de OpenAI. * Modelos de Código Abierto y Fine-tuning: A medida que la startup crezca y acumule más datos, explorar el fine-tuning de modelos LLM de código abierto (ej. Llama 3 8B, Mistral) para tareas específicas (ej. generación de notas SOAP). Esto podría reducir drásticamente los costos de LLM a largo plazo, especialmente para tareas con datos específicos del dominio. Podrían ejecutarse en instancias de GPU más pequeñas o incluso en la propia infraestructura.

1. Optimización de Base de Datos:

* Bases de Datos Serverless (ej. Aurora Serverless v2 PostgreSQL): Si la carga de la base de datos es altamente variable, una opción serverless escalará automáticamente a cero o a un mínimo costo durante períodos de baja actividad, lo que puede ser más económico que una instancia db.t3.micro constante. * Servicios Gestionados de Bajo Costo (ej. Supabase/Neon): Para una micro-startup, estos proveedores ofrecen bases de datos PostgreSQL gestionadas con planes gratuitos o de bajo costo que pueden ser más económicos que RDS directamente, especialmente para arrancar.

1. Monitoreo y Alertas de Costos:

* Presupuestos y Alertas Cloud: Configurar presupuestos mensuales y alertas en AWS Cost Explorer (o equivalentes en GCP/Azure) para recibir notificaciones cuando los gastos se acerquen a los umbrales definidos. Esto permite una acción proactiva ante aumentos inesperados. * Etiquetado de Recursos: Implementar una estrategia de etiquetado consistente para todos los recursos cloud (%%INLINE48%%, %%INLINE49%%, owner:finops) para tener una visibilidad granular de los costos por componente y facilitar la atribución.

Al aplicar estas estrategias FinOps, ClarityNote AI puede asegurar que su infraestructura y uso de IA sean lo más eficientes posible, maximizando el margen de beneficio y permitiendo un crecimiento sostenible.