Grafo: A JSON Architecture Diagram Format Optimized for LLM Reasoning — Enabling AI to Understand Structured Expressions of System Design

Grafo is a JSON model format designed specifically for system architecture diagrams and flowcharts, developed by ruslanvs and hosted on GitHub (https://github.com/ruslanvs/grafo, updated 2026-05-26). Its core goal is to enable both human understanding and efficient machine (LLM) reasoning. It addresses the limitations of traditional diagram formats (e.g., PNG, SVG) that are hard for LLMs to parse, thus bridging the gap between human-centric communication and AI-native processing.

System architecture diagrams are essential for engineering communication, but traditional formats struggle with LLM compatibility. Here's a comparison:

Format	Human Readability	LLM Processability	Editability
PNG/JPG	High	Very Low (requires OCR)	Low
SVG	High	Low (XML parsing needed)	Medium
PlantUML/Mermaid	High	Medium (DSL parsing needed)	High
Draw.io XML	Medium	Low (complex XML)	Medium
Grafo JSON	Medium	High (native JSON)	High

Grafo fills the 'LLM-native' architecture representation gap.

Grafo is a JSON specification for system architecture and flow diagrams. Its key features include:

1. Hierarchical Structure: Nested nodes and subgraphs to represent complex systems (e.g., subsystems, components).
2. Semantic Attributes: Nodes/edges carry type info (service, database, sync call), metadata (version, owner), and context.
3. LLM-Friendly: Pure JSON format allows LLMs to directly process, understand topology, analyze dependencies, generate docs, and answer design questions.

Grafo's core data model consists of three elements:

• Nodes: Represent components (unique ID, type, display attributes, metadata).
• Edges: Represent relationships (source/target nodes, relation type, direction, labels).
• Subgraphs: Group related nodes for logical hierarchy (e.g., application layer, infrastructure layer).

LLM optimization features:

• Context Efficiency: JSON tokenizes efficiently, fitting larger architectures in LLM context windows.
• Structured Reasoning: Nested structure enables hierarchical analysis (top-down from system to components).
• Verifiability: JSON Schema validates Grafo documents for correctness.

Grafo enables various AI-enhanced workflows:

1. Architecture as Code: Version control, automated tests (e.g., cycle dependency detection), and diff analysis.
2. Natural Language to Diagram: LLM generates Grafo JSON from text (e.g., 'create a microservice architecture with user, order, payment services') then renders to visual charts.
3. Architecture Q&A: Answer questions like 'Which services depend on the payment service?' or 'What components are affected by a database failure?'.
4. Auto Document Generation: Generate ADRs, interface docs, and operation and maintenance manuals from Grafo.
5. Evolution Analysis: Track architecture changes, visualize tech debt, and assess refactor impact.

Grafo integrates with existing toolchains:

• Visualization: Convert to Mermaid, Draw.io, D3.js/SVG, or PlantUML.
• CI/CD: Trigger auto doc updates, compliance checks (e.g., security boundaries), and generate deployment topology.
• Document Systems: Embed in Docusaurus, MkDocs, Confluence, or Notion.

Grafo represents a shift toward AI-native architecture engineering. Potential enhancements:

• Semantic extensions for patterns (event-driven, CQRS).
• Dynamic data integration (runtime metrics like traffic, latency).
• Multi-view support (development, deployment, runtime views).
• Collaboration features (real-time editing) and version management.

Community goals: Become a standard via open specs, multi-language implementations, tool ecosystem, and best practices.