How AI Turns a Text Prompt Into an Architecture Diagram

"Build me an e-commerce platform with real-time inventory and payment processing."

A model can turn that sentence into boxes and arrows. The harder job is making the result editable, explainable, and safe to reject when it is wrong. That is the engineering problem behind Codelit's architecture workflow.

The stages below are a simplified design model and teaching examples, not a line-for-line description of every current generation route. Codelit's implementation keeps evolving; the boundaries are the part worth reusing.

A prompt-to-diagram workflow can be understood through five responsibilities: interpreting intent, choosing a topology, generating structure, calculating layout, and rendering an editor. They need not be five separate model calls. Each responsibility has a distinct failure mode and a contract worth testing.

Let me walk through them.

An intent parser can map a domain phrase like "e-commerce platform" onto candidate components, then apply explicit modifiers from the prompt. Candidate is the important word: catalog, cart, checkout, payments, orders, and auth are reasonable starting points, not requirements the user necessarily supplied.

"Build me an e-commerce platform" is vague. Does it include a mobile app? Admin dashboard? Analytics? Recommendation engine?

I don't try to read minds. The parser extracts explicit requirements and infers reasonable defaults. Modifiers change the output from there. "With real-time inventory" adds a WebSocket layer and an inventory service with event-driven updates. "And payment processing" adds a payment gateway (Stripe-like) with webhook handling.

A two-pass design keeps those responsibilities separate:

Pass 1: Keyword extraction and domain mapping. Deterministic rules cover familiar terms without a model call.

// Simplified domain mapping
const domainMap: Record<string, string[]> = {
  "e-commerce": ["product-catalog", "cart", "checkout", "payment", "orders", "auth"],
  chat: ["messaging", "websocket", "presence", "auth", "storage"],
  social: ["feed", "posts", "comments", "notifications", "auth", "cdn"],
};

// Modifier detection
const modifiers: Record<string, string[]> = {
  "real-time": ["websocket-server", "event-bus"],
  payment: ["payment-gateway", "webhook-handler"],
  ml: ["ml-service", "feature-store", "model-registry"],
};

Pass 2: Send ambiguous elements to the LLM for classification. Only fires when Pass 1 can't resolve the intent confidently. This keeps the common cases fast and cheap.

Generated diagrams can add infrastructure because a model or template assumes a particular topology. That assumption should be visible and reversible. An API gateway, broker, and load balancer are not mandatory just because an application has several business domains.

Once I know the components, I need to decide how they connect. This is where architectural knowledge gets encoded. I maintain a library of patterns, monolith, microservices, event-driven, CQRS, serverless, hybrid, and each pattern defines a topology: how services communicate, where data flows, what infrastructure sits between them.

E-commerce can fit a modular monolith or a distributed architecture. Team ownership, scaling needs, and operational capacity should drive the choice. "Keep it simple" is not a cosmetic modifier; it can remove entire services from the proposed design.

Structured output needs an explicit contract and a failure path. Use native schema-constrained generation where supported, validate the result locally, and bound any repair attempts. A model response is untrusted input even when it is syntactically valid JSON.

This is where most of the engineering effort lives. The LLM needs to produce a JSON object defining every node (type, label, properties, tier) and every edge (source, target, label, type). Getting LLMs to produce consistent, valid, schema-conformant JSON is genuinely hard. The progression is useful to understand:

Provider APIs differ, so keep their request details in adapters. The application-side shape can stay small. This simplified Zod example validates structure, not whether the proposed architecture makes sense:

import { z } from "zod";

const NodeSchema = z.object({
  id: z.string(),
  type: z.enum(["database", "service", "queue", "cache", "gateway", "client", "external"]),
  label: z.string(),
  tier: z.enum(["client", "edge", "application", "data", "external"]),
  properties: z.record(z.string(), z.unknown()).default({}),
});

const EdgeSchema = z.object({
  id: z.string(),
  source: z.string(),
  target: z.string(),
  label: z.string().optional(),
  type: z.enum(["sync", "async", "data-flow", "event"]),
});

const ArchitectureSchema = z.object({
  nodes: z.array(NodeSchema),
  edges: z.array(EdgeSchema),
});

After shape validation, check that node IDs are unique and every edge endpoint exists. Reject or repair missing references with a bounded retry budget. A serverless monolith is not inherently contradictory, and model failure should never be blamed on the prompt by default.

Stage 3 returns a flat JSON object with a nodes array and an edges array. Every node carries a type and a tier. Every edge carries a source, a target, and a type. For the e-commerce prompt, simplified, it looks like this:

{
  "nodes": [
    { "id": "client", "type": "client", "label": "Web App", "tier": "client" },
    { "id": "gateway", "type": "gateway", "label": "API Gateway", "tier": "edge" },
    { "id": "catalog", "type": "service", "label": "Product Catalog", "tier": "application" },
    { "id": "cart", "type": "service", "label": "Shopping Cart", "tier": "application" },
    { "id": "payment", "type": "service", "label": "Payment Service", "tier": "application" },
    { "id": "inventory", "type": "service", "label": "Inventory Service", "tier": "application" },
    { "id": "orders-db", "type": "database", "label": "Orders DB (PostgreSQL)", "tier": "data" },
    { "id": "cache", "type": "cache", "label": "Redis Cache", "tier": "data" },
    { "id": "queue", "type": "queue", "label": "Event Bus (RabbitMQ)", "tier": "data" },
    { "id": "stripe", "type": "external", "label": "Stripe", "tier": "external" }
  ],
  "edges": [
    { "id": "e1", "source": "client", "target": "gateway", "type": "sync" },
    { "id": "e2", "source": "gateway", "target": "catalog", "type": "sync" },
    { "id": "e3", "source": "gateway", "target": "cart", "type": "sync" },
    { "id": "e4", "source": "cart", "target": "payment", "type": "sync" },
    { "id": "e5", "source": "payment", "target": "stripe", "type": "sync", "label": "Charge" },
    {
      "id": "e6",
      "source": "inventory",
      "target": "queue",
      "type": "event",
      "label": "Stock Updated"
    },
    { "id": "e7", "source": "catalog", "target": "cache", "type": "data-flow" },
    { "id": "e8", "source": "payment", "target": "orders-db", "type": "data-flow" }
  ]
}

That typed graph drives everything downstream: layout, rendering, styling, interactivity. It's also the graph chaos mode walks when it propagates a cascading failure, which only works because every edge already knows whether it carries a synchronous call or an event.

Codelit's current architecture canvas finds root nodes, walks outgoing edges to assign depth, and groups nodes into rows. Type-based fallbacks place nodes the traversal did not visit. That keeps layout local and inspectable, separate from the model's description of the system.

A layout library such as Dagre offers another approach. Whatever computes the rows, architectural conventions can inform the result:

• Databases may sit below the services that use them
• Load balancers can center above the services they front
• Message queues can sit between producers and consumers
• External services can sit outside the primary system boundary

This is the same problem I hit converting Mermaid syntax into an interactive canvas: the source tells you what connects to what and never where anything sits. Whatever invents the geometry has to be deterministic, same input, same output. If you regenerate the same architecture and the boxes land somewhere else, you stop believing the diagram means anything.

React Flow renders the positioned graph, and the node and edge types from Stage 3 map straight onto visual treatments. The schema value decides the shape, the stroke and the animation, so nothing on the canvas is decorative.

Every element is interactive: click, drag, right-click to modify. The custom node components, the animated edges and the layout wiring are a subject of their own, and I pulled them apart in building the interactive architecture canvas with React Flow. The diagram is a starting point, not a finished product.

When a user asks to add caching, the product should make the proposed change inspectable without losing the architecture they already refined. A patch-oriented contract is one way to do that. A replacement response with version history is another, with a different preservation burden.

The naive approach is to generate a completely new diagram. That throws away every manual adjustment, repositioned nodes, renamed services, added annotations, and users notice immediately. Correct behaviour is narrow: add a Redis node, connect it to the relevant services, leave everything else untouched.

Context management is critical here. A 30+ node architecture with full properties eats a massive chunk of the context window. I aggressively summarise: the LLM doesn't need every property, just the structural skeleton. If details are omitted from model context, the application must decide explicitly whether to preserve, replace, or invalidate them.

Conversation history handles reference resolution across turns. "Make that database a cluster," which database? The one from the last turn. "Add a cache in front of it," in front of what? The service we just discussed. That context flows into every prompt.

Multiple providers give a generation workflow recovery options, but fallback is a policy choice, not a universal guarantee. A supported general-generation route may switch providers; a request pinned to the user's own key must respect that choice. Failures can still exhaust every permitted route.

I maintain provider-specific prompt variants. One model tends to over-generate and adds components nobody asked for. Another under-specifies edges, creating nodes but forgetting to connect them. The prompt variants compensate for those tendencies. The routing itself, and why a single provider is a liability, is a longer story I told in how Codelit's multi-provider fallback works.

A common validation boundary keeps provider-specific response shapes away from the renderer. It does not remove differences in reasoning, latency, or architectural quality. A well-formed graph still needs review.

I would define the graph contract and edit-preservation rules before polishing the first generation. Those decisions determine what can be validated, what a follow-up is allowed to change, and how the user recovers when the proposed update is wrong.

I wasted months wrestling with inconsistent LLM output before realising that enforcing a structured contract is an engineering problem, not an AI problem. Retrofitting statefulness onto a pipeline that assumed every generation was independent was the same lesson in a different costume.

For a complex system, staged generation is worth evaluating: establish the data boundary, then the application responsibilities, then the external interfaces. I would compare it against a fixed set of tasks before claiming it produces better architecture.

The same structured-output backbone drives two more canvases now: product boards and agent workflows. A generated agent workflow is a design to inspect, including model routing and approval gates. Real execution needs separate provider access, runtime checks, and outcome evidence. If you want the rest of that story, how Codelit got built starts with a Lucidchart rage-quit.

Try it yourself at codelit.io and check out the full feature set. The useful output is not the first plausible diagram. It is a draft you can inspect, correct, and keep editing without losing your work.