dgv

Treinta segundos

git clone https://github.com/ShAInyXYZ/Dia-GramV.git && cd Dia-GramV
npm install && npm run build
node packages/mcp/bin/dgv.mjs doctor                        # checks Node + the build, prints the lines below with your path
claude mcp add dgv -s user -- node "$PWD/packages/mcp/bin/dgv.mjs" mcp
ln -s "$PWD/skill" ~/.claude/skills/dgv                     # optional: teaches the agent the workflow

Luego, en cualquier proyecto, dile al agente:

Traza este sistema en DGV antes de empezar.

Lee el catálogo, escribe dgv/<name>.dgv.json, recibe un informe de lint en cada escritura, repara lo que rompió, maqueta el diagrama y lo abre en http://127.0.0.1:7710. A partir de entonces, el archivo es el mapa: cada sesión posterior lo lee antes de leer código.

Requiere Node 20.19+ o 22.12+. npm install lo descarga todo (~100 MB, nada global); npm run build compila el visor una vez. Omite la compilación si solo quieres las herramientas MCP: todo funciona sin ella excepto dgv_open.

Related MCP server: mermaid-mcp-server

Qué es

Un solo archivo. dgv/<name>.dgv.json contiene marcos (límites), nodos (componentes) y aristas (conexiones). Cada nodo tiene un kind de un catálogo fijo — ui, service, api, db, queue, bridge, external… — y puede declarar ports. Cada arista nombra el puerto en el que aterriza y el protocolo que habla. JSON plano, en tu repositorio, junto al código que describe.

Dos vías de entrada. El servidor MCP es el del agente: crea, cambia y lee el archivo, y en cada escritura recibe un informe de lint — un código estable, el elemento y correcciones concretas. El visor es tuyo: un lienzo de Svelte Flow donde los kinds tienen formas y los cables llevan su protocolo, con un inspector para cada campo y el mismo lint en vivo en un panel lateral. Cuando el agente cambia el archivo, la página se recarga.

Por qué importa cuando una IA escribe el código

El dibujo es la parte menos importante. Lo que importa es que el modelo del sistema sea un archivo que un programa pueda leer, comprobar y cambiar.

Si vibecodeas, el sistema crece más rápido de lo que puedes retener en tu cabeza, y la forma que crees que tiene se desvía de la forma que tiene. DGV le da a esa forma un lugar donde vivir, y un linter que protesta cuando deja de tener sentido.

Si desarrollas con una IA a tu lado, el diagrama es donde expresas intenciones que el código aún no puede expresar — el worker consume la cola; la API nunca escribe directamente en el bucket — una vez, en una forma que toda sesión posterior hereda.

Si eres el agente, esta es la diferencia entre hacer grep y saber. En un repositorio desconocido reconstruyes la imagen abriendo archivos. dgv_read te entrega la imagen. Su salida completa para la aplicación de notas de abajo, textualmente:

# Notes app
frames 3 · nodes 6 · edges 5 · updated 2026-08-27

## frame browser: Browser
- web [ui] Notes UI — SvelteKit
## frame server: Server · one process
- api [api] HTTP API — /api/notes ports: rest:http/in
- jobs [worker] Job runner — thumbnails, exports
## frame data: Data
- pg [db] Postgres — notes, users ports: sql:sql/in
- redis [queue] Job queue — Redis lists ports: jobs:redis/in
- s3 [storage] Object store — uploads ports: put:s3/in

## edges
- web-api: web → api [sync http] fetch ports ·→rest
- api-pg: api → pg [data sql] ports ·→sql
- api-redis: api → redis [async redis] enqueue ports ·→jobs
- jobs-redis: jobs → redis [async redis] consume ports ·→jobs
- jobs-s3: jobs → s3 [data s3] ports ·→put

Un agente que puede leer api → pg [data sql] ·→sql no inventa un endpoint REST sobre la base de datos. Doscientos tokens sustituyen un recorrido por el árbol.

Qué hace — cuatro casos

1 · Planifica antes de construir, y entérate cuando el plan no puede funcionar

El agente describe una pequeña aplicación de notas en un solo dgv_apply. Contiene dos errores comunes: el puerto del almacén de objetos se llama put en el nodo y upload en la arista, y una base de datos está llamando de vuelta a la API.

dgv_apply({ name: "notes-app",
  nodes: [ { id: "s3", kind: "storage", label: "Object store", frame: "data",
             ports: [ { id: "put", protocol: "s3", dir: "in" } ] }, … ],
  edges: [ { id: "jobs-s3", source: "jobs", target: "s3", kind: "data", protocol: "s3", targetPort: "upload" },
           { id: "pg-api",  source: "pg",   target: "api", kind: "sync", protocol: "http", label: "notify on change" }, … ] })

La escritura se realiza y el informe vuelve en el mismo turno:

{ "ok": false, "lint": { "error": 1, "warning": 2, "info": 0 },
  "diagnostics": [
    { "code": "port/undeclared", "severity": "error",
      "message": "edge \"jobs-s3\" uses target port \"upload\" but node \"s3\" does not declare it",
      "subject": { "type": "edge", "id": "jobs-s3", "field": "targetPort" },
      "fixes": [ "add port {id:\"upload\"} to node \"s3\"", "point the edge at one of: put" ] },
    { "code": "kind/store-initiates", "severity": "warning",
      "message": "\"pg\" is a db; stores do not initiate sync calls to \"api\"",
      "subject": { "type": "edge", "id": "pg-api" },
      "fixes": [ "reverse the edge and mark it kind:\"data\"",
                 "if it is a trigger/CDC stream, add a worker or queue between them" ] }, … ] }

El mismo informe en el visor: el cable que falla está en rojo, y cada entrada salta a su elemento:

El primer error es una errata que se habría convertido en un bug. El segundo es una arquitectura que un agente habría implementado sin pensárselo dos veces. Ambos vuelven como un id, un código y una corrección, de modo que el plan se repara antes de que exista código alguno:

dgv_apply({ name: "notes-app",
            edges: [ { id: "jobs-s3", targetPort: "put" } ],       // partial: id + the field that changes
            remove: { edges: [ "pg-api" ] } })
→ { "ok": true, "lint": { "error": 0, "warning": 0, "info": 0 } }

2 · Traza un sistema que ya tienes

Señala al agente un repositorio — traza la arquitectura de Cerveau en DGV, desde el código — y lee puntos de entrada, listeners, clientes y configuración, y luego escribe lo que encontró. El harness local de IA de abajo son 13 componentes en cuatro límites: un panel y un teléfono que conducen un núcleo Go, un servidor llama.cpp, Typesense para la memoria, un sidecar de embeddings en Python.

A tamaño completo — el propio Cerveau, 35 componentes en 7 límites, cada llamada vinculada a un puerto declarado:

Pulsa S y cada marco se pliega en un solo nodo, con los cables que lo cruzaban fusionados en un único enlace etiquetado. El mismo archivo; no hay un segundo diagrama general que mantener sincronizado con el primero:

3 · Sigue el desarrollo en el mismo diagrama

Un nodo puede llevar un status — todo wip done blocked failed update. Pulsa 2 y el lienzo se colorea por estado en lugar de por tipo; el archivo es ahora el tablero de desarrollo. Un agente retoma donde se quedó la última sesión leyendo lo que sigue en todo, y una note en un nodo bloqueado dice por qué:

4 · Saber cuándo deja de ser cierto

El lint dice que el plan es coherente. No puede decir que el plan sea cierto — que el código en disco siga siendo el código que describe el diagrama. Dale a un nodo un path (un archivo, un directorio, un glob, una lista) y dgv_drift recorre el proyecto — git ls-files, de modo que se respeta .gitignore — e informa de un path que no coincide con nada (drift/missing), un directorio de código que no pertenece a ningún nodo (drift/unclaimed), y dos nodos que reclaman el mismo archivo (drift/shared).

Este repositorio mantiene así su propia arquitectura, cada nodo con un path:

La primera vez que drift se ejecutó sobre él, encontró algo:

$ node packages/mcp/bin/dgv.mjs drift dia-gramv
warning drift/unclaimed  packages/mcp/ — 1 of 5 files belong to no node
        fix: add a node with this path | widen an existing node's path to cover it | add it to meta.driftIgnore if it is not part of the system

packages/mcp/package.json, reclamado por nadie, porque el path del nodo MCP era un solo archivo. Se amplió, y quedó limpio.

Dos hooks opcionales de Claude Code cierran el ciclo (hooks/; doctor imprime el bloque de configuración con tu ruta):

• SessionStart imprime en el contexto el esquema de cada diagrama en ./dgv, con su resumen de drift — lo primero que sabe el agente es la forma del sistema y si el mapa está desactualizado.

• Stop ejecuta drift después de cada turno y, solo cuando hay algo que decir, deja una línea: DGV · app: 1 node path no longer exists (old). Nunca bloquea.

El visor

node packages/mcp/bin/dgv.mjs serve → http://127.0.0.1:7710 — o dgv_open desde el agente.

Arrastra un nodo a un marco y se une a él; los marcos crecen para adaptarse. Ctrl+Z deshace. Ctrl+S guarda — y si el agente cambió el archivo mientras tenías ediciones sin guardar, la página lo indica y te deja elegir. L alterna el estilo de cable: bezier flotante, enrutado alrededor de las tarjetas, recto. Shift+S guarda lo que hay en pantalla como un SVG autocontenido, que es como se hizo cada diagrama de este README.

La vista plegada mantiene su propia disposición por diagrama en tu navegador, nunca en el archivo.

Referencia

Los diagramas van a ./dgv en el directorio en el que se inició el agente; DGV_DIR los coloca en otro lugar.

Primero la forma (schema/invalid), luego las referencias (ref/missing-node, ref/missing-frame, ref/duplicate-id), y después las reglas siguientes. Los errores bloquean ok; las advertencias y la información son consejos.

Errores — corrígelos antes de continuar.

Advertencias — el plan probablemente tiene una laguna.

Información — merece un vistazo, silenciosa en los recuentos: kind/store-access, kind/module-loose, kind/external-inside, graph/shared-store, layout/unplaced.

Una advertencia que es intencionada recibe ack: "<reason>" en su elemento: se convierte en información con el motivo adjunto, y el motivo viaja con el archivo. Los errores no se pueden reconocer.

{ "dgv": 1,
  "meta":   { "title": "Notes app", "description": "…", "colorBy": "kind", "edgeStyle": "routed" },
  "frames": [ { "id": "server", "label": "Server · one process", "tone": "amber",
                "position": { "x": 480, "y": 60 }, "size": { "width": 380, "height": 300 } } ],
  "nodes":  [ { "id": "api", "kind": "api", "label": "HTTP API", "sublabel": "/api/notes",
                "frame": "server", "status": "done", "path": "src/api", "position": { "x": 520, "y": 120 },
                "ports": [ { "id": "rest", "protocol": "http", "dir": "in" } ] } ],
  "edges":  [ { "id": "web-api", "source": "web", "target": "api",
                "kind": "sync", "protocol": "http", "targetPort": "rest", "label": "fetch" } ] }

kind es obligatorio en un nodo. En una arista se infiere del protocolo cuando se omite — data para sql redis s3 fs smb, async para kafka nats amqp mqtt sse ws, y en caso contrario sync. Las posiciones se guardan, así que una disposición que hayas hecho se mantiene. El catálogo completo — cada tipo, protocolo y código de lint — está en skill/references/format.md.

node packages/mcp/bin/dgv.mjs serve  [--dir d] [--port p] [--no-open]      # viewer, default http://127.0.0.1:7710
node packages/mcp/bin/dgv.mjs lint   <name|file> [--json]
node packages/mcp/bin/dgv.mjs layout <name|file> [--direction TB|LR]
node packages/mcp/bin/dgv.mjs export <name|file> [--format markdown|mermaid|summary|svg]
node packages/mcp/bin/dgv.mjs drift  <name|file> [--root dir] [--json]
node packages/mcp/bin/dgv.mjs list | catalog | doctor | open <name>

npm test — core: esquema, reglas de lint, semántica de parches, contención de la disposición, plegado, exportaciones, SVG, drift.

Límites

DGV no analiza tu código fuente. El lint puede decirte que el plan es coherente; el drift puede decirte que cada nodo sigue apuntando a código que existe y que cada directorio de código tiene un nodo. Ninguno de los dos puede decirte que las llamadas que dibuja el diagrama son las llamadas que hace el código — eso todavía lo lee una persona, o el agente, y el archivo que vive en el repositorio es lo que hace que esa lectura sea revisable.

No está aquí: colaboración o alojamiento, diagramas de secuencia y de ciclo de vida, descubrimiento de la estructura de un repositorio. El formato tiene versión (dgv: 1) para que esas cosas puedan añadirse sin romper los archivos existentes.

De dónde viene

Cerveau es un harness de codificación agéntica local-first. Su carpeta de docs contenía un borrador privado llamado arch-viewer: un lienzo de Svelte Flow que leía un Diagram.json de su arquitectura — 99 nodos, 127 aristas, nodos con un tipo, aristas con una etiqueta. Nada más que un navegador podía leerlo, así que el agente que hacía la construcción nunca lo vio. DGV conserva el lienzo, los marcos y la disposición, y pone un contrato debajo: un catálogo, puertos y protocolos, pertenencia declarada, un linter y un MCP para que el agente lea y escriba el mismo archivo. archify aportó la idea de una representación intermedia tipada con diagnósticos reparables.

MIT © Mounir Belahbib