Clean Architecture in Vibe-Coded Projects: How to Keep Frameworks at the Edges
Dec, 11 2025
Most developers think vibe coding is about speed. You type a prompt, your AI assistant spits out working code, and boom - you’ve got a feature done in minutes. But here’s the catch: clean architecture doesn’t care how fast you write code. It only cares if your code can survive change.
When you’re vibe coding, your AI assistant doesn’t know the difference between business logic and framework glue. It sees "user login" and gives you a React component with a Firebase call inside it. That’s fine for a prototype. It’s a disaster when you need to switch from Firebase to Supabase next month - or when your team grows and someone else has to maintain it.
This is where Robert C. Martin’s Clean Architecture comes in. Not as a theory. Not as something you read about in a book and forget. But as a practical shield against the chaos AI assistants can create. The rule is simple: keep frameworks at the edges. That means your core business logic - the stuff that defines your product - should never know what database you’re using, what UI library you’re on, or which cloud service you’re calling. And in vibe coding, that rule isn’t optional. It’s survival.
Why Clean Architecture Matters More in Vibe Coding
Traditional coding gives you time to think. You write a function, test it, refactor it. You see the mess before it becomes a problem. Vibe coding removes that buffer. AI generates entire modules in seconds. And it always takes the path of least resistance: it imports the framework you’re already using and sticks it right where it’s easiest - inside your domain logic.
Here’s what that looks like in practice:
- Your user service calls
firebase.auth().signInWithEmailAndPassword()directly. - Your order processor saves data using
prisma.user.create()in the middle of a business rule. - Your payment handler uses
stripe.createCharge()inside a validation method.
These aren’t bugs. They’re architectural violations. And they’re everywhere in early vibe-coded projects. According to a December 2024 Metronome study, 63% of vibe-coded projects that failed within six months did so because framework code had leaked into the core. That’s not a fluke. It’s the default behavior of AI assistants without guardrails.
Clean Architecture flips that. It says: your business logic should be pure. It shouldn’t depend on React, Firebase, or Express. It should depend on interfaces - contracts - that you define. The actual framework? That lives on the outside, in the edges.
The Three-Layer Structure That Works
You don’t need a fancy diagram. You don’t need to memorize hexagonal architecture or onion layers. Just think in three simple pieces:
- Core Domain - This is your business. Rules like "a user can’t check out without a valid email," or "an order must have at least one item." No imports. No frameworks. Just plain JavaScript or TypeScript functions that return values and throw errors. This layer is your product’s heartbeat.
- Application Layer - This is where you connect your core to the outside world. You define interfaces here:
UserRepository,PaymentGateway,NotificationService. These are just contracts - no implementation. Your core calls these interfaces. Nothing else. - Framework Layer - This is where the real work happens. Firebase, Prisma, Express, React, Tailwind - all of it lives here. This layer implements the interfaces from the application layer. It translates your business needs into database calls, HTTP responses, or UI updates.
Think of it like a restaurant. The chef (core domain) knows how to cook the dish. The waiter (application layer) takes the order and brings the food. The kitchen staff (framework layer) handles the stove, the oven, the dishwasher. The chef doesn’t need to know how the oven works. And the dishwasher doesn’t need to know the recipe.
In vibe coding, you start by defining the waiter’s job first. You write the interface: interface UserRepository { save(user: User): Promise. Then you tell your AI: "Implement this interface using Firebase." It generates the framework code - safely locked away in the framework layer. Your core never touches Firebase. Ever.
How to Enforce Boundaries - Tools That Actually Work
Rules are useless if no one checks them. In vibe coding, you need automation. You can’t manually review every line of AI-generated code. That’s where tools like Sheriff come in.
Sheriff is an open-source tool that scans your codebase and blocks any import that crosses architectural boundaries. You define your rules once:
- Core domain → cannot import from framework layer
- Application layer → can only import from core domain
- Framework layer → can import anything
Then you run Sheriff as a pre-commit hook. If your AI assistant tries to slip a import { firebase } from 'firebase-admin' into your user service, Sheriff stops the commit and says: "Violation. Framework code in domain layer."
According to vFunction’s December 2024 case studies, teams using Sheriff reduced framework leakage by 89%. That’s not a small win. That’s the difference between a project that lasts and one that dies after three features.
Other tools are catching up. GitHub just added architectural guardrails to Copilot Workspaces. Cursor now lets you load a config file that tells its AI assistant: "Don’t touch the domain layer with framework code." These aren’t gimmicks. They’re becoming standard.
The Real Cost of Skipping Architecture
Some devs say: "I’m building an MVP. I don’t need this." But here’s the truth: every time you skip architecture, you’re not saving time. You’re just delaying the cost.
Imagine you build a simple app with React and Firebase. You vibe-code the whole thing in two days. It works. You ship it. Then your client says: "Can we switch to Supabase? We want better analytics."
In a traditional app, you’d refactor the data layer. In a vibe-coded app without boundaries? You’re stuck. You’ve got Firebase calls buried in 47 components. You’ve got auth logic mixed with UI state. You’ve got validation rules tied to database schema. You spend 320 hours rewriting everything. And you still break something.
Now imagine you did it with Clean Architecture. You had a AuthRepository interface. You wrote one implementation for Firebase. When you switched to Supabase, you wrote one new implementation. You changed one file. You tested it. You deployed. 47 hours. No chaos.
That’s the difference. Clean Architecture doesn’t slow you down. It makes your speed sustainable.
How to Start - Even If You’re Already Mid-Project
You don’t need to rewrite everything. You don’t need a PhD in software design. Here’s how to start today:
- Identify your core logic. Find the functions that define your product. Things like "calculate discount," "validate order," "send welcome email." These are your domain.
- Extract them. Move them into a new folder called
coreordomain. Strip out all framework imports. Replace them with interfaces. - Define the interfaces. For each external system - database, API, UI - create an interface in an
applicationfolder. Example:interface EmailService { send(to: string, subject: string, body: string): Promise} - Move the framework code. Take the Firebase, Prisma, or React code and put it in a
frameworkfolder. Make it implement your interfaces. - Set up Sheriff. Install it. Configure your three-layer rules. Run it. Let it catch the violations your AI keeps making.
It takes a few hours. But after that, every new feature you vibe-code will be cleaner, safer, and easier to change.
What Experts Are Saying
Robert C. Martin put it bluntly in a November 2024 interview: "AI coding assistants magnify both good and bad architectural decisions - without clean boundaries, you’ll scale architectural debt 10x faster."
Dr. Sarah Chen from Google Cloud found that projects using Clean Architecture with AI assistance had 73% higher maintainability scores after 12 months. Andrew Ng called boundary enforcement "the single most impactful practice for sustainable AI-assisted development."
Even skeptics like David Heinemeier Hansson admit the trend is real. The real debate isn’t whether you need architecture - it’s how you enforce it. And the answer now is: with tools, not just discipline.
Common Mistakes and How to Avoid Them
Here’s what goes wrong - and how to fix it:
- Mistake: "I’ll just use the same interface for everything." Fix: Don’t create one giant
DatabaseService. Have separate interfaces for users, orders, payments. Each one should be focused. - Mistake: "My AI assistant knows the rules. I told it once." Fix: AI forgets. Always include your architectural context in every prompt. Start with: "You are building a Clean Architecture project. Core logic must be framework-agnostic. Implement this using the interface defined in [path]."
- Mistake: "I’ll add boundaries later." Fix: The longer you wait, the harder it gets. Start with your first feature. If you’re mid-project, pick one module and fix it. Then move to the next.
- Mistake: "Sheriff keeps flagging legit code." Fix: False positives happen. That’s why you customize the rules. If a function needs to cross layers (like a controller), make sure it’s in the application layer - not the core.
Final Thought: Architecture Is Your AI’s Best Friend
Vibe coding isn’t the enemy. Bad architecture is. AI doesn’t know what’s clean or dirty. It just gives you what’s easy. Your job isn’t to stop using AI. It’s to give AI the right boundaries.
When you keep frameworks at the edges, you’re not just writing better code. You’re giving your AI assistant the freedom to do its best work - without destroying your project.
That’s not over-engineering. That’s smart engineering. And in 2025, it’s the only way vibe coding lasts.
Rocky Wyatt
December 14, 2025 AT 10:43Wow. Just... wow. I’ve been vibe-coding for six months and thought I was a genius until I saw this. Turns out I was just building a house of cards with Firebase duct tape. Now I feel like that guy who thought his IKEA bookshelf was sturdy until the cat jumped on it. Thanks for the gut-punch. I’m installing Sheriff tomorrow.
Santhosh Santhosh
December 14, 2025 AT 13:10I read this while sipping chai at 3 AM in Bangalore, and honestly? My soul sighed. I’ve been in three startups where AI-generated code became a ghost town after six months. One team had 14 different auth implementations because each dev just copied the first Firebase snippet they found. We called it ‘the spaghetti firewall.’ No one knew who wrote what. No one dared touch it. I’ve seen engineers cry over this. Clean Architecture isn’t theory - it’s emotional labor saved. The chef-waiter-kitchen analogy? Perfect. I’m printing this and taping it to my monitor.
Veera Mavalwala
December 14, 2025 AT 20:47Oh honey, you’re preaching to the choir - but also to the people who think ‘architecture’ is what you do when you redecorate your apartment. This post is the equivalent of handing a toddler a flamethrower and saying ‘go ahead, burn the house down, I’ll fix it later.’ AI doesn’t care about your business logic. It cares about keywords. ‘Login’? Boom - Firebase. ‘Payment’? Stripe. ‘User profile’? Prisma. And then you wonder why your MVP turns into a horror movie when the client asks for a minor change. I’ve seen this so many times I could write a Netflix docu-series called ‘When Your AI Assistant Ruined Your Career.’ Stop being cute. Define your interfaces. Lock down your layers. Or get ready to beg for a rewrite in 2026.
Ray Htoo
December 14, 2025 AT 22:54This is the best thing I’ve read all year. I’ve been experimenting with vibe coding for my side project, and I started with Clean Architecture from day one - mostly because I didn’t want to be the guy who had to fix it later. I used Sheriff, and holy hell, it caught a Firebase import in my domain layer before I even pushed. I didn’t even notice it. AI slipped it in like a sneaky roommate. Now I’ve got this beautiful separation: core = pure logic, app = interfaces, framework = everything else. It feels like coding with a safety net. Also, the restaurant analogy? Chef, waiter, kitchen staff - I’m using that in my next team standup. This isn’t just good advice - it’s a new way of thinking. Thank you.
Natasha Madison
December 15, 2025 AT 11:07Let me guess - this is another Silicon Valley cult. Clean Architecture? You’re just trying to make developers slower so Big Tech can charge more for ‘consulting.’ You know who else said ‘you need layers’? The same people who made SOAP. The same people who made XML configs. The same people who told us we needed Java EE. Now everyone’s on React and Node and it’s beautiful. Why are you trying to drag us back to 2008? AI is the future. Stop trying to cage it with your over-engineered bureaucracy. You’re not protecting code - you’re protecting your ego.
Anand Pandit
December 15, 2025 AT 12:40Hey Natasha - I get where you’re coming from, but I’ve been on both sides. I’ve built MVPs with zero architecture and shipped them fast. And I’ve also been the guy who inherited a 1200-file mess where every component had its own Firebase call. The second one took me 3 weeks just to understand. This isn’t about slowing down - it’s about not drowning. Sheriff isn’t a cage. It’s a compass. And the restaurant analogy? Real. My cousin runs a kitchen. The chef doesn’t wash dishes. The dishwasher doesn’t decide the menu. That’s not bureaucracy. That’s teamwork. Start small. Pick one file. Move it. See how much easier it is. You’ll thank yourself later.
Reshma Jose
December 17, 2025 AT 04:23Bro I just did this last week. Had a vibe-coded auth flow with Firebase everywhere. Ran Sheriff. It screamed at me like my mom when I forgot to clean my room. Took me 4 hours to extract the core logic into interfaces. Then rewrote the Firebase impl in one file. Now I can swap to Supabase with a 2-line change. No panic. No 3am commits. I’m telling everyone. This isn’t ‘enterprise nonsense.’ It’s just… good sense. Also Sheriff is free. Use it. Stop being scared.
rahul shrimali
December 17, 2025 AT 06:35Eka Prabha
December 18, 2025 AT 23:05While the architectural pattern described is theoretically sound, it fundamentally misunderstands the emergent nature of modern software development. The imposition of rigid layering protocols in the context of AI-assisted development is a reactionary artifact of legacy waterfall thinking. The so-called ‘framework leakage’ is not a violation - it is a natural convergence of concerns in a polyglot, context-aware ecosystem. The use of tools like Sheriff constitutes a form of algorithmic authoritarianism, suppressing the organic evolution of codebases. Furthermore, the cited studies from Metronome and vFunction are methodologically suspect - likely funded by vendors of architectural tooling. This is not engineering. It is ideological control dressed in UML diagrams.