WookcomDocsIr a Wookcom ↗

Documento histórico conservado. Describe una etapa anterior y contiene afirmaciones de integración y garantías no verificadas para la arquitectura actual. Para el estado auditado consulte la visión general.

ARCHITECTURE.md · Arquitectura de NexusBuilder (Edición 2026)

Este documento describe la arquitectura técnica de NexusBuilder, un constructor web de posicionamiento libre absoluto (Drag & Drop estilo Flazio y Builderall) con una interfaz 100% flotante, diseño responsivo independiente para móvil/tableta/escritorio, formas contenedoras inteligentes y gestión multisitio persistente.

1. Arquitectura de Interfaz Flotante (Floating UI)

  1. Herramienta de Elementos con Despliegue a la Par (FloatingElementsTool.tsx & FloatingElementsDrawer.tsx):

    • Alineación y Separación Superior: Posicionado en fixed top-8 left-6 z-50. Separación limpia de 32px (top-8), alineado milimétricamente con el riel lateral derecho.
    • Botón "Agregar" Flotante:
      • Botón blanco cuadrado con esquinas redondeadas (w-10 h-10 rounded-2xl), borde limpio border-slate-100 y sombra sutil.
      • Icono vectorial CopyPlus.
      • Tooltip Animado: Al pasar el cursor (hover), despliega fluidamente un tooltip con indicador azul diciendo "Agregar", el cual desaparece de inmediato al retirar el puntero (onMouseLeave).
      • Apertura y Cierre: Al presionar "Agregar", el botón se oculta y se despliega el menú flotante. Al cerrarse, reaparece en su posición exacta.
    • Comportamiento Inicial:
      • Al abrirse, solo se muestra el listado de categorías (Texto, Media, Formas, Botones, etc.). No se despliegan paneles secundarios sin acción del usuario.
    • Categorías Limpias sin Contenedores Anidados:
      • Cada elemento (H1, H2, H3, Botones, Formas, Tarjetas, Video, Imagen) se presenta de forma pura, sin bordes pesados ni fondos oscuros.
      • Los textos descriptivos y nombres se muestran en tooltips flotantes al pasar el cursor, evitando recargar la interfaz visual.
    • Cierre Automático al Soltar en el Lienzo:
      • Al arrastrar y soltar cualquier elemento sobre el lienzo (onDragEnd), el menú flotante se cierra automáticamente de inmediato, despejando la visión para el diseñador.

  2. Formas y Contenedores Inteligentes con Desplazamiento Atómico:

    • Las formas (card, pricing-card, o cualquier elemento con isContainer: true) actúan como superficies contenedoras.
    • Detección Unificada (isContainerElement): Se centralizó la lógica en src/utils/responsiveLayout.ts para que tanto el lienzo en vivo (CanvasSection.tsx), el renderizado de elementos (CanvasElement.tsx) y el gestor de estado maestro (App.tsx) compartan la misma definición exacta de qué es un contenedor.
    • Arrastre Coordinado de Hijos: Al arrastrar una forma contenedora por el lienzo, todos los elementos contenidos en su área delimitada se desplazan armónicamente en tiempo real conservando sus posiciones relativas. Al mover elementos individuales dentro de una forma, únicamente se actualizan las coordenadas del elemento seleccionado sin desplazar el contenedor ni los demás elementos.
    • Persistencia Atómica (Sin Borrado de Elementos): La actualización de coordenadas tras soltar la forma o sus elementos se procesa en una única llamada atómica (handleUpdateElementPosition) utilizando un updater funcional setPagesWithHistory((prevPages) => ...).
    • Sincronización Inmediata de Historial (useBuilderHistory.ts): Se vinculó la derivación de pages a currentIndexRef.current, impidiendo que lecturas entre ticks de renderizado lean instantáneas obsoletas que causaban la desaparición de elementos del lienzo.
    • Z-Index Predictivo: Las formas contenedoras se crean y renderizan con zIndex: 1, asegurando que cualquier elemento interactivo colocado sobre ellas (botones, textos, títulos, imágenes) se mantenga al frente con zIndex: 10, completamente visible y accesible.

  3. Sección Premium Modo Claro en Media (src/constants/premiumMediaSection.ts):

    • Catálogo integrado en la sección de Media con una cuadrícula de 4 tarjetas elegantes:
      • Encabezado con Insignia "Nuevas Soluciones", Título "Colección de Productos Claros" y Subtítulo.
      • 4 tarjetas independientes con contenedores blancos, bordes sutiles, imágenes de alta fidelidad, títulos de producto, descripciones, botones índigo interactivos y pies de estado.
      • Previsualización visual dedicada en el cajón de Media y soporte completo de drag & drop hacia el lienzo.

  4. Arquitectura Responsiva Independiente (Desktop / Tablet / Mobile):

    • Independencia Total de Vistas (src/utils/responsiveLayout.ts):
      • Modificar o centrar un elemento en la vista móvil (breakpoint = 'mobile') NUNCA afecta ni modifica las coordenadas x, y, width o height de la vista de escritorio (desktop).
      • Cada elemento en CanvasElementData almacena su disposición específica en:
        • x, y, width, height: Coordenadas maestras de escritorio (ancho de lienzo 1000px).
        • mobileLayout?: DeviceLayout: Coordenadas x, y, width, height específicas para la pantalla móvil (ancho de lienzo 375px).
        • tabletLayout?: DeviceLayout: Coordenadas específicas para tabletas (ancho de lienzo 768px).
    • Cálculo y Centrado Automático:
      • Al alternar a la vista móvil o al presionar el botón de centrado horizontal en móvil, se calcula la posición centrada dentro del viewport móvil de 375px ((375 - width) / 2).
      • Al regresar a la vista de escritorio, cada elemento conserva intactas sus coordenadas originales de PC sin ninguna alteración.
    • Previsualización Real (LivePreview.tsx):
      • El componente de previsualización en vivo evalúa el punto de ruptura activo y aplica el mobileLayout / tabletLayout correspondiente para garantizar fidelidad al 100%.

  5. Gestión Multisitio Persistente (src/hooks/useSiteManager.ts & FloatingSettingsDrawer.tsx):

    • Soporte para crear nuevos sitios sin reemplazar ni sobrescribir los sitios anteriores.
    • Cada sitio cuenta con identificador único, nombre, fecha de creación, páginas y secciones propias.
    • Selector y listado visual en las configuraciones para alternar rápidamente entre proyectos web.
    • Persistencia local automática en localStorage con clave nexus_builder_sites_catalog.

  6. Barra de Acciones Flotante del Elemento (CanvasElement.tsx):

    • Píldora blanca translúcida con efecto frosted glass:
      • Candado (Lock / Unlock): Bloquea o desbloquea el elemento para evitar arrastres accidentales.
      • Botón "Aa": Despliega directamente el modal de tipografía y texto para componentes textuales.
      • Botón de Centrado Horizontal (AlignCenter): Centra el elemento en la sección según el breakpoint actual (PC o Móvil).
      • Botón de Editar (Pencil): Abre el modal contextual de estilos (botón, imagen, forma, video).
      • Duplicar (Copy) y Eliminar (Trash2): Acciones rápidas con iconos limpios.

2. Mapa de Directorios

src/
├── components/
│   ├── canvas/
│   │   └── CanvasViewport/
│   │       ├── CanvasElement.tsx        # Elemento con barra flotante y soporte de disposición responsiva
│   │       ├── CanvasSection.tsx        # Sección con cálculo de drop centrado y viewport responsivo
│   │       ├── CanvasViewport.tsx       # Contenedor con zoom, atajos y cambio de breakpoint (PC/Tablet/Móvil)
│   │       ├── ElementContextMenu.tsx   # Menú contextual de clic derecho
│   │       └── EmptyCanvasState.tsx     # Estado inicial sin secciones
│   ├── floating/
│   │   ├── FloatingDrawer/              # Cajón flotante genérico reutilizable
│   │   └── FloatingToolbar/             # Barra de herramientas flotante central
│   ├── inspector/
│   │   ├── AppModalsHost.tsx            # Host central de renderizado de modales flotantes
│   │   ├── PropertyModals/              # Modales individuales desacoplados (Texto, Botón, Imagen, Video, Forma)
│   │   └── RightInspector/              # Inspector lateral con pestañas de Contenido, Estilo y Avanzado
│   ├── layout/
│   │   └── StudioHeader/                # Cabecera con selector de dispositivos (Desktop, Tablet, Mobile) y logo oficial
│   ├── modals/                          # Modales de exportación, plantillas y publicación
│   ├── preview/
│   │   └── LivePreview/                 # Previsualización interactiva con adaptación responsiva
│   ├── sidebar/
│   │   └── LeftSidebar/                 # Paneles laterales secundarios (capas, páginas, configuración)
│   └── toolbar/
│       ├── FloatingElementsTool/        # Herramienta izquierda con botón "Agregar" y tooltip
│       └── FloatingSidebar/             # Riel flotante con herramientas y cajones desplegables
├── constants/
│   ├── elementLibrary.ts                # Biblioteca y catálogo de elementos base
│   ├── initialData.ts                   # Estructura del sitio por defecto
│   ├── prebuiltSectionsCatalog.ts       # Secciones prediseñadas (Hero, Features, Media, Precios, etc.)
│   └── premiumMediaSection.ts           # Sección Premium Modo Claro con 4 tarjetas de productos
├── hooks/
│   ├── useBuilderHistory.ts             # Historial atómico sincronizado con currentIndexRef (Deshacer / Rehacer)
│   ├── useDraggableFloating.ts          # Hook de arrastre libre para modales flotantes
│   ├── usePageOperations.ts             # Operaciones CRUD sobre páginas del sitio
│   └── useSiteManager.ts                # Gestión multisitio persistente
├── types/
│   └── builder.ts                       # Tipos estrictos (CanvasElementData, DeviceLayout, ElementStyles, etc.)
└── utils/
    ├── codeGenerator.ts                 # Exportador de código HTML/Tailwind
    └── responsiveLayout.ts              # Utilidad de cálculo de dimensiones y centrado independiente para móvil/desktop

3. Flujo de Datos y Eventos Críticos

  1. Inserción de Elemento por Drag & Drop: FloatingElementsDrawer emite evento dragstart -> El usuario arrastra sobre CanvasSection -> CanvasSection calcula coordenadas dropX, dropY relativas al workspace centrado -> Se despacha onDropElementAtPosition -> FloatingElementsDrawer invoca onClose() de inmediato -> El elemento queda centrado en el punto de colocación sin empujar coordenadas al vacío.

  2. Arrastre de Contenedores y Movimiento Atómico: Al interactuar con un elemento con isContainer: true, CanvasSection calcula liveContainerOffsets para arrastre visual fluido -> Al soltar (handleLiveDragEnd), se ejecuta una única llamada a onUpdateElementPosition(draggedId, newX, newY) -> App.tsx actualiza el contenedor y todas sus subpiezas en un único ciclo de estado atómico con setPagesWithHistory((prevPages) => ...) -> Se preservan el 100% de los elementos previos del lienzo.

  3. Independencia Móvil vs Escritorio: Al cambiar a breakpoint = 'mobile', CanvasViewport reduce el ancho visible a 375px. Al modificar o centrar la posición de un elemento en este modo, App.tsx actualiza únicamente el campo mobileLayout del elemento ({ x, y, width, height }), dejando el x e y principales de escritorio 100% inalterados. Al regresar a breakpoint = 'desktop', el elemento se dibuja en sus coordenadas originales.

4. Sistema E-Commerce estilo Shopify y Logística Boxful

  1. Gestión de Pedidos estilo Shopify (ShopifyOrdersManager.tsx):

    • Métricas en tiempo real: Ventas Totales, Órdenes por Despachar, Envíos en Tránsito con Boxful y Entregas Exitosas.
    • Pestañas de filtrado rápido al estilo Shopify Admin: Todos, Por Despachar, En camino Boxful, Entregados, No pagados.
    • Búsqueda en vivo de órdenes por ID, cliente, número telefónico o número de rastreo.
    • Generación de pedidos manuales (Draft Orders).
    • Impresión y visualización de etiquetas de despacho oficiales con código de barras simulado y datos del remitente/destinatario.

  2. Despacho a Transportadoras con Boxful (boxfulService.ts):

    • Integración oficial con la red de transportadoras aliadas de Boxful: Boxful Express Last-Mile, Cargo Expreso, DHL Express Global, FedEx Priority, Moovin Urbana.
    • Generación de guías de rastreo instantáneas con prefijo oficial BXF- y sincronización con el historial de eventos.
    • Cotización de tarifas dinámicas en el Checkout basadas en el departamento/municipio de entrega y dimensiones del paquete.

  3. Detalle de Producto estilo Shopify (ProductDetailModal.tsx):

    • Galería interactiva de imágenes de alta resolución.
    • Selector de variantes (Talla, Color, Capacidad) y contador interactivo de cantidad (+ / -).
    • Acciones de compra: "Añadir al Carrito" y "Comprar Ahora" (Shopify instant buy).
    • Insignia de garantía y cálculo automático de porcentaje de ahorro sobre precio original.

  4. Componentes E-Commerce de Arrastre y Soltar:

    • product-grid: Catálogo completo con buscador, filtros y vista modal.
    • product-card: Tarjeta individual de producto destacado con compra rápida.
    • cart-button: Botón con contador de artículos y apertura fluida del carrito.
    • checkout-form: Formulario con cotización Boxful en vivo y métodos de pago (Tarjeta, Efectivo contra entrega y PayPal).
    • boxful-tracker: Widget interactivo para rastreo con número de guía Boxful.

  5. Motor de Exportación y Conexión Real con Boxful API (BoxfulExportModal.tsx & boxfulService.ts):

    • Conversión estricta de órdenes a la especificación oficial requerida por Boxful (POST /v1/packages / POST /v1/orders).
    • Mapeo automático de direcciones de origen (bodega), destinatario, pesos en libras, dimensiones, valores declarados y cobro contra entrega (COD).
    • Exportación individual o en lote (Batch JSON) con metadatos de auditoría y totales calculados.
    • Copia al portapapeles en 1 clic y descarga de archivo .json para consumo directo en webhooks, automatizaciones Zapier/Make o Postman.
    • Ejecución HTTP REAL contra los servidores de Boxful (POST /v1/packages), mostrando el código de estado HTTP real (ej. 201 Created, 401 Unauthorized, 422 Unprocessable) y la respuesta directa de Boxful.
    • Persistencia segura y en tiempo real de credenciales y API Keys en Firestore (/users/{uid}/settings/boxful).

  6. Configuración de Credenciales de API y Webhooks Boxful (BoxfulSettingsSection.tsx):

    • Pestaña dedicada en StoreManagerModal para configurar la API Secret Key (Sandbox y Producción) con validación en vivo contra los servidores de Boxful.
    • Generación de Endpoint de Webhook específico por comercio (/api/webhooks/boxful?uid={userId}) con botón de copia en 1 clic.
    • Configuración de Webhook Secret para validación de firma criptográfica HMAC-SHA256 de eventos entrantes.
    • Checklist y suscripción a eventos de ciclo de vida (package.created, package.picked_up, package.in_transit, package.out_for_delivery, package.delivered, package.failed).
    • Sincronización bidireccional en tiempo real: sincronización manual inmediata y polling periódico configurable para actualizar automáticamente estados de guías y pedidos en Firestore.
    • Probador de Webhook interactivo para disparar y auditar la actualización inmediata de pedidos en la interfaz y en la base de datos sin simulaciones ficticias.

  7. Sistema de Notificaciones Toast en Tiempo Real (src/components/toast/):

    • Arquitectura modular compuesta por ToastContainer.tsx (orquestador flotante fijo z-50) y ToastNotification.tsx (tarjeta interactiva individual).
    • Suscripción en tiempo real a Firestore (onSnapshot sobre /users/{uid}/store_orders) que detecta inmediatamente inserciones de nuevos pedidos.
    • Alerta visual y auditiva inmediata mediante Web Audio API nativo cuando ingresa un pedido nuevo a través de los webhooks de Boxful (package.created / order.created).
    • Desglose informativo del pedido: número #ORD-..., nombre del cliente, total en USD, transportadora aliada y número de guía oficial.
    • Barra de progreso temporal de auto-cierre con pausa automática en cursor hover.
    • Botón de acción directa "Ver en StoreManager" para abrir y enfocar la orden en el gestor de pedidos con un solo clic.

  8. Panel de Control & Analítica Recharts en Tiempo Real (src/components/ecommerce/analytics/):

    • Pestaña de entrada principal en StoreManagerModal conectada reactivamente al estado en vivo de Firestore.
    • Tendencia de Ventas & Volumen (SalesTrendChart.tsx): Gráfico interactivo con ComposedChart de Recharts que combina área degradada para facturación ($ USD) y barras verticales para conteo de pedidos diarios, con filtros de periodo (7 días, 30 días, histórico).
    • Ranking de Productos Más Vendidos (TopProductsChart.tsx): Gráfico horizontal BarChart con desglose visual de unidades vendidas, porcentaje de participación e ingresos generados por cada producto en catálogo.
    • KPIs Ejecutivos (OrdersMetricsSummary.tsx): Tarjetas de alto impacto con Facturación Total (desglose pagado vs COD), Volumen de Pedidos (entregados vs en ruta), Ticket Promedio (AOV) y Tasa de Eficiencia Logística Boxful.

  9. Arquitectura Espacial y Estética Minimalista Estilo Apple & Wookcom (StoreManagerModal.tsx, LeftSidebar.tsx & FloatingSidebar.tsx):

    • Márgenes de Separación Ininterrumpidos en Paneles Derechos: Los cajones flotantes de herramientas (FloatingSettingsDrawer, FloatingPagesDrawer, FloatingStylesDrawer, TrendsDrawer, HelpDrawer) se posicionan a right-[76px], manteniendo un margen de separación limpio (~24px) que evita que solapen o tapen los botones flotantes del dock vertical derecho (FloatingSidebar a right-6).
    • Separación Amplia en el Panel de Gestión (StoreManagerModal.tsx): Se ubica a right-[96px] sm:right-[104px] con un margen libre de más de 32px respecto a la barra de iconos. Se extiende horizontalmente (w-auto sm:w-[calc(100vw-128px)] max-w-6xl 2xl:max-w-7xl) permitiendo máxima amplitud de lectura para gráficos Recharts y tablas de pedidos.
    • Cajón Flotante Izquierdo Separado (LeftSidebar.tsx): El sub-cajón activo (ElementsDrawer, PagesDrawer, etc.) se renderiza como una tarjeta blanca flotante con margen ml-3 my-3 rounded-2xl, separada por un canal de aire limpio respecto al carril vertical de iconos principal, replicando la geometría exacta de Wookcom.
    • Cero Elementos Oscuros Agresivos / Estilo Apple Puro: Fondos translúcidos con desenfoque de cristal (bg-white/95 backdrop-blur-2xl), controles segmentados suaves (bg-slate-200/70 con pastilla blanca activa), tipografía nítida en tonos carbón y gris mineral, y total ausencia de datos ficticios o simulados.