grafical

Architecture diagrams that coding agents build in small, checked steps.

An agent states what a diagram says, one operation at a time: this node is in that layer, connected to that one, colored like this. grafical decides where everything goes and lays the picture out again after every change. The agent never gives a coordinate, so only what it named changes and the picture always looks finished.

grafical drew the picture above itself, from docs/images/pipeline.grafical.

What it does

• 🪜 Small steps: every change is one command, such as node --set or edge --set.
  • A change keeps every fact it does not name.
  • --try shows what a change would do and writes nothing.
• ⚙️ The engine does the dirty work: it sizes and places and spaces every node.
  • It routes every edge and checks every write for defects.
  • A mistake is refused at once, with the facts to fix it.
• 🎨 Looks are free, places are facts: an agent may pick any color or edge width.
  • It states a node's place as a layer or a column or steps from another node, never as a coordinate.
• 📁 A file in git: the diagram is one .grafical file.
  • The same file gives the same SVG and PNG on any machine.
  • grafical diff shows a change as operations.
• 🤖 Made for agents: an agent learns grafical from grafical --help.
  • Every reply is facts and counts, never advice.

Install

git clone https://github.com/jinhuang712/grafical.git && cd grafical && pnpm install

INSTALL.md has what it needs first and how to check it worked.

How to use

An agent's prompt only has to say to draw with grafical. Here is what an agent does to draw a service and its database:

grafical -f arch.grafical diagram --set --title "Order flow"
grafical -f arch.grafical layer --set app,data
grafical -f arch.grafical node --set api --label "Order API" --type service --layer app
grafical -f arch.grafical node --set db --label Postgres --type store --layer data
grafical -f arch.grafical edge --set api-db --from api --to db --label writes
grafical -f arch.grafical render --png arch.png

Adding a cache later is two more steps, and the API and Postgres keep their layers and their order:

grafical -f arch.grafical node --set cache --label Redis --type store --layer data --after db
grafical -f arch.grafical edge --set api-cache --from api --to cache --label reads

Before	After

To watch an agent draw, open a window that redraws on every change:

grafical -f arch.grafical view

💡 From a clone, write node src/cli/main.ts in place of grafical.

Architecture

Every write runs the same parts, and only the agent's operations go in:

agent ──────command───────> command line ──records──> agent
                              │    └──writes──> diagram file (.grafical, in git)
                              │ operations
                              ▼
                            model ── refusals ──> command line
                              │ facts
                              ▼
  text measurer ──> layout: placement ⇄ routing ──> text placement <── theme
                              │ laid-out picture
                              ├──> checker ── defects, warnings, counts ──> command line
                              └──> renderer ──> SVG ──> PNG

Docs

• PROPOSAL.md: why grafical exists and what it won't do.
• PHILOSOPHY.md: the questions grafical takes a stance on.
• DESIGNS.md: what every design change must meet.
• FEATURES.md: what it does and will and won't do.
• CLI.md: every command, what it prints and how it fails.
• plan/GOALS.md: the checks that say whether it works.
• plan/ROADMAP.md: what is done and what comes next.
• plan/TODO.md: the open items with no checkpoint yet.
• specs/ARCHITECTURE.md: the parts and how they connect.
  • specs/model.md: the model.
  • specs/grafical-file.md: the .grafical file.
  • specs/placement.md: placement.
  • specs/routing.md: routing.
  • specs/labels.md: text placement.
  • specs/text.md: the text measurer.
  • specs/theme.md: the theme.
  • specs/checks.md: the checker.
  • specs/rendering.md: the renderer.
  • specs/answers.md: how grafical answers.
  • specs/benchmark.md: how the benchmarks run.
• specs/decisions: each fork taken and what was not chosen.
• GLOSSARY.md: one name for each thing.
• INSTALL.md: how to install, update and remove it.
• CHANGELOG.md: what changed in each release.
• AGENTS.md: how agents develop in this repository.

License

MIT.