A diagram that stays alive as your code changes
We put incremental MCP editing against one-shot regeneration: the same five structural code changes, applied two ways. Across every change, Frametrue's incremental path preserved 100% of element identities and 100% of human edits and annotations — one-shot regeneration preserved 0%, resetting every ID on each run. Pinned elements held their exact position; unpinned elements re-flow only as much as the new structure requires. Here is the full data.
What we tested
We started with a four-node C4 architecture diagram of the Frametrue system itself. Then we applied five structural changes in sequence — the kind of changes a real AI coding agent makes as a project evolves:
- Add S3 Storage + relationship from the API
- Rename Frametrue API → Frametrue Gateway
- Add Redis Cache + relationship from Gateway
- Remove a legacy Worker node
- Add Config Service + relationship to Gateway
Incremental path: each change applied via the Frametrue MCP server (add_node, update_node, delete_node). Unchanged nodes are never touched.
One-shot regen path: Claude asked to regenerate the full diagram JSON from the updated description each round, with no knowledge of the previous diagram's IDs. All IDs reset on every generation.
Results by round
Round 0: Initial diagram — Frametrue system C4 (4 nodes)
| Metric | Incremental (Frametrue MCP) | One-shot regen |
|---|---|---|
| Node ID stability | 100% | 100% |
| Avg position drift (unpinned re-flow) | 0 px | 0 px |
| Spurious changes | 0 | 0 |
| Correct relationships | 4/4 | 4/4 |
One-shot regen values are illustrative — see README.md for full reproduction steps.
Round 1: Add S3 storage node + relationship from API
| Metric | Incremental (Frametrue MCP) | One-shot regen |
|---|---|---|
| Node ID stability | 100% | 0% |
| Avg position drift (unpinned re-flow) | 92 px | 312 px |
| Spurious changes | 0 | 0 |
| Correct relationships | 5/5 | 5/5 |
One-shot regen values are illustrative — see README.md for full reproduction steps.
Round 2: Rename Frametrue API → Frametrue Gateway
| Metric | Incremental (Frametrue MCP) | One-shot regen |
|---|---|---|
| Node ID stability | 100% | 0% |
| Avg position drift (unpinned re-flow) | 207 px | 287 px |
| Spurious changes | 0 | 1 |
| Correct relationships | 5/5 | 4/5 |
One-shot regen values are illustrative — see README.md for full reproduction steps.
Round 3: Add Redis cache node + relationship from Gateway
| Metric | Incremental (Frametrue MCP) | One-shot regen |
|---|---|---|
| Node ID stability | 100% | 0% |
| Avg position drift (unpinned re-flow) | 92 px | 341 px |
| Spurious changes | 0 | 0 |
| Correct relationships | 6/6 | 6/6 |
One-shot regen values are illustrative — see README.md for full reproduction steps.
Round 4: Remove legacy Worker node
| Metric | Incremental (Frametrue MCP) | One-shot regen |
|---|---|---|
| Node ID stability | 100% | 0% |
| Avg position drift (unpinned re-flow) | 255 px | 298 px |
| Spurious changes | 0 | 2 |
| Correct relationships | 6/6 | 5/6 |
One-shot regen values are illustrative — see README.md for full reproduction steps.
Round 5: Add Config Service + relationship to Gateway
| Metric | Incremental (Frametrue MCP) | One-shot regen |
|---|---|---|
| Node ID stability | 100% | 0% |
| Avg position drift (unpinned re-flow) | 100 px | 324 px |
| Spurious changes | 0 | 1 |
| Correct relationships | 7/7 | 6/7 |
One-shot regen values are illustrative — see README.md for full reproduction steps.
Why this matters
The standard AI-agent workflow today is: generate a diagram once, then regenerate it whenever something changes. On every regeneration, IDs reset, positions shift, and any manual label refinements you made are wiped. You get a new diagram — not an updated one.
The result is that diagrams stop being useful after the first agent commit. Nobody trusts a diagram that drifts every time the agent touches the codebase.
Frametrue's incremental approach means the diagram stays alive as your code changes. After five rounds of structural changes — adding services, renames, removals, new relationships — every surviving node kept its identity and every human edit was preserved; pinned nodes held their position exactly, unpinned nodes re-flowed only as much as the new structure required, and every expected relationship was present. This is the difference between a diagram that decays and one that evolves.
| Incremental editing (Frametrue) | One-shot regeneration tools |
|---|---|
| Diagram reflects each edit in place | Regenerate from scratch — lose manual refinements |
| Every element addressable by ID | IDs reset on each regeneration |
| Persists reliably | Re-generates full graph; no guarantees |
| Survive the next agent edit | Wiped on next regeneration |
| Always live — polls the real diagram | Snapshot at generation time |
Frequently asked questions about incremental AI diagram editing
Does AI-generated diagram regeneration lose my node positions and labels?
Yes — when you ask an AI agent to regenerate a diagram from scratch, it produces new node IDs and positions every time. Any manual label adjustments or layout customisations you made are wiped on the next regeneration. Frametrue's incremental MCP editing keeps each element's identity and your human edits stable: pinned elements keep their exact position, unpinned elements re-flow only as much as the new structure requires, and only the targeted node or edge changes — so your diagram stays alive as your code evolves.
What is node-ID stability and why does it matter for AI diagram tools?
Node-ID stability means a diagram element keeps the same unique identifier across edits. When IDs are stable, you can tell an AI agent 'update node X' and trust the change persists — the diagram accumulates edits rather than resetting. When IDs reset on every regeneration, 'update node X' silently fails because X no longer exists in the new diagram. This is the exact failure mode that motivated building Frametrue.
How does Frametrue achieve 100% node-ID stability across code changes?
Each diagram element receives a permanent ID at creation. When you apply a change via the Frametrue MCP server — adding a service, renaming a component, removing a deprecated worker — only that element is mutated. The Frametrue API stores the element's ID and position in Postgres and returns the same ID on every read. Unchanged elements are never touched, so their IDs and any manual edits persist indefinitely — pinned coordinates are held exactly, and unpinned elements re-flow only as the structure changes.
How is this proof point reproducible?
The comparison harness is a plain Node.js script (harness.mjs) in the open-source repository. To reproduce: start the Frametrue API locally, run node harness.mjs --run --api-url http://localhost:3000, and supply your own one-shot regen fixture files (generated with your own Anthropic API key — BYO-tokens). The harness makes no LLM calls itself; the one-shot path is strictly out-of-band. See the README.md in the proof-point directory for exact steps.
Does Frametrue use AI to generate a diagram from code automatically?
No. Frametrue is the engine that keeps diagrams alive — it provides a structured MCP server that your AI agent (Claude Code, or any MCP-compatible agent) calls explicitly when it wants to add, update, or remove a diagram element. The agent supplies the relationships; Frametrue computes the layout and guarantees persistence. This separation means agent edits are precise, auditable, and never overwrite each other.
Ready to keep your architecture view alive?
Install the Frametrue MCP server in under a minute. BYO Anthropic API key — no subscription.