Pular para o conteúdo principal

Ruta de aprendizaje de Crimoo

Esta ruta es para un desarrollador que ya conoce la app Angular y quiere dominar todo el sistema Crimoo: lógica de negocio, backend, runtime GTM server-side, flujo de tracking, infraestructura, depuración y pruebas.

Crimoo es una plataforma para administrar GTM server-side. Permite crear y operar contenedores GTM server-side, enrutar tráfico de tracking por dominios propios, capturar identidades CRM, inspeccionar eventos del navegador, enviar conversiones offline y gestionar suscripciones.

Cómo usar estos docs​

Lée esta página como mapa principal:

  1. Usa esta ruta como guía.
  2. Lee Lógica de negocio para aprender el lenguaje del dominio.
  3. Usa Mapa de proyectos para entender qué carpeta pertenece a cada responsabilidad.
  4. Abre las páginas de proyecto en Proyectos cuando necesites detalle de implementación.
  5. Usa Índice de consulta para skills cuando quieras preguntar a Codex sobre lógica, ownership o depuración.

Fase 1: Producto y dominio​

Objetivo: explicar Crimoo sin mencionar frameworks.

Debes poder responder:

  • Qué es un workspace y por qué agrupa GTMs, CRM, conversiones y analytics.
  • Qué diferencia hay entre un registro GTM y un contenedor Docker GTM.
  • Qué es dominio primario, dominio custom, dominio del loader y dominio de tracking.
  • Qué datos viven en PostgreSQL y cuáles en ClickHouse.
  • Por qué el flujo normal de tracking responde 202 Accepted antes de que el contenedor procese el evento.
  • Por qué preview/debug va por una ruta sincrónica.

Lee:

Practica:

  • Dibuja el camino de un page view desde browser a gtm-proxy, Pub/Sub, gtm-fabric, el contenedor GTM y ClickHouse.
  • Toma un GTM en la UI e identifica la entidad backend, dominios, VM, contenedores, puertos y certificados.

Fase 2: Control plane​

Objetivo: entender cómo Crimoo guarda configuración y coordina al resto de servicios.

El control plane está principalmente en node-api junto con PostgreSQL, ClickHouse, Stripe, Gemini, Cloudflare y las APIs internas que usan gtm-fabric y gtm-proxy.

Lee:

Domina:

  • Middleware y registro de rutas en Express.
  • Entidades y migraciones de TypeORM.
  • Scope por workspace y guards de auth.
  • Casos de uso del ciclo de vida GTM.
  • Endpoints internos bajo /internal/fabric/*.
  • Scheduler de renovación de certificados.
  • Ciclo de billing con Stripe checkout y webhooks.
  • Integración con Copilot y Gemini.

Practica:

  • Sigue POST /api/v1/gtm desde la ruta hasta controller, use case, persistencia y llamada a fabric.
  • Sigue GET /internal/fabric/gtms?vmId=X y enumera los campos que necesita un servicio del data plane al arrancar.
  • Sigue un batch de CRM capture desde fabric a node-api y hasta contacts.

Fase 3: Data plane​

Objetivo: entender el runtime que recibe tráfico productivo de tracking.

El data plane está principalmente en gtm-proxy y gtm-fabric.

Lee:

Domina:

  • Routing HTTP y lookup dinámico de certificados por SNI.
  • Routing de api.crimoo.com hacia node-api.
  • Routing de /api/* del dominio del cliente hacia management/fabric.
  • Flujo async de tracking: el proxy responde 202 y luego publica en Pub/Sub.
  • Flujo sync de preview: el proxy reenvía directo al contenedor GTM.
  • GA4 bypass y desofuscación de rutas/query params.
  • Consumer de Pub/Sub, rate limiting, circuit breaker, parser chain, enriquecimiento y batch insert en ClickHouse.
  • Config stateless en gtm-fabric: fetch al arrancar desde node-api y cache en memoria.

Practica:

  • Dado un host y una ruta, decide si gtm-proxy devuelve 403, 404, 503, JS del custom loader, publish a Pub/Sub, forward a node-api, forward a fabric o proxy directo al contenedor GTM.
  • Simula un miss de cache de certificado y explica cada componente.
  • Explica por qué I/O bloqueante dentro del event loop de Netty es peligroso.

Fase 4: Angular y experiencia de desarrollo​

Objetivo: conectar tu conocimiento de Angular con backend y contratos del data plane.

Lee:

Domina:

  • Modelo auth con withCredentials: true.
  • Workspace context y scope de requests.
  • Wizard de GTM setup y pantallas de settings.
  • Contacts, deals, timelines y configuración de captura.
  • Pantallas de offline conversions.
  • Dashboard de analytics y filtros.
  • Puntos de entrada de Copilot.

Practica:

  • Elige un servicio Angular y mapea cada método a un endpoint backend.
  • Toma una acción del dashboard y sigue el cambio de estado, la llamada HTTP, el efecto backend y el feedback de UI.

Fase 5: Inspector, Copilot e integraciones​

Objetivo: entender herramientas que rodean la plataforma central.

Lee:

Domina:

  • Inyección del inspector en Shadow DOM y creación de reglas vía postMessage.
  • Ciclo de vida de sesiones Copilot y passthrough de clicks en iframe.
  • Límites entre Gemini, GTM automation y verificación de DOM.
  • Intención de los plugins WordPress y Shopify.

Practica:

  • Abre una sesión de debug y explica cómo se carga el bundle del inspector.
  • Sigue un mensaje crimoo:create-rule desde el sitio del cliente hasta Angular y después al backend.

Fase 6: Infra, despliegue y contexto legado​

Objetivo: saber qué corre en producción, qué es histórico y qué es experimental.

Lee:

Domina:

  • Topología de producción en la VPS de Hostinger.
  • Firebase Hosting para la UI Angular.
  • Docker Compose alrededor de node-api, PostgreSQL y ClickHouse.
  • Por qué gtm-proxy es hoy la entrada pública real para tracking.
  • Qué proyectos Go/VM manager antiguos son útiles como contexto pero no como ruta productiva.

Practica:

  • Reconstruye el diagrama de despliegue de memoria.
  • Lista qué debe revisarse antes de declarar una carpeta como core de producción.

Fase 7: Pruebas y confianza​

Objetivo: saber validar cambios sin adivinar.

Lee:

Domina:

  • Tests unitarios e integración en node-api.
  • Tests Maven en servicios Java.
  • Tests unitarios de Angular.
  • Playwright browser tests.
  • Smoke tests manuales para GTM lifecycle, tracking, CRM capture y billing.

Practica:

  • Ejecuta primero el test más pequeño relevante antes de tocar un módulo.
  • Después de un cambio cross-service, escribe un script de verificación manual con requests, logs y efectos en base de datos esperados.

Checklist de dominio​

Estás listo para trabajar por todo el proyecto cuando puedas:

  • Explicar el flujo normal y el flujo preview de tracking.
  • Cambiar un comportamiento de GTM lifecycle sin romper el contrato proxy/fabric.
  • Agregar un endpoint backend y conectarlo con Angular respetando workspace/auth.
  • Depurar SSL/certificados entre Cloudflare, node-api, fabric y proxy.
  • Inspeccionar writes a ClickHouse y datos de control en PostgreSQL.
  • Razonar sobre fallos async: retries de Pub/Sub, timeouts de container, circuit breakers y stale cache.
  • Saber qué carpetas son core de producción, herramientas de apoyo, docs, tests, plugins o legado.