> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Diagramas (@diagram)

> Renderiza diagramas de arquitetura, dependências, fluxo e ER em PNG/SVG/JPG a partir de Graphviz DOT — com texto nítido e 100% correto. O Graphviz roda embedado (WebAssembly), sem instalação; se houver um Graphviz do sistema ('dot') no PATH ele é usado automaticamente para fontes e layout mais nítidos.

O tool **`@diagram`** renderiza diagramas de **arquitetura, dependências, fluxo e ER** em **PNG, SVG ou JPG** a partir de Graphviz **DOT** — com os textos **nítidos e exatamente corretos**, porque os rótulos vêm do layout engine, não de pixels "chutados" por um modelo de visão.

O Graphviz é **embedado**: o `go-graphviz` traz o engine upstream compilado para **WebAssembly**, executado pelo runtime **wazero** (Go puro). Portanto funciona **sem cgo, sem instalação e sem rede** — o mesmo DNA self-contained do TTS/STT embedados e das notas de voz puro-Go. Quando há um **Graphviz do sistema** (`dot`) no PATH, o backend passa a usá-lo por padrão (`backend=auto`): renderizar o mesmo DOT via fontconfig + as fontes do SO + cairo gera saída mais nítida e melhor diagramada. O engine embedado continua sendo o fallback, então o tool **nunca exige instalação**. Veja [Backend de renderização](#backend-de-renderiza%C3%A7%C3%A3o).

<Tip>
  Para **qualquer diagrama de nós/arestas**, prefira `@diagram` ao [`@image`](/pt/tools/image-generation). O `@image` gera uma imagem raster e erra letras; o `@diagram` é determinístico e os nomes saem 100% corretos. SVG é infinitamente escalável; PNG com `dpi=300` é qualidade de impressão.
</Tip>

***

## Uso

```text theme={"system"}
<tool_call name="@diagram" args='{"cmd":"render","dot":"digraph{rankdir=LR; cli->agent; cli->llm}","output":"/tmp/arch.png"}' />
<tool_call name="@diagram" args='{"file":"./arch.dot","format":"svg","output":"/tmp/arch.svg"}' />
<tool_call name="@diagram" args='{"cmd":"gomod","root":".","format":"svg","output":"/tmp/imports.svg"}' />
```

O LLM invoca `@diagram` automaticamente quando você pede um diagrama de arquitetura/dependências como imagem — ele escreve o DOT (os modelos são bons em DOT) e renderiza aqui.

São dois subcomandos: **`render`** (DOT → imagem) e **`gomod`** (grafo de imports real de um módulo Go → imagem).

***

## Subcomando `render`

Renderiza DOT — inline (`dot`) ou de um arquivo `.dot` (`file`) — para uma imagem.

### Argumentos

| Argumento | Descrição | Default |
| :- | :- | :- |
| `dot` | Código Graphviz DOT inline. Exatamente um de `dot` \| `file`. | *(um dos dois)* |
| `file` | Caminho para um arquivo `.dot` a renderizar. Exatamente um de `dot` \| `file`. | *(um dos dois)* |
| `format` | `png` \| `svg` \| `jpg` | `png` (SVG no embedado sem `format`) |
| `engine` | Layout: `dot` \| `neato` \| `fdp` \| `sfdp` \| `circo` \| `twopi` \| `osage` \| `patchwork` | `dot` |
| `dpi` | Resolução raster para png/jpg (30–600, com clamp) | `150` |
| `backend` | Engine de renderização: `auto` \| `system` \| `embedded`. `auto` prefere o `dot` do sistema se instalado (mais nítido) e cai no WASM embedado. Sobrepõe `CHATCLI_DIAGRAM_BACKEND`. | `auto` |
| `output` | Caminho do arquivo de saída. Omitido, grava num arquivo temporário e retorna o caminho. | *(temp)* |

***

## Subcomando `gomod`

Constrói o **grafo de imports real** de um módulo Go (via `go list -json ./...`) e o renderiza, clusterizado por diretório de topo — um grafo de dependências **fiel ao código 1:1**, sem enumerar pacote na mão.

### Argumentos

| Argumento | Descrição | Default |
| :- | :- | :- |
| `root` | Diretório do módulo a analisar | `.` |
| `internalOnly` | Só arestas entre pacotes deste módulo (descarta dependências de terceiros) | `true` |
| `cluster` | Agrupa pacotes em clusters por diretório de topo | `true` |
| `style` | `dark` \| `light` \| `plain` | `dark` |
| `dotOnly` | Retorna o **código DOT gerado** em vez de renderizar a imagem | `false` |
| `format` / `engine` / `dpi` / `backend` / `output` | Iguais ao `render` | — |

<Tip>
  Use `dotOnly: true` para obter o DOT gerado e editá-lo (cores, agrupamentos, rótulos) antes de renderizar com `render`. Para diagramas focados, aponte `root` para um subdiretório (ex.: `./cli`) — o grafo do módulo inteiro pode ficar muito largo.
</Tip>

***

## Saída

Para `render` e `gomod` (sem `dotOnly`), o tool grava o arquivo e retorna um resumo com caminho, formato, tamanho e — para raster — as dimensões:

```text theme={"system"}
Diagrama renderizado → /tmp/arch.png (PNG, 245.1KB)
dimensões: 1200x800
```

Com `dotOnly: true`, o `gomod` retorna o próprio código DOT (texto), pronto para editar ou versionar.

***

## Backend de renderização

O `@diagram` renderiza o **mesmo DOT** por um de dois engines. O DOT gerado é idêntico — só muda **quem rasteriza**:

| Backend | Engine | Quando usar |
| :- | :- | :- |
| `auto` *(default)* | `dot` do sistema se houver no PATH, senão o embedado | Melhor padrão: bonito quando dá, nunca quebra |
| `system` | Graphviz nativo (ex.: `brew install graphviz`) | Força a saída mais nítida (fontconfig + cairo); erro se faltar |
| `embedded` | go-graphviz (WebAssembly/wazero) | Força o engine self-contained, sem depender de instalação |

O embedado rasteriza com `gg`/`freetype` (sem cairo/pango), então o **PNG/JPG** sai um pouco mais suave que o do `dot` nativo. Para minimizar isso, o embedado usa **fontes Go embarcadas** com hinting completo e escolhe a família certa por nome (proporcional vs **monospace**, regular vs negrito) — texto nítido e consistente em qualquer máquina. O `dot` do sistema usa **fontconfig + as fontes do SO + cairo**, então fica ainda um pouco mais polido. No modo `auto`, se o render pelo `dot` do sistema falhar, há **fallback transparente** para o embedado.

<Tip>
  **Quer paridade total sem instalar nada?** Use `format=svg`. O SVG é vetorial e idêntico ao do `dot` nativo (mesmo engine de layout) — por isso, quando o engine **embedado** renderiza e você **não** passa `format`, a saída usa **SVG por padrão**. Um `format` explícito ou uma extensão de arquivo reconhecida (`.png`/`.svg`/`.jpg`) sempre prevalecem.
</Tip>

### Configuração

Três formas, da mais ampla à mais específica:

* **Variável de ambiente** `CHATCLI_DIAGRAM_BACKEND=auto|system|embedded` (process-wide)
* **Argumento** `backend` por chamada (sobrepõe o env): `{"dot":"...","backend":"system"}`
* **`/config diagram`** mostra o backend configurado, o efetivo (após resolver o `auto`) e se há um `dot` instalado, com a versão:

```text theme={"system"}
/config diagram
```

***

## Notas

* **Não é read-only** e **não é concurrency-safe**: o tool grava um arquivo (e o `gomod` invoca `go list`), então passa pela confirmação de segurança padrão e não entra em lotes paralelos read-only.
* **Embedado de verdade**: o Graphviz roda como WebAssembly via wazero — nada para instalar, funciona offline já no primeiro uso, em qualquer SO/arquitetura. Com um `dot` do sistema instalado, o backend `auto` o usa automaticamente para saída mais nítida (veja [Backend de renderização](#backend-de-renderiza%C3%A7%C3%A3o)).
* Engines suportados: `dot` (hierárquico, default), `neato`/`fdp`/`sfdp` (força), `circo` (circular), `twopi` (radial), `osage`/`patchwork` (clusters/treemap).

<Tip>
  Combine com o [`@docs-flatten`](/pt/context/knowledge-base) e o `@context`: monte uma base de conhecimento do projeto e peça um diagrama de arquitetura — a IA usa o que aprendeu para escrever o DOT e o `@diagram` para renderizá-lo com fidelidade.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.