A generated diagram is only useful if the engineer can disagree with it.
That is why I built Codelit's architecture surface on React Flow. The graph stays editable: move a component, change a connection, inspect its role, or replace part of the design.
Make the graph readable
The canvas distinguishes familiar component families such as services, databases, queues, caches, gateways, CDNs, and external systems. The visual treatment helps a reader recognize a role before opening its details.
Those roles describe the proposed architecture. They are not live telemetry. An animated edge communicates an intended direction of flow, not evidence that a request passed through a deployed system.
Keep identity stable
Node and edge IDs connect model output, layout, selection, and editing. If an update changes identity unnecessarily, the application can lose selection, attach an edge to the wrong node, or overwrite a manual adjustment.
I treat layout as a separate responsibility from rendering. Automatic placement gives the diagram a starting structure; manual edits let the user make it legible for the conversation they are having.
The canvas implementation article covers custom rendering, Dagre layout, and the trade-offs behind that separation.
Make edits recoverable
Undo and redo are part of the product contract, not just toolbar buttons. The canvas records architecture versions so supported edits can be reversed.
The engineering questions are concrete: when should a drag become one history entry, what belongs in a snapshot, and what should happen when a model update arrives while the user is editing? A new diagram should not silently erase the work that made the old one useful.
| Concern | Design goal |
|---|---|
| Selection | Survive unrelated updates |
| Layout | Separate automatic placement from user intent |
| History | Restore meaningful graph states |
| Connections | Preserve valid endpoints and labels |
| Model changes | Keep the proposed change inspectable |
Show context without claiming certainty
Component descriptions and relationships make a node more useful than a box with a label. They explain why a component appears in the proposal and what it connects to.
Generated explanations still need review. A convincing description is not proof that the component is necessary or that its failure behavior has been tested.
That distinction matters when exploring a template or a repository-derived diagram.
The result
The canvas turns model output into material an engineer can work with. It connects generation to inspection rather than asking the user to trust a finished-looking picture.
Open Codelit, create or load an architecture, and make one deliberate change. The useful question is whether the design becomes easier to explain afterwards.