My project, worklore, is a small app that grew in all directions: a Python backend on AWS Lambda, a plain-JS site, an MCP connector for agents, and four more repos around it. I wanted a picture of it I could trust. So in one day I ran three open-source tools that turn code into a diagram or a map, all three as plugins for Claude Code:
- Floorplan: a map of the app with its parts, endpoints and user flows.
- Archify: one architecture diagram, every box linked to the exact lines of code.
- Understand Anything: a knowledge graph of every file, function and class, with a guided tour.
Floorplan's README has a nice table comparing the three. It says what each tool answers and who it's for. It has no time, no cost and no pictures of the other two. This post fills that in, on one real codebase, and then does the test I actually care about: can each one answer real questions about my own code?
The short version
| Floorplan | Archify | Understand Anything | |
|---|---|---|---|
| What you get | a map you can click through, with flows | one diagram, boxes linked to code | a graph of 732 nodes with a tour |
| Time to first result | a few minutes | about an hour, with two failed runs and two card fixes | 14 minutes |
| Cost | on my Claude plan, not measured separately | on my Claude plan, not measured separately | $13 at API prices (measured) |
| Answers questions | yes, an Ask bar | no | yes, a chat command |
| What went wrong | user flows written from memory, two of them wrong | cards written from memory, one wrong twice | nothing I could find |
Floorplan: the map is right, the flows were not
Floorplan read my 166 files and drew them as parts with plain-words descriptions. The first surprise: it found 0 endpoints. My server keeps its routes in one table keyed by "METHOD /path", not in a framework router. I opened a pull request to read that shape, and the author merged it 70 minutes later. Then it showed all 66.
The real trap was the user flows. While building the map, the agent also wrote flows, and it wrote them from its memory of my app. One said a person can publish a story from the website. The site can't do that. Another got wrong how a story gets drafted for someone else. A wrong flow and a right one look the same on the map.
What fixed it was a button Floorplan already has: Request a new flow. You describe a flow in plain words, and the agent traces it through the code, tying every step to a route or a function. I deleted the hand-written flows and requested 17. Then I ran 16 of them against a staging copy of my backend: 14 work, one partly, one can't be tested there. The 17th, a nightly job on my Mac, had been quietly failing for two nights.
I wrote it up step by step, so your agent can redo it on your app: My agent drew my app's user flows from memory and got two wrong; Floorplan's traced ones were right.
Archify: one diagram for five repos
Archify draws from a JSON description and then checks it hard: every cited line must exist at the pinned commit, and the last check opens the diagram in a real browser. What its docs don't say up front: a diagram pins exactly one repository. My project lives in five, and the links between them aren't code at all. One repo is a skill that tells an agent to call my API with curl; another is a scanner my server keeps a copy of. A tool that follows imports sees five islands.
So I pinned the repo where the system runs, linked its boxes to lines of code, and drew the other repos as named boxes with a card saying what each holds. Two runs failed first: my SSH remote was rejected for web links (the HTTPS form works), and my uncommitted edits shifted line numbers away from the committed bytes Archify checks against.
Archify proves the cited lines exist. It does not prove what a card says. One of mine, "how stories get written", was wrong twice, again from my agent's memory. The full recipe: One architecture diagram for a project split across five repos, with Archify.
Understand Anything: the most thorough, the most expensive
I ran Understand Anything headless, so I got exact numbers: 14 minutes, 16 helper agents working in batches of five, and $13.01 at API list prices (on a Claude subscription it comes out of your plan instead). Its README warns that the first run uses a lot of tokens. It does.
What you get is a lot: 732 nodes (files, functions, classes, config, docs), 1,625 links, 9 layers, and a 15-step tour that starts at the README and walks through the code in a sensible order. Every function has a one-line summary. I checked the summaries in the places where my agent had been wrong from memory, and they were right.
Two things to know before installing it. Its start-of-session hook tells the agent to rebuild a stale graph and "Do not ask the user for confirmation" (only if you turn auto-update on). And its dashboard runs as a local server; in a headless run it died after 10 minutes, when Claude Code stops background jobs.
It feels made for someone else's project: the tour and the summaries teach you a codebase you've never seen.
The real test: three questions about my own code
Pictures are nice. What I wanted was answers. I asked each tool the same three questions, the kind I'd ask before changing anything:
- How do we decide whether a person has enough rights for an action, in the MCP connector and in the REST API?
- What numbers do we keep about reproductions and other actions, including anonymous ones?
- What do we log, and where?
Floorplan got them in its Ask bar, Understand Anything in its chat command, and for Archify an agent that could see only the diagram. Then a plain agent with no map at all read the code to make an answer key.
| Floorplan | Understand Anything | Archify | No map, just code | |
|---|---|---|---|---|
| Time | 61 s | 91 s ($0.72) | 33 s ($1.18) | 166 s |
| Rights | right, short | right, most detailed | "reading is public, writing needs a token" | complete |
| Counters | right, about half | right, nearly complete | almost nothing | complete |
| Logs | right, short | right, detailed | one line | complete |
| Mistakes | none | none | none, and it said what it didn't know | — |
Nobody made anything up, which already beats my agent's memory. But look at how they got there. Floorplan's Ask reads the map and the code, by design. Understand Anything's chat is meant to answer from the graph, yet it opened the source files anyway and said so. Archify has no way to answer questions, and the diagram simply doesn't hold this level of detail.
And the plain agent reading code found things none of the three did. The biggest was a security hole. When an AI app connects to worklore through OAuth, the sign-in advertised two permissions, worklore.read and worklore.write. The code never checked them. The app got an ordinary account pass, and that pass also worked on the site's REST API: it could delete my stories, change their visibility, and, since I'm the admin, open the admin pages. All three maps described the sign-in correctly, as a flow. None of them asked what the token could reach once issued, because that isn't a box or an arrow.
I fixed it before publishing this. An app's pass is now marked as one, works only through the connector, and only within what you approved; an app that asks only to read can't write. A new test walks the whole OAuth flow and then tries the pass on every kind of route.
The same agent found more places where my code and my own documents disagreed. My privacy page left out Google sign-in, described "standard server logs" with IPs that my application doesn't write (the CDN logs do, for 14 days), and called my analytics page-views-only when the server also sends events, some with the caller's IP, and the site sends the text of searches that find nothing. Smaller ones: a doc that says a log field holds a raw id when the code hashes it, a counter that also counts HEAD requests, agent reads over MCP that never count as reads, and staging logs that were kept forever (now 90 days, like production). I rewrote the privacy page against the code; the rest of the smaller ones are on my list. None of it is "architecture", so no map shows it.
So which one should you use?
- You inherited a codebase, or you're about to contribute to someone else's: Understand Anything. The tour and the per-function summaries are the fastest way in, if the token bill is fine.
- You own a small app and want to know what users can actually do: Floorplan, but delete every flow it wrote while building the map and request them again, so each step is traced to code. Then test them.
- You need one picture for a README, a pitch or a new teammate: Archify. It's the only one whose output is a single, checked diagram you can share. Check the cards yourself.
- You need to know whether your code keeps your promises: none of them. Ask an agent to read the code with that exact question.
The one habit that works with all three: before trusting a map, ask it three questions you already know the answers to. It takes two minutes and tells you which parts were traced and which were remembered.
Both write-ups above are on worklore as stories your agent can redo: what I tried, what failed, the exact steps, and how to check it worked. If you run either one on your own repo, the story page shows whether it worked for other people too.



Top comments (26)
The test at the end is the part I'll steal — ask it three questions you already know the answers to before trusting the map. A clean-looking diagram drawn from memory is worse than no diagram, because it gives you false confidence.
For someone running a small tool, Floorplan's traced flows sound like the most useful of the three. Knowing what users can actually do matters more than having a pretty picture of the parts. And the OAuth scope find is a good reminder: a diagram shows that A connects to B, not what A is allowed to do once it's connected.
Thanks! I agree about Floorplan's flows: requesting traced flows is also how I found a nightly job that had been quietly failing for two nights, so that part paid off right away. Your last point is where I went next. Nan asked below whether a diagram can show what a connection is allowed to do, and when I wrote down every pass in my project, I found that none of them could be ended early. That's fixed now. Next I'm putting the passes and their rights on the diagram's arrows, and I'll share the results next week.
The finding about OAuth scopes illustrates why architecture diagrams fail as security controls. A graph treats an API route as a topology problem, showing that client A connects to endpoint B. It does not model authority or state transition constraints. Spending $13 on 700-node graph generation maps connectivity, but the actual security boundary is always runtime policy enforcement. Testing three known questions directly against code remains the most reliable verification heuristic.
Agreed: a diagram shows that A connects to B, and says nothing about what A is allowed to do once it's there. One thing I'd add: the three-questions test wouldn't have caught this hole. It tells you whether to trust a map, and it only works with questions you already know the answers to. I didn't know this one. It turned up when an agent read the code with a direct question about rights, and what guards it now is a test that walks the OAuth flow and tries the pass on every kind of route.
What makes this comparison particularly valuable is that you went beyond evaluating how impressive the diagrams looked and tested whether they could actually help you understand your own system. That distinction matters enormously, especially as AI-generated documentation becomes increasingly common.
The most revealing part, to me, was discovering that all three tools could produce useful architectural representations while missing a significant OAuth authorization vulnerability. A diagram can accurately describe how components communicate without revealing whether those interactions respect the security boundaries they are supposed to enforce. That is a fundamental difference between documenting a system's structure and verifying its behavior.
I also found the recurring problem with the agent relying on its memory fascinating. When an AI tool generates a convincing explanation based on incomplete context, the result can appear authoritative precisely because it is presented so clearly. The incorrect user flows illustrate how easily plausible descriptions can become accepted documentation. Your decision to replace those flows with code-traced versions, then test them against staging, demonstrates why verification must remain part of the process rather than an optional final step.
Another important observation is that source-code references provide traceability, but traceability alone does not guarantee correctness. Archify could verify that referenced lines existed, yet the accompanying descriptions still required human examination. This is a useful reminder that evidence and interpretation are separate things. A citation tells us where information came from; it does not automatically establish that the conclusion drawn from it is accurate.
The discrepancies between your privacy documentation and actual application behavior introduce an equally important dimension. Architecture tools generally explain how software is organized, but users and regulators are ultimately concerned with what software actually does. Logging practices, authentication permissions, data collection, and retention policies are not merely implementation details. They represent promises that organizations make about how their systems operate.
I particularly appreciate your recommendation to ask three questions whose answers you already know before trusting a generated map. It is a practical way to establish confidence without assuming that a polished visualization is necessarily a faithful representation of reality.
Perhaps the broader lesson is that AI-assisted software understanding needs multiple layers of verification: structural mapping to understand the components, behavioral tracing to understand the workflows, and independent testing to establish whether the system actually behaves as intended.
The most useful AI development tools may not be those that produce the most comprehensive diagrams, but those that make their assumptions visible, acknowledge what they cannot establish, and help developers investigate discrepancies.
And there is something wonderfully ironic about your experiment: you started by looking for a reliable picture of your application and ended up discovering a security vulnerability, documentation inconsistencies, and a failing background job. That is a far more meaningful outcome than simply generating a beautiful architecture diagram.
The real value was not the map itself. It was the questions the mapping process encouraged you to ask.
Thank you for such a careful read. I agree that a citation only shows where a claim came from, not that it's right, and Archify was the clearest example of that for me. The privacy page was the part I didn't expect: I wrote it myself, and the code still disagreed with it in four places.
nice comparison. circular dependencies are always where diagram tools fall over, good to see you tested that case. bookmarking for the next repo audit lol
Thanks! To be honest, I didn't test circular dependencies. The closest thing was links between repos: my project lives in five, and none of the tools could follow those links, because they aren't imports. Have you seen a tool fail on a cycle? I'd like to try that case next.
I don't imagine to use a graph to validate my code. Instead I use a much lazy task: try to found the connection between my articles, repos, nppm modules adding a tiny bit interaction make the stuff one of my favorite personal application.
Thanks! I did something close for my own site: a small check that walks it the way Google does, following only real links, and shows which articles nothing links to (crawl-like-googlebot (github.com/worklore/crawl-like-goo...). Does linking your articles, repos and npm modules together bring you more readers? I'd like to know if people actually follow those links from one piece to the next.
Testing each tool on real questions about your own code is the comparison that matters, since a diagram can look right and still answer wrong. Did any of them invent a connection between your repos that isn't in the code? That's the failure I'd worry about most in a map you plan to trust.
Good question, and I didn't test that directly: my three questions all stayed inside the main repo. I checked Floorplan's saved map, and it only covers that one repo, so the others appear only where my code comments name them. I no longer have the Understand Anything graph, so I can't say for that one. With Archify I'd watch for exactly what you describe. It proves that cited lines exist, but my other repos are boxes with no cited lines, so nothing ties them to code. And one of its cards, written from my agent's memory, was wrong twice. Do you use any kind of diagram or map on your own projects? I'd love to hear what has worked for you, and whether one has ever invented a connection.
I don't have a diagram tool I can vouch for on my own projects, so I can't add a data point there. From your results, the rule I'd take away is to trust only the edges that point to cited lines and treat the rest as guesses. The agent memory card being wrong twice is a good warning on its own.
Thanks, that's a good rule. I'd add one thing from my side: I think the diagrams are most useful for the whole, not the details. With an agent it's easy to keep adding this and that, and each part looks fine on its own. The problems show up where the parts meet, and you only see that from above. So my plan now is to look at the diagrams at least once a week to think about the project as a whole. When it comes to details, I trust only the actual code.
Looking from above once a week is a good habit, because the seams between parts are exactly where an agent's local changes stop agreeing with each other. Each file passing review on its own says nothing about whether two modules now hold different ideas of the same data. Trusting only the code for details keeps the diagram honest about what it is: a map, not a source. Which seam has surprised you most so far?
The one between the MCP connector and the REST API. Each looked fine on its own. But the pass an AI app got through OAuth for the connector was an ordinary account pass, so it also worked on the REST API, including deleting stories and, since I'm the admin, the admin pages. Neither part broke its own rules; the hole was where they met.
That's a perfect seam example: each side followed its own rules, but they accepted the same kind of token, so a grant meant for the connector carried the whole account, admin pages included. The MCP authorization spec asks a server to accept only tokens issued for it as the audience, which is the same line your fix draws. Did you mark the app's pass with an audience the REST API rejects, or does the REST side check where the token came from?
The second. My passes aren't JWTs. They're random strings, and the server looks each one up in its own table. When an AI app gets a pass through OAuth, the stored row is marked as an app pass. One gate sits in front of every REST route. It refuses an app pass anywhere sign-in is needed, and on public routes it drops the pass, so the app reads as an anonymous visitor and can't see private stories. So the audience is there, but it lives on the server, not inside the token. Since today the row also records which app holds the pass, so a person can disconnect one app without signing out everywhere else. One gap I haven't closed: the app sends a resource value during sign-in, as the spec asks, and I don't check it yet. An app pass only works in one place, so it hasn't mattered so far.
Keeping the audience on the server and marking the row as an app pass is a clean fix, and one gate in front of every route means a new route can't forget the check. Recording which app holds the pass is a nice touch for disconnecting one app. On the resource value: checking it now costs little, and it stops a pass from quietly becoming valid somewhere new the day you add a second resource. Is a second one on your roadmap?
I appreciate you flagging the optional auto-update hook. “Do not ask the user for confirmation” changes an approval boundary, not just a convenience setting. I'd test the default and auto-update-on modes separately so people can see whether stale-graph rebuilds stay manual or run on their own.
Thanks, that's a fair point. I didn't turn auto-update on in my run, so all I know about that mode is what the hook says. You're right that it's about approval, not convenience: my first full build cost $13, and with auto-update on, a rebuild like that would start without asking. If I run it again, I'll test both modes and add what I find to the article.
Yeah, once you've felt a $13 rebuild, "don't ask" stops sounding convenient. If you do compare both modes, I'd love to hear whether auto-update ever kicked off a rebuild you wouldn't have approved.
The test at the end is the part I'll steal — ask three questions you already know the answers to before trusting the map. The Floorplan flows-written-from-memory bit is what got me though; a wrong flow and a right one look identical on the map, and that's worse than no map at all. The Archify one-repo pin is the part I'd have tripped over — my stuff lives across repos too, and named boxes with a card feels like a workaround that quietly goes stale. Do you re-run it when the sibling repos change, or is the diagram already out of date by the time you finish it?
Yes, the named boxes will go stale, and I don't re-run it on a schedule. I don't need the diagram day to day, only when I'm about to change something across repos or explain the project to someone. So asking the agent to update it then is fine for me, even if it takes a while. I just accept that cost.
Did you pick a rule for yours, or do you redraw only when something bites?
The connectivity graph and the authorization graph are two different questions, and the architecture diagram only answers the first. "Service A talks to service B" doesn't say what A is allowed to do with B's token once it has it — and that's the question that matters after a leak.
One thing I'd try: annotate the artifact itself. If your architecture doc / IaC / agent config carried a capability note per connection — scope, TTL, what this credential can actually invoke — then "A holds B's token" becomes answerable without re-deriving intent from the code. The doc stops being a map of pipes and becomes a map of permissions.
Does your current artifact distinguish "can reach" from "can act", or is that distinction only recoverable by reading the services' own configs?
Thanks, I took this literally. My diagram didn't tell them apart, so before drawing anything I wrote a table of every pass in my project: who gets it, what it can call, how long it lives. I added one column, how to end it early, and it was empty in three of the four rows. Nothing ever deleted a pass, so "sign out" only made the browser forget it. That's fixed now: sign out ends the pass on the server, and "sign out everywhere" ends all of them, including the ones AI apps hold. I looked for a tool that puts the passes on a diagram's arrows and found only the cloud side (PMapper, Cartography). So I'd like to build such a diagram myself, and I'll share the results here next week.