graph-go es un mapeador de infraestructura orientado a CLI. Descubre automáticamente tu infraestructura conectándose al demonio de Docker, inspeccionando contenedores en ejecución y sondando bases de datos y servicios de almacenamiento. La interfaz de usuario es servida por el backend y refleja el estado real del backend — no se necesita inventario manual.

Etiquetas Docker

graph-go respeta un conjunto pequeño de etiquetas de contenedor graphgo.* (configúralas en cualquier contenedor que desees controlar):

Úsalas para rescatar contenedores mal clasificados, apuntar graph-go a un DSN personalizado, u ocultar un contenedor del grafo sin eliminarlo.

Inicio rápido — pruébalo en 30 segundos

Inicia el stack de demostración precargado con la CLI. Esta es la forma más rápida de ver graph-go en un entorno realista y la ruta de incorporación prevista para nuevos usuarios:

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

Abre http://localhost:8080. El comando se ejecuta adjunto mediante Docker Compose. Presiona Ctrl+C para detener la sesión adjunta.

La primera ejecución puede tardar varios minutos en una máquina fría porque Docker puede necesitar descargar imágenes base y construir las imágenes locales de demostración. Las ejecuciones posteriores son mucho más rápidas.

El stack de demostración espera que estos puertos del host estén libres: 8080, 5432, 27017, 9000 y 9001.

Si necesitas una limpieza explícita después:

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

Ejecutar contra tu propio stack

Un contenedor, un puerto. Monta el socket de Docker en modo solo lectura y graph-go descubre automáticamente todo lo que se ejecuta en el host:

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

graph-go solo lee del socket de Docker. La bandera :ro lo impone — mantenla.

Abre http://localhost:8080. El auto-descubrimiento maneja los contenedores Docker y (cuando hay un kubeconfig o una cuenta de servicio dentro del clúster) los recursos de Kubernetes sin necesidad de archivo de configuración.

Para servicios que viven fuera de Docker/Kubernetes (bases de datos remotas, servicios gestionados en la nube), monta un archivo de configuración — consulta Configuración.

Binario precompilado

Binario único autocontenido — la interfaz de usuario está incrustada, pero el punto de entrada sigue siendo la CLI.

# Linux amd64 (requiere GitHub CLI; consulta Releases para otras 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   # o simplemente `./graph-go` — es lo mismo

Abre http://localhost:8080. Otras plataformas en la página de Releases.

Comandos

Banderas globales (aplican a todos los subcomandos): --config, --log-level, --log-format. Consulta graph-go <comando> --help para la superficie completa por comando.

Flujo típico:

1. graph-go demo para un recorrido local realista.
2. graph-go serve para ejecutar contra tu propia infraestructura.
3. graph-go scan para automatización puntual, exportaciones o comprobaciones CI.

Puertos

Configuración

El auto-descubrimiento es el camino. Monta el socket de Docker y/o ejecuta dentro de un clúster de Kubernetes — graph-go descubre tu infraestructura sin necesidad de archivo de configuración.

Usa la configuración YAML (conf/config.yaml) solo como una vía de escape para servicios que no son alcanzables mediante descubrimiento — bases de datos remotas, servicios gestionados en la nube, endpoints externos. Consulta conf/config.sample.yaml para el esquema completo — ejemplos para cada adaptador y cada bloque de configuración (server, docker, kubernetes, connections).

Para usar un archivo de configuración con el Docker run anterior:

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 únicamente: graph-go es para visualizar infraestructura que posees o para la que tienes permiso de acceso. No lo apuntes a sistemas sin autorización.

Resumen de la Arquitectura

Backend (Go)

                          ┌─────────────────────────────────────┐
                          │         Interfaz Discoverer         │
                          │  Discover() · Watch() · Close()     │
                          └──────────┬──────────┬───────────────┘
                                     │          │
                          ┌──────────▼──┐  ┌────▼──────────────┐
                          │   Docker    │  │   Kubernetes       │
                          │  Discoverer │  │   Discoverer       │
                          │ (contened., │  │ (informers, pods,  │
                          │  clasificar,│  │  deployments,      │
                          │  eventos)   │  │  servicios, salud) │
                          └──────┬──────┘  └────┬──────────────┘
                                 │               │
                          ┌──────▼───────────────▼──────┐
                          │  Descubrimiento Paralelo +  │
                          │  Fusión (concatena ServiceInfo)  │
                          └──────────────┬──────────────┘
                                         │
Config (YAML) ──→ Fusión YAML ─────────▶│
                                         ▼
                          ┌─────────────────────────────┐
                          │     Registro de Adaptadores  │
                          │  ├─ PostgreSQL  → Tablas + FK│
                          │  ├─ MongoDB    → Colecciones │
                          │  ├─ MySQL      → Tablas + FK │
                          │  ├─ Redis      → Keyspaces   │
                          │  ├─ Elasticsearch → Índices   │
                          │  ├─ S3         → Buckets      │
                          │  └─ HTTP       → Salud + dep. │
                          │                               │
                          │  + Topología (nodos/aristas K8s) │
                          └──────────────┬───────────────┘
                                         ▼
                          Modelo de Grafo (Nodos + Aristas)
                                         ▼
                          API REST + WebSocket (Tiempo real)

Componentes clave:

• Interfaz Discoverer: Contrato uniforme (Discover, Watch, Close) para todos los backends de descubrimiento — Docker y Kubernetes se ejecutan en paralelo, los resultados se concatenan
• Descubrimiento Docker: Inspecciona contenedores, clasifica imágenes, extrae credenciales de variables de entorno, observa eventos de Docker para cambios de topología en vivo
• Descubrimiento Kubernetes: Usa informers de client-go con manejo de eventos debounced; descubre Namespaces, Deployments, StatefulSets, DaemonSets, Pods y Services con mapeo de salud
• Adaptadores: Implementan la interfaz Adapter para sondear bases de datos y servicios de almacenamiento
• Registro: Gestiona adaptadores y conjuntos de topología, crea nodos padre a nivel de servicio, agrega datos del grafo
• Caché: TTL de 30 segundos con patrón singleflight para evitar avalancha de peticiones
• WebSocket: Transmite actualizaciones de salud cada 5 segundos

Frontend (React + TypeScript)

• Disposición en carriles: Disposición consciente de namespaces con clasificación de zona (namespaces de sistema, infra, aplicación)
• Contenedores de grupo: Los namespaces de K8s se renderizan como cajas delimitadoras colapsables mediante agrupación de React Flow
• Inspector de nodos: Panel lateral que muestra metadatos detallados y conexiones
• Hook WebSocket: Actualizaciones de salud en tiempo real sin sondeo

Jerarquía de Nodos

Descubiertos por adaptador:
  Nodo de Servicio (postgres/mongodb/s3)
      └─ Nodo de Base de Datos/Bucket
          └─ Nodo de Tabla/Colección/Prefijo

Descubiertos por Kubernetes:
  Namespace (contenedor de grupo)
      └─ Deployment / StatefulSet / DaemonSet
          └─ Pod
      └─ K8sService ──rutas_a──→ Pod

Las aristas representan relaciones (contains, foreign_key, routes_to, etc.).

Stack Tecnológico

Backend:

• Go 1.25.6
• gorilla/mux (enrutamiento HTTP)
• k8s.io/client-go (descubrimiento + informers de Kubernetes)
• 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 (pruebas de integración)

Frontend:

• TypeScript
• React 19
• @xyflow/react v12 (visualización de grafos)
• Vite (herramienta de compilación)

Infraestructura:

• Docker + Docker Compose
• PostgreSQL 17
• MongoDB 7
• MySQL 8
• Redis 7
• Elasticsearch 8
• MinIO (compatible con S3)

Pruebas

Pruebas Unitarias

go test ./...

Se ejecutan sin Docker. Incluye pruebas de funciones puras y pruebas de manejadores HTTP.

Pruebas de Integración

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

Requiere Docker. Usa testcontainers-go para levantar instancias reales de bases de datos (PostgreSQL, MongoDB, MySQL, Redis, Elasticsearch, MinIO) — sin mocks.

Cada adaptador ejecuta la suite de pruebas de contrato (adaptertest.RunContractTests) que valida:

• Ciclo de vida de conexión/desconexión
• Descubrimiento de nodos/aristas (IDs únicos, referencias padre válidas, tipos correctos)
• Métricas de salud (clave de estado, claves requeridas)

Ejecutar las pruebas de un solo adaptador:

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

Todas las Pruebas

make test  # unitarias + verificación de tipos
go test -tags=integration -timeout=5m ./internal/adapters/...  # integración

Referencia de la API

GET /api/graph

Devuelve el grafo completo de la infraestructura (nodos + aristas).

Respuesta:

{
  "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}

Devuelve los detalles de un nodo específico.

GET /api/health

Devuelve el estado de salud del adaptador (ok/degraded/error).

WS /websocket

Transmite actualizaciones en tiempo real. Se emiten dos tipos de mensaje, ambos envueltos como { "type": "...", "payload": { ... } }. No hay campo timestamp — los clientes infieren el orden por la llegada.

health_update — enviado para cada nodo una vez por barrido (cada 5s). Los nodos propiedad del adaptador obtienen salud mediante la búsqueda del adaptador; los nodos de topología (ej. recursos Kubernetes) llevan la salud directamente en el nodo.

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

health es uno de healthy, degraded, unhealthy.

graph_update — se envía cuando cambia el conjunto de IDs de nodos (se añadió o eliminó un nodo por descubrimiento). payload está vacío; los clientes deben volver a obtener /api/graph.

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

Añadir un Nuevo Adaptador

1. Crear paquete del adaptador en internal/adapters/{nombre}/
2. Implementar la interfaz Adapter:
   root@kitploit:~

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

3. Auto-registrarse mediante init() con adapters.RegisterFactory("nombre", ...)
4. Agregar pruebas de integración (obligatorio) — crear {nombre}_integration_test.go con:
   • Etiqueta de compilación //go:build integration
   • TestMain usando testcontainers-go para iniciar una instancia real
   • Sembrar datos representativos
   • Llamar a adaptertest.RunContractTests para validar el contrato de la interfaz
   • Agregar pruebas específicas del adaptador (filtrado, formato de ID, metadatos, etc.)
5. Importar el adaptador en internal/server/server.go (importación en blanco para )

Añadir un Nuevo Discoverer

Los Discoverers viven en internal/discovery/{nombre}/ e implementan la interfaz Discoverer:

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

1. Crear paquete del discoverer en internal/discovery/{nombre}/
2. Implementar la interfaz Discoverer — devolver []ServiceInfo desde Discover(). Los discoverers que producen topología (como K8s) llenan Nodes/Edges directamente; los orientados a adaptadores (como Docker) llenan Config para el puente de adaptadores.
3. Integrar en el servidor en internal/server/server.go — agregar una función build{Name}Discovery() y llamarla junto con los discoverers existentes.
4. Agregar pruebas de integración con //go:build integration — usar infraestructura real (kind/k3d para K8s, testcontainers para otros). Sin mocks.

Consulta CONTRIBUTING.md para una guía detallada.

Contribuciones

¡Aceptamos contribuciones! Consulta CONTRIBUTING.md para pautas sobre:

• Configuración del desarrollo
• Convenciones de estilo de código
• Cómo añadir nuevos adaptadores
• Envío de pull requests

Alcance de Uso y Ética

Uso previsto:

• Visualizar y monitorear infraestructura que posees o para la que tienes autorización de acceso
• Paneles de DevOps y mapeo de topología
• Documentación de infraestructura e incorporación
• Exploración de esquemas de bases de datos y relaciones

No previsto para:

• Escaneo o reconocimiento no autorizado de sistemas
• Pruebas de seguridad sin permiso explícito
• Acceder a sistemas que no posees o controlas

Los usuarios son responsables de asegurarse de tener la autorización adecuada antes de conectar graph-go a cualquier infraestructura.

Licencia

Este proyecto está licenciado bajo la GNU Affero General Public License v3.0 (AGPL-3.0).

Consulta el archivo LICENSE para más detalles. AGPL requiere que las versiones modificadas utilizadas a través de una red también se publiquen como código abierto.

CI/CD y Lanzamientos

El proyecto usa GitHub Actions para integración continua y lanzamientos automatizados.

• CI se ejecuta en cada push/PR a main — pruebas unitarias del backend, pruebas de integración (testcontainers) y compilación del frontend
• Releases se activan mediante etiquetas de versión (v*) y producen:
  • Binarios multiplataforma (Linux, macOS, Windows) mediante GoReleaser
  • Imagen Docker única enviada a ghcr.io/guilherme-grimm/graph-go

Para crear un release:

git tag v0.1.0
git push --tags

Hoja de Ruta

• Auto-descubrimiento Docker
• Monitoreo de salud de servicios HTTP
• Adaptador MySQL
• Adaptador Redis
• Adaptador Elasticsearch
• Pruebas de integración con testcontainers-go (todos los adaptadores)
• Suite de pruebas de contrato para cumplimiento de interfaz de adaptador
• Interfaz Discoverer (backends de descubrimiento conectables)
• Orquestador Kubernetes (Namespaces, Deployments, StatefulSets, DaemonSets, Pods, Services)
• Monitorización en tiempo real de K8s basada en informers con debounce
• Disposición en carriles con contenedores de grupo por namespace
• Puente de adaptadores K8s (clasificar pods por imagen, conectar adaptadores a bases de datos en pods)
• Observabilidad de flujo (visualización de flujo de datos en tiempo real)
• Disparador de estrés integrado (k6 con visualización de impacto en tiempo real)

Soporte

• Issues: github.com/guilherme-grimm/graph-go/issues
• Discussions: github.com/guilherme-grimm/graph-go/discussions

Construido con ❤️ para ingenieros de DevOps e infraestructura