Vantus — AI-Powered Assistant Widget SaaS

Iron MVP 1.0 — Lanzamiento certificado por el Tribunal de Arquitectura (25/25 Correctness Properties validadas)

Vantus es una plataforma SaaS B2B de grado empresarial que permite a cualquier empresa desplegar un widget de asistente inteligente inexpugnable, conectado a un motor de IA (RAG) con aislamiento multi-tenant garantizado por construcción.

🏛️ Estado del Proyecto

| Fase | Estado | Specs | Cobertura | Tribunal | |------|--------|-------|-------|----------| | Fase 1 — Widget UX | ✅ Cerrada | 5 | 100% | Validado | | Fase 2 — Base de Datos | ✅ Cerrada | 2 | 100% | Validado | | Fase 3 — Panel Cliente | ✅ Cerrada | 5 | 100% | Validado | | Fase 4 — AI Core | ✅ Cerrada | 10 | 100% | Validado | | Fase 5 — Hardening | ✅ Cerrada | 3 | 100% | Validado | | Fase 6 — Ops & E2E | ✅ Cerrada | 6 | Grand Slam | Validado |

Veredicto del Tribunal: 🟢 LUZ VERDE — LANZAMIENTO AUTORIZADO (GA)

Verdicto final: docs/audits/SUPREME-TRIBUNAL-VERDICT-IRON-MVP-20260516.md

🏗️ Arquitectura

┌─────────────┐     ┌─────────────┐     ┌─────────────────────────────────────────┐
│   Widget    │────▶│   Edge      │────▶│         AI Core (FastAPI)               │
│   (JS)      │     │ (CloudFlare)│     │  LangGraph · RAG · Tools · SSE          │
└─────────────┘     └─────────────┘     └─────────────────────────────────────────┘
                                               │
                    ┌────────────┬─────────────┼────────────┬────────────┐
                    ▼            ▼             ▼            ▼            ▼
               ┌────────┐  ┌─────────┐  ┌──────────┐  ┌────────┐  ┌──────────┐
               │Postgres│  │ Qdrant  │  │  Redis   │  │  KMS   │  │  Stripe  │
               │(RLS)   │  │(Vectors)│  │(Cache)   │  │(AWS)   │  │(Billing) │
               └────────┘  └─────────┘  └──────────┘  └────────┘  └──────────┘

Capas y Garantías de Aislamiento

| Capa | Tecnología | Garantía Multi-tenant | |------|-----------|-----------------------| | Widget | Vanilla JS IIFE | Sanitización XSS (sanitizeHtml) y Auth via API Key | | Panel | Next.js 14 + SSR | Middleware de seguridad y Contexto de Usuario SSR | | AI Core | FastAPI + LangGraph | AgentContext inyectado, protección contra Prompt Injection | | Vector DB | Qdrant Cloud | Filtro must obligatorio en SecureVectorStore (PBT n5-51) | | Database | Supabase (Postgres 15) | FORCE ROW LEVEL SECURITY en el 100% de las tablas | | KMS | AES-256-GCM | Envelope encryption con account_id como AAD obligatorio |

🚀 Características del Iron MVP

Widget Inteligente

• 💬 Acciones sugeridas con topic tags y textarea auto-resize.
• 📎 Carga de archivos (imágenes/audio) con previsualización.
• 🎟️ Tarjetas de cupones y carruseles de productos con fallback offline.
• 📝 Formularios interactivos para captura de leads integrados.

Panel de Administración (SaaS)

• 🏭 Widget Factory: Generación segura de API Keys (vx_live_...) y snippets.
• 🔐 Seguridad Avanzada: MFA TOTP, validación zxcvbn y chequeo HIBP.
• 💳 Billing Industrial: Gestión de planes vía Stripe con Feature Gating inquebrantable.
• 📊 Caché de Cuotas: Monitoreo de uso O(1) mediante triggers asíncronos.

Ecosistema y Operaciones

• 🧪 Grand Slam Testing: Suite E2E con Playwright (aislamiento de BD por test).
• 🏭 CI/CD Industrial: Docker multi-stage non-root, artefactos inmutables (SHA).
• 🩺 Deep Healthcheck: Autodiagnóstico con protección Thundering Herd.
• ✉️ Post-Purchase Drip: Campaña de onboarding asíncrona mediante drip_queue.

📦 Estructura del Repo

vantus-chat-widget/
├── js/                          # Widget Vanilla JS
│   └── chat-widget.js           # IIFE autocontenido
├── ai-core/                     # Python FastAPI AI Core
│   ├── app/
│   │   ├── main.py              # FastAPI app + lifespan
│   │   ├── routes/
│   │   │   └── chat.py          # POST /chat/stream (SSE)
│   │   ├── graph/
│   │   │   ├── builder.py       # LangGraph compiled graph
│   │   │   └── nodes/
│   │   │       ├── agent.py
│   │   │       ├── action.py    # Tool dispatcher
│   │   │       └── rag_retrieval.py
│   │   ├── services/
│   │   │   ├── vector_store.py  # SecureVectorStore (Qdrant)
│   │   │   ├── ingestion/       # Chunker + Embedder + Pipeline
│   │   │   ├── extraction/      # PDF/DOCX/TXT/CSV/MD extractors
│   │   │   ├── rag/             # HybridRetriever + ContextFormatter + Reranker
│   │   │   ├── provider_hub.py  # BYOK + multi-provider adapters
│   │   │   └── kms.py           # AES-256 envelope encryption
│   │   ├── tools/
│   │   │   ├── dispatcher.py    # @register_tool + execution
│   │   │   └── implementations/ # capture_lead, create_ticket, search_knowledge
│   │   └── models/
│   │       ├── context.py       # AgentContext (tenant isolation)
│   ├── tests/
│   └── pyproject.toml
├── client-panel/                # Next.js 14 Panel de Cliente
├── packages/
│   ├── react/                   # @vantus/react-widget (npm)
│   └── wordpress/               # Vantus Assistant Widget (WP plugin)
├── supabase/
│   └── migrations/              # SQL con RLS estricto
├── docs/
│   ├── ARCHITECTURE-MASTER-BLUEPRINT.md  # Autoridad suprema
│   ├── audits/                  # 32 auditorías del Tribunal
│   ├── IMPLEMENTATION-ORDER.md  # Roadmap de fases
│   └── adr/                     # Architecture Decision Records
└── README.md

🧪 Tests

# AI Core — Pytest suite
cd ai-core
poetry run pytest tests/

# Global E2E — Playwright Grand Slam
cd client-panel
npx playwright test

📋 Instalación

Snippet (IIFE)

<script src="https://cdn.vantus.io/widget/v1.0.0-iron/chat-widget.js"
        integrity="sha384-..."
        crossorigin="anonymous"
        data-api-key="vx_live_tu_llave"></script>

🛣️ Roadmap V2 (Planificado)

• [ ] Super-Admin Shell: Jerarquía Reseller y God Mode auditado.
• [ ] RLHF Training Center: Interfaz para corrección humana de respuestas de IA.
• [ ] Hybrid Handoff Routing: Enrutamiento avanzado de chats a agentes humanos.
• [ ] Analytics BI Center: Dashboards de inteligencia de negocio profundos.

📜 Gobernanza

Este proyecto ha sido construido y auditado bajo el Protocolo TRIBUNAL v2.0, garantizando que cada línea de código cumple con la Constitución Técnica del Master Blueprint.

Sellado por el Tribunal Supremo — 2026-05-16