graph-go é um mapeador de infraestrutura focado em CLI. Ele descobre automaticamente sua infraestrutura conectando-se ao daemon Docker, inspecionando contêineres em execução e sondando bancos de dados e serviços de armazenamento. A interface é servida pelo backend e reflete o estado real do backend — sem necessidade de inventário manual.

Labels Docker

O graph-go respeita um conjunto pequeno de labels de contêiner graphgo.* (defina-as em qualquer contêiner que deseja controlar):

Use estas para resgatar contêineres mal classificados, apontar o graph-go para um DSN personalizado ou ocultar um contêiner do grafo sem removê-lo.

Início Rápido — experimente em 30 segundos

Inicie o stack de demonstração com dados de exemplo usando a CLI. Esta é a maneira mais rápida de ver o graph-go em um ambiente realista e o caminho de integração recomendado para novos usuários:

git clone https://github.com/guilherme-grimm/graph-go.git
cd graph-go
go run ./cmd/app demo

Abra http://localhost:8080. O comando é executado anexado via Docker Compose. Pressione Ctrl+C para parar a sessão anexada.

A primeira execução pode levar vários minutos em uma máquina fria porque o Docker pode precisar baixar imagens base e construir as imagens de demonstração locais. Execuções posteriores são muito mais rápidas.

O stack de demonstração espera que as seguintes portas do host estejam livres: 8080, 5432, 27017, 9000 e 9001.

Se precisar de uma desmontagem explícita após:

docker compose -f docker-compose.demo.yml down

Execute contra seu próprio stack

Um contêiner, uma porta. Monte o socket do Docker como somente leitura e o graph-go descobre automaticamente tudo que está rodando no host:

docker run -d -p 8080:8080 \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  ghcr.io/guilherme-grimm/graph-go:latest

O graph-go apenas lê do socket Docker. A flag :ro impõe isso — mantenha-a.

Abra http://localhost:8080. A descoberta automática lida com contêineres Docker e (quando um kubeconfig ou conta de serviço in-cluster está presente) recursos Kubernetes sem qualquer arquivo de configuração.

Para serviços que estão fora do Docker/Kubernetes (bancos de dados remotos, serviços gerenciados em nuvem), monte um arquivo de configuração — veja Configuração.

Binário pré-compilado

Binário único auto-contido — a interface está embutida, mas o ponto de entrada ainda é a CLI.

# Linux amd64 (requer a CLI do GitHub; veja Releases para outras plataformas)
gh release download --repo guilherme-grimm/graph-go --pattern 'graph-go_*_linux_amd64.tar.gz' --clobber
tar xzf graph-go_*_linux_amd64.tar.gz
./graph-go serve   # ou apenas `./graph-go` - mesma coisa

Abra http://localhost:8080. Outras plataformas na página de Releases.

Comandos

Flags globais (aplicam-se a todos os subcomandos): --config, --log-level, --log-format. Veja graph-go <comando> --help para a superfície completa de cada comando.

Fluxo típico:

1. graph-go demo para um passo-a-passo realista local.
2. graph-go serve para executar contra sua própria infraestrutura.
3. graph-go scan para automação pontual, exportações ou verificações em CI.

Portas

Configuração

A descoberta automática é o caminho. Monte o socket Docker e/ou execute dentro de um cluster Kubernetes — o graph-go descobre sua infraestrutura sem necessidade de arquivo de configuração.

Use a configuração YAML (conf/config.yaml) apenas como uma saída de emergência para serviços que não são alcançáveis via descoberta — bancos de dados remotos, serviços gerenciados em nuvem, endpoints externos. Veja conf/config.sample.yaml para o esquema completo — exemplos para cada adaptador e cada bloco de configuração (server, docker, kubernetes, connections).

Para usar um arquivo de configuração com o comando Docker acima:

docker run -d -p 8080:8080 \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v $(pwd)/conf/config.yaml:/app/conf/config.yaml:ro \
  ghcr.io/guilherme-grimm/graph-go:latest

Uso autorizado apenas: o graph-go é para visualizar infraestrutura que você possui ou tem permissão para acessar. Não o aponte para sistemas sem autorização.

Visão Geral da Arquitetura

Backend (Go)

                          ┌─────────────────────────────────────┐
                          │         Interface Discoverer         │
                          │  Discover() · Watch() · Close()     │
                          └──────────┬──────────┬───────────────┘
                                     │          │
                          ┌──────────▼──┐  ┌────▼──────────────┐
                          │   Docker    │  │   Kubernetes       │
                          │  Discoverer │  │   Discoverer       │
                          │ (contêineres,│  │ (informers, pods,  │
                          │  classificar,│  │  deployments,      │
                          │  eventos)   │  │  serviços, saúde) │
                          └──────┬──────┘  └────┬──────────────┘
                                 │               │
                          ┌──────▼───────────────▼──────┐
                          │  Descoberta Paralela + Merge │
                          │  (concatena ServiceInfo)     │
                          └──────────────┬──────────────┘
                                         │
Config (YAML) ──→ Merge YAML ──────────▶│
                                         ▼
                          ┌─────────────────────────────┐
                          │     Registro de Adaptadores  │
                          │  ├─ PostgreSQL  → Tabelas + FK│
                          │  ├─ MongoDB    → Coleções    │
                          │  ├─ MySQL      → Tabelas + FK│
                          │  ├─ Redis      → Keyspaces   │
                          │  ├─ Elasticsearch → Índices   │
                          │  ├─ S3         → Buckets      │
                          │  └─ HTTP       → Saúde + deps │
                          │                               │
                          │  + Topologia (nós/arestas K8s) │
                          └──────────────┬───────────────┘
                                         ▼
                          Modelo de Grafo (Nós + Arestas)
                                         ▼
                          API REST + WebSocket (Tempo real)

Componentes Chave:

• Interface Discoverer: Contrato uniforme (Discover, Watch, Close) para todos os backends de descoberta — Docker e Kubernetes executam em paralelo, resultados são concatenados
• Descoberta Docker: Inspeciona contêineres, classifica imagens, extrai credenciais de variáveis de ambiente, observa eventos Docker para mudanças de topologia ao vivo
• Descoberta Kubernetes: Usa informers do client-go com tratamento de eventos com debounce; descobre Namespaces, Deployments, StatefulSets, DaemonSets, Pods e Services com mapeamento de saúde
• Adaptadores: Implementam a interface Adapter para sondar bancos de dados e serviços de armazenamento
• Registro: Gerencia adaptadores e conjuntos de topologia, cria nós pai de nível de serviço, agrega dados do grafo
• Cache: TTL de 30 segundos com padrão singleflight para evitar sobrecarga
• WebSocket: Transmite atualizações de saúde a cada 5 segundos

Frontend (React + TypeScript)

• Layout de Raias (Swimlane): Layout com conhecimento de namespace e classificação de zonas (namespaces de sistema, infraestrutura, aplicação)
• Contêineres de Grupo: Namespaces K8s renderizados como caixas colapsáveis via agrupamento do React Flow
• Inspector de Nó: Painel lateral com metadados detalhados e conexões
• Hook WebSocket: Atualizações de saúde em tempo real sem polling

Hierarquia de Nós

Descoberta por adaptador:
  Nó de Serviço (postgres/mongodb/s3)
      └─ Nó de Banco de Dados/Bucket
          └─ Nó de Tabela/Coleção/Prefixo

Descoberta por Kubernetes:
  Namespace (contêiner de grupo)
      └─ Deployment / StatefulSet / DaemonSet
          └─ Pod
      └─ K8sService ──rotas_para──→ Pod

Arestas representam relacionamentos (contém, chave_estrangeira, rotas_para, etc.).

Stack Tecnológico

Backend:

• Go 1.25.6
• gorilla/mux (roteamento HTTP)
• k8s.io/client-go (descoberta Kubernetes + informers)
• pgxpool (PostgreSQL)
• mongo-driver v2 (MongoDB)
• go-sql-driver/mysql (MySQL)
• go-redis/v9 (Redis)
• go-elasticsearch/v8 (Elasticsearch)
• AWS SDK v2 (S3)
• coder/websocket (WebSocket)
• testcontainers-go (testes de integração)

Frontend:

• TypeScript
• React 19
• @xyflow/react v12 (visualização de grafos)
• Vite (ferramenta de build)

Infraestrutura:

• Docker + Docker Compose
• PostgreSQL 17
• MongoDB 7
• MySQL 8
• Redis 7
• Elasticsearch 8
• MinIO (compatível com S3)

Testes

Testes Unitários

go test ./...

Executa sem Docker. Inclui testes de funções puras e testes de handlers HTTP.

Testes de Integração

go test -tags=integration -v -timeout=5m ./internal/adapters/...

Requer Docker. Usa testcontainers-go para iniciar instâncias reais de bancos de dados (PostgreSQL, MongoDB, MySQL, Redis, Elasticsearch, MinIO) — sem mocks.

Cada adaptador passa pela suíte de teste de contrato (adaptertest.RunContractTests) que valida:

• Ciclo de vida connect/disconnect
• Descoberta de nós/arestas (IDs únicos, referências pai válidas, tipos corretos)
• Métricas de saúde (chave de status, chaves obrigatórias)

Execute testes de um único adaptador:

go test -tags=integration -v ./internal/adapters/redis/

Todos os Testes

make test  # unitários + verificação de tipos
go test -tags=integration -timeout=5m ./internal/adapters/...  # integração

Referência da API

GET /api/graph

Retorna o grafo completo da infraestrutura (nós + arestas).

Resposta:

{
  "data": {
    "nodes": [
      {
        "id": "service-postgres",
        "type": "postgres",
        "name": "postgres",
        "metadata": { "adapter": "postgres" },
        "health": "healthy"
      }
    ],
    "edges": [
      {
        "id": "edge-1",
        "source": "service-postgres",
        "target": "pg-mydb",
        "type": "contains",
        "label": "contains"
      }
    ]
  }
}

GET /api/node/{id}

Retorna detalhes de um nó específico.

GET /api/health

Retorna o status de saúde dos adaptadores (ok/degraded/error).

WS /websocket

Transmite atualizações em tempo real. Dois tipos de mensagem são emitidos, ambos encapsulados como { "type": "...", "payload": { ... } }. Não há campo timestamp — os clientes inferem a ordenação pelo momento de chegada.

health_update — enviado para cada nó uma vez por varredura (a cada 5s). Nós gerenciados por adaptadores obtêm saúde via consulta ao adaptador; nós de topologia (ex.: recursos Kubernetes) carregam saúde diretamente no nó.

{
  "type": "health_update",
  "payload": {
    "nodeId": "service-postgres",
    "health": "healthy"
  }
}

health é um dos valores: healthy, degraded, unhealthy.

graph_update — enviado quando o conjunto de IDs de nós muda (um nó foi adicionado ou removido pela descoberta). payload está vazio; os clientes devem buscar novamente /api/graph.

{
  "type": "graph_update",
  "payload": {}
}

Adicionando um Novo Adaptador

1. Crie o pacote do adaptador em internal/adapters/{nome}/
2. Implemente a interface Adapter:
   root@kitploit:~

   type Adapter interface {
       Connect(config ConnectionConfig) error
       Discover() ([]nodes.Node, []edges.Edge, error)
       Health() (HealthMetrics, error)
       Close() error
   }
   

3. Auto-registre-se via init() com adapters.RegisterFactory("nome", ...)
4. Adicione testes de integração (obrigatório) — crie {nome}_integration_test.go com:
   • Build tag //go:build integration
   • TestMain usando testcontainers-go para iniciar uma instância real
   • Popule dados representativos
   • Chame adaptertest.RunContractTests para validar o contrato da interface
   • Adicione testes específicos do adaptador (filtragem, formato de ID, metadados, etc.)
5. Importe o adaptador em internal/server/server.go (importação em branco para )

Adicionando um Novo Discoverer

Discoverers ficam em internal/discovery/{nome}/ e implementam a interface Discoverer:

type Discoverer interface {
    Name() string
    Discover(ctx context.Context) ([]ServiceInfo, error)
    Watch(ctx context.Context, onChange func()) error
    Close() error
}

1. Crie o pacote do discoverer em internal/discovery/{nome}/
2. Implemente a interface Discoverer — retorne []ServiceInfo de Discover(). Discoverers que produzem topologia (como K8s) preenchem Nodes/Edges diretamente; os orientados a adaptadores (como Docker) preenchem Config para ponte com adaptadores.
3. Conecte no servidor em internal/server/server.go — adicione uma função build{Nome}Discovery() e chame-a junto com os discoverers existentes.
4. Adicione testes de integração com //go:build integration — use infraestrutura real (kind/k3d para K8s, testcontainers para outros). Sem mocks.

Veja CONTRIBUTING.md para orientações detalhadas.

Contribuindo

Aceitamos contribuições! Veja CONTRIBUTING.md para diretrizes sobre:

• Configuração do ambiente de desenvolvimento
• Convenções de estilo de código
• Como adicionar novos adaptadores
• Envio de pull requests

Escopo de Uso e Ética

Uso Pretendido:

• Visualizar e monitorar infraestrutura que você possui ou tem autorização para acessar
• Painéis de DevOps e mapeamento de topologia
• Documentação e integração de infraestrutura
• Explorar esquemas de banco de dados e relacionamentos

Não Pretendido Para:

• Varredura ou reconhecimento não autorizado de sistemas
• Testes de segurança sem permissão explícita
• Acessar sistemas que você não possui ou controla

Os usuários são responsáveis por garantir que possuem a devida autorização antes de conectar o graph-go a qualquer infraestrutura.

Licença

Este projeto está licenciado sob a GNU Affero General Public License v3.0 (AGPL-3.0).

Veja o arquivo LICENSE para detalhes. AGPL exige que versões modificadas usadas em rede também sejam de código aberto.

CI/CD & Releases

O projeto usa GitHub Actions para integração contínua e lançamentos automatizados.

• CI executa em cada push/PR para main — testes unitários do backend, testes de integração (testcontainers) e build do frontend
• Releases são acionadas por tags de versão (v*) e produzem:
  • Binários multiplataforma (Linux, macOS, Windows) via GoReleaser
  • Imagem Docker única enviada para ghcr.io/guilherme-grimm/graph-go

Para criar um release:

git tag v0.1.0
git push --tags

Roadmap

• Descoberta automática Docker
• Monitoramento de saúde de serviços HTTP
• Adaptador MySQL
• Adaptador Redis
• Adaptador Elasticsearch
• Testes de integração com testcontainers-go (todos os adaptadores)
• Suíte de teste de contrato para conformidade da interface do adaptador
• Interface Discoverer (backends de descoberta plugáveis)
• Orquestrador Kubernetes (Namespaces, Deployments, StatefulSets, DaemonSets, Pods, Services)
• Monitoramento K8s em tempo real baseado em informer com debounce
• Layout de raias com contêineres de grupo por namespace
• Ponte de adaptador K8s (classificar pods por imagem, conectar adaptadores a bancos de dados nos pods)
• Observabilidade de fluxo (visualização de fluxo de dados em tempo real)
• Gatilho de estresse integrado (k6 com visualização de impacto em tempo real)

Suporte

• Issues: github.com/guilherme-grimm/graph-go/issues
• Discussões: github.com/guilherme-grimm/graph-go/discussions

Feito com ❤️ para engenheiros de DevOps e infraestrutura