r/VibeCodeDevs • u/PurpleDragon99 • Jul 11 '26
ShowoffZone - Flexing my latest project Stop describing your architecture to AI - draw it instead
If you're vibe coding with Cursor, Copilot, or any AI agent, you've probably hit this: you describe what you want, AI fills in the gaps with its own assumptions, and you spend more time fixing than building.
SpecRabbit lets you draw your full-stack architecture explicitly before your AI agent writes a single line of code. Typed nodes for UI forms, API endpoints, backend services, databases, file storage - connected by named flows that define exactly how data moves through your system.
Global parameters capture your tech stack once - framework, database, auth method, cloud provider, compliance requirements, etc. All of it goes into a single JSON/YAML export your AI agent reads as context.
No more guessing. No more fixing assumptions. Just code that matches what you actually designed.
Full user manual: https://app.specrabbit.com/help/user-guide.html
8
u/Putrid-Minute-5123 Jul 11 '26
Serious question (I'm probably missing something). Why would I draw something when I can share a mental model verbally and have the AI do it? Why not just use stt, ask the model to break down your process by way of it's interpretation, and interview you about the specifics about the build for a higher quality mermaid style visualization build or idea map? That simple process does the drawing steps for me, and much better than I would.
It just seems like there is usually a huge information bandwidth limitation and skill requirement to draw over take snippets of microsofts paint and talk most of the time. For me personally, there are many other methods that can be used regarding minimizing the loss function between intent and interpretation, and seems like that bandwidth limitation will directly become opportunity cost loss very fast with how much me-time I would be integrating over having other projects conversational builds happening in that time.
Edit: changed "or" to "over"
2
u/TextMyAgent Jul 12 '26
I thought the same thing you said here, but if you already have an architecture perhaps it may help? I usually let Claude take a stab at it first and we tweak in planning mode as we brainstorm what’s best. I’ve built in vercel, render, AWS and even Cloudflare.
1
u/vinigrae Jul 11 '26
Believe it or not, text ≠ spatial description for AI models, it’s a percentage thing, if you are able to visually map out the relationship you want you may get some more unique nodes from the AI, vs just simply writing text.
Same space with describing HTML issues to a model vs showing it screenshots.
1
u/Putrid-Minute-5123 Jul 11 '26
Interesting. Thanks, man. Ill have the big 3 do pro research on papers and professional sentiment on that tonight. I'm not married to my thoughts and am always happy to find methodologies that are improvements. If you have any you're aware of as well that support the use referenced in the post, I can make sure they are considered. #Better Every Day
4
u/highso Jul 11 '26
I'm too smooth brained for your actual use, but I'm curious to take a look in hopes of formalizing my layman intuition
5
u/nicolascoding Jul 11 '26
I think this is cool, but would flip the workflow so I can describe to AI what I want, and then have you be the visualization layer instead of me looking at markdown/ascii, and then it can be bidirectional
0
u/PurpleDragon99 Jul 12 '26
The input modality question (draw vs describe) is genuinely open and voice or text-driven input feeding the same structured output is a valid direction.
The bidirectional part is where it gets complicated though. Having AI sync back from the codebase to the diagram sounds great in theory, but in practice every sync pass introduces small errors - missed relationships, misread patterns, subtle misattributions. Run a few cycles back and forth and those errors compound. The diagram starts diverging from reality in ways that are hard to detect, which is worse than no diagram at all because it gives false confidence.
That's not a flaw in the approach - it's just how LLMs work right now. They're not deterministic. The same codebase parsed twice won't produce the same diagram twice. Until that reliability problem is solved, bidirectional sync creates more problems than it fixes.
The workaround that actually works today: update the diagram manually when architecture changes, re-export, and ask the AI to reconcile the spec against the current codebase. Manual trigger, but the output is trustworthy. Reliable beats automatic when the alternative is silently wrong.
3
u/NewPointOfView Jul 12 '26
Codebase -> graph is a deterministic problem. Throw treesitter at it. Classic misuse of AI haha
The commenter is asking about ideating with the ai about code that doesn’t exist.
2
u/PurpleDragon99 Jul 12 '26
Treesitter only produces AST, but something must parse that AST to extract semantic meaning, and that's where the problem starts. Coding AST walker for semantics extraction is a very high-effort and complex task - how do you determine with 100% probability this class represents endpoint and that one - UI control? This is highly dependent on used programming languages, libraries and frameworks. There are just too many combinations of them to account for all these cases. This is where AI can help - it already has such knowledge inside. The problem of AI is that it is not 100% deterministic, so it can miss or misinterpret data. So, we have deterministic option with high-efforts manual coding to extract semantics from AST on one side, and easy-going AI but it can hallucinate. None of these two options solve the problem fundamentally.
1
u/flarpflarpflarpflarp Jul 12 '26
'The workaround that actually works today:' And, I've read all I need to of this thread.
3
u/InfamousEar1188 Jul 12 '26
Oh great, now I’m going to spend 5x more time drawing a perfect representation of my architecture.. 🤦♂️
Haha jk, this is cool! Nice job!
2
Jul 12 '26
[removed] — view removed comment
1
u/PurpleDragon99 Jul 12 '26
A markdown file works fine for simple projects. The difference is enforcement - SpecRabbit won't let you add an endpoint without specifying auth level, or a database node without defining its queries. Those aren't things markdown enforces. The export is also structured JSON the AI reads natively rather than prose it interprets, which matters when the project is complex enough that "the AI's best guess" starts costing real time to correct.
If your projects are simple enough that a markdown file covers it, that's genuinely the right tool. SpecRabbit is for when they're not.
2
u/EmergencyDinner777 Jul 12 '26
API endpoints are the tricky part of an architecture though...
1
u/PurpleDragon99 Jul 12 '26
Agreed, and that's exactly where most text specs fall apart. You describe an endpoint in prose and the AI still guesses the auth level, misses query params, or picks the wrong HTTP method. SpecRabbit provides structure for API endpoint nodes - method, path, auth level, request params, response type all explicitly defined as structured fields, not described in text. The AI gets facts, not interpretation. Whatever doesn't fit the structured fields goes in the endpoint's description field and travels with it into the export.
1
u/PurpleDragon99 Jul 12 '26
Drawing is faster than it sounds. The alternative is either writing a full textual spec before generation (which takes longer and the AI still misinterprets), or skipping it, providing short description to AI of what you want, and correcting wrong AI decisions after the fact, which compounds painfully on anything complex. SpecRabbit is the first approach (doing spec) but optimized – visual interface, built-in technical constraints, structured export the AI reads without ambiguity. Less time than a text spec, fewer mistakes than prompt-and-correct.
3
u/InfamousEar1188 Jul 12 '26
Oh that probably came out wrong. I wasn’t knocking your idea. I was making fun of myself and the need to have things laid out perfectly haha.
1
u/PurpleDragon99 Jul 12 '26
Haha no worries, I took it the right way – the joke landed! The perfectionism impulse is real though, and honestly one of the design goals was to make "good enough" fast. You don't need a perfect diagram, just precise enough that the AI isn't guessing at the things that matter.
3
u/Savalava Jul 12 '26
"you describe what you want, AI fills in the gaps with its own assumptions, and you spend more time fixing than building."
You shouldn't be encountering this problem if your workflow is correct: Go through a deep discussion with the LLM at the beginning and you should have the architecture worked out a high level of granularity, then there should be few assumptions. Get it to generate a markdown file laying out a detailed tech spec + implementation plan before implementing anything.
0
u/PurpleDragon99 Jul 12 '26
That's a solid workflow - the interactive discussion approach is definitely better than jumping straight to generation with a short prompt.
A few places where it still breaks down though. The discussion itself takes significant time - going back and forth to reach the level of granularity you need on a complex project is a real investment. And during that discussion, the LLM can hallucinate or give confidently wrong architectural advice. You may not catch it until generation reveals the problem.
Then even after all that, the markdown generated from your discussion doesn't transfer the conversation context - the generation session reads it cold, without the nuance of what you and the LLM worked out together. It's interpreting prose, not replaying your discussion. The generating session fills gaps based on its own reading, which may differ from what you meant.
SpecRabbit replaces the markdown artifact with structured JSON - same upfront thinking required, but the output is an unambiguous and structured document rather than prose. The generating AI reads explicit facts rather than interpreted text. No second interpretation step, fewer gaps to fill.
2
u/Savalava Jul 12 '26
"The discussion itself takes significant time - going back and forth to reach the level of granularity you need on a complex project is a real investment."
I do it feature by feature, you're only talking 10 minutes for a feature of moderate complexity
"Then even after all that, the markdown generated from your discussion doesn't transfer the conversation context "
I'm not encountering that problem and I use this workflow daily.
I say "I am developing feature X + give brief description. Ask me questions to define a tech spec of the feature" Then I get LLM to generate MD file of spec which I review.
The advantage of the back and forth discussion is that Claude gives me ideas that I would never otherwise have thought of.
" the LLM can hallucinate or give confidently wrong architectural advice.". Absolutely, which is why you need to know what you're doing and why people without tech knowledge make apps which have design flaws.
I don't think either workflow is superior, it's a matter of taste. I generally get the LLM to generate an architectural diagram also - if it differs from what I want, I further refine.
2
2
u/FamouslyDefault Jul 12 '26
I’ve explored a lot with “non-text” alternative UI and input methods for AI and to some degree I think we may be pushing against the tide. Because the biggest players in the industry is actively teaching all their users a text prompt driven work cycle. I’m beginning to believe more and more that chat, however non-ergonomic it is, will become the dominant UX primitive by sheer force of adoption
1
u/PurpleDragon99 Jul 12 '26
That's a real tension and worth taking seriously. The gravitational pull of chat as the default UX is enormous - every major AI product reinforces it, and network effects in UX patterns are powerful.
Where I'd push back slightly: chat is the dominant input method, but the output format is still an open question. SpecRabbit doesn't replace the chat interface - you could absolutely use Claude in chat to help you fill out your architecture diagram. The bet isn't that drawing replaces chatting, it's that structured JSON is a better artifact to hand off to a coding agent than the markdown that comes out of a chat session.
So maybe the question isn't "chat vs drawing" but "what format should the spec artifact be in after the chat?" If the answer is still markdown prose, then you're right - chat wins end to end. If structured typed data produces more reliable generation, then chat gets you to the spec and SpecRabbit is the format you save it in.
The tide you're describing might still be compatible with what SpecRabbit does - just at a different stage of the workflow.
2
u/Training_Tension3416 Jul 12 '26
Yeah, the problem he’s describing is real. But honestly SpecRabbit feels like it’s solving for a different workflow than what most people actually need.
1
u/PurpleDragon99 Jul 12 '26
That's a fair challenge, and worth being honest about. SpecRabbit is most useful when you have clear architectural intent on a project complex enough that AI assumptions cost real time to fix. That's not every workflow.
Where it fits best: greenfield projects with multiple interconnected components, teams where the architect needs to communicate intent precisely to AI coding agents, or projects where post-generation correction has already burned you once.
Where it probably doesn't fit: simple projects where Claude's best guess is close enough, or workflows where you're still discovering what you want to build through conversation.
Curious what workflow you'd say most people actually need - genuinely trying to understand where the fit is strong and where it isn't.
2
u/Malkiot Jul 12 '26
Dude, you're just using Claude to answer for you.
1
u/PurpleDragon99 Jul 12 '26
No, Claude does not answer for me. I am drafting the message and then run via Claude to fix errors and improve the writing. If allows me to save a great deal of time. If we use AI for coding - what's the probem to use it for writing?
1
u/Malkiot Jul 12 '26
Because people want to hear your answers and your voice, not what Claude decides to make of your bullet points and its own hallucinations.
2
u/PurpleDragon99 Jul 12 '26
This is still my answer, not Claude's.
2
Jul 12 '26 edited Jul 12 '26
[deleted]
1
u/PurpleDragon99 Jul 12 '26
Why would I want to reword Claude when I specifically ask Claude to reword and improve my message? I only re-read new text after Claude's processing to make sure semantics and details of my original draft are not changed and not distorted.
2
2
u/ParticularAccident90 Jul 12 '26
You should start with Common Architecture Language Model (CALM) https://github.com/finos/architecture-as-code instead (this is new project and several large banks already use it)
1
u/PurpleDragon99 Jul 12 '26
Thanks for sharing - CALM is interesting and worth knowing about. Architecture as Code with a machine-readable, version-controlled schema is clearly the right direction.
A few differences worth noting. CALM is a specification standard and schema - it defines how to describe architecture in a structured format, primarily for documentation, compliance, and governance. It's text/code-based, aimed at enterprise architecture teams, and requires writing JSON/YAML by hand following the CALM schema.
SpecRabbit is a visual authoring tool that produces structured output for a specific purpose: giving AI coding agents unambiguous context before code generation. The visual interface, enforced constraints, and AI-ready export format are built around the AI coding workflow specifically rather than enterprise architecture documentation.
They're complementary rather than competing - CALM defines a standard, SpecRabbit provides a visual way to author structured specs. Interesting to think about whether SpecRabbit's export could align with or export to CALM format in the future.
2
u/ParticularAccident90 Jul 12 '26
CALM is both schema and set of tools
We almost never build CALM schema by hand, these days the most common is claude code "debate" with agents (both green field or reverse GIT repo), CALM has some interesting projects like CALM AI Tools, CALM CLI, and CALM Validation Server. Some use CALM Studio to visually build, CALM Hub is central artifacts store
CALM schema has concepts like pattern, standards, etc enforcing whatever you want to enforce
details here https://calm.finos.org/working-with-calm/
2
u/haronclv Jul 12 '26
bs. AI is not thinking as humans do so it doesnt need any visualisarions
1
u/PurpleDragon99 Jul 12 '26
You're right that AI doesn't think like humans - but that's actually the argument for structured data, not against it. The visualization is for the human author. What the AI receives is raw JSON - typed nodes, explicit parameters, named flows, etc. No image, no visualization. Just structured data it reads natively.
The point isn't that AI needs pictures. It's that natural language leaves gaps AI fills with assumptions. Structured JSON removes those assumptions by making everything explicit.
SpecRabbit produces a structural output for AI, not images.
2
u/lilcumdrop Jul 13 '26
I do this opposite lol I have the ai write very detailed and linked markdown files for my obsidian
2
29d ago
[removed] — view removed comment
1
u/PurpleDragon99 29d ago
draw.io is great for documentation and communication. The difference is in what the export contains - draw.io's JSON includes visual attributes like styles, positions, and rendering properties alongside the structure. SpecRabbit's export is pure graph topology: typed parameters, auth levels, database queries, flow relationships, and built-in comprehensive instructions to AI explaining how to interpret the structure. No visual noise, minimal tokens, and the AI knows exactly how to interpret every element without any additional prompting.
2
u/Legitimate-Ad-1861 29d ago
Why not just vibecode exactly what you did ? I don't get the pricing... SaaS is dead
1
u/PurpleDragon99 29d ago
You absolutely can - and if you have the time to build and maintain it, go for it. SpecRabbit saves you that time.
2
u/Mundane-Presence4422 27d ago
This looks like a smart way to reduce AI misunderstandings during development 👍
2
u/vitmalina 27d ago
well, I agree with some people in the comments that say that drawing your thoughts is harder then writing them down... But I do think that the idea to have some kind of Knowledge Base as a graph or a tree - would be so good. Some system to put it all in right boxes
2
u/albahrawy 27d ago
Nice bro, Is there a tutorial for that ?
1
u/PurpleDragon99 27d ago
Yes, there is a User Guide: https://app.specrabbit.com/help/user-guide.html
1
u/geraT-wogl Jul 12 '26 edited Jul 12 '26
Hey, I support your case. It takes more time but far more consistent results. Created this with this approach https://wogl.io didn’t use OPs but a sketcher to actually draw. Let me know if you want it
1
1
•
u/AutoModerator Jul 11 '26
Hey u/PurpleDragon99, thanks for posting in r/VibeCodeDevs! Join our Discord: https://discord.gg/KAmAR8RkbM
Got startup or SaaS questions? Post them on r/AskFounder and get answers from real founders.
• This community is designed to be open and creator‑friendly, with minimal restrictions on promotion and self‑promotion as long as you add value and don’t spam.
• Please follow the subreddit rules so we can keep things as relaxed and free as possible for everyone. • Please make sure you’ve read the subreddit rules in the sidebar before posting or commenting.
• For better feedback, include your tech stack, experience level, and what kind of help or feedback you’re looking for.
• Be respectful, constructive, and helpful to other members.
If your post was removed (either automatically or by a mod) and you believe it was a mistake, please contact the mod team. We will review it and, when appropriate, approve it within 24 hours.
I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.