# Introduction

## Introduction

"Vibe coding" with AI has transformed how we approach application development. Using natural language prompts, you can generate entire applications in minutes. But here's what most people discover: **starting with AI is easy; building something production-ready requires understanding and strategy.**

#### Think of it like cooking with AI:

**Bad approach**: "AI, make me dinner"

* AI generates a recipe
* You don't know if ingredients are available
* You don't know if it matches dietary restrictions
* You can't adjust if something goes wrong
* Result: Might work, might be disaster

**Good approach**: "AI, create a 30-minute vegetarian pasta dish for 4 people, using ingredients I have: tomatoes, basil, garlic, olive oil. No dairy allergies."

* AI understands constraints
* You know what you're getting
* You can verify and adjust
* Result: Reliable, matches your needs

**This guide teaches you**:

* How to "specify your constraints" (system thinking, data design)
* How to "verify the recipe" (testing, iteration)
* How to "adjust when needed" (AI prompts vs. manual edits)
* How to use Buzzy specifically (not generic vibe coding)

By the end, you'll build applications effectively with Buzzy's AI-powered no-code platform, avoid common pitfalls, and create solutions that scale and last.

## The Dream of Vibe Coding

**What vibe coding promises**:

* "Generate a full-stack app from a single prompt"
* "No coding knowledge needed"
* "Go from idea to production in days"

**What traditional vibe coding actually delivers** (using tools like Cursor, Claude Code, etc.):

```
You: "Build me a task management app"
AI: *generates 5,000 lines of React code*
Result: Works today... but in 6 months?
  - Dependencies are outdated
  - Security vulnerabilities discovered
  - Framework needs updating
  - You can't understand the generated code
  - Each fix requires regenerating everything
```

**What Buzzy delivers instead**:

* **Structured App Definitions** (not raw code to maintain)
  * Think of it like a recipe card vs. a cooked meal
  * Recipe card = App Definition (can be interpreted many ways)
  * Cooked meal = Generated code (fixed, becomes stale)
* **Professionally-maintained Core Engine** (not fragile AI-generated code)
  * Buzzy maintains the "kitchen" (React, React Native, infrastructure)
  * You focus on your "recipe" (app logic and design)
* **Server-level security built-in** (not client-side workarounds)
  * Security enforced at database level, can't be bypassed
  * Organizations and Teams for multi-tenant apps
* **Automatic updates and maintenance** (React/Native updates handled for you)
  * No dependency updates needed on your part
  * Security patches applied automatically
  * Framework upgrades don't break your app

**Simple analogy**:

* **Traditional vibe coding** = AI builds you a house from scratch. When the foundation cracks, you need to rebuild everything.
* **Buzzy** = AI designs your floor plan. Buzzy provides the professionally-maintained building that interprets your floor plan. When the building needs maintenance, Buzzy handles it.

## The Challenge with Traditional Vibe Coding

When using traditional AI coding tools (Cursor, Claude Code, Devin, etc.), you face real challenges:

### 1. Context Loss

Every prompt stands alone. The AI doesn't remember what you discussed 5 prompts ago, leading to:

* Inconsistent implementations
* Forgotten requirements
* Conflicting logic
* Regression of previously working features

### 2. Hidden Complexity

AI makes it look easy, but the generated code has:

* Hard-coded values that should be configurable
* Missing error handling
* Security vulnerabilities
* Performance issues that don't appear until scale
* Logic that works for the happy path but fails edge cases

### 3. Tech Debt Accumulation

AI-generated code accumulates technical debt rapidly:

* Thousands of lines of code you didn't write
* Outdated dependencies and frameworks
* Security updates requiring retesting everything
* Each change risks breaking everything
* Hard to maintain 6 months later with different AI/prompts

**Example scenario**: You vibe-coded an app with React 17 and various packages. Six months later, security updates are needed. You prompt the AI to update... it changes thousands of lines of code, using different patterns, and everything needs retesting. What was working behaves differently now.

## How Buzzy Solves These Problems

### Buzzy Creates App Definitions, Not Code

Unlike traditional vibe coding tools that generate raw code, **Buzzy creates structured App Definitions** that are interpreted by the **Buzzy Core Engine**. This fundamental difference solves most vibe coding problems.

**Visual comparison**:

**Traditional Vibe Coding**:

{% @mermaid/diagram content="%%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%%
graph TB
A1\[Your Prompt] --> B1\[AI Generates Code]
B1 --> C1\[React Code<br/>5,000+ lines]
C1 --> D1\[You Deploy]
D1 --> E1\[You Maintain<br/>Dependencies<br/>Security<br/>Updates]
E1 --> F1\[Tech Debt<br/>Accumulates]" %}

**Buzzy Approach**:

{% @mermaid/diagram content="%%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%%
graph TB
A2\[Your Prompt] --> B2\[Buzzy AI v3]
B2 --> C2\[App Definition<br/>Structured Data]
C2 --> D2\[Buzzy Core Engine<br/>Interprets]
D2 --> E2\[Buzzy Maintains<br/>Everything]
E2 --> F2\[No Tech Debt<br/>For You]" %}

**What this means in practice**:

**Traditional approach**:

```
Day 1: AI generates React code → You deploy → Works great!
Day 180: Security vulnerability in dependency
  → You prompt AI to update
  → AI regenerates with different patterns
  → Tests break, features behave differently
  → You spend days fixing and retesting
```

**Buzzy approach**:

```
Day 1: Buzzy AI generates App Definition → Buzzy deploys → Works great!
Day 180: Security vulnerability in React
  → Buzzy updates Core Engine automatically
  → Your app keeps working (no changes needed)
  → Zero work for you
```

[Learn more about this difference](https://docs.buzzy.buzz/working-with-buzzy/faqs#code-generation-vs.-buzzys-no-code-architecture-why-it-matters)

### Key Advantages

**1. No Maintenance Burden**

* Buzzy maintains the Core Engine professionally
* React and React Native updates handled automatically
* Security patches applied to all apps
* You focus on your app's logic, not framework maintenance

**2. Server-Level Security**

* Not "hiding" data with client-side logic
* Organizations and Teams built-in
* Proper access control at the database level
* Security best practices enforced by the platform

**3. Structured Development**

* Brief → Blueprint → Data → Design → Publish workflow
* Visual editor for safe manual changes
* No risk of "breaking the code" with edits
* Version control built-in

**4. Scalable Architecture**

* Kubernetes-based infrastructure
* Horizontal and vertical scaling
* Professional deployment and hosting
* Mobile (iOS/Android) and web from same definition

## What You Still Need to Learn

While Buzzy solves the tech debt problem, **building good applications still requires understanding**. Think of it like using a professional kitchen: the equipment is world-class, but you still need to know how to cook.

### 1. System Thinking

**What it means**: Understanding how applications work at a fundamental level.

**Non-technical explanation**: Before you can tell Buzzy what to build, you need to understand what an application actually is—screens, data storage, user interactions, security, etc.

**Why it matters**:

* ❌ Without it: "Build me a CRM" → AI creates random screens with no strategy
* ✅ With it: "Build a CRM where sales reps log calls, track follow-ups, and see deal progress" → AI creates focused, useful app

**You'll learn**:

* How apps are structured (Brief → Blueprint → Data → Design)
* User experience basics (how people actually use apps)
* Security fundamentals (Organizations, Teams, Viewers fields)

### 2. Data Design

**What it means**: Planning how information should be organized in your app.

**Non-technical explanation**: Like organizing files in folders—should customer info and order info be in the same place or separate? How do they connect?

**Buzzy-specific concepts**:

* **Subtables** (1:M): One parent, many children (e.g., one invoice has many line items)
* **Linked Table Fields** (N:M): Many-to-many (e.g., students take multiple classes, classes have multiple students)

**Sample prompt showing good data design thinking**:

```
Create a project management app with:

Data Model:
1. Projects Datatable (parent)
   - project_name, description, start_date, end_date
   - tasks (Subtable field pointing to Tasks datatable)
   
2. Tasks Datatable (child of Projects)
   - task_name, description, due_date, completed (yes/no)
   - embeddingRowID (automatically links to parent Project)
   - assignee (Linked Table Field to Users datatable)
   
3. Users Datatable
   - name, email
   - assigned_tasks (Linked Table Field to Tasks datatable)

This creates:
- 1:M relationship between Projects and Tasks (via Subtable)
- N:M relationship between Users and Tasks (via Linked Table Field)
```

### 3. Functional Design

**What it means**: Defining what users can do and how the app responds.

**Non-technical explanation**: It's the difference between "there's a button" and "when users click this button while on the orders screen, it opens a form to add a new order, validates the inputs, saves to the database, and returns to the updated orders list."

**Buzzy-specific concepts**:

* **Display rules**: Show/hide elements based on conditions
* **Actions**: Submit actions, navigation actions, update actions
* **Context**: What data is available on each screen

**Sample prompt showing good functional design thinking**:

```
For the Task List screen:
- Display all tasks where current user is in the Viewers field
- Show "Add Task" button at top (navigates to Add Task form)
- Each task card shows: title, due date, assignee name
- Use display rules to show completed tasks with strikethrough text
- Click on task card navigates to Task Detail screen
- Empty state: "No tasks yet. Click Add Task to get started."
```

### 4. Prompting Strategy

**What it means**: How to communicate effectively with Buzzy AI v3.

**The spectrum**:

* **Too vague**: "Build a task app" → AI guesses everything
* **Too technical**: "Create a React component with useState..." → Wrong approach for Buzzy
* **Just right**: "Build a task app with a Tasks Datatable. Users should see only their own tasks (use Viewers field). Include screens for: task list, add task form, and task detail." → AI understands your intent

**Sample prompts at different levels**:

**Beginner-level prompt** (still effective):

```
Create a simple recipe app where users can:
- Add recipes with title, ingredients, and instructions
- View a list of all their recipes
- Search recipes by title
- Delete recipes they no longer want

Make it mobile-friendly with a clean design.
```

**Intermediate-level prompt** (more control):

```
Create a recipe management app with:

Data Model:
- Recipes Datatable with fields:
  - title (text, required)
  - ingredients (long text)
  - instructions (long text)
  - prep_time (number, in minutes)
  - image (image field)
  - Viewers field (set to current user for privacy)

Screens:
1. Recipe List: Shows all user's recipes with title and image
2. Add Recipe: Form with all fields, submit action creates record
3. Recipe Detail: Shows full recipe, includes Edit and Delete buttons

Security: Users see only recipes where they're in Viewers field.
```

**Advanced-level prompt** (maximum control):

```
Create a recipe management app with social features:

Data Model:
1. Recipes Datatable:
   - title, description, ingredients (long text), instructions (long text)
   - prep_time, cook_time (numbers in minutes)
   - difficulty (dropdown: Easy/Medium/Hard)
   - cuisine (dropdown: Italian/Mexican/Chinese/Other)
   - image (image field)
   - author (auto-filled with current user)
   - is_public (yes/no field, defaults to no)
   - created_at (date field, automatic)
   - Viewers field for private recipes
   - Team Viewers field for shared recipes
   
2. Comments Datatable (Subtable of Recipes):
   - comment_text (long text)
   - commenter (auto-filled with current user)
   - created_at (date field)
   - embeddingRowID (links to parent Recipe)

Screens:
1. My Recipes screen:
   - Lists recipes where current user is author
   - Search by title, filter by difficulty/cuisine
   - "Add Recipe" button
   
2. Public Recipes screen:
   - Lists recipes where is_public = yes
   - Search and filter options
   - Click to view (but not edit others' recipes)

3. Add/Edit Recipe screen:
   - Form with all recipe fields
   - Toggle for is_public
   - Submit action saves to Recipes datatable

4. Recipe Detail screen:
   - Shows full recipe details
   - If current user is author: show Edit and Delete buttons
   - Comments section at bottom (Subtable view)
   - "Add Comment" button for all users

Display Rules:
- Edit/Delete buttons visible only if current user = recipe.author
- Private recipes visible only via Viewers field
- Public recipes visible to all authenticated users

Use card layout for recipe lists, mobile-responsive design.
```

### 5. Testing & Iteration

**What it means**: Making sure your app actually works and improving it based on real use.

**Non-technical explanation**: Just like testing a recipe by cooking it, you need to test your app by actually using it—and have others use it too.

**Buzzy-specific workflow**:

1. **Preview**: Use Buzzy's preview mode (click eye icon in workspace)
2. **Test as different users**: Create test accounts with different roles
3. **Check edge cases**: What if someone leaves a field blank? What if they're offline?
4. **AI prompts vs. manual edits**:
   * Use AI prompts for: New features, major restructuring, bulk changes
   * Use visual editor for: Fine-tuning layouts, adjusting colors, fixing small issues

**Sample testing checklist prompt**:

```
I need to test this task management app. Please add the following test scenarios:

1. Empty states:
   - Show "No tasks yet" message when task list is empty
   - Show "No projects" message when project list is empty

2. Error handling:
   - If task title is empty, show error: "Task title is required"
   - If due date is in the past, show warning: "This task is already overdue"

3. Permission testing:
   - Users should only see tasks where they're in Viewers field
   - Only task creator can delete tasks (add display rule to hide Delete button)

4. Edge cases:
   - Long task titles should wrap, not overflow
   - If no assignee selected, show "Unassigned" instead of blank
```

## What This Guide Covers

**Visual overview of the complete guide**:

{% @mermaid/diagram content="graph TD
A\[Start Here] --> B{Your Level?}

```
B -->|Complete Beginner| C[Part 1: Foundation]
B -->|Some Experience| D[Part 2: Process]
B -->|Ready to Build| E[Part 3: Practice]

C --> C1[System Thinking<br/>Learn app fundamentals]
C --> C2[Design Fundamentals<br/>Data + Functional Design]
C1 --> E
C2 --> E

D --> D1[Project Workflow<br/>Planning → Deployment]
D --> D2[AI vs Manual Edits<br/>When to use each]
D --> D3[Testing Strategies<br/>Verify it works]
D1 --> E
D2 --> E
D3 --> E

E --> E1[Hello World App<br/>Your first build]
E --> E2[External API<br/>Integrations]
E --> E3[AI-Powered<br/>Advanced features]
E1 --> F
E2 --> F
E3 --> F

F[Part 4: Best Practices]
F --> F1[App Quality<br/>Performance tips]
F --> F2[Security<br/>Organizations/Teams]
F --> F3[What NOT to Build<br/>Learn limitations]

F1 --> G[Build Your Real App]
F2 --> G
F3 --> G

G --> H{Problems?}
H -->|Data Structure Issues| C2
H -->|Performance Issues| F1
H -->|Security Questions| F2
H -->|All Good| I[Launch & Maintain]" %}
```

### Part 1: Foundation

[**System Thinking**](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/system-thinking): Understanding how applications work

**What you'll learn**:

* How applications are structured (entities, relationships, screens)
* User experience basics (flows, navigation, context)
* Buzzy's architecture (Brief → Blueprint → Data → Design → Publish)
* Security fundamentals (Organizations, Teams, Viewers fields)
* When your idea is too complex for Buzzy

**Who needs this**: Complete beginners, business users, anyone who hasn't built apps before

**Time investment**: 1-2 hours reading, worth every minute

[**Design Fundamentals**](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals): Data modeling and functional design for Buzzy

**What you'll learn**:

* **Data Design**: How to structure information using Subtables (1:M) and Linked Table Fields (N:M)
* **Functional Design**: How to define user actions, display rules, and navigation in Buzzy
* Real examples with sample prompts

**Who needs this**: Everyone - this is core to building ANY Buzzy app

**Time investment**: 2-3 hours, refer back often

### Part 2: Process

[**Project Workflow**](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow): From idea to deployed app

**What you'll learn**:

* Planning before prompting (saves massive time later)
* The Buzzy workflow: Brief → Blueprint → Data → Design
* **One-shot vs. iterative development** (when to use each)
* **AI prompts vs. manual edits** (most important skill)
* **Testing strategies** specific to Buzzy apps
* **Making changes** without breaking things
* **Rollback strategies** using Buzzy's version control
* **Deployment** to Buzzy's infrastructure
* **Maintenance** (minimal, since Buzzy maintains the Core Engine)

**Who needs this**: Everyone building real apps

**Time investment**: 3-4 hours, reference throughout your project

### Part 3: Practice

[**Building Examples**](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples): Hands-on walkthroughs with complete code

**What you'll build**:

1. [**Hello World App**](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/hello-world) (1-2 hours)
   * Simple task list
   * Learn the complete workflow
   * First Buzzy AI v3 prompts
   * Testing in preview mode
   * Your first published app
2. [**External API Integration**](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/external-api-integration) (2-3 hours)
   * Weather app using external API
   * Introduction to **Buzzy Functions** (AWS Lambda)
   * Secure Constants for API keys
   * Error handling patterns
3. [**AI-Powered App**](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/ai-powered-app) (3-4 hours)
   * Chat app with OpenAI integration
   * Advanced Buzzy Functions
   * Streaming responses
   * Cost management for AI APIs
4. [**Game Development**](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/game-development) (4-6 hours)
   * Turn-based game (not action games)
   * Complex game state management
   * Multiplayer considerations
   * What games work in Buzzy vs. what doesn't

**Who needs this**: Everyone - learning by doing is essential

**Recommended order**: Do Hello World first, then others based on your project needs

### Part 4: Best Practices

[**Best Practices**](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices): What works, what doesn't, and why

**What you'll learn**:

1. [**App Quality & Performance**](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/app-quality-performance)
   * How to build fast, reliable Buzzy apps
   * Common performance pitfalls
   * Testing strategies
   * When to optimize (and when not to)
2. [**Compliance & Security**](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/compliance-security)
   * **Organizations pattern** for multi-tenant SaaS
   * **Teams pattern** for role-based access
   * **Viewers fields** for personal data
   * GDPR and compliance considerations
   * What Buzzy handles vs. what you handle
3. [**What NOT to Build**](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/what-not-to-build) ⚠️ Read this early!
   * Apps unsuitable for Buzzy (and any no-code platform)
   * Real-time games, blockchain, enterprise ERP (initially)
   * When to use traditional development instead
   * How to scope projects realistically

**Who needs this**: Read before starting any serious project

**Time investment**: 2-3 hours, saves weeks of wasted effort

## Who This Guide Is For

**Non-Technical Builders**: Learn how to think like a system designer and communicate effectively with Buzzy AI v3.

**Business Users**: Understand how to structure requirements and validate AI-generated app structures.

**Designers**: Learn the technical implications of design decisions in Buzzy's visual editor.

**Developers**: Master prompting strategies for Buzzy and understand when to extend with Buzzy Functions.

**Product Managers**: Set realistic expectations and plan projects with Buzzy's capabilities in mind.

## How to Use This Guide

### For Complete Beginners (Never built an app before)

**Your path** (2-3 weeks to competence):

**Week 1: Understand the basics**

1. Read [System Thinking](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/system-thinking) - Don't skip this! It explains concepts that seem obvious to developers but aren't.
2. Complete the [Hello World App](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/hello-world) - Build something simple to understand the workflow

**Week 2: Learn data and design**\
3\. Study [Data Design](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals/data-design) - Focus on understanding Subtables vs. Linked Table Fields 4. Study [Functional Design](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals/functional-design) - Learn about display rules and actions 5. Build a second simple app (modify Hello World to add features)

**Week 3: Plan your real project** 6. Review [Best Practices](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices) - Learn what NOT to build 7. Plan your actual app using [Project Workflow](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow) 8. Start building with realistic expectations

### For Technical Users (Have some coding experience)

**Your path** (3-5 days to competence):

**Day 1: Understand Buzzy's unique approach**

* Read the [main introduction](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-with-ai) to understand App Definitions vs. code generation
* Review [System Thinking](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/system-thinking) focusing on Buzzy-specific architecture
* Learn about [Subtables and Linked Table Fields](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals/data-design)

**Day 2: Learn the workflow**

* Build the [Hello World App](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/hello-world)
* Understand [AI vs. Manual Edits](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/ai-vs-manual-edits)
* Review [Making Changes](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/making-changes) effectively

**Day 3: Advanced features**

* Build [External API Integration](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/external-api-integration) using Buzzy Functions
* Build [AI-Powered App](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/ai-powered-app) to understand advanced integrations
* Review [Security with Organizations/Teams](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/compliance-security)

**Day 4-5: Build your real project**

* Start with your actual project
* Reference specific sections as needed
* Test thoroughly before going live

### For Business Users / Product Managers

**Your path** (1 week to understand scope and feasibility):

**Step 1: Understand what's possible**

* Read [What NOT to Build](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/what-not-to-build) first - Learn the limitations
* Read [System Thinking](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/system-thinking) - Understand app complexity levels
* Review [Building Examples](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples) - See what's realistic

**Step 2: Plan effectively**

* Use [Project Workflow](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow) to set realistic timelines
* Understand [Testing Approaches](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/testing-approaches) - Know what to expect
* Review [Deployment](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/deployment) to plan go-live

**Step 3: Write better requirements**

* Study [Data Design](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals/data-design) to structure requirements
* Learn [Functional Design](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals/functional-design) to specify behaviors
* Use sample prompts throughout this guide as templates

### For Experienced Buzzy Users

**Use this as a reference**:

* Jump directly to sections relevant to your current challenge
* Review before major architectural decisions
* Share specific sections with team members to align understanding

**Quick navigation by problem**:

* "My data structure is getting messy" → [Data Design](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals/data-design)
* "Testing is taking forever" → [Testing Approaches](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/testing-approaches)
* "Need to integrate external services" → [External API Integration](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/external-api-integration)
* "App is slow or buggy" → [App Quality & Performance](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/app-quality-performance)
* "Need multi-tenant security" → [Compliance & Security](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/compliance-security)

## Quick Reference

### Stuck with a Specific Challenge?

**Data & Structure Questions**:

* "How do I structure my data?" → [Data Design](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals/data-design)
* "One parent record, many children (e.g., invoice with line items)?" → Use [Subtables](https://docs.buzzy.buzz/design-fundamentals/data-design#one-to-many-buzzy-subtables)
* "Many-to-many relationships (e.g., students ↔ classes)?" → Use [Linked Table Fields](https://docs.buzzy.buzz/design-fundamentals/data-design#many-to-many-buzzy-linked-table-fields)
* "How do I normalize data?" → [Data Design - Normalization](https://docs.buzzy.buzz/design-fundamentals/data-design#normalization)

**Functional Design Questions**:

* "How do I show/hide elements conditionally?" → [Display Rules](https://docs.buzzy.buzz/design-fundamentals/functional-design#display-rules)
* "How do I handle form submissions?" → [Actions - Submit](https://docs.buzzy.buzz/design-fundamentals/functional-design#actions)
* "How does navigation work?" → [Navigation Actions](https://docs.buzzy.buzz/design-fundamentals/functional-design#navigation-actions)
* "What's available on each screen?" → [Context](https://docs.buzzy.buzz/design-fundamentals/functional-design#context)

**Security Questions**:

* "How do I restrict access to data?" → [Viewers Fields](https://docs.buzzy.buzz/best-practices/compliance-security#viewers-pattern)
* "How do I build multi-tenant SaaS?" → [Organizations Pattern](https://docs.buzzy.buzz/best-practices/compliance-security#organizations-pattern)
* "How do I do role-based access?" → [Teams Pattern](https://docs.buzzy.buzz/best-practices/compliance-security#teams-pattern)

**Integration Questions**:

* "How do I call external APIs?" → [External API Integration](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/external-api-integration)
* "How do I add AI features?" → [AI-Powered App](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/ai-powered-app)
* "Where do I store API keys securely?" → [Buzzy Constants](https://docs.buzzy.buzz/building-examples/external-api-integration#secure-constants)

**Performance & Quality Questions**:

* "My app is slow" → [Performance Optimization](https://docs.buzzy.buzz/best-practices/app-quality-performance#performance-optimization)
* "How do I prevent bugs?" → [Testing Approaches](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/testing-approaches)
* "Should I optimize now?" → [When to Optimize](https://docs.buzzy.buzz/best-practices/app-quality-performance#when-to-optimize)

**Workflow Questions**:

* "Should I use AI prompt or manual edit?" → [AI vs. Manual Edits](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/ai-vs-manual-edits)
* "How do I handle changes safely?" → [Making Changes](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/making-changes)
* "How do I roll back mistakes?" → [Rollback Strategies](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/rollback-strategies)
* "How do I test my Buzzy app?" → [Testing Approaches](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/testing-approaches)
* "One big prompt or multiple small ones?" → [One-Shot vs. Iterative](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/one-shot-vs-iterative)

**Feasibility Questions**:

* "Can I build this with Buzzy?" → [What NOT to Build](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/what-not-to-build)
* "Is my idea too complex?" → [System Thinking - Complexity](https://docs.buzzy.buzz/system-thinking#how-complex-is-your-idea)

### Sample Prompts Library

**Complete beginner prompt** (for simple personal app):

```
Create a simple expense tracker where I can:
- Add expenses with description, amount, and date
- See a list of all my expenses
- Filter expenses by month
- See total expenses

Make it mobile-friendly.
```

**Intermediate prompt** (with data structure understanding):

```
Create an expense tracker with:

Data Model:
- Expenses Datatable with:
  - description (text)
  - amount (number)
  - category (dropdown: Food/Transport/Entertainment/Other)
  - date (date field, defaults to today)
  - receipt_image (image field, optional)
  - Viewers field (set to current user)

Screens:
1. Expense List: Shows all expenses, sorted by date (newest first)
2. Add Expense: Form with all fields
3. Monthly Summary: Shows total by category, with chart

Display Rules:
- Show warning if amount > 100 (unusual expense)
- Use different colors for each category
```

**Advanced prompt** (with Subtables and security):

```
Create a team expense management system with:

Data Model:
1. Organizations Datatable (built-in)
   - One organization per company using the app

2. Expense Reports Datatable:
   - report_name, created_date, status (dropdown: Draft/Submitted/Approved/Rejected)
   - submitter (auto-filled with current user)
   - approver (linked to Users with role "Manager")
   - total_amount (formula: sum of line_items.amount)
   - expenses (Subtable field → Expense Lines datatable)
   - Team Viewers field (set to "All Employees" team for visibility)
   
3. Expense Lines Datatable (child of Expense Reports):
   - description, amount, category, date
   - receipt_image
   - embeddingRowID (links to parent report)

4. Teams (built-in):
   - "Employees" team (can submit reports)
   - "Managers" team (can approve reports)
   - "Finance" team (can view all reports)

Screens:
1. My Reports: Shows reports where current user is submitter
2. Pending Approvals: Shows reports where current user is approver and status = Submitted
3. Add Report: Form to create report and add expense lines (Subtable view)
4. Report Detail: Shows report with all line items, approve/reject buttons

Display Rules:
- "Submit" button visible only if status = Draft AND submitter = current user
- "Approve"/"Reject" buttons visible only if status = Submitted AND approver = current user
- "Edit" available only if status = Draft

Security:
- Users see only reports they submitted OR where they're the approver OR they're in Finance team
- Use Organizations to separate different companies' data
```

## Common Mistakes to Avoid

### Mistake #1: Prompting Too Vaguely

❌ **Bad**: "Build a CRM"

* AI has no idea what features you want
* Results in generic, unusable app
* You'll spend more time fixing than if you planned first

✅ **Good**:

```
Build a CRM for small sales teams where sales reps can:
- Log customer interactions (calls, emails, meetings)
- Track deals through stages (Lead → Qualified → Proposal → Closed)
- See upcoming follow-ups on a dashboard
- Search customers by name or company

Data security: Each sales rep sees only their own customers (use Viewers field).
Mobile-friendly for field sales.
```

### Mistake #2: Not Understanding Data Relationships

❌ **Bad**: Storing all data in one big table

```
Orders table with columns:
- order_id, customer_name, customer_email, customer_phone,
  product1_name, product1_price, product1_quantity,
  product2_name, product2_price, product2_quantity, ...
```

**Problems**:

* What if an order has 10 products?
* What if customer info changes?
* Can't query products separately

✅ **Good**: Use Subtables (1:M relationship)

```
Orders Datatable:
- order_id, customer_name, order_date, total_amount
- line_items (Subtable → Order Lines datatable)

Order Lines Datatable:
- product_name, price, quantity
- embeddingRowID (automatically links to parent Order)
```

[Learn more about Subtables](https://docs.buzzy.buzz/design-fundamentals/data-design#one-to-many-buzzy-subtables)

### Mistake #3: Forgetting Security

❌ **Bad**: "Build a task app" (no security mentioned)

* Result: All users see all tasks (data leak!)
* No privacy, no multi-tenant support

✅ **Good**:

```
Build a task app where:
- Users see ONLY tasks where they are in the Viewers field
- When creating a task, Viewers field is automatically set to current user
- Task can be shared by adding other users to Viewers field
```

[Learn more about security](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/compliance-security)

### Mistake #4: Not Testing Edge Cases

❌ **Bad**: Only testing the happy path

* "I can add a task!" ✓
* Doesn't test: empty fields, network errors, concurrent edits

✅ **Good**: Test systematically

```
Test checklist:
- What if title field is empty? (should show error)
- What if network request fails? (should show retry)
- What if two people edit simultaneously? (Buzzy handles this)
- What if date is invalid? (should validate)
- What if user is offline? (should queue or show error)
```

[Learn more about testing](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/testing-approaches)

### Mistake #5: Building Too Much at Once

❌ **Bad**: "Build a complete project management platform with time tracking, invoicing, resource planning, and team chat"

* Overwhelming AI and yourself
* Takes months to build and test
* Likely to fail or never finish

✅ **Good**: Start with MVP (Minimum Viable Product)

```
Phase 1 (Week 1): Task list only
- Add tasks, mark complete, view list

Phase 2 (Week 2): Projects
- Group tasks into projects (Subtable)

Phase 3 (Week 3): Team collaboration
- Assign tasks to team members (Linked Table Field)

Phase 4+: Add more features based on real usage feedback
```

[Learn more about project workflow](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow)

### Mistake #6: Using the Wrong Relationship Type

❌ **Bad**: Using Linked Table Field for invoice line items

```
Invoices and Invoice Lines with Linked Table Field
```

**Problem**: Line items belong to exactly ONE invoice (1:M), not many (N:M)

✅ **Good**: Use Subtable for 1:M

```
Invoices Datatable with:
- line_items (Subtable field → Invoice Lines)

Invoice Lines Datatable with:
- embeddingRowID (auto-managed by Buzzy)
```

**When to use what**:

* **Subtable** (1:M): Parent-child, belongs to one parent (invoices → line items, projects → tasks)
* **Linked Table Field** (N:M): Many-to-many (students ↔ classes, products ↔ categories)

[Learn more about relationships](https://docs.buzzy.buzz/design-fundamentals/data-design#relationships-how-data-connects)

### Mistake #7: Not Using Buzzy's Version Control

❌ **Bad**: Making major changes directly without saving version

* Changes break something
* No way to go back
* Panic and frustration

✅ **Good**: Use Buzzy's versioning

```
Before major changes:
1. Go to Versions tab in Workspace
2. Create a new version with description: "Before adding user roles"
3. Make your changes
4. Test thoroughly
5. If broken, restore previous version in one click
```

[Learn more about rollback strategies](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/rollback-strategies)

## The "Last Mile" Reality

Even with Buzzy, you'll discover that getting to 90% is quick, but that final 10% takes effort:

**The 90% (Fast with Buzzy AI v3)**:

* ✅ Basic data structure created
* ✅ Screens generated
* ✅ Core functionality working
* ✅ Looks decent

**The Final 10% (Requires effort)**:

* Testing edge cases and error scenarios (What if the internet drops? What if user enters weird data?)
* Refining UX based on real user feedback ("This button is confusing", "I can't find the export feature")
* Performance optimization for your specific use case (e.g., you have 100,000 records, not 100)
* Data migration if moving from another system (cleaning old data, mapping fields)
* Training users on your new application (documentation, onboarding flows)

**Time breakdown example** (small business app):

* 90% complete: 2-3 days with Buzzy
* Final 10%: 1-2 weeks of polish and testing
* **Total**: 2-3 weeks vs. 3-6 months traditional development

**The difference**: With Buzzy, you're spending time on your app's logic and UX, not fighting framework updates and maintenance. That last 10% is productive work that improves your app, not technical debt that breaks it.

## Final Thoughts

Buzzy provides a powerful platform for AI-assisted application development, but it's **not a replacement for understanding**. The builders who succeed with Buzzy are those who:

1. **Understand fundamentals**: System design, data modeling with Subtables and Linked Table Fields, user flows
2. **Think critically**: Review AI outputs, understand the generated structure
3. **Use the platform effectively**: Know when to prompt AI vs. use visual editor
4. **Test thoroughly**: Don't trust it works until you've verified with real users
5. **Leverage Buzzy's strengths**: Server-level security, maintained Core Engine, scalable architecture

This guide gives you the knowledge to build applications with Buzzy that are not just functional today, but maintainable and scalable tomorrow.

Let's get started.