Architecture Decision Tree for AI Projects

The Problem

You're starting a new web project with AI assistance. Your first instinct: "I'll use React." Or Next.js. Or whatever framework dominated Twitter last week. AI happily scaffolds it for you. Three weeks later, you're drowning in build configurations, dealing with hydration mismatches, and wondering why your simple landing page needs 500KB of JavaScript.

The issue: You chose architecture based on familiarity or hype, not requirements. AI made it easy to build the wrong thing fast.

Frameworks have costs - complexity, build time, bundle size, learning curve. With AI lowering the barrier to building anything, choosing the simplest viable architecture matters more than ever.

The Core Insight

Match architectural complexity to actual requirements. Start simple, add complexity only when you hit limitations.

The decision isn't React vs Vue vs Svelte. It's: "What's the minimum architecture that solves my actual problem?" Sometimes that's vanilla HTML. Sometimes it's a static site generator. Rarely, it's a full SPA framework. AI makes all of them equally easy to build, so choose based on maintainability and performance, not development speed.

The Decision Tree

Start Here: What Are You Building?

Q1: Does your content change based on user actions?
    NO  → Static content (marketing site, docs, blog)
    YES → Go to Q2

Q2: Do you need instant navigation without page reloads?
    NO  → Server-rendered pages work fine
    YES → Go to Q3

Q3: Is your app data-heavy with complex state management?
    NO  → Progressive enhancement with vanilla JS
    YES → Consider SPA framework (React, Vue, etc.)

Detailed Architecture Breakdown

Real Decision Examples

Example 1: Company Landing Page

Requirements:

• Marketing content, rarely changes
• Contact form
• Good SEO essential
• Fast load time

Wrong choice: Next.js with React - Overkill. You're shipping 200KB of JS for static content.

Right choice: Vanilla HTML or 11ty - Zero JS for content, sprinkle vanilla JS for form. Ships in 20KB.

# Prompt for AI:
"Create a landing page with:
- Hero section with CTA
- Features section (3 columns)
- Contact form with FormSubmit.co
- Footer

Use vanilla HTML/CSS/JS. No frameworks. Optimize for performance."

Example 2: SaaS Dashboard

Requirements:

• User authentication
• Real-time data updates
• Complex filtering and state
• SEO not important (behind login)

Wrong choice: Vanilla JS - You'll reinvent React badly.

Right choice: React + Vite or Next.js - Framework benefits outweigh costs for complex state.

# Prompt for AI:
"Create a React dashboard with:
- Auth using Clerk
- Data table with filters/sorting (TanStack Table)
- Real-time updates via WebSocket
- Charts using Recharts

Use Vite for fast dev, TypeScript for safety."

Example 3: Documentation Site

Requirements:

• Markdown content
• Search functionality
• Fast navigation
• Easy for writers to update

Wrong choice: Custom SPA - Why build what exists?

Right choice: Docusaurus, VitePress, or Astro - Purpose-built for docs.

# Prompt for AI:
"Set up a Docusaurus site with:
- Docs versioning
- API reference section
- Algolia search
- Dark mode

Start with the TypeScript template."

The Progression Ladder

Start simple, upgrade only when you hit clear limitations:

1. Vanilla HTML: Works until you need component reuse or state management
2. HTML + Alpine.js: Adds reactivity without build step, good for 80% of interactivity
3. Static Site Generator: When content management matters but interactivity is light
4. SSR Framework: When you need SEO + complex interactivity
5. Full SPA: When app complexity justifies the framework overhead

Failure Patterns

1. Framework First, Requirements Second

Symptom: You have a 3-page site with a 500KB bundle and a build process.

Fix: Ask "What would break if I removed the framework?" If answer is "nothing critical," you don't need it.

2. Premature Optimization

Symptom: You chose a cutting-edge framework "for performance" but your bottleneck is API latency.

Fix: Profile first, optimize second. Use simple tech until you measure a problem.

3. Resume-Driven Development

Symptom: Chose tech because you want to learn it, not because project needs it.

Fix: Learn new tech on side projects. Production gets boring, proven tech.

Special Case: AI-Generated Prototypes

When vibe-coding prototypes with AI, default to vanilla HTML unless you know it's headed to production with React:

# For prototypes, ask:
"Create a vanilla HTML prototype for [feature].
No frameworks, no build step.
Single file if possible.

Include:
- Inline CSS with CSS variables for theming
- Vanilla JS with clear comments
- Mock data inline

If this works, I'll migrate to [production stack] later."

Vanilla prototypes are faster to build and easier to throw away. Migration to a framework later is straightforward.

[ ] Content is mostly static? → Vanilla or SSG
[ ] Need SEO? → SSR or Static (not SPA)
[ ] Complex state? → React/Vue
[ ] Real-time features? → SPA with WebSockets
[ ] Behind login? → SPA is fine
[ ] Team has framework expertise? → Use it
[ ] Otherwise? → Start vanilla, add complexity later