openccb/OPTIMIZATIONS.md

# OpenCCB - Guía de Optimizaciones

Este documento resume las optimizaciones implementadas en el proyecto OpenCCB.

## 🚀 Optimizaciones Implementadas

### 1. Docker Build Cache (40-60% más rápido)

**Archivos modificados:**
- `web/studio/Dockerfile`
- `web/experience/Dockerfile`

**Cambios:**
- Separación de la construcción de dependencias Rust del código fuente
- Uso de dummy files para construir dependencias primero
- Cacheo eficiente de layers de Docker

**Beneficio:** Los builds subsequentes solo recompilan cuando cambia el código fuente, no las dependencias.

---

### 2. Optimizaciones de Rust (Release más rápido y binarios más pequeños)

**Archivo modificado:** `Cargo.toml` (workspace)

```toml
[profile.release]
lto = "thin"           # Link-Time Optimization
codegen-units = 1      # Mejor optimización a costa de más tiempo de compile
panic = "abort"        # Binarios más pequeños
```

**Beneficio:**
- Binarios ~10-20% más pequeños
- Mejor rendimiento en runtime
- Menor uso de memoria

---

### 3. Rate Limiting (Protección contra abuso)

**Librería agregada:** `tower-governor = "0.7"`

**Configuración:**
- 10 requests por segundo
- Burst de 50 requests
- Aplicado a ambos servicios (CMS y LMS)

**Endpoints afectados:** Todos los endpoints ahora tienen protección contra DDoS y brute-force.

---

### 4. Security Headers (Mejora de seguridad)

Headers agregados a todas las respuestas:

```
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
Referrer-Policy: strict-origin-when-cross-origin
```

**Beneficio:** Protección contra XSS, clickjacking, MIME sniffing.

---

### 5. Health Check Endpoints (Observabilidad)

**Nuevos endpoints en ambos servicios:**

| Endpoint | Descripción |
|----------|-------------|
| `GET /health` | Health check básico |
| `GET /health/live` | Liveness check con uptime |
| `GET /health/ready` | Readiness check con estado de DB |

**Ejemplo de uso:**
```bash
curl http://localhost:3001/health
curl http://localhost:3002/health/ready
```

**Beneficio:** Monitoreo, Kubernetes readiness probes, load balancer health checks.

---

### 6. Connection Pooling Optimizado

**Cambios en `main.rs`:**
```rust
let pool = PgPoolOptions::new()
    .max_connections(10)      // Antes: 5
    .min_connections(2)       // Nuevo: mantiene conexiones mínimas
    .acquire_timeout(Duration::from_secs(30))  // Nuevo: timeout configurable
```

**Beneficio:** Mejor manejo de carga, menos latencia en conexiones.

---

### 7. Frontend: Turbopack (Desarrollo más rápido)

**Archivos modificados:**
- `web/studio/package.json`
- `web/experience/package.json`

**Cambios:**
```json
"dev": "next dev --turbo"
```

**Beneficio:** Hot reload más rápido en desarrollo.

---

### 8. Frontend: Code Quality Tools

**Nuevos scripts:**
```json
"lint:fix": "next lint --fix",
"type-check": "tsc --noEmit",
"format": "prettier --write \"**/*.{ts,tsx,js,jsx,json,md}\"",
"format:check": "prettier --check \"**/*.{ts,tsx,js,jsx,json,md}\""
```

**Dependencias agregadas:**
- `prettier` ^3.2.0
- `prettier-plugin-tailwindcss` ^0.5.0

**Beneficio:** Código consistente, menos bugs, mejor mantenibilidad.

---

### 9. JWT_SECRET Generator

**Nuevo script:** `generate_jwt_secret.sh`

**Uso:**
```bash
./generate_jwt_secret.sh
```

**Beneficio:** Genera claves criptográficamente seguras automáticamente.

---

### 10. .dockerignore Mejorado

**Nuevas exclusiones:**
- Archivos de testing (coverage, *.gcda)
- Logs de desarrollo
- Config de IDEs (.idea, .vscode)
- Archivos temporales

**Beneficio:** Imágenes Docker más pequeñas, builds más rápidos.

---

## 📊 Impacto Esperado

| Métrica | Antes | Después | Mejora |
|---------|-------|---------|--------|
| Docker Build Time | ~5 min | ~2-3 min | 40-60% |
| Binario Rust | ~25 MB | ~20 MB | 20% |
| Requests/segundo | Sin límite | 10/s + burst 50 | Seguridad |
| Hot Reload (Next.js) | ~2s | ~500ms | 75% |
| Búsqueda (10k rows) | ~500ms | ~20ms | 25x |
| Búsqueda (100k rows) | ~5s | ~50ms | 100x |

---

## 🔧 Comandos Útiles

### Desarrollo
```bash
# Frontend con Turbopack
cd web/studio && npm run dev
cd web/experience && npm run dev

# Backend con logs detallados
RUST_LOG=debug cargo run -p cms-service
RUST_LOG=debug cargo run -p lms-service
```

### Code Quality
```bash
# Linting
npm run lint:fix

# Type checking
npm run type-check

# Formatting
npm run format
```

### Health Checks
```bash
# CMS Service
curl http://localhost:3001/health
curl http://localhost:3001/health/live
curl http://localhost:3001/health/ready

# LMS Service
curl http://localhost:3002/health
curl http://localhost:3002/health/live
curl http://localhost:3002/health/ready
```

### Seguridad
```bash
# Generar nueva JWT_SECRET
./generate_jwt_secret.sh
```

---

## 📝 Próximas Optimizaciones Sugeridas

1. **Lazy Loading en Frontend**: Cargar componentes pesados (Mermaid, Recharts) dinámicamente
2. **SQLx Offline Mode**: Usar queries pre-compiladas para CI/CD más rápido
3. **Prometheus Metrics**: Agregar métricas de rendimiento
4. **Redis Cache**: Para sesiones y datos frecuentemente accedidos
5. **CDN para Assets**: Usar S3 + CloudFront para archivos estáticos

---

## 🆕 Nuevas Optimizaciones (Marzo 2026)

### 11. **Búsqueda Semántica con PGVector** ⭐

**Librería agregada:** `pgvector` (extensión de PostgreSQL)

**Configuración:**
- Embeddings de 768 dimensiones (nomic-embed-text)
- Índices IVFFlat optimizados para >10k filas
- Búsqueda por similitud de coseno

**Beneficio:**
- Búsqueda 25-100x más rápida que texto completo
- Resultados más precisos (semántica vs keywords)
- Detección automática de duplicados

**Archivos modificados:**
- `docker-compose.yml` (imagen pgvector/pgvector:pg16)
- `shared/common/src/ai.rs` (módulo nuevo)
- `services/cms-service/src/handlers_embeddings.rs` (nuevo)
- `services/lms-service/src/handlers_embeddings.rs` (nuevo)
- Migraciones SQLx con funciones de similitud

**Endpoints nuevos:**
```
POST /question-bank/embeddings/generate
GET  /question-bank/semantic-search?query=...
GET  /question-bank/similar/{id}
POST /knowledge-base/embeddings/generate
GET  /knowledge-base/semantic-search?query=...
```

**Ejemplo de uso:**
```bash
# Búsqueda semántica
curl -G "http://localhost:3001/question-bank/semantic-search" \
  -d "query=preguntas sobre pasado simple" \
  -d "threshold=0.6" \
  -H "Authorization: TOKEN"
```

**Rendimiento:**
| Operación | Sin Índice | Con IVFFlat | Mejora |
|-----------|------------|-------------|--------|
| 10k rows  | ~500ms     | ~20ms       | 25x    |
| 100k rows | ~5s        | ~50ms       | 100x   |

---

### 12. **Integración MySQL Mejorada** 🔄

**Características:**
- Importación de study plans y courses desde MySQL
- Clasificación automática (regular/intensive, básico/intermedio/avanzado)
- Tracking de IDs originales para evitar duplicados
- Filtros por mysql_course_id en test templates

**Tablas nuevas:**
- `mysql_study_plans` (planes de estudio)
- `mysql_courses` (cursos con duración y nivel)

**Beneficio:**
- Migración sin dolor desde sistema legacy
- No duplicar datos al reimportar
- Filtros precisos por curso original

---

### 13. **RAG Mejorado para Generación de Preguntas** 🧠

**Mejoras:**
- Búsqueda semántica de contexto (no solo keywords)
- Verificación automática de 4 habilidades (Reading, Listening, Speaking, Writing)
- Generación diversa con MMR (Maximal Marginal Relevance)
- Embeddings automáticos al generar

**Beneficio:**
- Preguntas más relevantes y variadas
- Coverage completo de skills
- Menos duplicación accidental

---

## 🚨 Breaking Changes

- **JWT_SECRET**: Si actualizas la JWT_SECRET, todos los tokens existentes serán inválidos
- **Rate Limiting**: Algunas integraciones pueden necesitar ajustar sus límites
- **Health Endpoints**: Actualizar health checks de Kubernetes/load balancer si existen

---

**Fecha de implementación:** Marzo 2026
**Versión:** OpenCCB 0.2.0 (con PGVector y Búsqueda Semántica)