visual-architecture: Generate Precise AI System Architecture Diagrams with Structured JSON

The visual-architecture project aims to solve the randomness dilemma of AI-generated diagrams. By separating system structure description from visual rendering, it uses structured JSON to define architectures and generates clear, professional, and maintainable SVG diagrams through deterministic rendering rules. Key advantages include orthogonal arrow routing, semantic shapes, restrained style design, readable labels, and deterministic output, suitable for various scenarios such as technical documentation and multi-agent system design.

When AI assists in generating architecture diagrams, it often faces issues like chaotic layouts, random connections, inconsistent styles, label drift, and over-decoration, leading to poor readability and difficulty in maintenance. The root cause is that AI is responsible for both 'describing structure' and 'deciding layout'—impromptu geometric layout easily produces 'chart junk'.

The design philosophy of visual-architecture is 'describe the system structure, let the renderer handle the visuals', bringing the following advantages:

1. Orthogonal arrow routing: Avoids diagonal lines and minimizes crossings;
2. Semantic shapes: Different component types correspond to fixed shapes (e.g., hexagons for Agents, double-bordered rounded rectangles for LLMs);
3. Restrained style: Flat design, with colors distinguishing data flow types;
4. Readable labels: Automatic obstacle avoidance, using background masking when necessary;
5. Deterministic output: The same JSON generates the same SVG, facilitating version control.

The project includes the OpenClaw Skill module (containing usage documentation, rendering scripts, and examples) and a standard Python renderer. Workflow: 1. Define structures like nodes and edges using JSON; 2. Render to generate SVG; 3. Adjust JSON for iterative optimization. JSON Schema examples intuitively describe architectures, with advantages including version friendliness, programmable generation, human readability, and tool independence.

visual-architecture is suitable for the following scenarios:

• Technical documentation: Generate professional architecture diagrams to ensure synchronization with code;
• Multi-agent system design: Show collaboration relationships and message routing;
• Memory system visualization: Depict RAG system components;
• Microservice architecture: Show dependencies and data flow directions;
• Workflow orchestration: Visualize processing pipelines;
• Teaching demonstrations: Generate clear teaching diagrams.

Dimension	AI Impromptu Drawing	visual-architecture
Layout	Random, different each time	Deterministic, fixed rules
Connections	Diagonal lines, possible crossings	Orthogonal, minimize crossings
Consistency	Variable styles	Strictly follows semantic conventions
Maintainability	Hard to version control	JSON easy to diff
Professionalism	May be over-decorated	Restrained, focused on clarity
Iteration Cost	Need to regenerate	Just adjust JSON

AI impromptu drawing is suitable for the exploration phase, while structured rendering is more suitable for professional diagrams that require maintainability and collaboration.

Usage Suggestions:

1. Start with examples to understand the JSON schema;
2. Keep node type semantics accurate;
3. Focus on logical relationships first, then fine-tune the layout;
4. Include JSON in version control and generate SVG automatically.

Future Outlook: Expand support for more diagram types (sequence diagrams, state diagrams, etc.), add theme customization capabilities, but the core principle remains unchanged: structure description first, deterministic rendering rules.