Transcript
00:00:00Ask our coding agents to map a repo, and now we got Kafka, Redis, or an API gateway that doesn't even exist.
00:00:07The diagrams often look decent, but they miss a lot.
00:00:10This is Archify, where the agent doesn't draw anything.
00:00:14It outputs a typed graph, Archify validates it, and then renders the diagram.
00:00:19This may just be one of the best ways to visualize out our architecture.
00:00:23We're about to find out.
00:00:30Now, our model probably shouldn't be drawing the diagram at all.
00:00:33How Archify works is it describes the system as structured, typed JSON.
00:00:37That gets validated, and only then does a local compiler turn it into the final HTML.
00:00:42If the graph is invalid, it fails.
00:00:45That's Archify, and it picked up 44,000 stars in just a few months because it plugs directly into Cloud Code, Cursor, and Codex.
00:00:53So I want to put this to the test.
00:00:54I'm going to install Archify, point it at a repo, and make it answer one question about architecture.
00:01:00Then we'll see whether we can even use this result in a PR.
00:01:03And there are a few use cases where I absolutely would not use this, but we're going to dive into those soon.
00:01:08If you enjoy coding tools that speed up your workflow, be sure to subscribe.
00:01:11We have videos coming out all the time.
00:01:13Okay, so installing it is one command right here.
00:01:17And this isn't an app that I'm setting up.
00:01:19It's actually an agent skill.
00:01:22After it's installed, I can use the same skill from Cloud Code or any of the others I previously said
00:01:28without needing to change editors or even my workflow.
00:01:32Now I can send it a real job.
00:01:34I'm not going to ask it to draw the architecture of this repo.
00:01:37That sounds okay.
00:01:39But all in all, that's just going to return a bunch of garbage to us.
00:01:42So I'm going to ask one solid question.
00:01:45Use Archify, architecture diagram 8 to 12 nodes max.
00:01:49What happens on a cache miss in this service?
00:01:52Only include boxes that exist in this repo.
00:01:54If you can't prove a component, omit it.
00:01:58Deliver a self-contained HTML.
00:02:00That's like one plan, one question.
00:02:02Roughly 8 to 12 nodes.
00:02:04Because if we ask an agent to map our entire code base, have we even simplified anything or
00:02:08just made it harder to understand?
00:02:10Now I've just turned my repo tree into a flowchart.
00:02:14The agent writes the architecture as JSON.
00:02:16Then Archify validates it.
00:02:18I can also run that validation directly as I'm going to do right here.
00:02:23This is actually a really cool feature that I found in this.
00:02:27Nodes can also include repo evidence tied to a commit and a specific line range.
00:02:32If that proof isn't there, the node doesn't get an SRC badge just because the node sounds
00:02:37strong in the answer.
00:02:39All right.
00:02:39Now, how is this even helping?
00:02:41This looks like an architecture diagram.
00:02:43Yeah, sure, but you don't have to use it like one.
00:02:46I can search for an actual service within this.
00:02:50I can click on it and immediately see what's upstream and downstream.
00:02:55Then I can play that route and follow the cache miss path through the system.
00:02:59So instead of staring at 10 arrows and mentally trying to trace them back, I can now walk through
00:03:05them.
00:03:06And on top of doing that, I can export it.
00:03:08I can copy a PNG or I can generate a 1200 by 36 share card.
00:03:13The real difference here is this mermaid, right?
00:03:17The tool mermaid is normally something I read.
00:03:20This is something I can ask questions to and against.
00:03:23And the motion isn't being used to hide bad structure, export the diagram as a static image
00:03:28and the meaning is still there to survive.
00:03:31And there's a second use case that might actually be more useful, right?
00:03:35What are we thinking?
00:03:36Well, I'm thinking about code review.
00:03:38Say this is the system before a change.
00:03:41Then I add an existing retry worker.
00:03:44I can tell the agent to update the architecture without making up something out of thin air.
00:03:49Archify can then diff the two validated snapshots, added, removed, moved, rerouted.
00:03:54So instead of getting two generated diagrams, I can see what actually changed.
00:03:59And the editor is still just chat.
00:04:02But if I want this architecture to survive into the next agent session, I commit the JSON.
00:04:07At this point in the game, the easiest way to understand Archify is this.
00:04:11For the HTML VM for system maps, the coding agent is the front end.
00:04:15The JSON is the intermediate representation.
00:04:19The HTML is the compiled result.
00:04:21And that middle layer is doing a lot of the work.
00:04:24The JSON follows strict schemas.
00:04:26Unknown fields can fail validation.
00:04:28And there are five diagram modes.
00:04:30Architecture, workflow, sequence, data flow, and life cycle.
00:04:34But one of the most interesting decisions is what the model does not control.
00:04:38The layout.
00:04:39The model describes the system.
00:04:41It does not decide exactly where every box is going to go.
00:04:44They actually tried themed mermaid with automatic degree layout.
00:04:48It wasn't any better than normal mermaid.
00:04:51And validation also fails closed.
00:04:54Bad JSON doesn't become a pretty diagram in any way.
00:04:58You get diagnostics, rule codes, and supported repairs.
00:05:02Now, out of all this, here's maybe where I would not use Archify.
00:05:06If you need a diagram directly inside your readme file, maybe not.
00:05:10Might take some time.
00:05:11GitHub renders it.
00:05:12Archify HTML does not.
00:05:15Archify is solving a much different kind of problem here.
00:05:18There's already an agent in the loop.
00:05:20That agent is producing an architecture artifact.
00:05:23Maybe it goes into a PR.
00:05:25Maybe it goes into a design review.
00:05:27That's where checked output starts to matter.
00:05:30Now, within this, there's a lot that I liked here.
00:05:32It lives inside tools that we're already using every day.
00:05:35I can send the output out.
00:05:38Repo evidence gives me something concrete to actually check.
00:05:41And because the architecture is structured, I can keep editing it without things just changing over time.
00:05:46It also looks good enough that I probably wouldn't feel the need to have to redraw this in Figma or some other tool like that.
00:05:53But all this goes with saying, at the same time, Archify does not know your architecture.
00:05:58A graph can be completely valid and still describe the wrong system.
00:06:02You still have to read it.
00:06:03A bad model, as we know, will often just create JSON that works, but it still looks bad.
00:06:08And if the final home for your diagram is a readme, Mermaid might still be better here.
00:06:13With Archify, you're probably committing the JSON and HTML or you're exporting an image.
00:06:18And there's one mistake I would absolutely avoid here.
00:06:21Do not point it at a huge repo and say, map everything.
00:06:25I think you can guess how that's going to go because you're probably going to just get a load of garbage back.
00:06:29But that isn't really a failure of Archify.
00:06:32It's rather just a bad question.
00:06:34If you already work with coding agents and you regularly create diagrams that you're going to look at in the future or someone else might be, this makes sense.
00:06:42PR reviews, design docs, I would probably use this.
00:06:47I would not install this because I want a prettier version of something we already have, Mermaid for example.
00:06:52And I definitely would not expect it to reverse engineer anything for me.
00:06:55The barrier to trying is really tiny.
00:06:58One MPX command, node on the machine.
00:07:00There are no model weights here.
00:07:02My M4 Pro is basically irrelevant in this.
00:07:05But there is one rule I'd keep.
00:07:07One question per file.
00:07:08If you can't clearly say what question the diagram is answering, don't generate the diagram.
00:07:14I'm Josh from BetterStack.
00:07:15If you enjoy coding tips and tricks like this, be sure to subscribe to the channel.
00:07:19We'll see you in another video.
00:07:20We'll see you in another video.
Community Posts
No posts yet. Be the first to write about this video!
Write about this video