trafficanalytics

## Descripción general Traffic Analytics es un proxy de análisis web diseñado para sitios Ghost. Intercepta las llamadas `POST /api/v1/page_hit` realizadas por el script `ghost-stats.js` de Ghost, enriquece la carga útil (análisis de user-agent, análisis de referidores, generación de firmas de usuario) y reenvía los datos a la API `/v0/events` de Tinybird, donde se almacenan en una base de datos ClickHouse. ## Arquitectura y modos de ejecución - **Modo batch (predeterminado)** – El servicio de ingesta valida las solicitudes, filtra los bots y publica los eventos brutos en un tema de Google Cloud Pub/Sub. Un trabajador independiente consume la suscripción, enriquece cada evento, los agrupa y los reenvía a Tinybird. Esto desacopla el manejo de solicitudes de la ingesta y mejora el rendimiento. - **Modo proxy (sincrónico)** – Cuando no hay un tema de Pub/Sub configurado, el servicio de ingesta realiza el enriquecimiento en línea y actúa como proxy de la solicitud directamente a Tinybird en el mismo ciclo HTTP. El modo se selecciona a través de la variable de entorno `WORKER_MODE` y la presencia de `PUBSUB_TOPIC_PAGE_HITS_RAW`. ## Características principales - Análisis de user-agent para detección de SO, navegador y dispositivo. - Análisis y categorización de URLs de referidores. - Firmas de usuario que preservan la privacidad con sales que rotan diariamente. - Encabezado opcional `x-ghost-bot-detected: true` para el tráfico de bots filtrado. ## Configuración Copie `.env.example` a `.env` y ajuste los valores. Las variables importantes incluyen: - `WORKER_MODE` – `worker` o `ingest`. - `PUBSUB_TOPIC_PAGE_HITS_RAW` – define el modo batch. - `ENABLE_BOT_DETECTION_HEADER` – activa el encabezado de respuesta de detección de bots. ## Flujo de trabajo de desarrollo 1. **Prerrequisitos** – Docker (Desktop u Orbstack) y Docker Compose. 2. Clone el repositorio y ejecute `pnpm dev` para iniciar todos los servicios; la API de análisis estará disponible en `http://localhost:3000`. 3. Para la integración local con una versión de Ghost, ejecute `pnpm dev:ghost` en este repositorio y `pnpm dev:analytics:local` en el repositorio de Ghost. Esto conecta los dos contenedores a través de una red de Docker compartida. ### Soporte para Multi-Worktree El proyecto puede ejecutar múltiples worktrees de Git simultáneamente. Cada worktree utiliza su propio archivo `.env` para establecer puertos únicos, nombres de proyecto de Docker compose y volúmenes aislados, lo que permite el desarrollo paralelo sin conflictos de puertos. ## Pruebas y Linting - `pnpm test:types` – Verificaciones de tipos de TypeScript. - `pnpm test:unit` – Pruebas unitarias. - `pnpm test:integration` – Pruebas de integración. - `pnpm test:e2e` – Pruebas de extremo a extremo con WireMock. - `pnpm lint` – Linting con ESLint. Todos los comandos de prueba se ejecutan dentro de contenedores Docker para garantizar la consistencia del entorno. ## Pipeline de despliegue - **Flujo de ramas** – Abra un PR, opcionalmente etiquételo como `deploy-staging` para activar un despliegue de staging. - **Acciones de fusión** – Incremento automático de la versión de parche, creación de etiquetas de Git, publicación de imágenes en Docker Hub, despliegues de Cloud Run a staging y producción, verificaciones de estado y notificaciones de Slack. - **Activador manual** – Use la interfaz de GitHub Actions para ejecutar el flujo de trabajo "Deploy" a través de `workflow_dispatch`. Los detalles completos de CI/CD se encuentran en `docs/deployment.md`. ## Documentación - `docs/architecture.md` – Diagramas detallados de los modos batch vs. proxy, pipeline de Pub/Sub, OpenTelemetry y diseño del trabajador. - `docs/deployment.md` – Pipeline de CI/CD, flujo de staging/producción y procedimientos de reversión. ## Licencia MIT © Ghost Foundation (2013‑2026).