Guidelines do Hub

Regras específicas do módulo Hub. Os guidelines comuns a todo o monorepo estão em docs/0-common/8-guidelines.md.

Para referência de arquitetura mais profunda, ver também:

• Serviços: 1-services.md
• Modelo de dados: 2-data-model.md
• Filas: 3-queues.md
• Resiliência: 7-resilience.md
• Blueprint: 8-blueprint.md

Connectors

• Connectors são stateless — sem acesso direto a banco ou filas
• Qualquer persistência ou enqueue acontece fora do connector, no service que o orquestra
• Logos ficam como arquivos locais na pasta do connector; prepare.ts lê do disco via loadBlueprint

BullMQ

• FlowProducer parent jobs são skipped no worker (padrão BullMQ para tracking)
• Log entries de execução devem usar factory functions dedicadas — nunca duplicar a criação do job em múltiplos lugares
• Queue names centralizados em @hg/core#QUEUE_NAMES — não hardcode strings

Execuções e Runs

• Runs rastreiam override_id e credential_id; quando uma integração tem múltiplas variações de config, há um run por variação
• Métricas de execução (hub_execution_runs, hub_execution_items) são queries cross-tenant: sempre comentar // Cross-tenant system query

Blueprint

• pnpm blueprint:validate antes de qualquer commit que toque .blueprint.yaml
• pnpm blueprint:test para validar mocks e handlers
• Tipos de integração são registrados via pnpm db:prepare