Learn

Architecture & pattern guides

Read the idea, build it on a Grid, prove it in a challenge. Short, practical guides — illustrated with RodGrid's own nodes — on system design, design patterns, flow modeling, and how to get the most out of the app.

All articles

AI Architecture Analysis: a review of your diagram

Get an AI review of the architecture you drew: what is wrong, what is at risk, and what is still undecided.

What comes back, top to bottom

  • Verdict. One of five: Ready, Needs changes, Invalid, Not assessable, Partially assessed. Ready is hard to reach on purpose: it needs no findings, no contradictions, and every area actually assessed.
  • Priorities. Up to three findings, most severe first.
  • By area. Seven of them: Security, Data & consistency, Scale & performance, Resilience, Contracts & integration, Cost, Operations & observability. Each lists its findings, or what it checked and found fine, or says it could not be assessed from the diagram.

After those come Open decisions, what the Grid leaves for you to decide; Room to grow, for when the system gets bigger, where a replacement is only ever a component from the catalog; and Diagram inconsistencies, where the Grid contradicts itself.

That is Architecture Analysis: a verdict and findings on the design you drew. For a description of the Grid with no severity and no verdict, use Checking a diagram: Explain and Simulate.

Reading one finding

A read that goes around the API

The edge from Storefront to Orders DB is the kind of thing that gets filed: a client reading a database directly, around the API. A finding opens with a severity and a category, may carry a defect code (here, Layer bypassed), then gives the evidence on the Grid and a recommendation. The nodes it cites appear as chips, and a chip can jump to its node. Wording and severity can vary between runs, so check whether the evidence is something you actually drew.

This Grid says nothing about how the Storefront signs in, and that is not a finding. It only reports what your Grid shows: a mechanism it does not draw (authentication, monitoring, backups) comes back as an open decision instead of a problem, while a label saying a call has no timeout is evidence, because you wrote it. A small Grid is not faulted for being small, and cost and scale work from the load your Grid states: without one, they say what they assume instead of inventing numbers.

It writes no implementation spec, because a diagram says which parts talk to which and why, and usually leaves out the data, rules and screens of the product. It writes no product requirements either, because a diagram rarely states the problem, the users, or what success looks like. Writing a PRD from the diagram, in the same panel, asks you for those.

Running it

On a Diagram Grid, the Analysis Model button in the top bar brings up the Analysis panel, and Generate Architecture Analysis there shows its price. It stays disabled on an empty Grid and when your balance is short. Challenge Grids do not offer it.

NoteArchitecture Analysis spends AI credits: credits, not a plan. One run costs 25. Every new account starts with a one-time welcome grant (10, enough to try Explain, not a full analysis), the Pro plan and above add a monthly allowance, and a purchased pack is spendable whatever plan you are on. A very large Grid costs a little more: see AI credits: what they buy and how they are spent.

The run does not live in your tab: close it, or lose the connection, and the job keeps running on the server. If it succeeds, the result is waiting when you reopen the Grid, with earlier runs listed under Analysis history; if it fails, the panel says so in the browser that started it. Change the nodes or edges a run read, rather than just the layout, and that run moves from Current to Outdated: the original stays as it was, and only a new run reads the new drawing.

What the review can see

It reads each node's title, type and description, and each edge's label. Governance fields, comments, sticky notes and shapes are not part of what it reads. So the clearer your nodes and edges, the sharper the analysis:

  • Default titles and bare edges. The analysis inherits every ambiguity on the Grid. Naming nodes: inline rename & the inspector has the habit.
  • Unlabeled relationships. An edge that does not say what flows becomes a guess, and Contracts & integration can file the missing label itself. Label edges before generating; Connecting & styling edges shows how.
  • No stated load. Scale and cost have nothing to measure against. Write the figure where the review reads it, in a node's description: "800 requests per second at peak".
  • Treating the result as final. It is one reviewer's opinion. Check each finding against your intent as you would a teammate's review.

Test it on a system you know

On a Diagram Grid, draw a small, fully labelled diagram of a system you know well, including its real problems. Run it once and go through the findings against what you intended. For each wrong one, check the evidence it cites: if the Grid is unclear there, fix that part; if the Grid is clear, the review misread it, so ignore the finding.

Practice this