VIGILIO — Plataforma de Portfolio Inteligente (Astro 5 + NestJS 11)

Construí VIGILIO como mi plataforma de portfolio profesional de última generación, diseñada para redefinir cómo presento mi trabajo al mundo. Combina una experiencia de usuario inmersiva con inteligencia artificial integrada, un reproductor de música reactivo estilo Monstercat, chat en tiempo real con doble modo (IA + Humano), y un CMS completo multilenguaje. La arquitectura que diseñé prioriza la escalabilidad, la seguridad enterprise y una UX de nivel cinematográfico.

El sistema gestiona 26 módulos de negocio independientes, procesa documentos PDF para alimentar un pipeline RAG con embeddings vectoriales, transmite respuestas de IA token a token vía SSE, y orquesta chat en vivo mediante WebSockets — todo desplegado sobre una infraestructura containerizada con CI/CD automatizado y seguridad nivel enterprise.

🏗️ Arquitectura Monorepo SSR (Astro + NestJS)

Para gestionar la complejidad de un portfolio con IA, multimedia y tiempo real, diseñé el proyecto como un monorepo SSR que fusiona frontend y backend en un solo servidor:

• Hybrid SSR + SPA: Uso Astro 5 para generar páginas SSR con hidratación parcial en el sitio público (SEO óptimo, carga ultra-rápida), mientras que el dashboard de administración opera como una SPA completa con Wouter routing dentro de un island de Preact — logro lo mejor de ambos mundos sin la penalización de un framework SPA completo.
• NestJS como Motor Backend: Mi servidor NestJS actúa como el cerebro del sistema. Cada módulo de negocio (AI, Auth, Music, Projects, Chat...) está encapsulado con su propio Controller → Service → Repository → Entity, inyectado por el contenedor de dependencias de NestJS. Guards globales (HybridAuthGuard, RolesGuard) protegen automáticamente cada endpoint.
• Astro Proxy en Desarrollo: En modo desarrollo, Vite proxea las peticiones /api al servidor NestJS, permitiendo hot-reload instantáneo del frontend mientras el backend corre en paralelo. En producción, ambos se fusionan en un solo proceso Node.js con Express.
• Pipes, Filters e Interceptors: Implementé validación centralizada con Zod (ZodPipe), manejo global de excepciones (HttpExceptionFilter, DrizzleExceptionFilter), y transformación de respuestas consistente — garantizando que cada endpoint se comporte de manera predecible.
• Multi-Tenant por Diseño: Cada request pasa por mi InitialCacheMiddleware que resuelve el tenant activo y lo inyecta en req.locals, permitiendo aislamiento completo de datos entre tenants sin duplicar infraestructura.

🎵 NeuroPlayer — Motor de Audio Inmersivo

Mi reproductor de música no es un simple <audio> tag. Es un motor de experiencia sonora que diseñé inspirado en los visualizadores de Monstercat, para transformar la sidebar del portfolio en una experiencia sensorial:

• Visualizador Monstercat (Canvas/CSS): Construí un sistema de barras reactivas que responde en tiempo real a las frecuencias de bass y mid del audio mediante análisis de Web Audio API. Mi componente MonstercatVisualizer renderiza barras animadas que pulsan con cada beat, mientras ReactiveGlow genera un halo dinámico alrededor del player cuya intensidad de box-shadow fluctúa con los graves.
• Tres Modos Especiales: Más allá del player estándar, implementé modos inmersivos activables por botones flotantes: Protostar Mode (reemplaza el player por un video loop ambiente con overlay HUD), Nature Mode y Planet Mode — cada uno transforma completamente la estética visual del portfolio.
• Estado Global Reactivo (Preact Signals): Mi audioStore centraliza todo el estado del player (track actual, playlist, volumen, favoritos, bass/mid intensity, modo repeat) usando Preact Signals — actualizaciones a 60fps sin re-renders innecesarios. Cualquier componente del portfolio puede reaccionar al audio en tiempo real.
• Backend CRUD Completo: El módulo NestJS de música expone un REST API protegido por roles (@Roles(1) = admin only) con upload de archivos de audio y covers a MinIO/S3, validación Zod del schema, cache con Dragonfly, y paginación server-side. Los tracks se almacenan con metadata completa: título, artista, duración, sort_order, is_featured, is_public.
• Procesamiento de Audio (FFmpeg + Sharp): Los archivos subidos pasan por Fluent FFmpeg para extracción de metadatos y procesamiento, mientras Sharp optimiza las imágenes de portada con dimensiones configurables.

🤖 AI Nexus — Chat con Inteligencia Artificial (RAG Pipeline)

Mi chat de IA no es un simple wrapper de ChatGPT. Diseñé un sistema RAG completo (Retrieval Augmented Generation) que responde preguntas sobre mí usando mis propios documentos como fuente de verdad:

• Pipeline de Ingesta de Documentos: Desde el dashboard subo documentos PDF. Mi módulo Documents utiliza pdf-parse para extraer texto, lo divide en chunks procesables, y genera embeddings vectoriales de 1536 dimensiones usando el modelo text-embedding-3-small de OpenAI. Estos vectores se almacenan en PostgreSQL con la extensión pgvector.
• Búsqueda Semántica por Similaridad Coseno: Cuando un visitante hace una pregunta, el sistema convierte la pregunta en un embedding, busca los chunks más similares en la base vectorial, y construye un prompt contextualizado con la información relevante antes de enviarlo al modelo de IA.
• Streaming Token-a-Token (SSE): Las respuestas de IA no aparecen de golpe. Mi AiService utiliza la API de OpenRouter con streaming habilitado, y un Subject de RxJS convierte el stream en Server-Sent Events que el frontend consume en tiempo real — mostrando cada palabra a medida que el modelo la genera, exactamente como ChatGPT.
• Dual Mode (AI / LIVE): Implementé dos modos seamlessly intercambiables. En modo AI, las respuestas vienen del pipeline RAG. En modo LIVE, un WebSocket Gateway (ChatGateway) conecta al visitante directamente conmigo para conversación humana en tiempo real — con indicadores de escritura, persistencia en DB, y notificación automática.
• Lead Capture Inteligente: Antes de iniciar conversación, el sistema captura nombre y empresa del visitante. Esta información se inyecta como contexto invisible en el primer mensaje, permitiendo que la IA personalice sus respuestas y venda mis servicios de manera contextualizada a cada empresa.
• Configuración Dinámica del Modelo: Desde mi dashboard puedo cambiar el modelo de IA (GPT-4, Claude, Llama, etc. via OpenRouter), ajustar la temperatura, y modificar el system prompt — todo en caliente sin necesidad de re-deploy, con cache auto-invalidation en Dragonfly.

💬 Chat en Tiempo Real — WebSocket Architecture

Mi módulo de chat implementa comunicación bidireccional en tiempo real entre visitantes y yo como administrador:

• WebSocket Gateway (/chat namespace): Mi ChatGateway de NestJS maneja conexiones, rooms por conversación (conversation_{id}), y eventos tipados: join_conversation, leave_conversation, send_message, admin_typing. Cada mensaje se persiste automáticamente en PostgreSQL antes de ser broadcast.
• Cambio de Modo Automático: Cuando me uno a una conversación, el modo cambia automáticamente de AI a LIVE. El servidor emite mode_changed a todos los clientes en la room, y el frontend transiciona suavemente mostrando "A human architect has joined the conversation" con estética terminal.
• Estética Terminal Cyberpunk: El chat no usa burbujas genéricas. Cada mensaje se renderiza con estilo de terminal: timestamps en formato SYSTEM.AI / USER.ARCHITECT / SENIOR.HUMAN, bordes laterales coloreados por rol, y animaciones de "CALCULATING_RESPONSE..." con ping indicators mientras la IA procesa.

🖥️ Landing Page — Experiencia Inmersiva

Mi landing page no es una página estática convencional. La diseñé como un dashboard de sistema operativo ficticio para impresionar desde el primer segundo:

• Hero Terminal Draggable: El componente principal es una terminal interactiva que el usuario puede arrastrar por la pantalla. Muestra mi información con efecto de typing animado (TypedMessage), enlaces sociales con iconos Lucide, y un glow reactivo que responde al mouse y al audio del NeuroPlayer.
• System Stats en Tiempo Real: Construí un panel de telemetría que muestra CPU, RAM, uptime y latencia del visitante — detectando automáticamente el SO del cliente (Windows/Mac/Linux/iOS/Android) y mostrando datos "en vivo" con barras reactivas sincronizadas al audio del reproductor.
• Tech Orbit & Stack Radial: Visualizaciones interactivas de mis tecnologías: un sistema orbital animado (tech-orbit.tsx) y un diagrama radial (tech-stack-radial.tsx) que muestran mi stack tecnológico con animaciones de hover y transiciones suaves.
• Skill Bento Grid: Un grid estilo bento que organiza mis habilidades técnicas en cards de diferentes tamaños con glassmorphism, gradientes dinámicos, y micro-interacciones.
• Wave Timeline: Una línea temporal de mi experiencia laboral con estética de forma de onda (wave-timeline.tsx) que combina datos cronológicos con visualización gráfica.
• Animated Counter: Contadores animados que incrementan en scroll-view para mis estadísticas clave (años de experiencia, proyectos completados, etc.).
• Live Visitors: Widget que muestra visitantes activos en tiempo real en mi portfolio.

💼 Portfolio de Proyectos — Gestión Multilenguaje con GitHub Stats

Mi módulo de proyectos va más allá de un simple grid de cards:

• Schema Empresarial Completo: Cada proyecto almacena título, slug, descripción corta, contenido en Markdown, resumen de impacto (impact_summary), URLs de website y repositorio, estadísticas de GitHub (stars, forks, language stats), imágenes y videos múltiples, estado del proyecto, metadatos SEO completos, y relaciones polimórficas con tecnologías vía mi módulo Techeable.
• Sistema de Traducción por Herencia: Mis proyectos soportan 3 idiomas (es, en, pt) mediante un sistema parent_id donde el registro en español es el original y las traducciones en inglés/portugués se vinculan como hijos — permitiendo que cada idioma tenga su propio contenido markdown independiente sin duplicar metadata.
• Renderizado Markdown con Syntax Highlighting: El contenido de cada proyecto se renderiza con Marked para parsing de Markdown y Shiki para syntax highlighting de código — mostrando snippets con colores de IDE profesional directamente en las páginas del portfolio.
• SSR con SEO Optimizado: Cada página de proyecto se genera server-side con Astro, incluyendo Open Graph metadata, title tags dinámicos, y structured data — asegurando que cada proyecto sea indexable y compartible en redes sociales.

🔐 Autenticación & Seguridad — Defense in Depth

Implementé múltiples capas de seguridad para proteger tanto la API como el dashboard:

• Triple Strategy de Passport: Tres estrategias de autenticación coexisten: JWT (Bearer tokens para la API con access + refresh), Local (email/password con bcrypt hashing), y Google OAuth 2.0 (login social). Mi HybridAuthGuard detecta automáticamente qué método usar según el request.
• Autenticación de Dos Factores (2FA): Soporte completo para TOTP (Time-based One-Time Password) utilizando otplib para generar secrets, qrcode para producir QR codes escaneables desde cualquier app authenticator, y validación server-side en cada login protegido.
• Rate Limiting Granular: Mi ThrottlerModule limita a 100 requests por minuto por IP, previniendo ataques de fuerza bruta y abuso de la API.
• Headers HTTP Seguros: Helmet configura automáticamente headers de seguridad (HSTS, CSP, X-Frame-Options, etc.), mientras CORS se configura dinámicamente desde variables de entorno.

📊 Dashboard de Administración — SPA Embebida

Mi panel de administración es una aplicación completa embebida dentro de Astro:

• SPA con Wouter Routing: Un catch-all route de Astro (/dashboard/[...all].astro) renderiza un island de Preact que contiene un router SPA completo con Wouter — logrando navegación instantánea sin recargas mientras mantengo la autenticación server-side.
• CRUD Completo de 26 Módulos: Cada módulo de negocio (Projects, Blog, Music, Chat, Users, Technologies...) tiene componentes de tabla, creación y edición con formularios validados por React Hook Form + Zod, tablas interactivas con @vigilio/preact-table, paginación server-side con @vigilio/preact-paginator, y modales/alerts con @vigilio/sweet.
• Editores de Contenido Rico: MDX Editor y TinyMCE para la redacción de posts de blog y descripciones de proyecto — con toolbar completa, embebido de imágenes, y preview en tiempo real.
• Analytics con Recharts: Gráficos interactivos de analíticas (visitas, engagement, uso de IA) visualizados con Recharts directamente en el dashboard.

🗄️ Infraestructura de Datos & Servicios

Diseñé la capa de datos para rendimiento y type-safety end-to-end:

• PostgreSQL + pgvector: Base de datos relacional principal con la extensión pgvector para almacenar y buscar embeddings vectoriales de 1536 dimensiones — habilitando búsqueda semántica para el pipeline RAG sin necesidad de un servicio vectorial externo.
• Drizzle ORM: Elegí Drizzle por ser type-safe, generando queries SQL optimizadas con TypeScript completo — desde la definición del schema hasta el resultado del query, incluyendo joins y relaciones polimórficas, sin la overhead de un ORM tradicional.
• Dragonfly (Redis Compatible): Cache en memoria de alto rendimiento para listas paginadas, configuraciones de IA, y datos frecuentemente accedidos. Cada módulo tiene su propia clase Cache con invalidación automática en operaciones de escritura.
• MinIO/RustFS (S3 Compatible): Almacenamiento de objetos para archivos de audio, imágenes de proyecto, covers de música, y documentos PDF — con CDN configurable y URLs presignadas para uploads seguros desde el cliente.
• Nodemailer: Servicio de email para el formulario de contacto y notificaciones del sistema.
• Web Push (VAPID): Notificaciones push nativas del navegador para alertarme sobre nuevos contactos, conversaciones de chat, y eventos del sistema.

📡 Observabilidad & Monitoreo

Implementé trazabilidad completa para diagnóstico y rendimiento:

• OpenTelemetry SDK: Tracing distribuido con auto-instrumentación de HTTP, database queries, y llamadas externas (OpenRouter, S3). Las trazas se exportan via OTLP HTTP para visualización en Jaeger, Grafana Tempo, o cualquier backend compatible.
• Pino Structured Logging: Logging JSON estructurado en producción con nestjs-pino — cada log incluye request ID, tenant ID, timestamp, y contexto del módulo. En desarrollo, pino-pretty formatea los logs para lectura humana.
• Health Checks (@nestjs/terminus): Endpoints de salud que verifican conectividad con PostgreSQL, Dragonfly, y disponibilidad de disco — integrados con el pipeline de deploy para smoke tests post-deploy.

🐳 Containerización & Deploy

Empaqueto la aplicación como una imagen Docker optimizada para producción:

• Multi-Stage Build: 4 etapas (base → dependencies → build → production) que producen una imagen mínima basada en Node 24 Alpine. Las dependencias se cachean con pnpm store, el build genera tanto el cliente Astro como el servidor NestJS, y la imagen final solo incluye node_modules de producción + artifacts compilados.
• Usuario No-Root: Mi imagen de producción corre con un usuario dedicado (cearjs:nodejs) sin privilegios de root, con permisos mínimos solo sobre el directorio de logs.
• Docker Compose: Orquestación local con PostgreSQL, Dragonfly, y MinIO — un solo docker compose up -d levanta todo el stack de desarrollo.

🧪 Testing — Cobertura Multi-Capa

Implementé testing en múltiples niveles para garantizar fiabilidad:

• Unit Tests (Vitest + happy-dom): Tests de componentes Preact con Testing Library, tests de servicios NestJS con mocking vía vitest-mock-extended, y validación de schemas Zod — ejecutándose en happy-dom para máxima velocidad.
• E2E con Database Real (Vitest + Supertest): Tests de integración que levantan el módulo completo de NestJS contra una base de datos PostgreSQL real (test_db), ejecutando queries SQL reales y verificando el comportamiento end-to-end de cada endpoint. La DB se limpia automáticamente con TRUNCATE entre tests.
• Browser E2E (Playwright): Tests de navegador multi-browser con Page Object Model (POM) que verifican flujos completos del usuario: navegación, formularios, autenticación, y rendering del portfolio.
• Coverage con V8: Reportes de cobertura de código generados por @vitest/coverage-v8, integrados en el pipeline de CI.

🚀 Stack Tecnológico de Alto Rendimiento

• Backend: NestJS 11 (Node.js 24), Express 5, Drizzle ORM, Passport (JWT/OAuth/Local), Zod 4, Socket.IO.
• Frontend: Astro 5 (SSR), Preact 10 (Signals), TailwindCSS 4, Motion, Recharts, Wouter.
• IA: OpenRouter SDK, OpenAI SDK, LangChain, pgvector, pdf-parse.
• Datos: PostgreSQL 16 + pgvector, Dragonfly (Redis), MinIO/RustFS (S3).
• Observabilidad: OpenTelemetry, Pino, @nestjs/terminus.
• Testing: Vitest, Playwright, Testing Library, Supertest.
• DevOps: Docker (multi-stage), Gitea Actions (CI/CD), Renovate, Biome, Husky.
• Seguridad: Helmet, bcrypt, otplib (2FA), Throttler, SHA-pinned Actions, Trivy, SBOM.

💎 Módulos del Ecosistema a Detalle

1. NeuroPlayer & Audio Engine

• Visualizador Monstercat Reactivo: Barras de frecuencia sincronizadas al audio con análisis de bass/mid en tiempo real.
• ReactiveGlow: Halo dinámico que pulsa con los graves del track actual, aplicado como box-shadow con intensidad variable.
• Tres Modos Inmersivos: Protostar (video loop), Nature (ambiente natural), Planet (exploración espacial).
• Playlist Modal: Archivo de tracks con album art, indicadores de track activo (barras bouncing), y selección instantánea.

2. AI Nexus & RAG Engine

• Pipeline Vectorial Completo: PDF → parsing → chunking → embeddings (1536d) → pgvector → cosine similarity → prompt building → streaming response.
• Dual Mode Chat: Alternancia seamless entre IA (SSE streaming) y humano (WebSocket live).
• Lead Capture to AI Context: Los datos del visitante se inyectan como contexto invisible para personalización automática.
• Model Hot-Swap: Cambio de modelo/temperatura en caliente desde el dashboard sin re-deploy.

3. Portfolio & Project Showcase

• i18n por Herencia (parent_id): Traducciones vinculadas que permiten contenido independiente por idioma.
• GitHub Stats Integration: Stars, forks, y distribución de lenguajes sincronizados desde GitHub.
• SEO-First Rendering: Astro SSR con Open Graph, meta tags dinámicos, y structured data por proyecto.
• Relaciones Polimórficas: Tecnologías asociadas vía Techeable para filtrado y visualización cruzada.

4. Immersive Landing Experience

• Terminal Draggable: Hero interactivo con drag & drop, typing animation, y glow reactivo al audio.
• System Stats Live: Telemetría del cliente con CPU, RAM, uptime, latencia, y barras audio-reactivas.
• Tech Orbit & Radial: Visualizaciones animadas del stack tecnológico en layouts orbital y radial.
• Floating Chat FAB: Botón flotante que despliega el chat con animación de escala y backdrop blur.

5. Enterprise Security & Auth

• HybridAuthGuard: Detección automática de JWT vs Session en cada request.
• 2FA con TOTP + QR: Autenticación de dos factores con generación de QR code escaneable.
• Rate Limiting: 100 req/min por IP con @nestjs/throttler.
• CI Security Pipeline: pnpm audit, Trivy container scanning, TruffleHog secrets scanning, SBOM generation (CycloneDX).

🛡️ Ingeniería & Seguridad del CI/CD

• SHA Pinning de Actions: Todas mis GitHub/Gitea Actions están pinneadas por commit hash, no por tag — previniendo supply chain attacks. Renovate actualiza los SHAs automáticamente.
• Quality Gates Multi-Nivel: Cada push ejecuta lint (Biome), unit tests, build completo, y auditoría de seguridad antes de permitir merge.
• Deploy con Rollback Automático: Mi deploy a producción incluye health checks post-deploy y rollback automático si el servidor no responde — garantizando zero-downtime deployments.
• Observabilidad Completa: Tracing distribuido con OpenTelemetry, logging estructurado con Pino, y health checks con @nestjs/terminus para visibilidad total del sistema en producción.