Generating Architecture Diagrams with AI: Grid Alignment and Engineering Implementation

1. Background: Why Do Architecture Diagrams Always Look Like Drafts?

In technical proposals, bidding materials, and system design reviews, architecture diagrams are often underestimated yet highly time-consuming. While text logic can be iterated easily, drawing diagrams often traps people in a loop of “drag, align, tweak, re-align.” Two service boxes might be 3 pixels off, arrows cross text, components on the same layer have inconsistent heights, and legends clash with the main diagram. The final output is understandable but severely lacks professionalism.

The root cause isn’t the drawing tool itself, but the lack of systematic constraints in manual layout. Professional design drafts look clean because they rely on an implicit grid system, spacing rules, and symbol standards. Adjusting pixel by pixel manually is essentially approximating these rules by eye—costly and non-reusable.

This article discusses a more engineered approach: treating architecture diagrams as the product of “structured data + deterministic rendering rules.” AI handles understanding requirements and generating structured descriptions, while the rendering layer outputs graphics based on grid and constraint rules. The direct benefits are stable graphic quality, batch generation capability, version control compatibility, and integration into automated pipelines.

It should be noted that this article does not focus on specific commercial products. Instead, it extracts a universal technical solution that readers can implement using any LLM API supporting structured output and any SVG/Canvas rendering solution.

2. Overall Solution: A Three-Stage Pipeline

Splitting architecture diagram generation into three stages is key to stable reproduction. The stages are: Semantic Understanding & Desensitization → Structured Graph Description Generation → Grid-based Rendering. Each stage has a single responsibility and clear inputs/outputs, making it easy to debug and replace independently.

[Requirement Text/Draft]
      │
      ▼
① Semantic Understanding & Desensitization  ──►  Normalized Requirement Description (Entities, Relations, Layers)
      │
      ▼
② Graph Description Generation              ──►  JSON Graph Model (Nodes, Edges, Groups, Hierarchy)
      │
      ▼
③ Grid-based Rendering                      ──►  SVG / PNG (4px Grid Alignment, Unified Styles)

2.1 Why a Structured Intermediate Layer is Necessary

Directly asking a model to “draw a diagram” (e.g., outputting an image or free-form drawing code) has two major flaws: first, it is uncontrollable, with alignment quality varying randomly each time; second, it is unverifiable, making it impossible to pinpoint whether an error is semantic or layout-related.

By introducing a JSON graph model as an intermediate layer, semantic issues are exposed in the second stage, and layout issues in the third stage, creating clear debugging boundaries. More importantly, JSON can be diffed, reviewed, and stored in code repositories, giving architecture diagrams version traceability—a highly valuable feature in collaborative document environments.

2.2 Minimal Field Design for the Graph Model

A sufficient, non-over-engineered graph model can be defined as follows:

{
  "canvas": { "grid": 4, "padding": 32, "direction": "top-down" },
  "groups": [
    { "id": "layer-access", "label": "Access Layer", "order": 1 },
    { "id": "layer-service", "label": "Service Layer", "order": 2 }
  ],
  "nodes": [
    { "id": "gw", "group": "layer-access", "label": "API Gateway", "kind": "gateway" },
    { "id": "svc-a", "group": "layer-service", "label": "Order Service", "kind": "service" }
  ],
  "edges": [
    { "from": "gw", "to": "svc-a", "label": "Route", "style": "solid" }
  ]
}

The field design follows two principles: separate layout information from semantic information (nodes do not carry coordinates; coordinates are calculated by the rendering layer), and express styles as enums rather than specific values (kind determines symbols and colors, preventing the model from fabricating pixel values).

3. 4px Grid Alignment: From Mystery to Deterministic Algorithm

The 4px grid is not a proprietary standard but a fundamental grid unit widely adopted in UI design. Most screen rendering avoids half-pixel blurring at integer multiples of 4. Icons, spacing, and strokes are perfectly divisible, making it visually easier to achieve a consistent rhythm. Aligning architecture diagrams to a 4px grid essentially replaces a continuous coordinate system with a discrete coordinate system, eliminating “slightly off” issues.

3.1 Rendering Layer Alignment Process

The rendering stage should execute in the following order, with every step operating strictly on grid coordinates:

1. Size Quantization: After estimating node width and height based on content, round up to multiples of 4, and enforce minimum size limits (e.g., 96×48).
2. Layered Layout: Arrange layers top-to-bottom by group.order, with layer spacing set to a fixed grid multiple (e.g., 48px).
3. Intra-layer Distribution: Calculate spacing for nodes within the same layer based on quantity. Constrain total width within the canvas, set spacing to a multiple of 4, and evenly distribute remaining space.
4. Connection Anchor Calculation: Edges do not connect directly to node borders but select from an anchor set (top, bottom, left, right, center). Anchor coordinates are inherently grid points.
5. Routing & Avoidance: All turning points in orthogonal polyline paths must be strictly grid-aligned. Perform simple rectangle collision detection for line segments crossing nodes, and shift them by grid steps to avoid overlap.

Writing this process in pseudocode makes the logic very intuitive:

GRID = 4
def snap(v):
    return round(v / GRID) * GRID
def layout_layer(nodes, canvas_width, gap=32):
    # Quantize width to grid
    for n in nodes:
        n.w = snap(max(96, estimate_width(n.label)))
        n.h = snap(max(48, estimate_height(n.label)))
    total = sum(n.w for n in nodes)
    gap = snap(gap)
    free = canvas_width - total - gap * (len(nodes) - 1)
    # Distribute remaining space by grid to ensure overall centering
    offset = snap(max(0, free) / 2)
    x = offset
    for n in nodes:
        n.x = snap(x)
        x = n.x + n.w + gap

Note that snap is called at every step, rather than rounding all at the end. Layout-first-quantize-later causes cumulative errors, resulting in node overlaps.

3.2 Common Pitfalls

• Text Width Estimation Deviation: Estimating width by character count is highly inaccurate for mixed Chinese-English text. A viable approach is to convert using “1 full-width unit for Chinese, 0.5 half-width unit for English,” add a 16px inner padding, and finally quantize to the grid. It is better to be slightly wider than to truncate text.
• Arrow and Text Overlap: Edge labels should not be placed at the path’s midpoint. Instead, offset them to one side of the path and align to the grid; if the path is a polyline, place the label above the longest horizontal segment.
• Cross-layer Line Readability: Edges spanning multiple layers should be merged into a bus before distribution to avoid a “spider web.” This can be preprocessed at the graph model level, merging edges with shared sources/destinations into a bus type.

4. Engineering the AI Stage: Prompts and Validation

In the pipeline, AI acts as a “translator”—translating natural language requirements into a JSON graph model. To stabilize this step, the key is not longer prompts, but a trio of constraints + validation + retry.

4.1 Three Hard Constraints for Prompts

1. Output JSON Only with Fixed Field Whitelist: Explicitly list allowed fields and enum values. Forbid the model from inventing fields.
2. No Coordinates or Pixels: Position information must be calculated entirely by the rendering layer, cutting off the “model fabricating coordinates” problem at the source.
3. Node and Layer Limits: A single diagram should ideally have no more than 20 nodes and 5 layers. If exceeded, require the model to abstract and merge first. There is an upper limit to an architecture diagram’s information density; too many nodes inevitably sacrifice readability.

4.2 Output Validation and Auto-Retry

After receiving the model’s output, run a validator before rendering:

def validate(model):
    errors = []
    ids = {n["id"] for n in model["nodes"]}
    for e in model["edges"]:
        if e["from"] not in ids or e["to"] not in ids:
            errors.append(f"Edge references non-existent node: {e}")
    for n in model["nodes"]:
        if n["kind"] not in ALLOWED_KINDS:
            errors.append(f"Invalid node type: {n['kind']}")
    if len(model["nodes"]) > 20:
        errors.append("Too many nodes, consider merging")
    return errors

If validation fails, pass the error list back to the model for correction. It typically converges in one or two rounds. This mechanism is more reliable than tweaking prompts because it turns “correctness” into an executable check rather than relying on the model’s self-awareness.

4.3 The Desensitization Step Cannot Be Omitted

Proposal texts often contain sensitive information like internal system names, real domains, and account identifiers. A entity replacement must occur before sending it to the model: replace real system names with placeholders (e.g., SVC_01), and backfill them using a mapping table after generation. This meets compliance requirements and incidentally improves diagram reusability—the same graph model can be used for different clients just by swapping the mapping table.

5. Symbol and Style Standards: Making Diagrams “Look Professional”

The grid solves position issues, while styles solve semantic consistency. It is recommended to build a symbol library in the rendering layer driven by the kind field:

kind	Visual Representation	Semantics
service	Rounded rectangle	Business service
gateway	Hexagon or rectangle with arrow	Traffic entry point
storage	Cylinder	Data storage
queue	Parallelogram	Asynchronous message
external	Dashed border	External dependency

Supporting style rules should also be standardized: uniform 1.5px strokes, uniform 8px corner radius, consistent colors for the same node types, and text fonts using only two sizes (14px for titles, 12px for body). Fewer rules mean more consistency—a fundamental principle of design systems that applies equally to auto-generated graphics.

6. Implementation Suggestions and Effect Evaluation

6.1 Phased Implementation

• Phase 1: Run a single diagram using the JSON graph model + a hand-written renderer to validate the grid algorithm.
• Phase 2: Integrate the LLM to generate JSON, establishing the validation and retry pipeline.
• Phase 3: Store graph models in code repositories, integrating with CI to auto-render during document builds, achieving “document changes trigger diagram updates.”

6.2 How to Evaluate Results

Don’t just look at “whether it looks good.” Use three quantifiable metrics:

1. Rework Rate: The percentage of diagrams requiring manual tweaking after generation. Aim to reduce this below 10%.
2. Generation Time: End-to-end time from requirement text to final diagram, typically in seconds to a dozen seconds.
3. Consistency Score: Whether font sizes, spacing, and colors are consistent across multiple diagrams in the same document, evaluated via sampling manual review.

7. Conclusion

The professionalism of an architecture diagram comes from constraints, not manual finesse. The solution outlined in this article splits the process into three layers: AI handles semantic translation, the JSON graph model carries the structure, and the rendering layer outputs deterministic results using a 4px grid and symbol standards. Once decoupled, each layer can be optimized independently, and the entire pipeline becomes ready for engineering integration—verifiable, versionable, and automatable.

For teams frequently producing proposal documents, the true value of this solution isn’t “saving an hour of drawing.” It transforms architecture diagrams from one-off labor into reusable assets: a single graph model can be rendered into different sizes, color schemes, and language versions, and continuously diffed as the system evolves. This is the embodiment of engineering thinking in the documentation domain.