Lógica de negocio

Esta página explica los conceptos del negocio. Úsala antes de cambiar entidades, endpoints, flujos de UI, comportamiento de tracking o reglas de billing.

Modelo mental del producto

Crimoo ayuda a un cliente a operar GTM server-side sin gestionar la infraestructura a mano. El cliente configura GTMs, dominios, reglas de captura, conversiones offline y billing desde el dashboard. Luego Crimoo ejecuta el control plane y el data plane que reciben, enrutan, inspeccionan, enriquecen y guardan eventos.

Usuarios, workspaces y acceso

Un User puede ser dueño o miembro de uno o más Workspace a través de membresías. La mayoría de los datos del producto se scopean por workspace para que cada equipo gestione sus propios GTMs, contactos, reglas de conversión y billing.

Regla de desarrollo: toda lectura o escritura de datos de cliente debe revisar el scope del workspace y el contexto de auth.

GTM

Un GTM en Crimoo no es solo un identificador de Google Tag Manager. Es el registro del control plane que conecta:

• Ownership de workspace.
• Configuración del contenedor GTM server-side.
• Dominios primario y custom.
• Asignación de VM.
• Contenedores preview y tagging.
• Puertos y health.
• Custom loader y obfuscation.
• Estado de certificados.
• Logs, analytics y uso.

La UI crea y administra el GTM. node-api persiste el GTM y llama a gtm-fabric para el trabajo runtime. gtm-fabric crea y maneja contenedores Docker. gtm-proxy enruta el tráfico público al destino correcto.

Dominios y certificados

Crimoo separa los dominios así:

• Dominio primario: dominio por defecto del GTM.
• Dominio custom: dominio del cliente apuntado a Crimoo.
• Dominio API: api.crimoo.com, enroutado por gtm-proxy hacia node-api.
• Dominio de tracking: cualquier dominio usado por el sitio cliente para enviar tracking server-side.

Flujo de certificados:

1. El cliente apunta DNS al destino esperado.
2. Crimoo verifica DNS.
3. gtm-fabric ejecuta ACME/Let's Encrypt si hace falta.
4. node-api guarda el certificado.
5. gtm-proxy lo obtiene vía HTTP interno y cachea un SslContext por SNI.
6. La renovación la orquesta node-api y la ejecuta gtm-fabric.

Contenedores y VMs

Un GTM puede tener contenedores preview y tagging. Los contenedores corren en la máquina del data plane y los maneja gtm-fabric.

Distinción importante:

• El tracking normal es asíncrono y optimizado para velocidad.
• Preview/debug es sincrónico y optimizado para respuestas exactas del debugger de GTM.

Eventos de tracking

El tráfico de tracking entra por gtm-proxy.

Flujo normal:

1. El browser envía una request como /g/collect.
2. gtm-proxy valida y resuelve la ruta.
3. gtm-proxy responde 202 Accepted rápido.
4. gtm-proxy publica el evento en Pub/Sub.
5. gtm-fabric consume el evento.
6. gtm-fabric reenvía al contenedor GTM.
7. gtm-fabric parsea, enriquece y escribe analytics en ClickHouse.

Flujo preview:

1. El browser envía la request con indicadores de preview.
2. gtm-proxy detecta preview.
3. gtm-proxy reenvía sincrónicamente al contenedor GTM.
4. El browser recibe la respuesta completa que necesita el debugger.

Custom loader y obfuscation

El custom loader permite servir JavaScript de GTM desde un dominio propio/de cliente y evitar patrones comunes de bloqueo. El proxy puede:

• Servir JavaScript generado por Crimoo.
• Proxy del script GTM por una ruta configurada.
• Restaurar rutas GA4 ofuscadas.
• Decodificar query params ofuscados antes de publicar o reenviar eventos.

El valor de negocio es un tracking first-party más confiable.

CRM Capture

CRM capture conecta identidad del navegador, eventos y mapeos de campos para producir contacts y deals.

Conceptos clave:

• Las cookies de identidad identifican cliente y sesión.
• Las capture rules definen qué eventos o formularios producen datos CRM.
• Las field definitions describen los campos disponibles.
• Los contacts agregan identificadores, campos custom y actividades en timeline.
• Los deals representan oportunidades en pipeline.
• El inspector ayuda a crear reglas desde eventos y formularios reales.

gtm-fabric puede devolver batches de contacts a node-api, que es dueño de la persistencia durable de CRM.

Conversiones offline

La lógica de conversiones offline manda eventos de negocio/CRM a plataformas como Meta o Google cuando se cumplen reglas de trigger.

Conceptos clave:

• Las credenciales de plataforma guardan acceso externo.
• Los trigger configs definen eventos de negocio que deben generar conversiones.
• Los conversion events representan trabajos de conversión.
• Las delivery records guardan intentos, estado y errores.

node-api es dueño de credenciales, triggers, eventos, deliveries, hashing, retries y adaptadores de plataforma.

Billing

Billing vive en node-api y Stripe.

Objetos clave:

• Plans.
• Estado del plan del usuario.
• Subscriptions.
• Checkout sessions.
• Webhooks de Stripe.
• Usage reporting desde el data plane.

Regla de desarrollo: los webhooks de Stripe deben ser idempotentes y verificar firma antes de mutar el estado de suscripción.

Copilot

Copilot es la capa de IA alrededor de automatización GTM y ayuda del producto.

Hay dos implementaciones visibles en el workspace:

• Rutas integradas de sesiones Copilot dentro de node-api.
• Proyectos standalone CrimooCopilot-Backend y CrimooCopilot-front.

Ideas centrales:

• Creación de sesiones y activation tokens.
• Streaming por SSE.
• Reasoning con Gemini.
• Inspección y modificación de Google GTM API.
• Verificación de DOM y overlay por iframe.

Cuando cambies Copilot, primero identifica si el path activo es el integrado en node-api o el servicio standalone.

Fronteras de storage

Dato	Storage primario
Usuarios, workspaces, GTMs, dominios, CRM, billing, config de conversiones	PostgreSQL vía node-api
Eventos de tracking y logs de contenedor	ClickHouse
Cache runtime de rutas/config/certificados	Memoria en gtm-proxy y gtm-fabric
Transporte de eventos	Google Pub/Sub
Verdad externa de billing	Stripe
DNS/cert externos	Cloudflare y Let's Encrypt

Invariantes

• Los datos del cliente deben estar scopeados por workspace.
• gtm-fabric no debe convertirse en la fuente de verdad persistente de dominios/config.
• El tracking normal debe mantener baja la latencia del browser con publish async.
• Preview/debug debe permanecer sincrónico.
• Los certificados deben buscarse y cachearse sin bloquear el event loop de Netty.
• Los endpoints internos no deben convertirse en APIs públicas del producto.
• Las escrituras de analytics deben tolerar picos con batching y retries.