dgv

Module, APIs, Programme, Datenbanken, Warteschlangen, Bridges, Sidecars, Geräte — jedes ist ein Knoten mit einer Form und einer Art; jede Verbindung trägt ein Protokoll und bindet an einen Port, den das Ziel deklariert. Ein Lint-Durchlauf sagt dir mit einem stabilen Code und einem konkreten Fix, wann der Plan nicht funktionieren kann: eine Kante in einen nicht deklarierten Port, ein Protokollkonflikt, ein Store, der Aufrufe initiiert, eine einseitige Bridge, ein Importzyklus, eine API, die niemand aufruft. All das taucht bevor ein Tag an Tokens in den falschen Plan fließt auf.

Nur lokal, dateibasiert, keine Konten: Diagramme sind dgv/<name>.dgv.json in deinem Projekt.

Claude Code  ──MCP (stdio)──▶  dgv mcp  ──▶  dgv/*.dgv.json  ◀──  dgv serve ──▶ browser viewer (Svelte Flow)
                                                    ▲                              │
                                                    └──────── save / drag / edit ──┘

Inspiriert von archify (typisiertes IR + reparierbare Diagnosen) und vom arch-viewer-Entwurf in Cerveau (cerveau.sh) — der lokale-First-agentische Coding-Harness, für den DGV gebaut wurde, um zu planen. DGV unterscheidet sich von beiden bewusst: eine live editierbare Leinwand statt statischem SVG, explizite Frame-Zugehörigkeit statt Geometrie-Inferenz, dagre-Layout und Ports/Kontrakte auf Kanten.

Warum das in jede Phase gehört

Ein vibecodiertes System wird schneller geschrieben, als irgendwer es im Kopf behalten kann — du, deine Teammitglieder und der Agent raten am Ende alle über eine Form, die niemand aufgeschrieben hat. DGV schreibt sie in einer Form auf, die alle drei lesen können und mit der ein Linter streiten kann.

Beide Bilder unten sind echte Exporte aus dem Snapshot-Button dieses Repos: die Architektur von Cerveau, 35 Komponenten über 7 Grenzen, geplant in DGV, bevor der Code geschrieben wurde.

Falte es und dieselbe Datei beantwortet eine andere Frage. Jeder Frame wird zu einem Knoten, die Drähte, die jede Grenze kreuzen, verschmelzen zu einem beschrifteten Link, und ein System, das du nicht auf einen Blick erfassen kannst, wird zu sieben Boxen, die du kannst. Dasselbe Dokument — es gibt kein zweites Diagramm, das synchron gehalten werden muss, und keinen Moment, in dem Übersicht und Detail nicht übereinstimmen.

Planung — bevor ein Tag an Tokens in die falsche Richtung geht

Der billigste Bug ist der, der im Plan erwischt wird. dgv_lint liefert einen stabilen Code, das genaue Subjekt und konkrete Fixes, sodass ein Agent den Plan in derselben Runde reparieren kann, in der er ihn gebrochen hat: eine Kante in einen Port, den das Ziel nie deklariert hat, ein Protokoll, das eine Art nicht sprechen kann, ein Store, der Aufrufe initiiert, eine einseitige Bridge, ein Importzyklus, eine API, die niemand aufruft.

Ein falscher Plan kündigt sich nicht an. Er wird implementiert, und du findest es einen Tag Generierung später heraus.

Bauen — die Karte, die ein Agent liest, statt des ganzen Baums

Weise einen Agenten auf ein 200-Dateien-Repo hin und er grept, öffnet und inferiert, verbrennt Kontext, um ein Bild wiederherzustellen, das bereits existiert. dgv_export reicht ihm dieses Bild direkt — welche Komponente was besitzt, welcher Port welches Protokoll trägt, was was aufrufen darf — als Markdown, eine Gliederung, Mermaid oder ein SVG.

Die typisierten Kontrakte sind der Teil, der den erfundenen Endpunkt verhindert. Ein Modell, das memclient → typesense · search · http lesen kann, muss nicht raten, ob der Store SQL spricht.

Reviewen — Architekturdrift taucht im Diff auf

Das Diagramm ist eine JSON-Datei im Repo, also kommt eine Änderung, die ein Modul stillschweigend eine Datenbank direkt aufrufen lässt, im Pull Request als geänderte Kante an, neben dem Code, der es getan hat. Kein Screenshot, kein veraltetes Figma, kein Whiteboard-Foto in einem Wiki.

Warten — ein Plan, mit dem gestritten wird, bleibt wahr

Dokumentation verrottet, weil nichts sie prüft. Diese hier wird bei jedem Lesen geprüft — und sie braucht trotzdem deine Ehrlichkeit. Während diese README geschrieben wurde, hat Lint Cerveaus Diagramm erwischt, wie es den vLLM-Kern als Work-in-Progress bezeichnete, während cores.json ihn als aktiven Kern hatte, und hat einen Import markiert, der das überschritt, was das Diagramm als zwei Prozesse beschrieb, der Code aber als einen ausführt. Beides waren Fälle, in denen das Diagramm über ausgelieferte Arbeit log. Beides war ein Einzeiler-Fix, gefunden vom Tool statt von jemandem, der später darüber stolpert.

DGV zeichnet den Plan auf; es liest deinen Quellcode nicht. Es kann dir nicht sagen, dass der Code übereinstimmt — nur, dass der Plan kohärent ist und dass das, was du aufgeschrieben hast, immer noch das sagt, was du gemeint hast. Das ist die ehrliche Grenze, und es ist der Grund, warum die Datei im Repo lebt, wo Review sie erreichen kann.

Related MCP server: mermaid-mcp-server

Pakete

Setup

cd Dia-GramV
npm install
npm run build                         # builds the viewer once
node packages/mcp/bin/dgv.mjs doctor  # checks node, viewer, prints the mcp add line

# register the MCP server for Claude Code (user scope, any project)
claude mcp add dgv -s user -- node /ABS/PATH/Dia-GramV/packages/mcp/bin/dgv.mjs mcp
# install the skill
ln -s /ABS/PATH/Dia-GramV/skill ~/.claude/skills/dgv

Diagramme gehen nach ./dgv unter dem Verzeichnis, in dem Claude Code gestartet wurde (überschreibbar mit DGV_DIR).

MCP-Tools

Viewer

node packages/mcp/bin/dgv.mjs serve → http://127.0.0.1:7710

• Knoten nach Art hinzufügen, vom rechten Griff eines Knotens ziehen zum Verbinden, Knoten in Frames ziehen (Frames wachsen mit), Frames in der Größe ändern

• der Inspektor bearbeitet jedes Feld inkl. Ports; das Problem-Panel lintet live und springt zum Subjekt

• nach Art oder nach Build-Status einfärben; Strg+S speichert; die Seite lädt neu, wenn der Agent die Datei ändert (oder warnt, wenn du ungespeicherte Änderungen hast)

• einen Frame zu einem Knoten falten — über einen Frame fahren und falten, oder S für die einfache Ansicht drücken. Ein gefalteter Frame zeichnet sich als eine Karte, die zeigt, was er enthält, und die Drähte, die hineinkreuzen, verschmelzen zu einem beschrifteten N Links. Die gefaltete Ansicht behält ihr eigenes Layout, pro Diagramm, in deinem Browser — nie in der Datei

• Snapshot (Umschalt+S) speichert, was auf dem Bildschirm ist, als eigenständiges SVG für eine README- oder Doku-Seite: geroutete Drähte und alles, auf den Inhalt zugeschnitten, keine externen Schriften oder Bilder, nichts wird nachgeladen

• npm run dev startet Vite auf 5190 mit /api-Proxy auf 7710 zum Hacken am Viewer

Frames verschachteln sich nicht. Einen zu falten musste die Frage beantworten „und was ist mit den Frames darin“, und jede Antwort war ein Sonderfall; eine flache Ebene macht einen Frame zu genau einer Karte. frame/nested ist ein Lint-Fehler.

CLI

dgv lint <name|file> [--json]   dgv layout <name|file> [--direction TB|LR]
dgv export <name|file> [--format markdown|mermaid|summary|svg]
dgv list | catalog | doctor | serve [--dir d --port p --no-open] | open <name> | mcp

Dateiformat

Siehe skill/references/format.md für das Schema, die Arten und jeden Lint-Code.

Tests

npm test      # core: schema, lint rules, patch semantics, layout containment, exports, store

Nicht im Umfang (noch)

Kollaboration / Hosting, Sequenz- und Lebenszyklus-Diagrammtypen, automatische Repository-Erkennung. Das Dateiformat ist versioniert (dgv: 1), sodass diese kommen können, ohne bestehende Diagramme zu brechen.

MIT.