---
slug: "cabo-health-ai"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/guaderrama/cabo-health-ai@main/README.md"
repo: "https://github.com/guaderrama/cabo-health-ai"
source_file: "README.md"
branch: "main"
---
# Cabo Health Nova 🏥

> Asistente Médico con IA Conversacional de Próxima Generación

[![Estado](https://img.shields.io/badge/Estado-Producción-success)](https://etric4luf0vq.space.minimax.io)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue)](https://www.typescriptlang.org/)
[![React](https://img.shields.io/badge/React-18.3-61dafb)](https://reactjs.org/)
[![Supabase](https://img.shields.io/badge/Supabase-Backend-green)](https://supabase.com/)

## 🌐 Aplicación en Vivo

**URL:** https://etric4luf0vq.space.minimax.io  
**Cuenta de Prueba:** arxaonpy@minimax.com

## 📖 Descripción

Cabo Health Nova es una aplicacion medica de vanguardia que utiliza IA conversacional para realizar entrevistas clinicas detalladas. Integra tecnologia de voz nativa con Gemini 3 Flash para crear una experiencia natural de consulta medica, generando automaticamente resumenes clinicos en formato SOAP.

### Sistema de Cola de Resumenes

El sistema garantiza que **ninguna entrevista se pierda** mediante una arquitectura de cola asincrona:

1. **Guardado Prioritario**: Al finalizar la sesion, el transcript se guarda PRIMERO en `pending_summaries`
2. **Procesamiento con Fallback**: Gemini 3 Flash (primario) con fallback a Gemini 2.5 Flash
3. **Recuperacion Automatica**: Si el procesamiento falla, el transcript permanece seguro para reintentos

### ✨ Características Principales

✅ **Conversación Voz a Voz** - Interacción natural con IA usando WebRTC  
✅ **Transcripción en Tiempo Real** - Visualiza la conversación mientras ocurre  
✅ **Resúmenes SOAP Automatizados** - Generación de resúmenes clínicos profesionales  
✅ **Sistema de Persistencia** - Checkpoints automáticos, nunca pierdas tu progreso  
✅ **Backend Completo** - Persistencia de datos con Supabase  
✅ **Envío de Emails** - Envía resúmenes directamente al médico  
✅ **Bilingüe** - Soporte completo para Español e Inglés  
✅ **Seguro** - Autenticación, RLS, sanitización HTML  

## 🚀 Inicio Rápido

### Requisitos Previos

- **Node.js** 18+
- **pnpm** (recomendado) o npm
- **Cuenta de Google AI Studio** (para GEMINI_API_KEY)

### Instalación

```bash
# 1. Clonar el repositorio
git clone https://github.com/guaderrama/cabo-health-clinic.git
cd cabo-health-clinic

# 2. Instalar dependencias
pnpm install

# 3. Copiar variables de entorno
cp .env.example .env

# 4. Configurar GEMINI_API_KEY en .env
echo "VITE_GEMINI_API_KEY=tu_api_key_de_gemini" >> .env
```

### Desarrollo Local

```bash
# Iniciar servidor de desarrollo
pnpm dev

# La aplicación estará disponible en http://localhost:3000
```

### Compilar para Producción

```bash
# Crear build optimizado
pnpm build

# Vista previa del build
pnpm preview
```

## ⚙️ Configuración

### Variables de Entorno Requeridas

```env
# API Key de Gemini (OBLIGATORIO)
VITE_GEMINI_API_KEY=tu_api_key_de_gemini

# Configuración de Supabase (Ya configurado en producción)
VITE_SUPABASE_URL=https://cozsoshuctvhvdbmkmwc.supabase.co
VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

### Variables de Entorno Opcionales

```env
# API Key de Resend para envío real de emails
RESEND_API_KEY=tu_api_key_de_resend
```

### Cómo Obtener las API Keys

#### GEMINI_API_KEY
1. Visita [Google AI Studio](https://makersuite.google.com/app/apikey)
2. Crea un proyecto nuevo
3. Genera una API key
4. Configúrala en tu archivo `.env`

#### RESEND_API_KEY (Opcional)
1. Visita [Resend](https://resend.com)
2. Crea una cuenta gratuita
3. Genera una API key
4. Configúrala en Supabase Dashboard

## 🏗️ Arquitectura

### Stack Tecnológico

| Componente | Tecnología | Versión |
|------------|------------|---------|
| **Frontend** | React + TypeScript | 18.3 + 5.6 |
| **Build Tool** | Vite | 6.2 |
| **Backend** | Supabase | Latest |
| **Base de Datos** | PostgreSQL | 15+ |
| **IA** | Gemini 3 Flash (primario) / Gemini 2.5 Flash (fallback) | Latest |
| **UI** | TailwindCSS + Radix UI | Latest |
| **Audio** | WebRTC + Web Audio API | Native |

### Estructura del Proyecto

```
cabo-health-nova/
├── src/
│   ├── components/       # Componentes React (25+)
│   ├── contexts/        # Context API (Auth)
│   ├── lib/            # Utilidades (Supabase client)
│   ├── utils/          # Helpers (audio, sanitize)
│   ├── services/       # Servicios (audio, summaryQueue)
│   └── App.tsx         # Componente principal
├── supabase/
│   └── functions/      # Edge Functions (4)
├── .ai-context/        # Contexto para agentes
├── memory/            # Contexto entre sesiones
├── docs/              # Documentación técnica
└── public/            # Assets estáticos
```

### Flujo de Datos

1. **Audio Input** → WebRTC → Gemini AI
2. **Transcripción** → Edge Functions → Supabase Database
3. **Resumen SOAP** → Edge Functions → Email/Display
4. **Persistencia** → localStorage + Supabase (dual backup)

## 🗄️ Base de Datos

### Esquema Principal

| Tabla | Descripción | Registros |
|-------|-------------|-----------|
| `patients` | Información de pacientes | User-based |
| `consultations` | Consultas médicas | Generated |
| `transcriptions` | Transcripciones de conversaciones | Real-time |
| `summaries` | Resúmenes clínicos SOAP | Auto-generated |
| `sessions` | Sesiones de consultas | Session-based |
| `session_checkpoints` | Checkpoints de persistencia | Auto-saved |
| `pending_summaries` | Cola de generacion de resumenes | Queue-based |

### Edge Functions

| Función | Propósito | Estado |
|---------|-----------|--------|
| `save-consultation` | Guarda consulta completa | ✅ Activa |
| `generate-summary` | Genera resumen SOAP | ✅ Activa |
| `send-summary-email` | Envía email al médico | ✅ Activa |
| `get-consultations` | Obtiene historial | ✅ Activa |

## 🔒 Seguridad

- ✅ **RLS (Row Level Security)** en todas las tablas
- ✅ **Sanitización HTML** con DOMPurify
- ✅ **Autenticación JWT** con Supabase
- ✅ **Variables de entorno** seguras
- ✅ **CORS configurado** en Edge Functions

## 🧪 Uso de la Aplicación

### 1. Autenticación
- Registrarse con email y contraseña
- Iniciar sesión

### 2. Iniciar Consulta
- Ingresar nombre del paciente
- Seleccionar idioma (Español/Inglés)
- Permitir acceso al micrófono
- Hacer clic en "Iniciar Sesión"

### 3. Conversación con Nova
- Hablar naturalmente con la IA
- Responder preguntas del cuestionario
- Ver transcripción en tiempo real
- **Checkpoints automáticos** cada 2 mensajes

### 4. Finalizar y Enviar
- Hacer clic en "Finalizar Sesión"
- Revisar resumen SOAP generado
- Completar formulario de paciente
- Enviar al médico

## 🎯 Sistema de Persistencia

### Características
- **Guardado automático** cada 2 mensajes
- **Recuperación automática** de sesiones interrumpidas
- **Fallback dual**: localStorage + Supabase
- **Cleanup automático** al completar sesión

### Recuperación
- El sistema detecta automáticamente sesiones incompletas
- Modal de recuperación muestra información detallada
- Opciones: Continuar o Descartar sesión

## 📊 Métricas y Performance

### Build Stats
- **Bundle Size**: 720.34 kB (optimizado)
- **Build Time**: ~4 segundos
- **TypeScript**: 100% tipado
- **Code Coverage**: Manual testing + futuro automatizado

### Performance
- **Load Time**: < 3 segundos
- **Time to Interactive**: < 5 segundos
- **Audio Latency**: ~500ms
- **API Response**: < 2 segundos

## 🛠️ Comandos de Desarrollo

```bash
# Desarrollo
pnpm dev                    # Servidor de desarrollo
pnpm dev:local             # Desarrollo con variables locales

# Build y Deploy
pnpm build                 # Compilar para producción
pnpm build:prod           # Build optimizado
pnpm preview              # Vista previa del build

# Calidad de Código
pnpm lint                  # Verificar código
pnpm lint:fix             # Corregir problemas automáticamente
pnpm type-check           # Verificar tipos TypeScript

# Utilidades
pnpm clean                 # Limpiar dependencias
```

## 🐛 Errores Corregidos

Este proyecto incluye correcciones para:

1. ✅ **Variables de entorno inconsistentes** - Estandarizado con Vite
2. ✅ **Sanitización HTML insegura** - DOMPurify con configuración segura
3. ✅ **Duplicación de transcripciones** - Lógica mejorada sin duplicados
4. ✅ **Gestión de memoria de audio** - Cleanup completo implementado
5. ✅ **Simulación de envío de datos** - Backend real con Supabase

Ver [DOCUMENTACION_COMPLETA.md](https://github.com/guaderrama/cabo-health-ai/blob/HEAD/DOCUMENTACION_COMPLETA.md) para detalles.

## 📝 Documentación Adicional

- **[Arquitectura](https://github.com/guaderrama/cabo-health-ai/blob/HEAD/docs/ARCHITECTURE.md)** - Detalles técnicos del sistema
- **[Seguridad](https://github.com/guaderrama/cabo-health-ai/blob/HEAD/docs/SECURITY.md)** - Configuración de variables y secretos
- **[Operaciones](https://github.com/guaderrama/cabo-health-ai/blob/HEAD/docs/OPERATIONS.md)** - Deploy y mantenimiento
- **[Sistema de Persistencia](https://github.com/guaderrama/cabo-health-ai/blob/HEAD/docs/SISTEMA_PERSISTENCIA.md)** - Checkpoints y recuperación

## 🤝 Contribuciones

Las contribuciones son bienvenidas. Por favor:

1. Fork el proyecto
2. Crear una rama para tu feature
3. Commit tus cambios
4. Push a la rama
5. Abrir un Pull Request

## 📧 Contacto

Para soporte o consultas sobre este proyecto, contactar al autor original.

---

**Desarrollado con ❤️ por MiniMax Agent**

**Tecnologías:** React · TypeScript · Supabase · Gemini AI · TailwindCSS

---

*📚 Documentación completa disponible en la carpeta `docs/`*