Cerbero

Operações Karhub · reescrita em Go

O guardião de três cabeças

Cerbero é a reescrita das operações da Karhub de Node/TypeScript para Go, em arquitetura hexagonal e comunicação event-driven via Google Cloud Pub/Sub, com um modelo canônico de eventos. Três pilares guardam o portão: Vendas, Compras e NF/Logística.

Não é da área técnica? Comece aqui

Como a operação funciona → conta, em português comum e sem código, o que acontece entre o cliente comprar e a peça sair do CD. Junto vem um glossário com o vocabulário que a gente usa todo dia (furo, sobra, bip, pack, FULL, CD…) e uma página explicando por que existem dois sistemas rodando ao mesmo tempo.

O resto deste site é documentação de engenharia.

Chegou agora na squad? Comece por aqui

O Starter pack → explica o que é a Karhub, por que o sistema é assim, e em que ordem ler este site nas primeiras semanas. Junto vem o catálogo — SKU, marca, fornecedor, sku_supplier — a base que todo o resto assume que você já conhece.

O serviço de referência — ml-webhook-adapter — define os padrões arquiteturais que todos os demais seguem. Hoje todos os serviços do ecossistema estão implementados e em operação; o service-boilerplate empacota o padrão para o próximo serviço.

Os três pilares

Cabeça I

Vendas & Marketplace

ml-webhook-adapter · shopify-webhook-adapter · order-processor

Cabeça II

Compras & Supply Chain

purchase-recommendation · purchase-closing

Cabeça III

NF-e, Conferência & Logística

supplier-invoice-receiving · wms-service

O contexto de negócio completo (incluindo o sistema legado) vive no site de Operações Karhub. Este site foca na implementação Go.

Stack

Item	Tecnologia
Linguagem	Go 1.26
Arquitetura	Hexagonal (Ports & Adapters)
Comunicação	Google Cloud Pub/Sub (modelo canônico de eventos)
Banco	PostgreSQL 16 (schema cerbero para escrita; public/supplier read-only)
HTTP	chi/v5 · DB: sqlx + pgx/lib/pq
Observabilidade	OpenTelemetry + Prometheus + slog estruturado · Sentry
Infra	Docker, Kubernetes (Helm), monorepo via go.work
Frontend	Next.js 16 (App Router) · Auth.js · Tailwind v4

Mapa de serviços

Serviço	Pilar	Papel	Estado
ml-webhook-adapter	Vendas	Webhooks Mercado Livre → eventos canônicos	✅ referência
shopify-webhook-adapter	Vendas	Webhooks Shopify/Yampi → eventos canônicos	✅ concluído
order-processor	Vendas	Consome OrderEvent → persiste → downstream de compras	✅ concluído
purchase-recommendation	Compras	Recomendação de compra (REST + Pub/Sub)	✅ concluído
purchase-closing	Compras	Fecha pedidos de compra, export CSV, feriados/D+1	✅ concluído
supplier-invoice-receiving	NF/Log.	Recebimento de NF de entrada → conferência → Omie	✅ concluído
wms-service	NF/Log.	Estoque/alocação, surplus, espelho Omie	✅ concluído
access-service	Transversal	Roles & permissions do console de compras	✅ concluído
compras-web	Frontend	Console operacional das 5 etapas (Next.js)	🖥️ console
service-boilerplate	—	Ponto de partida para novos serviços	📦 template

Por onde começar

Arquitetura hexagonal →O padrão Ports & Adapters que todo serviço segue.Eventos canônicos →O contrato central: envelope, tópicos e IDs determinísticos.Chaves de ligação →Os IDs que ligam vendas, compras e conferência.Banco de dados →Schema cerbero, tabelas e fluxo de persistência.Serviço de referência →Estude o ml-webhook-adapter, o golden standard.Checklist obrigatório →O que todo serviço precisa cumprir antes de ficar pronto.

Migração v1 → v2

O ciclo completo de Compras (recomendação → fechamento → export → envio ao fornecedor) e o Recebimento de NF de entrada já estão migrados do legado operacoes/compras (Node/TS) para o Cerbero. Veja o mapa de substituição em Migração v1 → v2.