Compare your app's architecture between two releases
By Flavio
Save each release as a version in Architecture Dissector, then see which components, connections and tables changed between any two of them.
You shipped 1.1.0 a month ago, and now someone asks what changed in the app since 1.0.0. Not the commit list, which has 80 entries about typos and button colors. They want the structure: which parts are new, which ones went away, and whether the database changed.
A git diff between two tags can’t answer that. It shows lines, not components. The release notes say what users see, not how the app is built underneath.
Architecture Dissector answers it from maps your coding agent writes. You save the map as a version at each release, and the blueprint diff command lists what was added, removed and changed between any two versions. The Mac app shows the same comparison on the diagram, in color.
At the end you’ll have two releases saved, including one that shipped before you started, a comparison you can paste into a review, and a habit that keeps the next comparison free.
What you need
Architecture Dissector runs on macOS 14 Sonoma or later, on Apple silicon and Intel Macs. After buying it, download the app zip from your Polar receipt, unzip it, and drag Architecture Dissector to your Applications folder. The receipt also has the full MIT source code of the same version.
You need a coding agent that can run shell commands, to write the maps. The agent skill that comes with the app links itself for Claude Code, Cursor and Codex.
Your project has to be a git repository with a tag for each release you want to compare, like v1.0.0 and v1.1.0. Mapping an old release reads the code at its tag, and saving a version without a name uses the tag on the current commit.
Open Architecture Dissector once, then use two items in its application menu:
- Install Command Line Tool links
blueprintinto/usr/local/bin. - Install Agent Skill copies a skill to
~/.agents/skills/blueprintand links it for those three agents.
The preflight check is one command in Terminal:
blueprint --version
blueprint 1.3.1
If the app isn’t mapped yet, start with Draw the architecture of an app an AI agent built, which covers the first map in detail.
The project, paths and commit hashes below come from a real run on a small made-up Mac app called Recipe Box. The names are examples.
Understand what a version is
A version is a frozen copy of the map, not of the code. When an agent saves a map with blueprint set, Architecture Dissector stores the JSON along with the commit and a hash of every file it describes. A version copies that map under a name, like 1.1.0, and keeps it forever. Without versions there’s nothing to compare: the current map only ever tells you how the app looks today. That’s why saving one at each release matters more than anything else in this tutorial. If you skip a release, its structure is gone from the history, and you’d have to map it again from the old code.
Here’s the whole loop, from the first map to a comparison:
Comparisons work by id. Every component, connection and table in the map has one, like store or sync-worker. Two versions are matched id by id, so a component that keeps its id but gets a new description shows as changed, and one whose id disappears shows as removed.
Map a release that already shipped
Most people start using Architecture Dissector after a few releases are out. Those releases still matter, because the first comparison you’ll want is usually “what changed since the last big version”. The guide that ships with blueprint has a section for this: the agent extracts the old tag into a temporary folder with git archive, reads that code, and saves its map with --past. The --past flag is what keeps your current map safe. Without it, blueprint set replaces the current architecture, and the diagram would show 1.0.0 as if it were today’s app.
The easiest way is the prompt from the README, which asks the agent to include past releases in the first map:
Add this app to Architecture Dissector and map it, including its past releases. Run `blueprint guide` and follow it.
The agent extracts each tag without touching your working tree:
mkdir -p /tmp/recipe-box-1.0.0 && git archive v1.0.0 | tar -x -C /tmp/recipe-box-1.0.0
Then it writes the map of that code, reusing the ids of the newer map for every component that already existed, and saves it from the project folder:
blueprint set --file /tmp/recipe-box-1.0.0.json --version 1.0.0 --past
warning: Component importer lists Sources/RecipeBox/Importer.swift, which doesn't exist in /Users/flavio/dev/recipe-box.
warning: There are no flows. Map every workflow of the app, from users, the owner, agents and the app itself: run blueprint guide to see how.
warning: There are no explainers. Add 2 to 6 short videos about parts of the app: run blueprint guide to see how.
Saved Recipe Box 1.0.0 (at 38bdd10): 6 components in 2 groups, 5 connections, 3 overview blocks, 1 entity. The current architecture is unchanged.
The first warning is expected here. The web importer was removed after 1.0.0, so its file isn’t in today’s folder. Warnings are saved anyway. The last line is the one to check: it names the tag’s commit, and it says the current architecture is unchanged.
Save a version when you ship
From now on, saving a version is one command at release time. Run it after the map matches the code you’re shipping, because a version is only as accurate as the map it copies. If the agent changed the code but didn’t update the map, the version freezes a stale picture, and every later comparison starts from the wrong place. That’s why the order is: agent updates the map, you tag the release, then you snapshot. On a tagged commit you don’t need to name the version, because blueprint snapshot uses the tag without its v:
blueprint snapshot
Saved the current architecture of Recipe Box as version 1.1.0.
In the app, the same thing is the + at the end of the timeline under the diagram, or Diagram → Save Current as Version… (⌘S). It asks for a name, suggests one, and saves it.
blueprint versions lists what you have, oldest first, then the current map:
blueprint versions
1.0.0 saved just now at 38bdd10, 6 components
1.1.0 saved just now at 89bb61f, 7 components
current saved just now at 89bb61f, 7 components
Run the snapshot twice and the second run stops instead of overwriting. On a commit with no tag, you’ll get an error and need to pass --version yourself. Both are covered at the end.
Compare two releases from the terminal
This is the part you came for. blueprint diff matches the two versions id by id and prints three lists: components, connections and data. It’s a structural summary, so it ignores everything a git diff is full of, like formatting, renamed variables or new tests. Without options, it compares the newest saved version with the current map, which is what you want during development. Between releases, pass both ends. Run it from the project folder, or pass the app id when you’re somewhere else.
Example 1: what changed between 1.0.0 and 1.1.0. We added cloud sync and dropped the web importer in this release, and added a column to the recipes table:
blueprint diff --from 1.0.0 --to 1.1.0
Recipe Box: 1.0.0 → 1.1.0
2 added, 1 removed, 1 changed, data: 1 changed
+ Sync client (sync-client, service)
Sends local changes to the sync worker.
+ Sync worker (sync-worker, worker)
Receives changes from every Mac and hands them back.
- Web importer (importer, service)
~ Recipe store (store, service)
New description
Connections
+ Recipe store → Sync client reports changes
+ Sync client → Sync worker pushes changes
- Web importer → Recipe store saves imports
+ group Cloudflare Worker
Data
~ recipes (recipes)
Added field tags
Read it top down. + is new, - is gone, ~ changed. The store shows as changed because its description now mentions tags. The new Cloudflare Worker group tells you part of the app now runs somewhere it didn’t before, which is the kind of fact a reviewer cares about most.
From any other folder, name the app first:
blueprint diff recipe-box --from 1.0.0 --to 1.1.0
To compare a release with today’s map, use --to current, or leave --to out.
Hand the comparison to a reviewer or an agent
The text output is for you. For a pull request description, release planning or another agent, the JSON version is easier to work with, because each list is already split into added, removed and changed ids. An agent preparing release notes can read it and know which parts to describe, without reading 80 commits. A reviewer gets the same thing pasted under a heading. Without it, you’d copy the text and someone would reformat it by hand.
Example 2: the same comparison as JSON.
blueprint diff --from 1.0.0 --to 1.1.0 --json
{
"from" : "1.0.0",
"changed" : [
{
"details" : [
"New description"
],
"id" : "store"
}
],
"connections" : {
"changed" : [
],
"removed" : [
"importer->store"
],
"added" : [
"store->sync-client",
"sync-client->sync-worker"
]
},
"removed" : [
"importer"
],
"to" : "1.1.0",
"added" : [
"sync-client",
"sync-worker"
],
"entities" : {
"changed" : [
{
"details" : [
"Added field tags"
],
"id" : "recipes"
}
],
"removed" : [
],
"added" : [
]
}
}
Connections are written as from->to ids. Entities are the tables and files the app stores, compared field by field, so a migration shows up as fields added, removed or changed. If you only care about the schema, Show your coding agent the database schema before it changes code goes deeper on that side.
To make every agent read the map before it touches the code, add the snippet from the README to the project’s AGENTS.md. I wrote about how agents read that file in AGENTS.md.
See the comparison on the diagram
The terminal tells you what changed. The diagram tells you where, which matters once a release touches more than a few parts. In the Mac app, the timeline under the diagram has one capsule per version and one for the current map. Comparing two of them colors the diagram: new components in green, changed ones in amber with what changed, removed ones in red. The Data tab shows how the schema migrated, field by field. Without the timeline you’d be matching the diff’s ids to boxes by hand.
There are two ways to start a comparison:
Timeline under the diagram:
1.0.0 → 1.1.0 → Current +
^ click the arrow between two versions
("Show what changed from 1.0.0 to 1.1.0")
Right-click a version capsule:
Changes Since 1.0.0
─────────────
Delete Version 1.0.0
The inspector then shows What changed, with a line like “1.0.0 → 1.1.0: 2 added, 1 removed, 1 changed.” To leave the comparison, press Esc, click the x in the comparison pill, or choose Diagram → Stop Comparing.
blueprint open --compare 1.0.0 opens the app on the current map with changes since 1.0.0 highlighted, which is handy when an agent finishes a diff and you want to look yourself.
Delete Version in that menu has no confirmation step. It moves the version file to the Trash, so put it back from the Trash if you click it by mistake. The terminal equivalent is blueprint snapshot --version 1.0.0 --delete, which prints “Moved version 1.0.0 of Recipe Box to the Trash.”
Keep ids stable, or the comparison lies
This is the one rule that makes everything above trustworthy. Because versions are matched by id, renaming an id breaks the history of that part. The guide asks agents to keep the id of every component and entity that still exists, even when they rename it, and to change only its name. An agent in a hurry sometimes rewrites the map from scratch, picks fresh ids, and saves. Nothing fails, but the next diff reports a part as removed and a new one as added.
Example 3: a rename that looks like a removal. Here an agent renamed the sync worker and changed its id from sync-worker to sync-api:
blueprint diff
Recipe Box: 1.1.0 → current
1 added, 1 removed
+ Sync API (sync-api, worker)
Receives changes from every Mac and hands them back.
- Sync worker (sync-worker, worker)
Connections
+ Sync client → Sync API pushes changes
- Sync client → Sync worker pushes changes
Same summary, same role, different id. That’s the tell. The fix is to put the old id back and keep the new name. Ask the agent to restore sync-worker as the id, or edit it yourself:
blueprint show --json > /tmp/recipe-box.json
# set "id": "sync-worker" back on the Sync API node and in its connections
blueprint set --file /tmp/recipe-box.json
blueprint diff
Recipe Box: 1.1.0 → current
No changes.
With the old id back and the new name kept, the diff reports what really happened:
Recipe Box: 1.1.0 → current
1 changed
~ Sync API (sync-worker, worker)
Renamed from Sync worker
Between releases, blueprint status tells you when the code moved on since the map was saved, and which components the changed files belong to:
blueprint status
Recipe Box: 1 file changed since the architecture was saved just now at 89bb61f, 1 commit ago.
Components with changed files:
Recipe store (store)
Sources/RecipeBox/Store.swift
Have the agent update the map whenever this lists something, so the next snapshot copies an accurate picture.
If something looks wrong
- If
blueprint diffsaysRecipe Box has no version 0.9.0. Its versions: 1.0.0, 1.1.0., the version was never saved. Pick one from that list, or map the old tag with--pastfirst. - If
blueprint snapshotsaysPass the version, like --version 1.2.0. The current commit has no tag to use., tag the release commit, or pass--versionyourself. - If
blueprint snapshotsaysRecipe Box already has version 1.1.0. Use --force to replace it., that version exists.--forceoverwrites it, and the old copy is gone, so use it only when the saved one was wrong. - If you get
This folder isn't inside an app Architecture Dissector tracks. Add it with: blueprint add ., you’re outside the project.cdinto it, or pass the app id, likeblueprint diff recipe-box. - If a diff shows one component removed and a near-identical one added, an id changed. Restore the old id, as in Example 3.
- If the diff says
No changes.but you know the code changed, the map wasn’t updated. Runblueprint statusand have the agent update the map before you snapshot. - If saving a past version warns that a component’s file
doesn't exist, the paths are checked against today’s folder. For a component removed since that release, the warning is expected and the version is saved. - If an older version is missing from the Flows or Data timeline, it was saved before those parts were mapped. The app shows a prompt to paste into an agent, which fills them in from that version’s code.
Get Architecture Dissector
Explore your apps through architecture diagrams, workflows, data maps and version comparisons. Includes the Mac app, blueprint CLI and full MIT source.
See Architecture Dissector → · Read the docs · $20. See the app page for tax details, with full source code.
Want me to talk about your product? You can sponsor this site.