trafficanalytics

## Visão Geral Traffic Analytics é um proxy de análise web projetado para sites Ghost. Ele intercepta as chamadas `POST /api/v1/page_hit` feitas pelo script `ghost-stats.js` do Ghost, enriquece o payload (análise de user-agent, análise de referência, geração de assinatura de usuário) e encaminha os dados para a API `/v0/events` do Tinybird, onde são armazenados em um banco de dados ClickHouse. ## Arquitetura e Modos de Execução - **Modo batch (padrão)** – O serviço de ingestão valida as requisições, filtra robôs e publica eventos brutos em um tópico do Google Cloud Pub/Sub. Um trabalhador separado consome a assinatura, enriquece cada evento, os agrupa e os encaminha ao Tinybird. Isso desacopla o tratamento de requisições da ingestão e melhora o throughput. - **Modo proxy (síncrono)** – Quando nenhum tópico do Pub/Sub está configurado, o serviço de ingestão realiza o enriquecimento em linha e encaminha a requisição diretamente ao Tinybird no mesmo ciclo HTTP. O modo é selecionado pela variável de ambiente `WORKER_MODE` e pela presença de `PUBSUB_TOPIC_PAGE_HITS_RAW`. ## Recursos Principais - Análise de user-agent para detecção de sistema operacional, navegador e dispositivo. - Análise e categorização de URLs de referência. - Assinaturas de usuário preservadoras de privacidade com sal diário rotativo. - Cabeçalho opcional `x-ghost-bot-detected: true` para tráfego de robôs filtrado. ## Configuração Copie `.env.example` para `.env` e ajuste os valores. Variáveis importantes incluem: - `WORKER_MODE` – `worker` ou `ingest`. - `PUBSUB_TOPIC_PAGE_HITS_RAW` – define o modo batch. - `ENABLE_BOT_DETECTION_HEADER` – ativa/desativa o cabeçalho de detecção de robô. ## Fluxo de Desenvolvimento 1. **Pré-requisitos** – Docker (Desktop ou Orbstack) e Docker Compose. 2. Clone o repositório e execute `pnpm dev` para iniciar todos os serviços; a API de análise estará acessível em `http://localhost:3000`. 3. Para integração local com uma instância do Ghost, execute `pnpm dev:ghost` neste repositório e `pnpm dev:analytics:local` no repositório do Ghost. Isso conecta os dois contêineres por meio de uma rede Docker compartilhada. ### Suporte a Múltiplos Worktrees O projeto pode executar múltiplos worktrees do Git simultaneamente. Cada worktree usa seu próprio arquivo `.env` para definir portas únicas, nomes de projeto do Docker Compose e volumes isolados, permitindo desenvolvimento paralelo sem conflitos de porta. ## Testes e Linting - `pnpm test:types` – Verificação de tipos TypeScript. - `pnpm test:unit` – Testes unitários. - `pnpm test:integration` – Testes de integração. - `pnpm test:e2e` – Testes ponta a ponta com WireMock. - `pnpm lint` – Linting com ESLint. Todos os comandos de teste são executados dentro de contêineres Docker para garantir consistência de ambiente. ## Pipeline de Implantação - **Fluxo de branch** – Abra um PR, opcionalmente marque com `deploy-staging` para acionar uma implantação de staging. - **Ações de merge** – Atualização automática de versão patch, criação de tag Git, publicação da imagem no Docker Hub, implantações no Cloud Run para staging e produção, verificações de saúde e notificações no Slack. - **Gatilho manual** – Use a interface do GitHub Actions para executar o fluxo "Deploy" via `workflow_dispatch`. Detalhes completos do CI/CD estão em `docs/deployment.md`. ## Documentação - `docs/architecture.md` – Diagramas detalhados dos modos batch e proxy, pipeline do Pub/Sub, OpenTelemetry e design do worker. - `docs/deployment.md` – Pipeline CI/CD, fluxo de staging/produção e procedimentos de rollback. ## Licença MIT © Fundação Ghost (2013–2026).