How we engineered an 8-stage compiler to generate clean system diagrams
Designing an AI diagram generation pipeline that processes raw prompts, sanitizes graph relations, layouts nodes, and self-heals layouts.
01Why asking LLMs for direct layout coordinates fails
If you ask a standard large language model to output a diagram with exact layout positions, the results are highly chaotic. LLMs do not have native spatial awareness. They will stack database nodes directly on top of client browsers, place load balancers at random coordinates, and draw edges that cross each other. Furthermore, they frequently omit critical architecture nodes—for instance, placing a CDN without an origin object storage or connecting a database directly to a client browser. We need to treat diagram generation as a multi-stage compilation pipeline.
02The 8-stage compilation architecture
To generate professional architectures, we divide the pipeline into distinct stages. In Stage 1, we identify the architectural domain. Stage 2 plans the abstract tiers (e.g., Client tier, Gateway tier, Compute tier, Database tier). Stage 3 extracts the required nodes and metadata. Stage 4 maps the edges and protocols. Stage 5 runs semantic validation filters (e.g., checking if database connections bypass the backend compute tier, or verifying that push notification gateways use websockets). Stage 6 feeds the clean structural graph to a layered layout calculator to assign coordinates. Stage 7 translates layout boundaries to the canvas coordinate system, and Stage 8 scores the diagram quality.
03Creating automated self-healing layout feedback loops
If the pipeline detects validation errors (e.g. a database connecting directly to the browser client, or an auth service acting as an intermediate gateway hop for general business requests), it does not fail. Instead, it triggers an auto-repair loop. The pipeline packages the specific structural violations, compiles them into a developer-friendly error log, and feeds them back to the reasoning model as a corrective prompt. The model processes the feedback, refines the adjacency relationships, and runs the layout generator again, repeating up to three times until the quality score passes.
04Applying layered layout algorithms
Once the logical connections are finalized, we pass the nodes and edges to a layered graph layout engine (such as ELK or Dagre). These engines organize nodes into horizontal or vertical ranks. Nodes in the Client tier are ranked first, followed by Gateways, Compute, and Databases. The layout engine computes positions that minimize crossing lines, keeps nodes vertically aligned, and maintains a minimum separation boundary (e.g., 120px between tiers, 60px between nodes in the same tier), resulting in neat, professional diagrams.