QueryCraft

Text-to-SQL-to-Insight — Sistema de consultas ejecutivas con IA

QueryCraft es una plataforma que permite a usuarios no técnicos formular preguntas en lenguaje natural sobre sus datos empresariales. El sistema traduce estas preguntas a consultas SQL optimizadas, las ejecuta contra bases de datos SQL Server, y presenta los resultados como visualizaciones interactivas e insights ejecutivos redactados por IA.

Stack Tecnológico

Capa	Tecnología	Versión
Frontend	Angular, Angular Material, Chart.js	22
Backend	.NET (ASP.NET Core Web API)	10
LLM	Ollama (modelos open-source: llama3.1:8b)	latest
Embeddings	nomic-embed-text (vía Ollama)	—
Vector DB	Qdrant (RAG de metadatos)	latest
Base de datos local	SQLite (Entity Framework Core)	—
Bases de datos fuente	SQL Server (vía ADO.NET)	—
Autenticación	JWT (Bearer) + BCrypt	—
Contenedores	Docker, Docker Compose	—

Arquitectura

┌─────────────┐     ┌──────────────┐     ┌─────────────┐     ┌──────────────┐
│   Angular   │────▶│  .NET 10    │────▶│   Ollama    │────▶│   Qdrant     │
│   Frontend  │     │   Web API   │     │   (LLM)     │     │  (Vectors)   │
└─────────────┘     └──────────────┘     └─────────────┘     └──────────────┘
                           │
                           ▼
                    ┌──────────────┐
                    │  SQL Server  │
                    │  (Databases) │
                    └──────────────┘

Flujo Principal

Pregunta → RAG (Qdrant) → LLM (Ollama) → SQL → Validar → Ejecutar (BD) → Gráfico → Insight → Respuesta

El sistema orquesta un pipeline de 8 pasos:

1. RAG — Busca metadatos relevantes de la BD en Qdrant (embeddings semánticos)
2. Generar SQL — Envía contexto + pregunta al LLM para obtener SQL
3. Validar — Verifica que el SQL sea solo SELECT (sin DROP, DELETE, etc.)
4. Reintentar — Si el SQL es inválido, reintenta hasta 2 veces con feedback
5. Ejecutar — Corre el SQL contra la BD fuente (read-only, timeout 30s)
6. Graficar — Determina automáticamente el tipo de gráfico según los datos
7. Insight — Genera conclusión ejecutiva de 2 párrafos vía LLM
8. Responder — Retorna SQL + datos + gráfico + insight al frontend

Estructura del Repositorio

querycraft/
├── docs/
│   ├── sdd/                        # Software Design Document
│   ├── prompts/                    # Prompts del sistema (4 prompts)
│   ├── qa/                         # Planes de pruebas
│   ├── seguridad/                  # Análisis de riesgos
│   └── manuales/                   # Guías de usuario y operación
├── backend/
│   ├── QueryCraft.Api/             # Web API (6 Controllers REST)
│   ├── QueryCraft.Core/            # Lógica de dominio (Models, Interfaces)
│   ├── QueryCraft.Infrastructure/  # Acceso a datos y servicios externos
│   └── QueryCraft.Tests/           # Pruebas unitarias y de integración
├── frontend/
│   └── querycraft-ui/              # Aplicación Angular 22
├── infra/
│   ├── docker-compose.yml          # Orquestación: Qdrant + Ollama + API
│   └── Dockerfile                  # Build de la API .NET
├── scripts/                        # Scripts de utilidad
├── .env.example                    # Variables de entorno de ejemplo
└── README.md                       # Este archivo

API REST

Endpoints Públicos

Método	Ruta	Auth	Descripción
GET	/health	—	Health check de la API
POST	/api/auth/register	—	Registrar nuevo usuario
POST	/api/auth/login	—	Iniciar sesión (retorna JWT)

Endpoints Protegidos (JWT)

Método	Ruta	Descripción
GET	/api/auth/me	Perfil del usuario autenticado
GET	/api/connections	Listar conexiones de BD
POST	/api/connections	Crear nueva conexión
POST	/api/connections/test	Probar conexión sin guardar
GET	/api/chat/history	Historial de chat
POST	/api/chat/query	Enviar pregunta en lenguaje natural
GET	/api/queries	Listar consultas guardadas
POST	/api/queries/save	Guardar consulta como favorito
DELETE	/api/queries/{id}	Eliminar consulta guardada

Endpoint Webhook (API Key)

| Método | Ruta | Auth | Descripción | ||--------|------|------|-------------| || POST | /api/webhook/query | X-API-Key | Consulta desde sistemas externos (n8n, Telegram) |

📊 Dashboard Analítico (v5.0 — Opción C)

El Dashboard Analítico permite a los usuarios crear dashboards configurables tipo Power BI, armando widgets desde las respuestas del chat y organizándolos en un canvas tipo grid con drag & resize.

🆕 Novedades vs. Dashboard v3 (admin)

Aspecto	Dashboard v3 (admin)	Dashboard v5 (Opción C)
Propósito	Métricas de uso del sistema	Dashboards configurables por el usuario
Audiencia	Solo admin	Todos los usuarios
Contenido	Métricas predefinidas	Widgets personalizados desde el chat
Layout	Fijo	Configurable (drag & resize)
Widgets	KPIs y gráficos fijos	5 tipos: chart, kpi, table, text, trend
URLs públicas	❌ No	✅ Sí
Múltiples dashboards	❌ Uno solo	✅ Hasta 20 por usuario
Templates	❌ No	✅ Sí (4 predefinidos)
Ruta	/dashboard (admin)	/dashboards + /dashboard/:id

Nota: El dashboard v3 de administración se mantiene intacto. El Dashboard Analítico v5 es un módulo completamente nuevo.

🧩 Tipos de Widget

Tipo	Icono	Descripción
chart	📊	Gráficos Chart.js (bar, line, pie, doughnut)
kpi	🎯	Tarjeta con número grande, color e icono
table	📋	Datos en formato tabular con scroll
text	📝	Texto libre con markdown (sanitizado)
trend	📈	Indicador con flecha y porcentaje de cambio

🛣️ Rutas del Frontend

Ruta	Componente	Auth	Descripción
/dashboards	DashboardsListComponent	JWT	Lista de dashboards del usuario
/dashboard/:id	DashboardCanvasComponent	JWT	Canvas con grid de widgets
/d/public/:token	PublicDashboardComponent	Ninguna	Dashboard público solo lectura

🔌 API Endpoints del Módulo

Método	Ruta	Auth	Descripción
GET	/api/dashboards	JWT	Listar dashboards del usuario
POST	/api/dashboards	JWT	Crear nuevo dashboard
GET	/api/dashboards/{id}	JWT	Obtener dashboard con widgets
PUT	/api/dashboards/{id}	JWT	Actualizar nombre/descripción
DELETE	/api/dashboards/{id}	JWT	Eliminar dashboard (cascade)
POST	/api/dashboards/{id}/publish	JWT	Publicar (generar token UUID)
POST	/api/dashboards/{id}/unpublish	JWT	Despublicar (revocar token)
GET	/api/dashboards/{id}/widgets	JWT	Listar widgets del dashboard
POST	/api/dashboards/{id}/widgets	JWT	Agregar widget al dashboard
PUT	/api/dashboards/{id}/widgets/positions	JWT	Batch update posiciones
PUT	/api/dashboards/{id}/widgets/{wid}/config	JWT	Actualizar configuración widget
DELETE	/api/dashboards/{id}/widgets/{wid}	JWT	Eliminar widget del dashboard
GET	/api/d/public/{token}	Ninguna	Obtener dashboard público
GET	/api/templates	JWT	Listar templates disponibles

📦 Nuevas Dependencias (Frontend)

Paquete	Versión	Propósito
@katoid/angular-grid-layout	^3.x	Grid con drag & resize
dompurify	^3.x	Sanitización HTML (XSS prevention)
marked	^12.x	Renderizado de markdown

⚙️ Nuevas Variables de Entorno

Variable	Default	Descripción
DASHBOARD_MAX_PER_USER	20	Máximo de dashboards por usuario
DASHBOARD_MAX_WIDGETS_PER_DASHBOARD	50	Máximo de widgets por dashboard
DASHBOARD_PUBLIC_BASE_URL	https://querycraft	Base URL para URLs públicas

📚 Documentación del Módulo

Documento	Ubicación
SDD Dashboard Analítico	docs/sdd/sdd-dashboard-analitico.md
Manual Técnico	docs/manuales/manual-tecnico-dashboard-analitico.md
Manual de Usuario	docs/manuales/manual-usuario-dashboard-analitico.md
Code Review	docs/reviews/code-review-dashboard-analitico.md
Seguridad	docs/reviews/seguridad-dashboard-analitico.md
QA	docs/qa/qa-dashboard-analitico.md

Requisitos

• .NET SDK 10.0+
• Node.js 20+ y Angular CLI
• Docker y Docker Compose
• Ollama (para inferencia local de LLM)
• Qdrant (para almacenamiento vectorial de metadatos)
• SQL Server (base de datos fuente)

Inicio Rápido

1. Clonar y configurar

git clone http://192.168.3.216:3000/JMarin1980/querycraft.git
cd querycraft
cp .env.example .env

2. Variables de entorno

Edita .env con los valores correctos:

# Obligatorio: JWT Secret (mín. 32 caracteres, NO el valor por defecto)
JWT_SECRET=tu_clave_secreta_muy_segura_de_32_chars

# URLs de servicios
OLLAMA_URL=http://192.168.3.149:11434
QDRANT_URL=http://192.168.3.216:7100

# Opcional: modelo LLM, webhook, ruta SQLite
OLLAMA_MODEL=llama3.1:8b
WEBHOOK_API_KEY=genera_una_api_key_de_32_caracteres

⚠️ Importante: Cambia JWT_SECRET y WEBHOOK_API_KEY de sus valores por defecto antes de usar en producción. La API fallará al inicio si el JWT Secret tiene el valor CHANGE_ME.

3. Iniciar servicios con Docker

docker compose -f infra/docker-compose.yml up -d

Esto inicia:

• Qdrant en puerto 6333 (base de datos vectorial)
• Ollama en puerto 11434 (inferencia LLM, con soporte GPU NVIDIA)
• QueryCraft API en puerto 5000

Nota: Si es la primera vez que usas Ollama, descarga el modelo:

docker exec querycraft-ollama ollama pull llama3.1:8b
docker exec querycraft-ollama ollama pull nomic-embed-text

4. Compilar y ejecutar backend (desarrollo)

cd backend
dotnet restore
dotnet build
dotnet run --project QueryCraft.Api
# API disponible en http://localhost:5233

5. Iniciar frontend (desarrollo)

cd frontend/querycraft-ui
npm install
ng serve
# Frontend disponible en http://localhost:4200

6. Verificar instalación

curl http://localhost:5000/health
# {"status":"healthy","timestamp":"...","version":"1.0.0"}

Usuarios por Defecto

Usuario	Rol	Descripción
admin	admin	Administrador del sistema (gestiona conexiones BD)
user	user	Usuario ejecutivo (solo chat y dashboard)

Regístrate con POST /api/auth/register o usa el formulario de registro en el frontend.

Roles

Rol	Permisos
admin	Chat ejecutivo, Dashboard, Gestión de conexiones BD, Webhooks
user	Chat ejecutivo, Dashboard, Gestión de favoritos

Documentación

Documento	Ubicación	Descripción
SDD	docs/sdd/sdd-querycraft.md	Software Design Document completo
Manual Técnico	docs/manuales/manual-tecnico.md	Arquitectura, API, configuración, despliegue
Manual de Usuario	docs/manuales/manual-usuario.md	Cómo usar el sistema paso a paso
Prompts del Sistema	docs/prompts/	Prompts para generación SQL, validación, gráficos e insights
Plan de Pruebas	docs/qa/	Planes y reportes de pruebas
Análisis de Seguridad	docs/seguridad/	Análisis de riesgos y políticas de seguridad

Licencia

Propietaria — Todos los derechos reservados.