# Welcome to Buzzy No developer. No code. No problem. An intelligent, instant app platform, Buzzy empowers anyone to create fully functional, feature-rich, pixel perfect apps and websites in minutes - with no code! Buzzy helps you create working apps with real data, user-generated content, forms, screens, automation, and deployment options. You can start from a prompt, a template, an existing app, a Figma design, or a structured AI-agent workflow. For most serious builds, use [**Buzzy Builder MCP**](/the-building-blocks/mcp/buzzy-builder-mcp). It lets an AI agent such as Codex or Claude Code work with Buzzy in stages: brief, flows, data model, theme, blueprint, screens, sample data, and runtime verification. [**Buzzy AI**](https://app.buzzy.buzz) lets you create and edit apps directly from prompts in the Buzzy workspace. This is useful for quick app generation, focused edits, and early exploration. The [**Buzzy Figma plugin**](https://www.figma.com/community/plugin/980407395621457657) lets you design, test and deploy working apps with real data, user-generated content and live forms without leaving [Figma](https://www.figma.com/about/). {% hint style="success" %} New to Buzzy? Start with [Getting Started with Buzzy](/getting-started-with-buzzy/getting-started-with-buzzy), then use [What to use when](/getting-started-with-buzzy/what-to-use-when) to choose the right build path. {% endhint %} ## External Resources * [The Buzzy website (pricing info and more)](https://www.buzzy.buzz/) * [The Buzzy Figma plugin](https://www.figma.com/community/plugin/980407395621457657) * [Templates & demo apps](https://app.buzzy.buzz/app/3702d99d7ac3e3a578559cf4?_gl=1*1dzfupm*_ga_LB8G7B6ZQ1*MTcyNDYzODQ5Ny4xLjAuMTcyNDYzODQ5OS4wLjAuMA..) * [Figma files & templates](https://www.figma.com/@buzzy) * [Release notes](https://www.buzzy.buzz/release-notes) ## Support * [Accessibility at Buzzy](/accessibility) * [Discord community forum](https://discord.gg/qt7svhCMbj) * [Email support@buzzy.buzz](mailto:support@buzzy.buzz) {% hint style="info" %} **What is Figma?** [Figma](https://www.figma.com/about/) has become the leading collaborative graphics editing and user interface design app. It is used globally by designers, businesses and large organisations to build better products. {% endhint %} # Accessibility at Buzzy How Buzzy supports accessible custom app runtimes, MCP interfaces and the Buzzy Workspace, including current testing and practical verification paths. Buzzy is working to make both the applications created with Buzzy and Buzzy's own building interfaces accessible to as many people as possible. Our current engineering target for user-facing web interfaces is **WCAG 2.2 Level AA**. Accessibility in Buzzy is a governed delivery process: start with accessible platform components, test the real user journeys, keep evidence for the exact release scope, and complete human assistive-technology review before making a conformance claim. {% hint style="info" %} The results on this page describe the interfaces, applications, states and environments that have been tested. They do not certify every custom Buzzy app, mobile build, third-party integration or MCP client. Contact Buzzy when you need evidence for a particular product version, deployment or procurement scope. {% endhint %} ## The four Buzzy user interfaces Buzzy has four main user-facing interaction paths, excluding REST and other programmatic APIs: | Interface | What it is | Accessibility path | | ---------------------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | **Buzzy Custom App Runtime** | The web or mobile interface of an application built with Buzzy | Accessibility-aware Buzzy runtime and native components, app-specific automated checks, and manual browser/device testing | | **Buzzy Custom MCP** | Optional app-specific tools and selected Buzzy Functions exposed to an MCP client | A structured, conversational and potentially non-visual path governed by the app's tools, permissions and data model | | **Buzzy Workspace** | Buzzy's browser-based builder and application-management interface | First-party web accessibility engineering, repeatable browser checks and manual assistive-technology review | | **Buzzy Builder MCP** | Buzzy's MCP tools for building, inspecting, testing and managing applications through an agent | A structured builder path with accessibility inventory, preflight, browser audit, persisted evidence and release-gate tools | An organisation may use more than one path. For example, a team can build an app through Builder MCP, review it in the Workspace, publish it to the web and mobile runtimes, and optionally expose selected app functions through Custom MCP. ## Buzzy Custom App Runtime ### Web applications Published Buzzy applications run in a browser at their deployed app URL. Buzzy's web runtime and native components provide an accessibility-aware foundation for common application behavior, including: * semantic headings, landmarks, lists, tables, forms and controls * accessible names, labels, descriptions, validation and status announcements * keyboard operation, visible focus and dialog focus management * responsive reflow, zoom and text-spacing support * forced-colour/high-contrast and reduced-motion behavior * non-visual alternatives for maps, charts and other interactive visualisations where configured * authentication-aware experiences, including presenting a login path before protected actions The final accessibility of a custom app also depends on its screen design, content, configuration, roles, data states, code widgets and third-party integrations. App owners should verify every important user journey rather than assume that use of an accessible component makes the whole app conformant. ### Mobile applications Buzzy supports two mobile delivery paths: * **Capacitor** packages the Buzzy web runtime in an iOS or Android application container. It retains the web application's semantic foundation, while actual assistive-technology behavior also depends on the operating system, WebView, plugins and app configuration. * **React Native** provides a native-client path for supported Buzzy deployments. Native semantics and behavior must be reviewed on the target iOS and Android versions. Web-browser evidence does not by itself establish mobile accessibility. Before release, test the production mobile build with VoiceOver on iOS and TalkBack on Android, including navigation, forms, errors, dialogs, gestures, orientation, text scaling and any device-specific integrations. ### Current runtime testing Buzzy has completed scoped functional and automated accessibility work across representative Recipe, CRM, map and chart applications. The test approach includes real Playwright journeys, axe checks, keyboard/focus assertions, 320 CSS px reflow and disability-settings simulations, accessibility-tree inspection, screenshots and Lighthouse smoke checks. These representative results establish an engineering baseline for the tested applications and states. They are not a guarantee for every generated app or later app version, and browser accessibility-tree inspection is not a substitute for a screen reader. ## Buzzy Custom MCP Custom MCP can be enabled for an existing Buzzy app from its MCP configuration in the Workspace. An authenticated MCP client can then use the app-specific tools Buzzy exposes, including governed datatable operations and selected Buzzy Functions. Custom MCP can provide an alternative interaction path that does not depend on navigating the app's visual screens. Buzzy provides: * structured tool names, descriptions, inputs and outputs * OAuth-based user authentication * the app's existing row, field and Private Data permissions * control over the datatables, operations and functions exposed as tools * the option to wrap governed application logic in a Buzzy Function and expose that function through MCP MCP is a machine-to-machine protocol, not a visual user interface. The accessibility of ChatGPT, Claude or another MCP client is provided by that client and its platform. If an MCP client renders a Buzzy widget, that rendered widget is a user interface and should be tested separately. Buzzy does not describe an MCP client as WCAG conformant on the client's behalf. ## Buzzy Workspace The Buzzy Workspace is available through Buzzy's browser interface. It covers application creation and management, login and password recovery, dashboards, global navigation, editor panels, dialogs, tests, publishing and administration surfaces. The current first-party Workspace automated baseline covers: * login, failed login and password recovery * dashboard and global navigation * keyboard-based app creation, opening and reopening * 17 primary editor destinations * representative copy and destructive dialogs * global-admin Templates, Cookbooks, Toolkit and Widgets routes * representative populated editor states, including first-screen creation and version history * 320 CSS px reflow, forced colours, reduced motion and WCAG text-spacing simulations In the recorded Chromium/macOS scope, the accumulated Workspace suite completed **14 of 14 Playwright tests** and **40 of 40 first-party evidence rows**, with no serious or critical axe violations. Twenty-eight axe incomplete checks remain recorded for human disposition: 25 indeterminate contrast checks and three dialog focus-guard checks. Keyboard focus containment, Escape behavior and trigger-focus restoration passed for the representative dialogs. This is a strong automated baseline for the tested Workspace scope, not a complete conformance statement. VoiceOver/Safari, NVDA/Chrome or Firefox, real zoom, platform high contrast and accountable human review remain part of the release-evidence path. Optional third-party interfaces are assessed separately when enabled. ## Buzzy Builder MCP Builder MCP lets an MCP-capable agent such as Codex or Claude Code build, inspect, test and manage a Buzzy application through structured tools. Connect from **Account Settings → Developer → MCP Access**, using OAuth where supported or a bearer token when an approved client requires it. Builder MCP is another way to operate Buzzy; it does not replace the accessibility of the visual Workspace. The accessibility of the agent application's own interface is the responsibility of that client. Buzzy's Builder MCP tools help the agent create and verify accessible Buzzy outputs. ### Accessibility tools available to builders | Builder MCP tool | What it provides | What it does not prove | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | `get_native_widget_accessibility_matrix` | Inventories the native widgets and functional categories present in an app, with applicable WCAG criteria, required checks, complexity, effort and risk | It is a planning matrix, not a test result | | `audit_app_accessibility_structure` | Runs a deterministic preflight over persisted screens and returns stable findings for issues such as missing form ownership, missing action names, heading structure, image alternatives and code-widget review | It does not run the app in a browser or screen reader | | `run_app_accessibility_audit` | Runs and persists an isolated-browser audit of route-backed states using axe, code-widget frame checks, keyboard traversal, 320 CSS px reflow, forced colours, reduced motion, accessibility-tree inspection and screenshots | It cannot judge every human, content, screen-reader or mobile requirement | | `get_app_accessibility_run` | Retrieves one persisted run with its state snapshot, findings and evidence | It only describes that recorded run and scope | | `list_app_accessibility_runs` | Lists prior persisted runs so repeated results can be compared | It does not imply that a newer app version still passes | | `get_app_accessibility_release_gate` | Evaluates explicitly selected run IDs, required screen coverage, structural findings, manual-evidence status and accountable review; returns `pass`, `fail`, `blocked` or `manual_evidence_required` | It does not expand the selected scope or turn automation into certification | ### Recommended Builder MCP verification flow 1. Finish and review the app's data model, screen inventory and authentication posture. 2. Call `get_native_widget_accessibility_matrix` and keep only the categories marked as present. 3. Call `audit_app_accessibility_structure`, repair deterministic failures by finding code, and rerun the preflight. 4. Run the real functional journey first using generated or saved Playwright tests. Reach dialogs and child contexts through visible actions rather than direct URLs. 5. Call `run_app_accessibility_audit` with explicit route-backed states where the default inventory is not sufficient. 6. Retrieve the persisted evidence with `get_app_accessibility_run` or compare runs with `list_app_accessibility_runs`. 7. Complete the manual checks below and keep references to the results with the release evidence. 8. Call `get_app_accessibility_release_gate` with the exact run IDs and every screen ID required by the release scope. 9. Publish only the narrow claim returned for that evidence scope. A result of `manual_evidence_required` means the automated evidence is ready but human verification or approval is still missing. ## How to test manually Automated tools find many common failures, but they cannot determine whether an experience is understandable and usable for a person with a disability. Test the real task from beginning to end, including anonymous, authenticated, empty, loading, validation-error, success and destructive-confirmation states. ### Keyboard-only Put the mouse or trackpad aside and complete each journey with the keyboard: * use Tab and Shift+Tab to check that focus follows a logical order and remains visible * use Enter and Space to activate controls as expected * verify that every action is reachable and no region traps focus * open dialogs, check that focus enters and remains in the dialog, then close it and confirm focus returns to the invoking control * verify that skip links, menus, disclosures, tables, maps, charts and custom widgets have an operable keyboard path ### Screen readers Use at least one combination relevant to the release. For higher-risk or customer-facing releases, include both major desktop platforms: * VoiceOver with Safari on macOS * NVDA with Firefox or Chrome on Windows * VoiceOver on iOS for Capacitor or React Native iOS builds * TalkBack on Android for Capacitor or React Native Android builds Check headings and landmarks, control name/role/state, field labels and instructions, errors, live status updates, table relationships, dialog announcements, focus movement and non-visual access to maps, charts and custom widgets. Listen to the experience rather than only inspecting the browser accessibility tree. ### Zoom, reflow and text spacing * test real browser zoom at 200% and 400% * test a narrow 320 CSS px viewport without losing content or actions * increase text spacing to at least 1.5 times font-size line height, 2 times font-size paragraph spacing, 0.12 times font-size letter spacing and 0.16 times font-size word spacing * check that content does not overlap, clip, disappear or require two-dimensional scrolling except where the content itself genuinely requires it * on mobile, test the operating system's larger text and display settings ### Colour, contrast and motion * use Windows Contrast Themes or the relevant platform high-contrast settings * verify that focus, selected state, errors and meaning do not depend on colour alone * check text and control contrast in the actual rendered state, including content over images or charts * enable reduced motion and confirm that essential information and controls remain available without unnecessary animation ### Record the result Keep a simple evidence matrix containing: * app and version * route, screen, role and state * expected and actual result * browser, operating system, viewport and assistive technology/version * PASS, FAIL, BLOCKED or NOT TESTED * applicable WCAG criteria * screenshot, trace, audit or manual note reference * defect, fix and rerun date Do not include passwords, tokens, session identifiers or private customer data in screenshots or reports. For criterion-level guidance, see the [W3C WCAG 2.2 Quick Reference](https://www.w3.org/WAI/WCAG22/quickref/). ## Shared responsibility | Party | Responsibility | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **Buzzy** | Platform semantics, accessible native-component foundations, Workspace engineering, Builder MCP verification tools and documented testing paths | | **App owner** | App content, workflows, roles, permissions, custom code, code widgets, external integrations, app-specific testing and release decisions | | **MCP client provider** | Accessibility of the MCP client's own interface and any client-rendered widget container | | **Mobile publisher** | Testing the final signed build on supported devices, operating-system versions and assistive technologies | ## Standards, evidence and claims Buzzy's current engineering target is WCAG 2.2 Level AA for user-facing web behavior. Where a customer needs EN 301 549, AS EN 301 549, an Accessibility Conformance Report or another procurement artifact, the applicable product version, deployment, user journeys, exclusions and evidence package must be agreed and reviewed explicitly. An automated pass is evidence for the tested scope; it is not by itself proof that an app or the Buzzy product is WCAG conformant. A conformance statement should name the product and version, tested scope, methods, browser and assistive-technology matrix, known limitations, evidence date and accountable reviewer. ## Feedback and accessibility requests Contact to report an accessibility problem or discuss evidence for a customer deployment. Include the interface or app, page or task, browser/device, assistive technology and a description of what prevented completion. Do not send passwords, authentication tokens or sensitive customer data. **Statement last reviewed:** 30 July 2026 **Current engineering target:** WCAG 2.2 Level AA # Start Here Choose the right Buzzy workflow before you start building. Buzzy gives you several ways to create and improve an app. The best starting point depends on how much structure you already have, whether you want to work with an AI agent, and how much visual control you need. For most serious app builds today, start with **Buzzy Builder MCP**. It gives an AI agent such as Codex or Claude Code a structured way to build with Buzzy in stages: brief, flows, data model, theme, blueprint, screens, sample data, and verification. {% hint style="success" %} **Recommended for new builders:** use [Buzzy Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp), especially when you want to build from a template, work iteratively, inspect the app with screenshots, or test real workflows before shipping. {% endhint %} ## Choose Your Starting Path | If you want to... | Start with... | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------- | | Build a production-minded app with staged review | [Buzzy Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp) | | Adapt an existing template into a new app | [Builder MCP from a template](/the-building-blocks/mcp/buzzy-builder-mcp/from-a-template) | | Create a quick prompt-first app in the workspace | [Buzzy AI prompt workflow](/getting-started-with-buzzy/new-buzzy-ai-v3) | | Design and publish directly from Figma | [Buzzy Figma plugin](/getting-started-with-buzzy/getting-started-with-figma) | | Change an app that already exists | [Builder MCP for existing apps](/the-building-blocks/mcp/buzzy-builder-mcp/editing-existing-apps) | For a fuller comparison, see [What to use when](/getting-started-with-buzzy/what-to-use-when). ## The Recommended Builder Workflow The most reliable Buzzy builds are planned and reviewed in stages: 1. define the app brief 2. map the key flows 3. model the data 4. choose the theme direction 5. review the blueprint and navigation 6. generate or adapt screens 7. add realistic sample data 8. verify the app in preview or runtime This staged flow keeps changes easier to review and cheaper to correct. It is especially important for apps with roles, permissions, sensitive data, payments, external integrations, or several connected workflows. ## Helpful Next Reads * [Getting started with Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp/getting-started) * [Tutorial: Build a carer app from a template](/the-building-blocks/mcp/buzzy-builder-mcp/tutorial-carer-app-from-a-template) * [The building blocks](/the-building-blocks/the-building-blocks) * [The Ultimate Guide for Vibe Coding an Application with AI](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-with-ai) * [In-App Debugging](/troubleshooting/in-app-debugging) # What to Use When Buzzy has multiple creation paths because builders start from different places. Use this guide to pick the right workflow before you spend time prompting, designing, or adapting an app. ## Quick Decision Table | Workflow | Best for | Use when | Avoid when | | --------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | **Builder MCP from a template** | Fastest reliable path for common app patterns | A template is structurally close to your idea | You need a completely novel data model or interaction pattern | | **Builder MCP from scratch** | Serious custom apps | You want staged review of brief, flows, data, screens, and runtime behavior | You only need a quick throwaway prototype | | **Builder MCP for an existing app** | Focused changes and refinements | You already have an app and want an agent to inspect, plan, edit, and verify | You have not identified the target app or change | | **Builder MCP from an external app/codebase** | Migration or rebuild projects | You have a Lovable app, legacy app, screenshots, or codebase to use as reference | You expect source code to be copied directly into Buzzy unchanged | | **Builder MCP from a Figma file** | Agent-assisted builds using a design reference | You want Buzzy structure plus design direction from Figma | You need to keep editing the live app entirely through Figma | | **Buzzy AI prompt workflow** | Quick prompt-first app generation | You want to generate or edit directly in the Buzzy workspace | You need careful staged artifact review or external-agent testing | | **Buzzy Figma plugin** | Figma-native no-code design | You want to design, mark up, and publish from Figma | You are starting from a Buzzy AI app that is not editable in Figma | ## Recommended Defaults Use **Builder MCP from a template** when a template is close enough. It gives you a proven starting structure and lets the agent focus on adapting the app to your domain. Use **Builder MCP from scratch** when your app has custom workflows, sensitive data, complex permissions, or a data model that needs careful review. Use **Buzzy AI prompt workflow** when speed matters more than staged review. It is a good way to explore an idea quickly inside the Buzzy workspace. Use **Buzzy Figma plugin** when your primary workflow is visual design in Figma and you want to keep working there. ## Good Builder Habits * Plan first: describe the app, roles, data, and core workflow before asking for screens. * Build in layers: brief, flows, data model, theme, blueprint, screens, sample data, verification. * Keep review gates small enough to inspect. * Use templates and reference apps for proven structure. * Use Playwright, screenshots, or browser inspection for important runtime paths. * Verify permissions and sensitive data with both allowed and denied users where relevant. # Buzzy AI Prompt Workflow Buzzy AI v3 launched in August 2025. ## Overview {% embed url="" %} Buzzy AI enables you to generate and edit full-stack applications directly from prompts inside the Buzzy workspace. This guide covers the prompt-first workflow: writing prompts, previewing the app, understanding the workspace, editing with AI, using the Design tab, debugging, themes, troubleshooting, and release tests. If you are choosing a build path for the first time, start with [Getting Started with Buzzy](/getting-started-with-buzzy/getting-started-with-buzzy) and [What to use when](/getting-started-with-buzzy/what-to-use-when). For serious staged builds, template adaptation, existing-app changes, external codebase rebuilds, or Figma-reference builds, [Buzzy Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp) is usually the better starting point. {% hint style="info" %} New apps generated via Buzzy AI are not the same as apps created through the Buzzy Figma plugin. If you want to keep working primarily in Figma, start with the [Buzzy Figma plugin](/getting-started-with-buzzy/getting-started-with-figma). If you want an AI agent to build, inspect, and verify the app in stages, start with [Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp). {% endhint %} *** ## Sections {% content-ref url="/pages/L1tiETwoeP5jpN3nxbUP" %} [1. Writing a Prompt](/getting-started-with-buzzy/new-buzzy-ai-v3/1.-writing-a-prompt) {% endcontent-ref %} {% content-ref url="/pages/lCNTFvfjU7MJC9vho9ld" %} [2. Previewing Your App](/getting-started-with-buzzy/new-buzzy-ai-v3/2.-previewing-your-app) {% endcontent-ref %} {% content-ref url="/pages/uozVGG0MdjY0UXlUdwPr" %} [3. Understanding the Workspace Editor](/getting-started-with-buzzy/new-buzzy-ai-v3/3.-understanding-the-workspace-editor) {% endcontent-ref %} {% content-ref url="/pages/bbkmFWmvz1A0FBgAWhfO" %} [4. Editing your app via AI](/getting-started-with-buzzy/new-buzzy-ai-v3/4.-editing-your-app-via-ai) {% endcontent-ref %} {% content-ref url="/pages/5D5mGuetPUkKGlF1rfLX" %} [5. Editing your app in the Design Tab](/getting-started-with-buzzy/new-buzzy-ai-v3/5.-editing-your-app-in-the-design-tab) {% endcontent-ref %} {% content-ref url="/pages/UfENnkegF3nld5uTsQFt" %} [6. Debugging with the Debug Tab and Debug Agent](/getting-started-with-buzzy/new-buzzy-ai-v3/6.-debugging-with-the-debug-tab-and-agent) {% endcontent-ref %} {% content-ref url="/pages/F3BIImMQhhNVMhbBX3eD" %} [7. Working with themes](/getting-started-with-buzzy/new-buzzy-ai-v3/7.-working-with-themes) {% endcontent-ref %} {% content-ref url="/pages/ZEkHMGpis5IYVN3EMwbN" %} [8. Troubleshooting](/getting-started-with-buzzy/new-buzzy-ai-v3/8.-troubleshooting) {% endcontent-ref %} {% content-ref url="/pages/DdevOQVjXNd87rPXyo0G" %} [9. Release Tests](/getting-started-with-buzzy/new-buzzy-ai-v3/9.-release-tests) {% endcontent-ref %} # 1. Writing a Prompt
Start by describing what you want to build in plain language. Prompts can range from a short description to a detailed breakdown of features, roles, data, flows, or screens. Prompt-first creation is best for quick starts and focused edits. For larger apps, use the same planning discipline you would use with [Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp): define the brief, flows, data model, screen intent, and review checkpoints before asking Buzzy to build too much at once. **Example prompts:** * "A to-do list app with projects and due dates." * "A mobile-first CRM dashboard for tracking customer interactions and sales pipelines." Prompts can be entered: * From the **Workspace** home screen (to start a new app) * From the **Design > AI** section (to update an existing screen or app) ## What to Include * what the app is for * who uses it * the core data objects and relationships * the main user journeys * permissions or private data rules * the most important screens * integrations, functions, or external APIs * what should be left out of the first version {% hint style="info" %} For complex apps, avoid one giant prompt that tries to finish everything. Start with the app shape, review what Buzzy creates, then iterate through data, screens, debugging, testing, and deployment. {% endhint %} # 2. Previewing Your App

Preview your app in the Workspace Editor view

After submitting a prompt, Buzzy generates an app structure, including screens, data, and UI components. The Buzzy Workspace will switch to the Workspace Editor view, which has a navigation panel on the left that lets you access your entire app's structure, including brief, data model, design, settings and more. See below for more. The App Editor will default to the Design view, were you'll see a preview of your app when it's ready. Not every screen will be generated at first - the editor will prompt you to create the missing ones when needed. You can also **preview a live version of the generated app** by clicking the **Live view** button in the top toolbar. This opens a live version of the app using real data and navigation. **Preview features:** * Test real interactions (e.g. forms, navigation) * View responsive layouts * Interact with mock or connected data # 3. Understanding the Workspace Editor
When a prompt is processed, the Buzzy Workspace is populated with structured views of your app. The sidebar navigation is organised into the following sections: *** ## Dashboard A central overview of your app, showing key information such as app name, creator, creation date, and last modified date. The Dashboard also provides quick links to documentation and getting started guides, as well as a summary of your app's development progress and suggested next steps. *** ## BUILD #### 🔹 Brief A high-level summary of what your app does, based on your prompt. You can revise this at any time to re-guide the AI. #### 🔹 Blueprint An auto-generated list of screens and key components. This gives a birds-eye view of your app's structure and user flow. Note: Blueprint is hidden for Figma-created apps. #### 🔹 Design Where you view and edit the actual screens. This includes layout, components, bindings, actions, and screen-level logic. Inside the Design workspace you will usually work across four areas: * the left panel for screen structure and assets * the centre preview for interacting with the current screen * the right-hand tabs for **Properties**, **Code**, and **Debug** * the AI chat panel for prompting, diagnosis, and autofix suggestions The **Debug** tab is contextual to the current screen or selected node. It shows issue counts, data-binding details, runtime context, and entry points for AI diagnosis. The AI chat panel also includes a dedicated diagnose flow, so you can start debugging from either side of the editor. For Figma-created apps, screens are previewed here but are not directly editable. A button is provided to open the linked Figma file for editing. #### 🔹 Data A list of data collections (e.g. tasks, users, products) and their fields. These power your app's dynamic content. *** ## CONFIGURE #### 🔹 Constants `Beta` Secure storage for API keys, passwords, database URLs, and other configuration values used by your app and its Functions. Constants can be regular (plain text) or secret (AES-encrypted). Use the `BUZZYCONSTANTS()` syntax to reference them in your Functions' environment variables. #### 🔹 MCP `Beta` Configure [Model Context Protocol (MCP)](/the-building-blocks/mcp) for your app. MCP enables AI assistants like ChatGPT and Claude to interact with your app through natural language — querying data, creating records, and performing actions. Buzzy automatically generates the MCP server and tools from your app's data model. #### 🔹 Functions `Beta` Build and manage serverless [Buzzy Functions](/the-building-blocks/buzzy-functions-and-constants/buzzy-functions) — AWS Lambda functions that extend your app with custom code for external API integrations, AI processing, webhooks, and complex business logic. Functions can be written manually or generated with AI from a natural language prompt. #### 🔹 People Where you can manage access and permissions for your app. #### 🔹 Settings Control your app's settings and core information here, including privacy and publish status, custom header code and more. *** ## RELEASE #### 🔹 Publish Shows your app's publish information (live URL, QR code to preview on a device) and more. It also includes deployment controls and information — you'll need to sign up to a deployment plan to get your app into one of the app stores. #### 🔹 Tests Create and run reusable [Release Tests](/getting-started-with-buzzy/new-buzzy-ai-v3/9.-release-tests) for important app workflows before you publish. The Tests section includes saved test definitions, manual authoring, viewport targets, and run history. #### 🔹 Versions Buzzy includes version control so you can roll back to previous versions if needed. # 4. Editing your app via AI Once your app has been generated, you can continue to use AI to make changes at any time. Open the **AI** chat panel (top right in the toolbar) and describe what you want to change in plain language. AI editing works across several areas of your app: * **Theming** — Ask AI to change your app's look and feel. You can switch between built-in themes (e.g. *"Switch to the Zen theme"*), toggle dark or light mode, adjust colours, typography, shadows, borders and more. See the [Working with themes](/getting-started-with-buzzy/new-buzzy-ai-v3/7.-working-with-themes) section for details. * **Data model** — Ask AI to add, rename or restructure data collections and fields (e.g. *"Add a priority field to the Tasks table"*, *"Create a new Comments collection linked to Posts"*). * **Screens & layout** — Request new screens, rearrange layouts, or add UI components (e.g. *"Add a dashboard screen with summary cards"*, *"Change the list to a two-column grid"*). * **Logic & actions** — Describe behaviour changes such as navigation flows, form submissions or button actions (e.g. *"When the user submits the form, navigate to the confirmation screen"*). > 💡 Tip: You can combine multiple requests in a single prompt — for example *"Add a search bar to the top of the Products screen and switch to dark mode."* ## Diagnosing before changing When something looks broken, it is often better to diagnose first and edit second. Buzzy's AI panel supports both workflows: * normal editing prompts, where you ask Buzzy to change the app * debug diagnosis, where you ask Buzzy to explain what is wrong before you change anything ### Using the debug button If you already have the relevant screen or component selected, click the debug or diagnose entry point in the AI panel without adding extra text. Buzzy uses the current editor context to inspect the selected node or screen and returns a structured diagnosis. ### Guiding the diagnosis with a short prompt You can also add a short prompt before diagnosing, especially when you want Buzzy to focus on a specific symptom. For example: * "Why is this list empty?" * "Check whether this button is navigating to the wrong place." * "Find out why this form does not save." Keep the prompt short. The editor context already carries most of the technical detail. ### From diagnosis to autofix Diagnosis results can include one or more recommended fixes and an autofix button. Review the diagnosis before you apply a fix. If you want a deeper view of the current binding or issue counts first, open the **Debug** tab in the right-hand panel and launch diagnosis from there instead. For the full workflow, see [Debugging with the Debug Tab and Debug Agent](/getting-started-with-buzzy/new-buzzy-ai-v3/6.-debugging-with-the-debug-tab-and-agent). # 5. Editing your app in the Design Tab The Design tab is where you make direct screen-level changes in the editor. It supports both AI-assisted changes and manual editing, so you can move quickly between prompting, selecting, inspecting, and adjusting the layout. ## Make changes with AI from the Design tab 1. Open **Build** > **Design**. 2. Choose the screen you want to change from the screen picker above the preview. 3. Open the **AI** panel from the top-right toolbar if it is not already visible. 4. Enter a prompt describing the change you want, such as "Add a search bar at the top", "Change this list to a two-column grid", or "Add an export button below the table". The AI updates the selected screen based on your instruction. Review the result in the preview before moving on.

You can collapse the navigation and chat panels when you want more room to inspect the screen.

## Make manual changes in Edit mode 1. With the correct screen open, switch the preview to **Edit** mode. 2. Select an item directly in the preview or from the left-hand structure panel. 3. Use the right-hand tabs to inspect and edit the selection: * **Properties** for labels, layout, actions, bindings, and display settings * **Code** when a selected element exposes editable code-backed configuration * **Debug** when you want to inspect bindings, context, and issues before changing anything > 💡 Tip: You can mix manual edits, AI edits, and debug diagnosis in the same session. ## Insert components from Assets 1. Open **Design** and switch the preview to **Edit** mode. 2. Select the area or component where you want to insert something new. 3. Open the **Assets** tab in the left panel. 4. Browse or search the available Buzzy components. 5. Preview the asset if needed. 6. Choose **Before**, **After**, or **Inside** to insert it relative to the current selection.
## Diagnose a problem before editing If a component looks wrong, open the **Debug** tab before you start making changes. This is especially useful for: * broken data bindings * visibility or display-rule issues * repeated content such as lists and sub-tables * actions that appear to be wired incorrectly From the Debug tab, you can inspect the issue list and launch **Diagnose with AI** for the current selection or screen. For the full debug workflow, see [Debugging with the Debug Tab and Debug Agent](/getting-started-with-buzzy/new-buzzy-ai-v3/6.-debugging-with-the-debug-tab-and-agent). *** For more examples and help, visit the [Buzzy AI Prompt Guide](https://docs.buzzy.buzz/getting-started-with-buzzy/buzzy-ai/example-prompts). # 6. Debugging with the Debug Tab and Debug Agent The Buzzy editor includes a built-in debugging workflow for screens, components, and data bindings. You can use it to spot problems visually, understand what is selected, ask AI for a diagnosis, and apply targeted fixes without leaving the editor.
Buzzy workspace editor showing the preview, left navigation, AI chat panel, and the right-hand Debug tab.

The Debug workflow lives inside the editor, alongside the normal design and AI tools.

## What these tools are for Use the **Debug** tab when you want structured, contextual information about the current screen or selected node. Use the debug agent when you want help interpreting those signals, narrowing the problem, or generating a safe autofix. In practice, the workflow is: 1. Select the screen or component that seems wrong. 2. Open the **Debug** tab to inspect issue counts, bindings, and context. 3. Launch diagnosis from the Debug tab or the AI chat. 4. Review the diagnosis and apply an autofix if the recommendation matches what you want. 5. Re-check the screen after the change. ## Debug tab vs debug agent Use the **Debug** tab when you need: * a quick read of the current selection * issue counts for the selected node or full screen * data-binding details * runtime context such as row data, table fields, visibility, or display information Use the **debug agent** when you need: * help understanding what the issues mean * a plain-language summary of what is broken * a recommended fix strategy * an autofix for a clearly scoped problem ## Diagnose the current selection 1. Open **Build** > **Design** and choose the screen you want to inspect. 2. Switch the preview to **Edit** mode. 3. Click the exact item that looks wrong in the preview or select it from the left panel. 4. Open the **Debug** tab in the right-hand panel. 5. Review the selection summary, binding details, and issue list. 6. Click **Diagnose with AI** if you want Buzzy to explain the problem and suggest a fix.
Debug tab focused on a selected review component, showing issue counts, the current selection section, and a Diagnose with AI button.

Selection-level diagnosis is the fastest way to investigate one broken control or binding.

Selection scope also affects the fix packages Buzzy can offer. If you select a single component or branch first, Buzzy can keep the repair focused on that area instead of proposing a broader screen cleanup. ## Diagnose the current screen Sometimes the issue is broader than one component. In that case, click the screen itself in the left panel or clear the selection until the screen is the active context, then open **Debug** again. At screen scope, Buzzy shows: * the total node count for the screen * the number of info, warning, and error items in scope * issues on the current screen * descendant issues for child nodes deeper in the layout You can click a descendant issue to jump directly to the affected node.
Debug tab showing screen-level issue counts and a descendant issue entry for a review component.

Screen scope is useful when you know a screen is broken but do not yet know which component is causing it.

Use screen scope when you want a broader repair pass. At that level, Buzzy can offer fixes for all errors on the screen, all warnings on the screen, or a full cleanup across both. ## Guide the diagnosis with a short prompt You do not need to type a prompt to use the debug tools, but a short prompt can help when the issue is ambiguous. For example: * "Why is this review list empty?" * "Check whether this button is wired to the wrong screen." * "Find out why this form does not submit." Keep the prompt short and focused on the visible problem. The selected screen or node provides most of the technical context automatically. The debug agent is strongest when the selected node or screen is clearly related to the visible issue and the cause is present in the current structure, binding, or runtime context. It is less reliable for problems driven by external services, live data quality, or causes far away from the current screen. If the first diagnosis is too broad, change the selection and run it again. ## Reading the Debug tab The exact sections vary by context, but the Debug tab can include: * **Selection**: what is currently selected and how Buzzy is interpreting it * **Data binding**: which table, field, or row context the node is using * **Issues**: current-selection issues plus descendant issues * **Visibility and display**: conditions that affect whether something appears * **Runtime context**: context such as route, row, or surrounding view state * **Row data** or **Table fields**: extra data context when Buzzy can infer it Issue severity is grouped as: * **Info**: useful context or a condition to be aware of * **Warning**: something looks suspicious and may cause a problem * **Error**: Buzzy found a concrete misconfiguration or broken dependency ## Focused selection in repeating content When you click inside repeating content such as a list, table, or sub-table view, Buzzy tries to select the focused rendered instance you actually clicked. This is important because repeated layouts often share one design definition but render many rows. That focused selection helps the Debug tab give more precise context for: * the active row * the bound field or view * where a repeated child sits inside its parent data structure ## Read diagnosis results After you click **Diagnose with AI**, the AI panel returns a structured diagnosis. This usually includes: * the main issues Buzzy found * a plain-language explanation of what those issues mean * one or more recommended fixes * a fix button when Buzzy can offer an autofix
AI chat panel showing a diagnosis with issues listed, a recommended fix, and a fix button.

The diagnosis explains what Buzzy found before you decide whether to run an autofix.

## Using autofix safely Autofix can be used broadly or narrowly depending on what you want to change. You can fix all of the errors on a screen in one run, or you can select one area first if you want a more cautious, smaller-scope change. Before you click a fix button: 1. Check that the diagnosis matches the issue you are trying to solve. 2. Make sure the selection or screen scope is correct. 3. Choose the full-screen fix if you want Buzzy to clean up everything in scope, or choose the narrower fix if you want to limit the changes to one part of the screen. Autofix recommendations are usually narrow and concrete. They commonly focus on things like reconnecting a binding to the right field type, fixing a broken screen or action reference, or moving a control back into the view context it needs. After the fix runs, re-open the Debug tab and confirm that the error count has dropped or the original issue has disappeared. ## Verifying the result After any diagnosis or autofix: 1. Re-check the affected screen in **Preview**. 2. Return to **Edit** mode and inspect the same node again. 3. Confirm the Debug tab no longer shows the original error. 4. Test the real workflow that was failing, such as opening the view, submitting the form, or using the button. If you need a reference for the individual Debug sections and common issue types, see the [In-App Debugging](/troubleshooting/in-app-debugging). # 7. Working with themes Buzzy AI apps come with a powerful theming system. Every app starts with a default theme, and you can customise it — or switch to an entirely different one — via AI prompts or the Theme editor tab. ## Theming with AI You can ask Buzzy AI to make theme changes in natural language. The AI will decide the best course of action — whether that's tweaking a few variables, toggling dark mode, or rebasing your entire theme on a different default. **What AI can do with themes:** | Action | When it's used | Example prompt | | -------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------- | | **Choose a starting theme** | On app creation, AI picks a suitable default based on your prompt | *"Build a wellness tracker app with a calm, natural look"* | | **Customise the starting theme** | On app creation with specific style guidance | *"Start with the Zen theme but use orange as the primary colour"* | | **Update specific parts** | Refine colours, typography, shadows, or borders without switching theme | *"Use a warm grey background with softer shadows and no borders"* | | **Toggle light/dark mode** | Switch between light and dark mode | *"Switch to dark mode"* | | **Switch to a different theme** | Rebase onto a completely different named default theme | *"Switch to the Slate theme"* | | **Reset to default** | Revert all customisations back to the basic Buzzy default | *"Reset theme to default"* | **More example prompts:** * *"Switch to the Fashion theme"* * *"Make it light mode"* * *"Use blue as the primary colour"* * *"Give it a softer, rounder look with subtle shadows"* * *"Switch to the Stone theme but keep our brand colour"* * *"Revert to the default dark mode theme"* ## Available default themes Buzzy ships with several built-in named themes. Each is available in both **light** and **dark** variants. When no specific theme is requested, Buzzy uses the **Neutral** theme as a starting point. | Theme | Description | Best suited for | | ----------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | **Neutral** | Clean, basic monochromatic theme with no shadows and elegant use of borders and whitespace. Good default or starting point. | AI, tech, corporate, enterprise, consumer, prototyping | | **Zinc** | Softer, approachable theme with rounded corners and soft shadows. Friendly, modern look. | Consumer apps, lifestyle, productivity | | **Slate** | Cool, crisp theme with sharp corners and a cyan accent. Information-dense and efficient. | Dashboards, SaaS, developer tools, data-heavy apps | | **Stone** | Warm, earthy, natural theme with a strong, approachable feel. | Hospitality, food, service | | **Zen** | Calm, meditative, gentle theme. Softer than Stone, with generous rounding and no borders. | Health, wellness, meditation, mindfulness | | **Fashion** | High-contrast black-and-white editorial theme with sharp edges, solid borders, and no shadows. | Fashion, online stores, blogs, media, journalism | | **Air** | Bright, neutral theme with large rounded corners, soft depth, and restrained coral accents. | Booking flows, hospitality, travel, marketplaces | ## The Theme tab in the editor You can also view and fine-tune your app's theme manually via the **Theme** tab in the workspace editor's left-hand navigation panel. The Theme tab gives you direct control over: * **Dark mode** — Toggle between light and dark mode. * **Brand colours** — Set your primary, link, info, success, warning, and danger colours. * **Scheme colour** — The foundational base colour from which many UI colours are derived. * **Typography** — Configure font families (primary, secondary, code), base font size, weight, line height, and heading styles. * **Border radius** — Control the roundness of UI elements (from sharp to fully rounded). * **Shadows** — Enable or disable shadows, and adjust offset, blur, spread, and opacity. * **Borders** — Configure border visibility, colour, and luminosity. * **Body background** — Adjust the overall page background colour or luminosity. Changes made in the Theme tab apply globally across all screens in your app. You can mix manual theme edits with AI-driven changes at any time. # 8. Troubleshooting Occasionally you might run into a bug or situation where the Buzzy Workspace stops working. It may be loading a blank screen, showing a broken layout, or otherwise behaving in a way you did not expect. ## Step 1: Use the Debug tab first when the editor still loads If the editor opens but one screen or component seems broken, start with the built-in debug tools before you refresh the browser. Open **Build** > **Design**, select the affected screen or component, and then open the **Debug** tab in the right-hand panel. Use it to: * check whether the issue is on the current selection or a descendant node * review data binding and runtime context * launch **Diagnose with AI** * apply a recommended autofix when the diagnosis is clear and narrow For the full workflow, see [Debugging with the Debug Tab and Debug Agent](/getting-started-with-buzzy/new-buzzy-ai-v3/6.-debugging-with-the-debug-tab-and-agent) and the [In-App Debugging](/troubleshooting/in-app-debugging). ## Step 2: Refresh the page The first thing to try is refreshing the current page in the browser. How you do this will depend on your device and browser, but generally there will be a refresh icon or button at the top near the url bar.
Screenshot showing refresh button in the Chrome browser on a Mac.

The refresh button in Chrome (shown in MacOS).

## Step 3: Clear your cache If a simple refresh doesn't work, try clearing the cache. Again, how you do this will depend on your browser. Here's how to do this in some common browsers: ### Safari (Desktop) To clear the Safari cache on a Mac, go to the Develop menu and select Empty Caches, or go to Settings > Privacy > Manage Website Data and click Remove All. The "Develop" method is faster for cache only, while the "Privacy" method clears both cache and cookies for all websites. ### Chrome (Desktop) To clear the cache in Chrome, open the browser, click the three dots in the top-right corner, and select **More tools > Clear browsing data**. Next, choose a time range from the dropdown menu (select "All time" to delete everything) and ensure the "Cached images and files" box is checked, then click **Clear data**. **BONUS: Chrome also has a shortcut to do this:**
### Microsoft Edge To clear the cache in Microsoft Edge, go to Settings and more (...) > Settings > Privacy, search, and services, then select Clear browsing data and choose the types of data and time range you want to delete before clicking Clear now\.Alternatively, you can use the keyboard shortcut `Ctrl+Shift+Del` or type `edge://settings/clearbrowserdata` in the address bar for a quicker method. ### Firefox To clear the cache in Firefox, click the menu button (three horizontal lines) in the top-right corner, go to "History," then "Clear Recent History." In the pop-up window, set the "Time range to clear" to "Everything," check the box for "Cache," and click "Clear Now". ### Internet Explorer To clear Internet Explorer's cache, open the browser, press Ctrl + Shift + Delete, uncheck "Preserve Favorites Website Data," ensure "Temporary Internet Files and website files" and "Cookies and website data" are selected, and then click Delete. Close and reopen Internet Explorer for the changes to take effect. (Also, why are you still using this?!) # 9. Release Tests Release Tests help you create reusable checks for important app workflows before you publish or hand an app to users. They are designed for practical smoke and regression testing: confirm the key paths still work, catch obvious breakages, and keep a record of what was run. Release Tests are not a replacement for human review. You should still check layout, wording, permissions, unusual edge cases, and the parts of the user experience that need judgement. ## Open the Tests section 1. Open your app in the Buzzy Workspace editor. 2. In the left navigation, go to **Release**. 3. Select **Tests**. The Tests panel is titled **Release Tests**. It lets you define reusable tests for the app, then run them as a suite against the live runtime. ## Test Suite Library The main area of the Tests section is the **Test Suite Library**. It has two main tabs: * **Definitions**: saved tests you can search, filter, edit, run, duplicate, archive, or restore. * **Run History**: suite run history, including the status of previous test runs. Each saved test can show: * its name and description * viewport target, such as Desktop, Tablet, or Mobile * whether it was created manually or generated * active, draft, archived, or disabled status where relevant * latest run status * how many runs have been recorded Use search, status filters, and sorting when the list grows. Archived tests are hidden from the active list until you switch the status filter or restore them. ## Create tests The Tests section supports reusable test definitions. Manual test creation is the available authoring path. The two AI-assisted creation options, **Generate starter tests** and **Add test from prompt**, are shown as **Coming soon** in this workflow. ### Generate starter tests `Coming soon` The UI includes a **Generate starter tests** option labeled **Coming soon**. It does not create tests in this workflow. Use **Create manually** to build the tests you want in the suite. ### Add test from prompt `Coming soon` The UI also includes an **Add test from prompt** option labeled **Coming soon**. The intended input is a plain-language test description such as: ``` Open a restaurant detail page, read the reviews, create a new review, submit it, and verify the new review appears. ``` This prompt-based workflow is designed around: * choose one or more viewport targets * describe the user flow, expected proof points, and any important runtime details * generate one or more saved test definitions For this workflow, write the test manually and use **Record** to capture supported interactions from the preview. ### Create manually Use **Create manually** when you want direct control over the script. The **Create test** dialog asks for: * **Name** * a short description of what the test should cover * **Viewport target** After creation, the authoring workspace opens. A new manual test starts with a visit step so the test has a runtime page to begin from. ## Author a manual test Manual authoring has three working areas: * **Steps**: the scripted actions and checks in order. * **Details**: the selected step's type, target, value, and supporting information. * **Preview**: the app runtime shown inside the editor so you can inspect or record actions.
Buzzy manual test authoring workspace in Record mode, showing a live app preview and recording controls.

The manual authoring workspace lets you inspect or record steps against the app preview.

Use **Add** or **Add after** to insert steps. Use the previous and next step controls to move through the script. Common steps include visiting a route, clicking a test ID, filling a field, waiting for an element, and asserting that something is visible. The Preview area has three modes: * **Use app**: interact with the runtime normally. * **Inspect**: select runtime targets without triggering their actions. This is useful when choosing buttons, fields, or visible proof points for a step. * **Record**: capture supported clicks and field input from the preview into the test script. When you choose **Record**, Buzzy shows **Start recording steps** with a short checklist. Make sure the preview is on the right starting screen, then click buttons, links, and fields in the preview. Recorded steps appear in the script so you can review and adjust them before saving. Use **Save Test** or **Save Changes** to save without running. Use **Save & Run** when you want to save the script and immediately execute it. ## Viewport targets Release Tests can target: * **Desktop** * **Tablet** * **Mobile** Viewport target is set when the test is created and cannot be changed later. Create a separate test for another target when you need coverage across different screen sizes. ## Run tests
Buzzy Test Suite Library with two saved tests selected and Run selected visible.

Select saved tests in Definitions, then use Run or Run selected to execute them.

From **Definitions**, you can: * run one test with **Run** * select multiple tests and click **Run selected** * edit or view **Details** for a saved test * archive, restore, duplicate, or regenerate supported generated tests from the actions menu Runs execute against the live runtime. If the app or environment needs time to respond, a run may briefly show queued, starting, or running states before it passes or fails.
Buzzy suite run detail dialog showing a passed test with What ran, Execution details, and Debug details sections.

Open run details to review pass/fail status, step information, execution details, debug output, and proof where available.

## Read run results Use **Run History** to review suite history. A suite run can include: * overall status * app version information where available * viewport summary * live URL * individual test runs * planned steps and step results * execution details * debug details * proof screenshots, when captured Step summaries may show passed, failed, pending, or planned-only results. If only planned steps are available, treat that as an incomplete run record rather than proof that every step passed. When a run fails, open the run details and look for the first failing step. Fix the app or the test at that point, then rerun. Avoid rewriting steps that already passed unless the user flow itself has changed. ## Recommended workflow 1. Start with the main user journeys: login, key forms, important navigation, submissions, permissions, and the workflows users rely on most. 2. Create a small manual suite. 3. Review each test definition before trusting it. 4. Run the suite before publishing. 5. Fix app issues or refine tests. 6. Rerun the suite until the important tests pass. 7. Keep useful tests active and archive stale tests. For broader testing strategy, see [Testing Approaches](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/testing-approaches). For a broader product overview, see [Buzzy Next](https://www.buzzy.buzz/buzzy-next/) or watch the [Buzzy Next release video](https://www.youtube.com/watch?v=9u-a-xtW0aA). {% hint style="info" %} Release Tests work best as repeatable checks for important paths. Use them alongside preview testing, live app checks, permission review, and real user feedback. {% endhint %} # Getting Started with Figma This series of short video lessons focuses on using the Buzzy Figma plugin to manually create a custom app from scratch. It will step you through the creation of a simple app, starting with basic screens and slowly introducing more advanced concepts. This is essential knowledge for taking an AI-generated app, and refining it for production. {% content-ref url="/pages/OmAdkHmXMbuFjSk7o7tj" %} [1. Using Buzzy with Figma](/getting-started-with-buzzy/getting-started-with-figma/1.-using-buzzy-with-figma) {% endcontent-ref %} {% content-ref url="/pages/YKRn2K5eLsUwhyII6MxM" %} [2. The Buzzy Figma plugin](/getting-started-with-buzzy/getting-started-with-figma/2.-the-buzzy-figma-plugin) {% endcontent-ref %} {% content-ref url="/pages/tysWyYPxYtrwA7Anw2bg" %} [3. Creating a simple app](/getting-started-with-buzzy/getting-started-with-figma/3.-creating-a-simple-app) {% endcontent-ref %} {% content-ref url="/pages/w8du9niN3oIZ9Z5Cs8M5" %} [4. Screens and navigation](/getting-started-with-buzzy/getting-started-with-figma/4.-screens-and-navigation) {% endcontent-ref %} {% content-ref url="/pages/F2OpCIENQURDrS6WnRua" %} [5. Forms, fields and data](/getting-started-with-buzzy/getting-started-with-figma/5.-forms-fields-and-data) {% endcontent-ref %} {% content-ref url="/pages/GDmTj1QXaT9RraAmzXgr" %} [6. Data-driven menus & content](/getting-started-with-buzzy/getting-started-with-figma/6.-data-driven-menus-and-content) {% endcontent-ref %} {% content-ref url="/pages/yHEVfyUu9UA36af2sEbd" %} [7. Data edit and delete](/getting-started-with-buzzy/getting-started-with-figma/7.-data-edit-and-delete) {% endcontent-ref %} {% content-ref url="/pages/B22IHVzvT6W99HX7xPyI" %} [8. Search, sort and filter](/getting-started-with-buzzy/getting-started-with-figma/8.-search-sort-and-filter) {% endcontent-ref %} {% content-ref url="/pages/RCPMwpjcfHoOM2KhVjBo" %} [9. User login and registration](/getting-started-with-buzzy/getting-started-with-figma/9.-user-login-and-registration) {% endcontent-ref %} *** ### Extending Buzzy with code Coming soon - this section will look at extending Buzzy with code widgets and API calls, external integrations, and other advanced concepts. In the mean time, check out some of our existing articles, videos and templates: {% embed url="" %} {% embed url="" %} {% embed url="" %} {% embed url="" %} {% embed url="" %} {% hint style="success" %} [Template: Course Quiz App](https://app.buzzy.buzz/app/3702d99d7ac3e3a578559cf4/cd3d3f61ca1be15dfc1dcbc2/KKyiytQeb6otJwvPjpCJJr7B) A quiz app consisting of courses and multiple choice quizzes, with an admin interface and simple login flow. Uses code widgets to add and remove courses from a student account and manage data duplication/deletion. {% endhint %} {% hint style="success" %} [Template: AI-powered chat app](https://app.buzzy.buzz/app/3702d99d7ac3e3a578559cf4/cd3d3f61ca1be15dfc1dcbc2/wR9rXzwbq8aHfB8LPnfq7hr5) A real AI-powered chatbot, with chat history, login and search. Requires some manual setup to integrate a working AI into your Buzzy app. {% endhint %} {% hint style="success" %} [Template: Contact list with search examples](https://app.buzzy.buzz/app/3702d99d7ac3e3a578559cf4/cd3d3f61ca1be15dfc1dcbc2/B52ZDTtjSJPjRfLb5Dme8XFY) A simple single-field search, a formula-based search of multiple fields plus a custom filter example using a code widget to provide more complex range-based filtering. {% endhint %} # 1. Using Buzzy with Figma Introduces the Buzzy plugin for Figma, and explains the difference between the free version and the Buzzy AI subscription version. {% embed url="" %} **Key words**: Figma account, plugin, connect to Buzzy, new account, email address, start screen, Buzzy AI subscription, import, automarkup, expert mode, manual mode, free # 2. The Buzzy Figma plugin An overview of the Buzzy Figma plugin, demonstrating how it works and integrates with your Figma design. Learn about the different modes, features, and tabs available in the plugin and how they help you create and iterate on your apps. {% embed url="" %} **Key words**: Figma design, Buzzy plugin, connect to account, AI subscription, wizard mode, expert mode, manual mode, context, Figma page, multiple Buzzy apps, Figma components and variables, import AI app, automarkup, data model, brief, data model, design, publish, preview, workspace, live update # 3. Creating a simple app The process of using the Buzzy Figma plugin to create a simple example application. We demonstrate how to convert a basic Figma splash screen design into a Buzzy app, touching on essential concepts such as selecting items, marking up elements, setting up the layout, and publishing the app. We also discuss how Figma's autolayout features translate to Buzzy's responsive behaviours and show how to preview and update the app in real-time. {% embed url="" %} Keywords: Layout, screen, start screen, basic screen, overlay screen, autolayout, flex, responsive, frames, layers, publish, update, preview # 4. Screens and navigation Expand our Buzzy app from a single screen to multiple screens, connecting them with screen-based navigation. We'll demonstrate how to define 'Basic' and 'Overlay' screens, configure navigation actions, and ensure responsive design. We also address issues like screen scrolling and fixed-position elements using Figma's settings. {% embed url="" %} **Key words**: Layout, screen, start screen, basic screen, overlay screen, navigation, actions, autolayout, flex, responsive, frames, layers, scroll, positioning, fixed, sticky, nesting, publish, update, preview # 5. Forms, fields and data Dive into Buzzy's data capabilities - learn how to create dynamic forms, fields, and inputs that capture real data. Follow along as we set up a data table, mark up a form, and configure fields and buttons for data submission within a responsive Buzzy app. {% embed url="" %} **Key words**: Layout, component, form, read, edit, capture, add, data, data table, data table row, insert, field, input, button, action, submit # 6. Data-driven menus & content Learn how to add a simple data-based menu to an app directly from your Figma design file - including pagination and a 'load more' action. Then turn this into dynamic navigation, linking to a detail screen for each data row. {% embed url="" %} **Key words**: Layout, component, form, view, list, menu, results, no results, mode, pagination, auto load, load more, actions, navigate, repeat, ignore, data table, data table row, field, value, read, summary, preview # 7. Data edit and delete Adding to our simple data-driven app demo, we're going to enable users to edit and delete the data they've added to our app. Includes adding confirmation dialogs and success messages. {% embed url="" %} **Key words**: Layout, component, form, view, list, menu, context, current data, results, no results, edit mode, overlay, close, delete # 8. Search, sort and filter {% hint style="info" %} A simple 'getting started' video on this topic is coming soon. In the meantime, the following information should provide a good reference. {% endhint %} The video and example app below demonstrate basic search functionality with the [Buzzy Figma plugin](https://www.figma.com/community/plugin/980407395621457657/Buzzy---No-Code-App-Builder), using the 'Filter' component. The video covers two search examples - a simple text-only search, and a more complex one using a formula field to search two data columns at once. The demo Figma file linked below includes those, plus an additional 'advanced' example where we implement an 'age range' filter, using a custom HTML code widget. {% embed url="" %} The FIgma file used in the video above is available as a Buzzy Figma community file: {% embed url="" %} # 9. User login and registration {% hint style="info" %} A simple 'getting started' video on this topic is coming soon. In the meantime, the following information should provide a good reference. {% endhint %} {% hint style="info" %} There are multiple ways of achieving this, and some of our template files include a simpler method - see the [AI-poowered chat app](https://app.buzzy.buzz/app/3702d99d7ac3e3a578559cf4/cd3d3f61ca1be15dfc1dcbc2/wR9rXzwbq8aHfB8LPnfq7hr5), the [course quiz app](https://app.buzzy.buzz/app/3702d99d7ac3e3a578559cf4/cd3d3f61ca1be15dfc1dcbc2/KKyiytQeb6otJwvPjpCJJr7B) and the [location reporting app](https://app.buzzy.buzz/app/3702d99d7ac3e3a578559cf4/cd3d3f61ca1be15dfc1dcbc2/P7h2oFqYsEowJgwmwXaikwR5) for working examples. {% endhint %} The video and example app below demonstrate how to set up a user registration and login flow from Figma using the Buzzy Figma plugin. {% embed url="" %} The FIgma file used in the video above is available as a Buzzy Figma community file: {% embed url="" %} # Introduction A comprehensive guide to building applications with AI using Buzzy's no-code platform, understanding the challenges of vibe coding, and mastering Buzzy's unique approach. ## 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. For current build-path guidance, start with [What to Use When](/getting-started-with-buzzy/what-to-use-when): Builder MCP is usually the strongest path for serious staged builds, while prompt-first Buzzy AI and the Figma plugin remain useful for the right cases. ## 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 %%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%% graph TB A1[Your Prompt] --> B1[AI Generates Code] B1 --> C1[React Code
5,000+ lines] C1 --> D1[You Deploy] D1 --> E1[You Maintain
Dependencies
Security
Updates] E1 --> F1[Tech Debt
Accumulates] ``` **Buzzy Approach**: ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%% graph TB A2[Your Prompt or Builder MCP Plan] --> B2[Buzzy App Builder] B2 --> C2[App Definition
Structured Data] C2 --> D2[Buzzy Core Engine
Interprets] D2 --> E2[Buzzy Maintains
Everything] E2 --> F2[No Tech Debt
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 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. **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 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
Learn app fundamentals] C --> C2[Design Fundamentals
Data + Functional Design] C1 --> E C2 --> E D --> D1[Project Workflow
Planning → Deployment] D --> D2[AI vs Manual Edits
When to use each] D --> D3[Testing Strategies
Verify it works] D1 --> E D2 --> E D3 --> E E --> E1[Hello World App
Your first build] E --> E2[External API
Integrations] E --> E3[AI-Powered
Advanced features] E1 --> F E2 --> F E3 --> F F[Part 4: Best Practices] F --> F1[App Quality
Performance tips] F --> F2[Security
Organizations/Teams] F --> F3[What NOT to Build
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**](/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**](/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**](/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**](/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**](/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 prompts * Testing in preview mode * Your first published app 2. [**Short Stay to Care Connect**](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/short-stay-template-adaptation) * Adapt a proven marketplace template into a new app domain * Use Builder MCP to inspect and change a semantic app definition * Review data, roles, booking flows, privacy, tests, and release risk 3. [**Builder MCP Change and Extension Workflow**](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/builder-mcp-change-workflows) * Modify an existing app safely * Generate or update code widgets * Create Buzzy Functions and wire them to app actions * Verify changes with preview, Release Tests, and Security Review 4. [**External API Integration**](/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 5. [**AI-Powered App Features**](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/ai-powered-app) (3-4 hours) * Add AI behavior inside a Buzzy app * Use Buzzy Functions and Constants for provider calls * Add code widgets only when richer AI UX is needed * Test AI outputs, permission paths, and error handling **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**](/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**](/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**](/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**](/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. **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](/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](/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](/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](/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](/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](/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](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-with-ai) to understand App Definitions vs. code generation * Review [System Thinking](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/system-thinking) focusing on Buzzy-specific architecture * Learn about [Subtables and Linked Table Fields](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals/data-design) **Day 2: Learn the workflow** * Build the [Hello World App](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/hello-world) * Understand [AI vs. Manual Edits](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/ai-vs-manual-edits) * Review [Making Changes](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/making-changes) effectively **Day 3: Advanced features** * Review [Short Stay to Care Connect](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/short-stay-template-adaptation) for template adaptation with Builder MCP * Build [External API Integration](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/external-api-integration) using Buzzy Functions * Build [AI-Powered App Features](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/ai-powered-app) to understand AI integrations inside a Buzzy app * Review [Security with Organizations/Teams](/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](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/what-not-to-build) first - Learn the limitations * Read [System Thinking](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/system-thinking) - Understand app complexity levels * Review [Building Examples](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples) - See what's realistic **Step 2: Plan effectively** * Use [Project Workflow](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow) to set realistic timelines * Understand [Testing Approaches](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/testing-approaches) - Know what to expect * Review [Deployment](/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](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals/data-design) to structure requirements * Learn [Functional Design](/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](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals/data-design) * "Testing is taking forever" → [Testing Approaches](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/testing-approaches) * "Need to integrate external services" → [External API Integration](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/external-api-integration) * "Need to adapt an existing app or template" → [Short Stay to Care Connect](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/short-stay-template-adaptation) * "Need to change an existing app safely" → [Builder MCP Change and Extension Workflow](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/builder-mcp-change-workflows) * "App is slow or buggy" → [App Quality & Performance](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/app-quality-performance) * "Need multi-tenant security" → [Compliance & Security](/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](/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](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals/data-design#one-to-many-buzzy-subtables) * "Many-to-many relationships (e.g., students ↔ classes)?" → Use [Linked Table Fields](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals/data-design#many-to-many-buzzy-linked-table-fields) * "How do I normalize data?" → [Data Design - Normalization](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals/data-design#normalization) **Functional Design Questions**: * "How do I show/hide elements conditionally?" → [Display Rules](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals/functional-design#display-rules) * "How do I handle form submissions?" → [Actions - Submit](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals/functional-design#actions) * "How does navigation work?" → [Navigation Actions](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals/functional-design#navigation-actions) * "What's available on each screen?" → [Context](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals/functional-design#context) **Security Questions**: * "How do I restrict access to data?" → [Viewers Fields](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/compliance-security#viewers-pattern) * "How do I build multi-tenant SaaS?" → [Organizations Pattern](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/compliance-security#organizations-pattern) * "How do I do role-based access?" → [Teams Pattern](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/compliance-security#teams-pattern) **Integration Questions**: * "How do I call external APIs?" → [External API Integration](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/external-api-integration) * "How do I add AI features?" → [AI-Powered App Features](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/ai-powered-app) * "Where do I store API keys securely?" → [Buzzy Constants](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/external-api-integration#secure-constants) **Performance & Quality Questions**: * "My app is slow" → [Performance Optimization](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/app-quality-performance#performance-optimization) * "How do I prevent bugs?" → [Testing Approaches](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/testing-approaches) * "Should I optimize now?" → [When to Optimize](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/app-quality-performance#when-to-optimize) **Workflow Questions**: * "Should I use AI prompt or manual edit?" → [AI vs. Manual Edits](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/ai-vs-manual-edits) * "How do I handle changes safely?" → [Making Changes](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/making-changes) * "How do I roll back mistakes?" → [Rollback Strategies](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/rollback-strategies) * "How do I test my Buzzy app?" → [Testing Approaches](/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](/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](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/what-not-to-build) * "Is my idea too complex?" → [System Thinking - Complexity](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/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](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/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](/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](/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](/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](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/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](/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)**: * ✅ 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. # System Thinking Understanding the fundamentals that experienced developers take for granted—essential knowledge for building successful applications with AI. ## Why System Thinking Matters **The hidden complexity problem**: When you ask AI to build an application, it generates code based on your description. But here's the challenge: **the AI assumes you understand what you're asking for**. **Think of it like ordering food**: * **Without understanding**: "I want food" → You get random food (might not match your diet, taste, budget) * **With understanding**: "I want a vegetarian Thai curry, medium spice, under $15, ready in 30 minutes" → You get what you actually want **Experienced developers naturally think in terms of**: * User experience flows (how people actually use the app) * Data relationships and integrity (how information connects) * Security boundaries and access control (who can see/do what) * Performance and scalability (will it work with 10,000 users?) * Error handling and edge cases (what if something goes wrong?) **Example of hidden complexity**: Without this foundation, you might say "build me a recipe app" and not realize you're actually requesting: ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%% graph TD A[Simple Request:
'Build a recipe app'] --> C[Data Structure] A --> D[Security] A --> E[User Experience] A --> F[Technical Details] C --> C1[Recipe schema] C --> C2[User relationships] C --> C3[Categories/tags] D --> D1[Authentication] D --> D2[Who sees what?] D --> D3[Edit permissions] E --> E1[Navigation flow] E --> E2[Search/filter] E --> E3[Mobile layout] F --> F1[API integrations?] F --> F2[Error handling] F --> F3[State management] F --> F4[Image uploads] style A fill:#c6f,stroke:#333,color:#000 style C fill:#09d,stroke:#333,color:#fff style D fill:#09d,stroke:#333,color:#fff style E fill:#09d,stroke:#333,color:#fff style F fill:#09d,stroke:#333,color:#fff ``` **Better approach**: Understand what you're building BEFORE prompting **Bad prompt**: "Build a recipe app" * AI makes dozens of assumptions * Result likely doesn't match your vision * Lots of fixing needed **Good prompt** (after system thinking): ``` Build a recipe app where users can: - Add their own recipes (title, ingredients, instructions, prep time, image) - Browse all their recipes in a grid view - Search recipes by title or ingredient - Recipes are private (each user sees only their own via Viewers field) Data Model: - Recipes Datatable with Viewers field for privacy Screens: - Recipe List (grid of cards) - Add Recipe (form) - Recipe Detail (full view with Edit/Delete buttons) Mobile-friendly design with clean layout. ``` ## How Complex Is Your Idea? Before you write your first prompt, assess the complexity. This helps set realistic expectations and plan your approach. **Visual complexity spectrum**: ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%% graph TD A[Simple
1-2 weeks] --> B[Moderate
3-6 weeks] --> C[Complex
2-3 months+] A1[AI does 90%
You refine 10%] -.-> A B1[AI does 60%
You build 40%] -.-> B C1[AI does 30%
You architect 70%] -.-> C style A fill:#4a4,stroke:#333,color:#fff style B fill:#fa3,stroke:#333,color:#000 style C fill:#f66,stroke:#333,color:#000 ``` ### Simple Applications (Good for AI) 🟢 **Characteristics**: * **Single user type** doing straightforward tasks * **Basic data relationships** (mostly one-to-many using Subtables) * **Standard patterns** (forms, lists, basic search) * **Minimal external integration** **Examples**: * Personal task list * Recipe collection * Simple inventory tracker * Contact list * Event calendar **Sample simple prompt**: ``` Create a personal recipe collection app where I can: - Add recipes with title, ingredients, instructions, and photo - View all my recipes in a scrollable list - Search recipes by title - Edit or delete recipes Data: Recipes Datatable with Viewers field (only I see my recipes) Screens: Recipe List, Add Recipe, Recipe Detail Mobile-friendly design ``` **Time estimate with Buzzy**: 1-2 weeks including testing and polish ### Moderate Applications (AI + Manual Work) 🟡 **Characteristics**: * **Multiple user types** with different permissions (Admins, Users, Managers) * **Complex relationships** (many-to-many using Linked Table Fields, hierarchical data) * **Custom business logic** and calculations (JSONATA formulas) * **External API integration** (using Buzzy Functions) * **Real-time features** (using Microapp Listeners) **Examples**: * Team project management (projects with tasks and team members) * E-commerce store (products, orders, customers, inventory) * Booking system (appointments, customers, services, availability) * CRM (customers, deals, activities, sales pipeline) * Event management (events, registrations, attendees, tickets) **Sample moderate prompt**: ``` Create a team project management app with: Data Model: 1. Projects Datatable: - name, description, start_date, end_date, status - tasks (Subtable → Tasks) - team_members (Linked Table Field → Users) - Team Viewers field (whole team sees the project) 2. Tasks Datatable (child of Projects): - task_name, description, due_date, priority, completed - embeddingRowID (links to parent Project) - assignee (Linked Table Field → Users) 3. Users Datatable (built-in) Screens: - Project List (cards showing project name, progress) - Project Detail (tasks list with add/edit) - Task Detail (full info with assign/complete actions) - Team Dashboard (my assigned tasks from all projects) Features: - Filter tasks by status/priority - Search projects and tasks - Display rules: show overdue tasks in red - Automatic progress calculation based on completed tasks Security: Team Viewers ensures project visibility ``` **Time estimate with Buzzy**: 3-6 weeks including iterations, testing, and polish ### Complex Applications (AI as Assistant Only) 🔴 **Characteristics**: * **Enterprise-level features** (SSO integration, advanced security) * **High performance requirements** (thousands of concurrent users) * **Complex compliance** (HIPAA, GDPR, financial regulations, audit trails) * **Custom algorithms** and data processing * **Real-time collaboration** features (concurrent editing, presence) * **Multiple external integrations** (payment gateways, analytics, third-party services) **Examples**: * Healthcare platforms (patient records, HIPAA compliance, scheduling) * Financial systems (transactions, reporting, regulatory compliance) * Large-scale SaaS (multi-tenant with advanced features) * Supply chain management (inventory, logistics, forecasting) * Enterprise resource planning (ERP) systems **Approach for complex apps**: * Start with ONE module only * Use Buzzy for the UI and basic workflows * Extend with Buzzy Functions for custom logic * Plan for significant manual work and testing * Consider hiring developers for critical components **Sample complex prompt** (just one module): ``` Create a patient appointment management module with: Data Model: 1. Organizations (built-in - one per clinic) 2. Patients Datatable: - name, date_of_birth, medical_record_number, phone, email - appointments (Subtable → Appointments) - Team Viewers: Healthcare Providers team 3. Appointments Datatable: - patient (Linked to Patients), provider (Linked to Users) - appointment_date, time_slot, duration, status, notes - embeddingRowID (links to parent Patient) - created_date, modified_date (for audit) 4. Teams: Healthcare Providers, Front Desk, Administrators Screens: - Patient Search/List (front desk view) - Patient Detail (appointment history) - Schedule Appointment (date picker, available slots) - Provider Calendar (day/week view of appointments) - Appointment Detail (notes, status updates) Security: - Front Desk: can view/create appointments - Providers: can view their appointments and add notes - Administrators: full access - Audit trail: track all changes to appointments Compliance: - No PHI displayed in URLs or logs - Session timeout after 15 minutes - Access logged for compliance Note: This is Phase 1. Later phases will add: - Insurance verification - Electronic health records integration - Billing - Reporting ``` **Time estimate**: 2-3 months for initial module with Buzzy + extensions {% hint style="warning" %} **Reality Check**: If your idea is complex, AI can help but won't build it entirely for you. Be prepared for significant manual work, or consider simplifying your initial scope. Start with ONE simple module and expand from there. {% endhint %} **Decision tree - Can Buzzy handle your idea?** ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%% graph TD START[Your App Idea] --> Q1{Single app or
multiple systems?} Q1 -->|Single app| Q2{How many
user types?} Q1 -->|Multiple systems| COMPLEX[Complex - Start Small] Q2 -->|1-2 types| Q3{Data relationships?} Q2 -->|3+ types| MODERATE[Moderate - Doable] Q3 -->|Simple 1:M| Q4{External APIs?} Q3 -->|Complex N:M| MODERATE Q4 -->|None or 1-2| SIMPLE[Simple - Perfect!] Q4 -->|Many APIs| MODERATE SIMPLE --> A1[Buzzy AI will
build 90% for you] MODERATE --> A2[AI builds framework,
you refine details] COMPLEX --> A3[AI assists, you
architect & build] style SIMPLE fill:#4a4,stroke:#333,color:#fff style MODERATE fill:#fa3,stroke:#333,color:#000 style COMPLEX fill:#f66,stroke:#333,color:#000 style START fill:#ccf,stroke:#333,color:#000 ``` ## The Core Concepts ### 1. User Experience (UX) **What it means**: How users interact with your application from start to finish. **Why it matters**: * AI can generate screens, but it doesn't know if the flow makes sense * Navigation that seems obvious to you might confuse users * Features might exist but be hard to find **Key questions to ask**: * What is the user trying to accomplish? * What's the most important action they'll take? * How many steps should it take to complete their goal? * What happens when something goes wrong? **Example**: * ❌ Bad: "Build a CRM" (AI generates generic CRUD screens) * ✅ Good: "Sales reps need to quickly log customer calls, see upcoming follow-ups, and track deal progress—all from a mobile-friendly dashboard" ### 2. Application Architecture with Buzzy **What it means**: How your application components work together in Buzzy's platform. **Why it matters**: * Affects performance, maintainability, and scalability * Determines how easy it is to add features later * Buzzy abstracts away infrastructure complexity **Buzzy's architecture**: **Brief**: High-level summary generated by Buzzy AI * Describes what your app does * Key functions and features * Generated automatically from your prompt **Blueprint**: Auto-generated screen structure * Lists all screens in your app * Shows navigation flow * Foundation for Design tab **Data**: Buzzy Datatables with relationships * **Subtables** for one-to-many relationships (1:M) * **Linked Table Fields** for many-to-many relationships (N:M) * Server-level security with Viewers and Team Viewers * JSONATA formulas for calculations **Design**: Visual screen layouts * Buzzy's visual editor for components * Display rules (conditional logic) * Actions (submits, navigation, CRUD) * No raw code to maintain **Buzzy Functions**: AWS Lambda for external integrations * Server-side logic when needed * Node.js 22 runtime * Secure Constants for API keys * Extends Buzzy beyond no-code when necessary **Publish**: Deployment infrastructure * Kubernetes-based scalable hosting * Web + iOS + Android from same definition * Automatic scaling * Professional infrastructure [Learn more about Buzzy architecture](https://docs.buzzy.buzz/working-with-buzzy/faqs) ### 3. Security Fundamentals **What it means**: Protecting your application and user data from unauthorized access and malicious use. **Why it matters**: * Data breaches can destroy your business * Regulatory compliance is legally required * User trust is hard to earn and easy to lose **Buzzy's security architecture**: **Authentication**: Built-in user system * Email/password authentication * User registration and login screens * Secure password hashing (handled by Buzzy) **Authorization**: Organizations and Teams * **Organizations**: Multi-tenant architecture (each customer/company) * **Teams**: Role-based groups within organizations * **Viewers field**: List specific users who can access a record * **Team Viewers field**: List teams who can access a record **Data Protection at Server Level**: * Security enforced at database level, not client-side * All queries automatically filtered by access rights * No way for users to bypass security through client manipulation * Built-in protection against injection attacks **Why this matters for vibe coding**: Traditional AI code generation often creates security holes: * Client-side security that can be bypassed * Hard-coded credentials in generated code * Missing server-side validation * Overly permissive access **Buzzy's approach eliminates these risks**: * Security is part of the platform * Server-level enforcement * No client-side security workarounds * Organizations/Teams pattern for multi-tenant apps **In Buzzy AI prompting**: Be explicit about access control * "Users should only see records where they are in the Viewers field" * "Only members of the Admin team can delete records" * "Each customer should have their own Organization" [Learn more about Buzzy's security](/the-building-blocks/datatables-fields-and-data/security-and-access-control) ### 4. Performance and Scalability **What it means**: How fast your app runs and how many users it can handle. **Why it matters**: * Slow apps lose users (people abandon apps that take >3 seconds to load) * Scalability determines if your success will crash your app * Performance issues are expensive to fix later **Key considerations**: **Database Performance**: * Index frequently queried fields * Avoid loading all data at once (use pagination) * Cache repeated queries **Frontend Performance**: * Minimize JavaScript bundle size * Lazy load images and components * Optimize for mobile networks **API Performance**: * Rate limit requests * Use appropriate HTTP methods * Return only needed data **When to worry about scale**: * ✅ Now: Design data structure for growth * ✅ Now: Implement basic caching * ⏱️ Later: Advanced optimization (wait until you have real load data) * ⏱️ Later: Horizontal scaling (wait until single server maxes out) ### 5. Error Handling and Edge Cases **What it means**: Planning for what happens when things go wrong. **Why it matters**: * Users encounter errors, not perfect scenarios * Network requests fail * Databases go down * Users input unexpected data **AI's blindspot**: AI generates happy-path code—everything works perfectly. Real applications need error handling. **Essential error scenarios**: * Network timeout or failure * Invalid user input * Missing or corrupt data * Permission denied * External API failures * Database errors **Better prompting**: * ❌ "Build a form to submit orders" * ✅ "Build an order form that validates all fields, shows clear error messages, handles network failures gracefully, and confirms successful submission" ## Business vs. Apps A common confusion: **Your business isn't your app**. **Your business**: The problem you solve, the value you create, your competitive advantage **Your app**: One tool (among many) that supports your business **Example**: * **Business**: Local bakery that takes custom cake orders * **App**: An order management system **The app should**: * Let customers request custom cakes * Allow bakers to track orders * Send notifications for pickups * Calculate pricing **The app should NOT**: * Try to be your entire business * Replace in-person customer service * Handle every edge case manually * Automate things better done by humans {% hint style="success" %} **Start Simple**: Build the smallest useful app for your core business need. Add features as you understand what users actually need. {% endhint %} ## Questions Before You Build Before writing your first prompt, answer these: 1. **Who will use this?** * One type of user or multiple roles? * How tech-savvy are they? 2. **What's the core action?** * If you could only build one feature, what would it be? * What's the minimum viable product? 3. **What data is involved?** * What information needs to be stored? * How do the data pieces relate? 4. **What happens when things go wrong?** * Network failure? * Invalid input? * Unauthorized access? 5. **How will it be used?** * Desktop, mobile, or both? * Public internet or internal network? * Real-time or batch processing? 6. **What are the constraints?** * Budget for hosting? * Compliance requirements? * Performance expectations? ## Taking It Further Now that you understand the system thinking fundamentals: * Learn how to structure your data: [Data Design Basics](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals/data-design) * Understand user interactions: [Functional Design](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals/functional-design) * Plan your development approach: [Project Workflow](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow) Remember: **The time you spend thinking before prompting saves hours of fixing later**. # Design Fundamentals Master the fundamentals of data and functional design for building robust Buzzy applications. Learn why design-first thinking leads to better AI-powered development. ## Why Design Comes First You wouldn't build a house without blueprints. Yet many people ask Buzzy AI to build applications without designing first. **Non-technical explanation**: Imagine asking someone to cook you dinner but only saying "make something good." They might create something edible, but it probably won't be what you really wanted. The same happens when you ask Buzzy AI to "build an app" without clear design specifications—you get something functional but not necessarily right for your needs. **The common mistake cycle**: ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%% graph TD A[Vague Prompt] --> B[AI Generates Generic App] B --> C[Not What You Wanted] C --> D[More Vague Prompts] D --> E[More Wrong Results] E --> F[Frustration & Give Up] style F fill:#f88,stroke:#333,color:#000 ``` **The result without design**: Apps that work initially but become increasingly difficult to modify, scale, or maintain because the foundation is wrong. **The solution**: Spend time on design fundamentals before writing prompts. Even 15-30 minutes of design thinking can save hours of iterating on incorrect app structures. ## The Two Pillars of Great Apps Think of building an app like constructing a building. You need both a strong foundation (data design) and a good layout (functional design). ### 1. Data Design 🏗️ **What you're building**: The structure of information your app stores and manages. **Non-technical explanation**: Data design is like designing the filing system for an office. You decide what information to keep, how to organize it, and what categories relate to each other. Good organization makes everything easy to find and update. Poor organization creates chaos. **Why it matters**: Bad data design creates cascading problems that are expensive to fix later. **Visual comparison**: ``` Good Data Design: ├── Users (clean, organized) ├── Tasks (clear relationships) ├── Projects (logical structure) └── Comments (proper linking) Result: Easy to build features, fast queries, clear logic Bad Data Design: ├── Everything in one giant table ├── Duplicate information everywhere ├── Unclear relationships └── Redundant fields Result: Slow app, confusing features, hard to maintain ``` **Examples of data design decisions**: * Should tasks belong to projects or users or both? * Can a user have multiple roles or just one? * Do comments link to tasks or to users? * Is address one field or separate street/city/state fields? → **Learn more**: [Data Design Basics](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals/data-design) ### 2. Functional Design 🎨 **What you're building**: How users interact with your app and accomplish their goals. **Non-technical explanation**: Functional design is like planning the layout of a restaurant. You decide where the entrance is, how customers move through the space, where the menu is displayed, how ordering works, and where they sit. Good flow makes dining pleasant. Poor flow creates confusion and frustration. **Why it matters**: Even with perfect data, poor functional design makes apps confusing and frustrating to use. **Visual comparison**: ``` Good Functional Design: User Journey: Clear → Logical → Efficient → Satisfying Entry → Action → Result → Success Bad Functional Design: User Journey: Confusing → Random → Frustrating → Abandonment Entry → ??? → Error → Give Up ``` **Examples of functional design decisions**: * What does a user see first when they open the app? * How many clicks does it take to complete the main task? * What happens when a user makes an error? * How do users find what they're looking for? * What can different types of users do? → **Learn more**: [Functional Design](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals/functional-design) ## The Design-First Approach ### Traditional Coding 1. Write requirements document 2. Design database schema 3. Create wireframes 4. Build frontend code 5. Connect to backend code 6. Test and iterate ### Building with Buzzy AI (Wrong Way) 1. ❌ Write vague prompt describing app 2. ❌ Let AI generate everything without review 3. ❌ Discover data model is wrong 4. ❌ Write more prompts trying to fix 5. ❌ Give up or start over ### Building with Buzzy AI (Right Way) 1. ✅ Design your data structure (Datatables, relationships) 2. ✅ Map out user flows 3. ✅ Write informed prompts with Buzzy-specific details 4. ✅ Review generated Brief, Blueprint, Data, and Design 5. ✅ Use visual editor for refinements 6. ✅ Test systematically in preview mode {% hint style="success" %} **Pro Tip**: Even 30 minutes of design thinking can save hours of iterating on your Buzzy app structure. {% endhint %} ## When to Design vs. When to Prompt ### Design First (Recommended) * You're building something for production use * Multiple users or user types involved * Data relationships are complex * You need it to last more than a few months * Security or compliance matters ### Prompt First (Acceptable) * Quick prototype or proof-of-concept * Personal project for learning * Very simple use case (contact form, basic list) * You're exploring what's possible ## Common Design Mistakes ### 1. Skipping Data Modeling **Mistake**: "Build me a project management app" **Problem**: AI doesn't know: * Can projects have sub-projects? * Can tasks belong to multiple projects? * Should users own tasks or projects? * How do you track time? **Better**: Design your entities and relationships first, then prompt with specifics. ### 2. Ignoring User Roles **Mistake**: Treating all users the same **Problem**: * Managers shouldn't edit developer comments * Customers shouldn't see admin pricing * Viewers shouldn't delete data **Better**: Define roles and permissions in your design before building. ### 3. Not Planning Navigation **Mistake**: Thinking about features, not flows **Problem**: * Users get lost in your app * Common tasks take too many clicks * Dead ends with no way back **Better**: Map out user journeys before asking AI to build screens. ### 4. Overlooking Mobile **Mistake**: Designing only for desktop **Problem**: * 60%+ of traffic is mobile * Tables don't work on small screens * Long forms are painful on phones **Better**: Design mobile-first or at minimum test on mobile early. ### 5. Ignoring Performance **Mistake**: Loading all data at once **Problem**: * Slow page loads * Database crashes under load * Poor user experience **Better**: Plan for pagination, search, and filtering from the start. ## Design Deliverables Before you start prompting AI, create: ### 1. Data Model Diagram * List all data entities (Users, Projects, Tasks, etc.) * Show relationships between them * Note required fields and data types * Identify unique constraints **Tools**: * Paper and pencil (seriously!) * Excalidraw or Miro (online diagramming) * Database design tools (if you prefer) ### 2. User Flow Diagram * Entry points (how users start) * Core actions (what they need to do) * Decision points (what choices they make) * Exit points (how they complete or cancel) ### 3. Screen List with Purpose * Screen name * What user can do there * What data is displayed * Where it links to ### 4. Permission Matrix * User roles * What each role can see * What each role can edit * What each role can delete ## Example: Task Management App Let's walk through a simple example: ### Bad Approach **Prompt**: "Build me a task management app" **Result**: AI creates generic task list with no consideration for your needs. ### Good Approach **1. Data Design**: ``` Entities: - Users (name, email, role) - Projects (name, description, owner_id) - Tasks (title, description, project_id, assignee_id, due_date, status) Relationships: - One user can own many projects - One project can have many tasks - One user can be assigned many tasks ``` **2. User Roles**: * Admin: Can create projects, assign tasks, view all * Team Member: Can create tasks, edit assigned tasks, view team projects * Viewer: Can view projects and tasks only **3. Key Flows**: * Create Project → Add Tasks → Assign to Team Members * View My Tasks → Update Status → Mark Complete * Search Tasks → Filter by Project → Sort by Due Date **4. Informed Buzzy Prompt**: "Build a task management app with the following Buzzy datatables: Users datatable with role field (Admin, Team Member, Viewer) Projects datatable: * name, description * owner (linked to Users) * tasks (subtable → Tasks datatable) Tasks datatable (subtable of Projects): * title, description, due\_date, status * assignee (linked to Users) Access control: * Admins: can create projects, assign any task, view all * Team Members: can create tasks in their projects, edit assigned tasks, view team projects * Viewers: can view projects and tasks only (read-only) Screens needed: * Project list with owner names * Project detail showing tasks in subtable * Task creation form within project * My assigned tasks screen (filtered by current user) Make it mobile-responsive with card layouts." **Result**: Buzzy AI generates an App Definition with proper Subtables and relationships, requiring minimal adjustments in the visual editor. ## Tools for Design You don't need expensive tools: **Free & Simple**: * Paper and pencil (seriously, start here) * Google Docs/Sheets (for lists and matrices) * Excalidraw (free online diagramming) **If You Want More**: * Figma (for UI mockups) * Miro (for collaborative diagrams) * dbdiagram.io (for database schemas) **Don't Overthink It**: * A hand-drawn diagram is better than no diagram * A simple list is better than no plan * Start small, refine as needed ## Next Steps 1. **Learn Data Design**: Understand entities, relationships, and normalization → [Data Design Basics](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals/data-design) 2. **Learn Functional Design**: Master user flows, actions, and interactions → [Functional Design](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals/functional-design) 3. **Apply Your Design**: Use your design to write better prompts → [Project Workflow](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow) {% hint style="info" %} **Remember**: Design doesn't mean perfection. It means thinking before building. Even rough design is better than no design. {% endhint %} # Data Design Basics Master data design fundamentals to build well-structured Buzzy applications. Learn how to organize information using Subtables and Linked Table Fields with practical examples and prompts. ## Why Data Design Matters Your data structure is the foundation of your application. Get it wrong, and every feature you build will be harder than it needs to be. **Think of data design like organizing a filing cabinet**: * **Good filing system**: Each folder is clearly labeled, related documents are grouped together, finding anything takes seconds * **Bad filing system**: Random papers everywhere, duplicates scattered about, searching takes hours and you're never sure you found everything **Good data design**: * Makes features easy to add * Keeps your app fast * Prevents data inconsistencies * Simplifies maintenance * Scales naturally as your app grows **Bad data design**: * Requires constant workarounds * Slows down as data grows * Creates bugs and edge cases * Makes changes expensive * Forces you to rebuild later (painful!) **Visual comparison**: **Good Data Design**: ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%% graph TD A1[Customers] --> B1[Orders] B1 --> C1[Order Items] D1[Products] -.->|referenced by| C1 ``` **Bad Data Design**: ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%% graph TD A2[Huge Table
customer_name
customer_email
order_date
product_name
product_price
quantity
...] --> B2[Duplicated
Data
Everywhere] B2 --> C2[Inconsistencies
& Bugs] ``` {% hint style="success" %} **Pro Tip**: Invest 30-60 minutes planning your data structure before writing your first Buzzy AI prompt. This saves hours of restructuring later. Use paper, a whiteboard, or a tool like draw\.io to sketch your entities and relationships. {% endhint %} ## The Basics: Entities and Attributes ### Entities (Things You Store) An **entity** is a type of thing your app manages. In Buzzy, these become **Datatables**. **Non-technical explanation**: Think of entities as the main "topics" or "categories" your app deals with. If your app is about recipes, your entities might be Recipes, Ingredients, and Cooks. If it's about project management, entities are Projects, Tasks, and Team Members. **Examples by industry**: * **E-commerce**: Products, Orders, Customers, Reviews, Categories * **School**: Students, Teachers, Classes, Assignments, Grades * **Medical**: Patients, Doctors, Appointments, Prescriptions, Medical Records * **Project Management**: Projects, Tasks, Team Members, Comments, Milestones * **Real Estate**: Properties, Agents, Clients, Showings, Offers **How to identify entities** (ask yourself these questions): * What are the main "things" or "nouns" I'm managing? * Do I need to store multiple instances? (many products, many customers) * Does this thing have information I need to track? * Will users create, view, update, or delete these things? **Practice exercise - Food Delivery App**: ``` App description: "Users order food from restaurants, drivers deliver" Entities identified: ✓ Users (customers placing orders) ✓ Restaurants (establishments offering food) ✓ Menu Items (what restaurants offer) ✓ Orders (user's food orders) ✓ Drivers (people delivering food) ✓ Deliveries (tracking delivery status) NOT entities: ✗ "Hungry" (this is a state, not a thing) ✗ "Fast" (this is a quality, not a thing) ✗ "Ordering" (this is an action, not a thing) ``` ### Attributes (Properties of Entities) **Attributes** are the specific pieces of information about each entity. In Buzzy, these become **fields** in your Datatables. **Non-technical explanation**: If an entity is a topic (like "Products"), attributes are the specific facts you know about each product - its name, price, description, etc. Just like a person has attributes (name, age, height), database entities have attributes too. **Example - Product Entity (E-commerce)**: ``` Product Datatable fields: - name (text, required) - e.g., "Wireless Bluetooth Headphones" - description (long text) - e.g., "Premium sound quality with 40hr battery" - price (number, required) - e.g., 79.99 - in_stock (boolean/yes-no) - e.g., true - inventory_count (number) - e.g., 45 - category (text or linked field) - e.g., "Electronics" - image_url (image upload) - uploaded product photo - created_date (date, auto-generated) - e.g., 2025-01-15 - sku (text, unique) - e.g., "BT-HEAD-001" ``` **Choosing attributes** (critical questions): * What information do I need to **display** to users? * What do users need to **search or filter** by? * What's required for **business rules** and **calculations**? * What do I need for **reporting** and **analytics**? * What **validation** or **security** rules apply? **Beginner's checklist for each entity**: * [ ] Name/title field (usually required) * [ ] Description or details field (optional but common) * [ ] Date fields (created, modified, due dates as needed) * [ ] Status or state field (if thing has workflow) * [ ] Owner/creator field (who created/owns this record) * [ ] Numeric fields (prices, quantities, ratings as needed) * [ ] Relationships to other entities (more on this below) ### Data Types Matter Choose the right data type for each attribute - this affects how Buzzy handles validation, display, and calculations. **Buzzy field types explained for beginners**: | Field Type | When to Use | Good Examples | Bad Examples | | ---------------------- | ---------------------------- | ---------------------------------------------------- | ------------------------------------------ | | **Text (short)** | Names, titles, short values | Product name, customer name, email | Long descriptions, multi-paragraph content | | **Text (long)** | Descriptions, notes, content | Product description, blog post, instructions | Just a name or short value | | **Number** | Values you calculate with | Price, quantity, age, rating | Phone numbers (use text), zip codes | | **Date/Time** | Dates, timestamps | Created date, due date, appointment time | Age in years (calculate from birthdate) | | **Boolean (Yes/No)** | True/false states | Is active? Is published? Is complete? | Status with 3+ options | | **Select/Dropdown** | Fixed set of options | Status (draft/published), priority (low/medium/high) | Values that should be calculated | | **Image/File** | Uploaded media | Product photo, profile picture, PDF document | URLs to external images | | **Subtable** | One-to-many relationships | Order → Order Items, Project → Tasks | Many-to-many relationships | | **Linked Table Field** | Many-to-many relationships | Products ↔ Categories, Students ↔ Classes | Simple one-to-many (use Subtable) | **Real-world data type decisions**: ``` Example: Building a Recipe App Recipe Datatable: ✓ name: Text (short) - "Chocolate Chip Cookies" ✓ instructions: Text (long) - "1. Preheat oven to 375°F. 2. Mix butter..." ✓ prep_time: Number - 15 (minutes) ✓ servings: Number - 24 ✓ is_vegetarian: Boolean - true ✓ difficulty: Select/Dropdown - "Easy", "Medium", "Hard" ✓ photo: Image - uploaded photo of finished dish ✓ created_date: Date - auto-generated timestamp ✓ ingredients: Subtable - links to Ingredients datatable ✓ categories: Linked Table Field - links to Categories (desserts, cookies, etc.) Common mistakes to avoid: ✗ prep_time as Text - can't calculate total time ✗ servings as Text - can't do portion math ✗ difficulty as Text - can't filter/sort consistently ✗ phone_number as Number - loses leading zeros ``` {% hint style="warning" %} **Common Mistakes to Avoid**: 1. **Storing numbers as text**: If you'll calculate with it, make it a number field. Price should be number (79.99), not text ("$79.99"). 2. **Phone numbers as numbers**: Store as text to preserve formatting and leading zeros. "(555) 123-4567" won't work as a number. 3. **Using text for status**: Use Select/Dropdown for finite options like "pending/approved/rejected" so you can filter and validate consistently. 4. **ZIP codes as numbers**: Text field preserves leading zeros. "01234" becomes 1234 as a number. {% endhint %} **Sample Buzzy AI prompt including data types**: ``` "Create a Products datatable with these fields: - name (text, required) - description (long text) - price (number, required, minimum 0) - in_stock (boolean, default true) - category (dropdown with options: Electronics, Clothing, Home, Food) - main_image (image upload) - created_date (date, auto-generated) - inventory_count (number, default 0)" ``` ## Relationships: How Data Connects Entities don't exist in isolation—they relate to each other. Understanding relationships is **the most important part of data design**. Get this wrong and your app will be frustrating to build and use. **Visual overview of relationship types**: ```mermaid graph TD A[Relationship Types] --> B[One-to-Many
Most Common
80% of cases] A --> C[Many-to-Many
More Complex
15% of cases] A --> D[One-to-One
Rare
5% of cases] B --> B1[Parent Entity] B1 --> B2[Child 1] B1 --> B3[Child 2] B1 --> B4[Child 3] C --> C1[Entity A] C --> C2[Entity B] C1 -.-> C2 C2 -.-> C1 D --> D1[Entity X] D1 -.one-to-one.-> D2[Entity Y] ``` ### One-to-Many (Most Common) - Buzzy Subtables **Definition**: One instance of Entity A can relate to many instances of Entity B, but each B belongs to only one A. **Non-technical explanation**: Think of it like a tree structure. A tree (parent) has many branches (children), but each branch belongs to only one tree. Or think of a book with chapters - one book has many chapters, but each chapter belongs to only one book. **Examples**: * One customer can place many orders (but each order belongs to one customer) * One blog post can have many comments (but each comment belongs to one post) * One project can have many tasks (but each task belongs to one project) * One invoice can have many line items (but each line item belongs to one invoice) **How to implement in Buzzy using Subtables**: * Create parent Datatable (e.g., Invoices) * Create child Datatable (e.g., Invoice Lines) * In the parent Datatable, add a **Subtable field** that points to the child Datatable * Buzzy automatically manages the `embeddingRowID` relationship (foreign key) **Example - Invoice → Invoice Lines**: ``` Invoices Datatable: - _id (auto-generated) - invoice_number - customer_name - invoice_lines (Subtable field → Invoice Lines datatable) Invoice Lines Datatable: - _id (auto-generated) - embeddingRowID (auto-managed by Buzzy, links to parent Invoice) - description - amount - quantity ``` **When viewing an Invoice**: Buzzy automatically shows all related Invoice Lines through the Subtable field. **Visual representation**: ``` Invoice #1001 Invoice #1002 ├─ Line 1: Widget × 5 ├─ Line 1: Gadget × 2 ├─ Line 2: Gadget × 2 └─ Line 2: Doohickey × 1 └─ Line 3: Gizmo × 1 ``` **More real-world examples**: * **Blog**: One post → many comments (each comment belongs to one post) * **Customer**: One customer → many orders (each order belongs to one customer) * **Album**: One music album → many songs (each song belongs to one album) * **Course**: One course → many lessons (each lesson belongs to one course) * **Trip**: One vacation trip → many expenses (each expense belongs to one trip) **Sample Buzzy AI prompts for Subtables**: **Example 1 - Simple Invoice**: ``` "Create an Invoices datatable with these fields: - invoice_number (text, unique, auto-generated) - customer_name (text, required) - invoice_date (date, default today) - total_amount (number, calculated from line items) - status (dropdown: Draft, Sent, Paid) Add a subtable field called 'line_items' that links to an Invoice Lines datatable with: - description (text, required) - quantity (number, default 1) - unit_price (number, required) - line_total (formula: quantity * unit_price) Users should be able to add, edit, and delete line items directly from the invoice screen." ``` **Example 2 - Project with Tasks**: ``` "Create a Projects datatable with a tasks subtable: Projects datatable: - project_name (text, required) - description (long text) - start_date (date) - status (dropdown: Planning, In Progress, Completed) - tasks (subtable → Tasks datatable) Tasks datatable (subtable of Projects): - task_name (text, required) - assigned_to (text) - due_date (date) - status (dropdown: To Do, In Progress, Done) - priority (dropdown: Low, Medium, High) Show tasks within each project detail screen." ``` **Example 3 - Blog with Comments**: ``` "Build a blog app where: Posts datatable: - title (text, required) - content (long text, required) - author (text) - published_date (date) - comments (subtable → Comments datatable) Comments datatable (subtable of Posts): - commenter_name (text, required) - comment_text (long text, required) - comment_date (date, auto-generated) The post detail screen should show all comments below the post content. Allow users to add new comments." ``` [Learn more about Subtables](/the-building-blocks/datatables-fields-and-data/advanced-fields/sub-tables) **When to use Subtables**: This covers 80% of relationships in Buzzy apps. Use Subtables when: * Things naturally "belong to" parent records * You need to add/edit children within parent screen * Deleting parent should cascade to children * Each child has only one parent ### Many-to-Many (More Complex) - Buzzy Linked Table Fields **Definition**: Many instances of Entity A can relate to many instances of Entity B, and vice versa. **Examples**: * Students and Classes (students take multiple classes, classes have multiple students) * Products and Categories (products can be in multiple categories, categories contain multiple products) * Tags and Articles (articles can have multiple tags, tags apply to multiple articles) * Projects and Team Members (projects have multiple members, members work on multiple projects) **How to implement in Buzzy using Linked Table Fields**: * Create both Datatables (e.g., Students and Classes) * Add a **Linked Table Field** in one or both tables * Buzzy uses `crossAppRowID` to manage the relationship * The field stores both a reference ID and display value **Example - Students ↔ Classes**: ``` Students Datatable: - _id (auto-generated) - name - email - classes (Linked Table Field → Classes datatable) Classes Datatable: - _id (auto-generated) - class_name - instructor - students (Linked Table Field → Students datatable, optional) When you add a student to a class: { value: "class_123", // crossAppRowID label: "Introduction to Physics" } ``` **Alternative pattern using junction table**: ``` Enrollments Datatable (Subtable of Students): - _id (auto-generated) - embeddingRowID (links to Student) - class (Linked Table Field → Classes) - enrollment_date - grade ``` **Visual representation**: ``` Student: Alice Classes: ├─ Math 101 ←──────────┬─ Math 101 (has Alice, Bob, Carol) ├─ History 201 ←────────│─ History 201 (has Alice, David) └─ Art 301 ←────────────│─ Physics 101 (has Bob, Carol) └─ Art 301 (has Alice) Student: Bob ├─ Math 101 └─ Physics 101 ``` **More real-world examples**: * **Products ↔ Categories**: Electronics can be in "Tech" AND "Gifts"; Clothing in "Fashion" AND "Sale Items" * **Movies ↔ Actors**: One movie has many actors, one actor appears in many movies * **Articles ↔ Tags**: One article can have tags "Technology", "AI", "Tutorial"; one tag applies to many articles * **Recipes ↔ Dietary Restrictions**: One recipe can be "Vegetarian" AND "Gluten-Free"; one restriction applies to many recipes * **Projects ↔ Skills Required**: One project needs "JavaScript", "Design", "Marketing"; one skill used in many projects **Sample Buzzy AI prompts for Linked Table Fields**: **Example 1 - Students and Classes (Simple N:M)**: ``` "Build a class enrollment system: Students datatable: - student_name (text, required) - email (text, required) - enrolled_classes (linked table field → Classes, multi-select) Classes datatable: - class_name (text, required) - instructor (text) - schedule (text) - students_enrolled (linked table field → Students, multi-select) Students can enroll in multiple classes. Classes can have multiple students. Show enrolled classes on student detail screen. Show enrolled students on class detail screen." ``` **Example 2 - Products and Categories (N:M with Display)**: ``` "Create a product catalog: Products datatable: - product_name (text, required) - price (number, required) - categories (linked table field → Categories, multi-select) Categories datatable: - category_name (text, required, unique) - description (text) Products can be in multiple categories (a hoodie could be in 'Clothing', 'Sale', and 'New Arrivals'). Product list screen should show category tags. Category screen should show all products in that category." ``` **Example 3 - Junction Table Pattern (N:M with Extra Info)**: ``` "Build a project management system where team members have roles: Projects datatable: - project_name (text, required) - description (long text) - team_assignments (subtable → Team Assignments datatable) Team Assignments datatable (subtable of Projects): - team_member (linked table field → Users) - role (dropdown: Lead, Developer, Designer, QA) - hours_allocated (number) - start_date (date) Team Members (Users) datatable: - name (text, required) - email (text, required) - skills (text) This pattern lets you track WHO is on each project AND their ROLE and HOURS." ``` **When to choose which pattern**: | Scenario | Use Linked Field | Use Junction Table (Subtable + Linked) | | ------------------------------------- | ----------------------- | ------------------------------------------------ | | Simple N:M, no extra info | ✅ Students ↔ Classes | | | Need to store info about relationship | | ✅ Projects ↔ Team Members (with role, hours) | | Just need to link records | ✅ Products ↔ Categories | | | Need relationship history | | ✅ Users ↔ Skills (with proficiency level, years) | [Learn more about Linked Table Fields](/the-building-blocks/datatables-fields-and-data/advanced-fields/linked-table-field) {% hint style="info" %} **Pro Tip**: Many-to-many relationships are the #1 source of data modeling confusion for beginners. Take 10 minutes to draw it out before building: 1. Draw boxes for each entity 2. Draw arrows both ways 3. Ask: "Do I need to store information ABOUT the relationship?" (like enrollment date, role, etc.) 4. If yes → use junction table pattern (Subtable + Linked Field) 5. If no → use simple Linked Table Field When in doubt, start with simple Linked Field. You can always add a junction table later if needed. {% endhint %} ### One-to-One (Rare) **Definition**: One instance of Entity A relates to exactly one instance of Entity B. **Examples**: * User and UserProfile (each user has one profile, each profile belongs to one user) * Employee and EmployeeBadge (each employee has one badge, each badge belongs to one employee) **When to use**: * Splitting large entities for organization * Separating sensitive data * Optional extended information **In most cases**: Just combine into one entity unless there's a strong reason to separate. ## Normalization: Avoiding Duplication **Normalization** means organizing data to reduce duplication and maintain consistency. ### The Problem: Denormalized Data **Bad Example - Order table**: ``` order_id | customer_name | customer_email | customer_address | product_name | product_price 1 | John Doe | john@email.com | 123 Main St | Widget | 19.99 2 | John Doe | john@email.com | 123 Main St | Gadget | 29.99 ``` **Problems**: * Customer info duplicated (what if address changes?) * Product info duplicated (what if price changes?) * Typos create "different" customers * Hard to update consistently ### The Solution: Normalized Data **Good Example**: **Customers table**: ``` customer_id | name | email | address 1 | John Doe | john@email.com | 123 Main St ``` **Products table**: ``` product_id | name | price 1 | Widget | 19.99 2 | Gadget | 29.99 ``` **Orders table**: ``` order_id | customer_id | product_id | order_date 1 | 1 | 1 | 2025-01-15 2 | 1 | 2 | 2025-01-16 ``` **Benefits**: * Update customer address once, affects all orders * Update product price once, historical orders unaffected * No duplication, no inconsistency ### When to Denormalize Sometimes duplication is okay: **Acceptable reasons**: * Performance (calculated fields to avoid complex queries) * Historical snapshots (order should remember price at time of purchase) * Reporting (denormalized reporting tables separate from operational data) **Rule of thumb**: Normalize by default. Denormalize only when you have a specific performance or business reason. ## Common Patterns ### 1. User-Generated Content **Pattern**: Users create content items (posts, listings, reviews, etc.) **Entities**: * Users * Content Items (each has author\_id linking to Users) **Example - Blog**: * Users (id, name, email) * Posts (id, title, content, author\_id, published\_date) ### 2. Hierarchical Data **Pattern**: Items can contain sub-items (categories, comments, tasks) **Entities**: * Parent items * Child items (with parent\_id) **Example - Comments**: * Posts (id, title, content) * Comments (id, content, post\_id, parent\_comment\_id) * parent\_comment\_id allows nested replies ### 3. Status Workflows **Pattern**: Items move through defined states **Entities**: * Main entity with status field * Optionally: StatusHistory table tracking changes **Example - Order Processing**: * Orders (id, customer\_id, status: pending/processing/shipped/delivered) * OrderHistory (id, order\_id, old\_status, new\_status, changed\_at) ### 4. Tagging and Categorization **Pattern**: Items can be grouped or tagged flexibly **Entities**: * Items * Tags * ItemTags (junction table) **Example - Recipe App**: * Recipes (id, name, instructions) * Tags (id, name: "vegetarian", "quick", "dessert") * RecipeTags (recipe\_id, tag\_id) ## Working with Buzzy's Data Model Buzzy provides powerful features specifically designed for no-code data modeling: ### Datatables - Your Core Data Structure Your entities become **Datatables** in Buzzy. Each Datatable automatically includes: * `_id`: Unique identifier (auto-generated) * `embeddingRowID`: Foreign key for Subtable relationships (auto-managed) * `author` and `userID`: Track who created each record * `viewers` and `teamViewers`: Server-level access control [See complete Buzzy Datamodel Overview](/the-building-blocks/datatables-fields-and-data/buzzy-datamodel-overview) ### Subtables - The Foundation of 1:M Relationships **Subtables** are Buzzy's implementation of one-to-many relationships: * Parent record contains a Subtable field * Child records automatically linked via `embeddingRowID` * Changes to child records don't affect parent * Can have multi-level nesting (grandparent → parent → child) **Common uses**: * Invoices → Invoice Lines * Blog Posts → Comments * Projects → Tasks * Customers → Orders → Order Items [Learn more about Subtables](/the-building-blocks/datatables-fields-and-data/advanced-fields/sub-tables) ### Linked Table Fields - The Foundation of N:M Relationships **Linked Table Fields** connect many-to-many relationships: * Reference records in another Datatable * Store `crossAppRowID` and display label * Can be multi-select or single-select * Enables complex relationship graphs **Common uses**: * Products ↔ Categories * Students ↔ Classes * Articles ↔ Tags * Projects ↔ Team Members [Learn more about Linked Table Fields](/the-building-blocks/datatables-fields-and-data/advanced-fields/linked-table-field) ### Formula Fields - Calculations and Validation Use **JSONATA** formulas for: * Calculated fields: `quantity * price` * Conditional logic: `user.highestRole = "admin"` * Data validation: `dueDate > $now()` * Complex transformations [Learn more about Formula Fields](/the-building-blocks/datatables-fields-and-data/advanced-fields/formula) ### Server-Level Security Design your data with security in mind from the start: * **Viewers field**: List specific users who can access a record * **Team Viewers field**: List teams who can access a record * **Organizations**: Multi-tenant architecture * **Teams**: Role-based access control Security is enforced at the server/database level, not client-side. [Learn more about Security and Access Control](/the-building-blocks/datatables-fields-and-data/security-and-access-control) ## Data Design Checklist Before building, verify your design: * [ ] **Entities identified**: Listed all the "things" your app manages * [ ] **Attributes defined**: Specified fields and data types for each entity * [ ] **Relationships mapped**: Documented how entities connect * [ ] **Normalization considered**: Eliminated unnecessary duplication * [ ] **Security planned**: Considered who can see/edit what * [ ] **Growth anticipated**: Thought about how data scales ## Prompting Buzzy AI with Your Data Design Once you've designed your data, include clear relationship descriptions in your prompts: **Bad Prompt**: "Build a recipe app" **Good Prompt for Buzzy**: "Build a recipe app with the following datatables: 1. Recipes datatable: * name (text, required) * instructions (long text) * prep\_time (number, minutes) * author (linked to Users) * ingredients (subtable → Ingredients datatable) 2. Ingredients datatable (subtable of Recipes): * ingredient\_name (text, required) * quantity (text, e.g., '2 cups') * notes (text, optional) 3. Users datatable: * name (text, required) * email (text, required) Relationships: * Each recipe belongs to one user (author) * Each recipe has multiple ingredients (one-to-many using subtable) * Users can create many recipes Screens needed: * Recipe list showing all recipes with author names * Recipe detail showing ingredients in a subtable * Form to add new recipe with ability to add multiple ingredients" **Result**: Buzzy generates an App Definition with proper Subtable relationships, requiring minimal adjustments. **Key tips for Buzzy AI prompts**: * Explicitly state "subtable" for 1:M relationships * Explicitly state "linked field" for N:M relationships * Describe the relationships in plain language * Mention what should be shown on each screen * Specify any access control (viewers, team viewers) ## Common Data Design Mistakes ### 1. Everything in One Table **Mistake**: Cramming all data into one giant table **Fix**: Separate into logical entities with relationships ### 2. Over-Normalization **Mistake**: Creating too many tiny tables, making queries complex **Fix**: Balance normalization with practicality ### 3. Wrong Data Types **Mistake**: Storing numbers as text, dates as strings **Fix**: Choose appropriate data types from the start ### 4. Missing Required Fields **Mistake**: Making everything optional, then handling blank data everywhere **Fix**: Mark essential fields as required ### 5. No Audit Trail **Mistake**: Not tracking who created/modified data or when **Fix**: Include created\_by, created\_at, modified\_by, modified\_at fields ## Next Steps * **Apply to user flows**: [Functional Design](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals/functional-design) * **See it in practice**: [Building Examples](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples) * **Start building**: [Project Workflow](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow) {% hint style="success" %} **Remember**: Good data design is iterative. Start with your best understanding, build, learn, and refine. Don't aim for perfection—aim for solid foundations that can evolve. {% endhint %} # Functional Design Master the art of designing how users interact with your Buzzy application. Learn to create intuitive user flows, actions, and interfaces with practical examples and prompts. ## What Is Functional Design? While [Data Design](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals/data-design) answers "what information does the app store?", **functional design** answers: * How do users get things done? * What actions can they take? * What do they see and when? * How do they navigate? **Non-technical explanation**: If data design is like designing the filing cabinets where you store information, functional design is like designing the office layout—where the desks are, which doors lead where, what happens when you press buttons, and how people move through the space to get their work done. **Visual comparison**: **Good Functional Design**: ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%% graph TD A1[Clear Entry Point] --> B1[Obvious Next Steps] B1 --> C1[Easy Actions] C1 --> D1[Success!] ``` **Bad Functional Design**: ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%% graph TD A2[Confusing Start] --> B2[Hidden Options] B2 --> C2[Unclear Actions] C2 --> D2[Frustration] ``` **Good functional design makes apps intuitive**: * Users accomplish goals without thinking about the app * Actions feel natural and obvious * Errors are prevented or handled gracefully * Navigation makes sense **Bad functional design makes simple tasks frustrating**: * Users get lost or confused * Actions are hidden or unclear * Errors are cryptic or unhelpful * Navigation feels random ## The Core Elements ### 1. Flows **A flow** is the path users and systems take to accomplish a goal. **Non-technical explanation**: Think of a flow like a recipe. Just as a recipe lists ingredients and step-by-step instructions (chop onions, heat pan, add ingredients in order), a flow documents each step needed to accomplish something (open screen, fill form, trigger action, see result). **Visual example - Creating a Task**: ```mermaid graph TD A[User on Task List] --> B[Clicks 'New Task' Button] B --> C[Form Appears] C --> D[User Fills Fields:
Title, Description,
Due Date, Assignee] D --> E[Clicks 'Save'] E --> F{Valid Input?} F -->|Yes| G[Task Created] F -->|No| H[Show Error Message] G --> I[Show Success Message] I --> J[Return to Task List] H --> C J --> K[New Task Visible in List] ``` **Step-by-step breakdown**: 1. **Entry Point**: User clicks "New Task" button on task list screen 2. **Display**: Form appears with fields (title, description, due date, assignee) 3. **Input**: User fills in the fields 4. **Action**: User clicks "Save" button 5. **Validation**: System checks if input is valid 6. **Success Path**: Task created → confirmation message → return to list → new task visible 7. **Error Path**: Validation fails → error message shown → form stays open with entered data **Why flows matter**: * **Identify all screens needed**: You can't build what you don't define * **Reveal missing steps**: What about canceling? Going back? Errors? * **Ensure logical progression**: Does each step make sense? * **Find friction points**: Where might users get confused or stuck? * **Enable clear prompting**: You can tell Buzzy AI exactly what to build **Related Buzzy docs**: * [Building Blocks: Flows](/the-building-blocks/flows) * [Buzzy AI (Flows in App Definition)](/working-with-buzzy/buzzy-ai) * [Datatables, Fields & Data](/the-building-blocks/datatables-fields-and-data) **Common user flows to map**: | Flow Type | Example | Key Considerations | | ---------------------- | --------------------------------------------------------- | ------------------------------------------- | | **Registration/Login** | Sign up → Enter email/password → Confirm → Access app | Email verification? Password requirements? | | **Core CRUD** | Create/Read/Update/Delete primary entities | Permissions? Confirmation dialogs? | | **Search/Filter** | Enter search → See results → Refine filters → Select item | Empty results? Multiple results? Sorting? | | **Multi-Step Process** | Start wizard → Step 1 → Step 2 → Step 3 → Complete | Can go back? Save progress? Abandon midway? | | **Approval Workflow** | Submit → Review → Approve/Reject → Notify | Who can approve? Comments? History? | | **Error Recovery** | Error occurs → Show message → Offer solution → Retry | Clear error? Helpful guidance? Easy retry? | **Sample Buzzy AI prompt with user flow**: ``` "Create a task management app with this user flow: Main Flow - Create Task: 1. User starts on Task List screen showing all tasks in a list 2. User clicks 'New Task' button (green, top right) 3. Form screen opens with fields: - Title (text, required, max 100 chars) - Description (long text, optional) - Due Date (date picker, required, default tomorrow) - Assignee (dropdown linked to Users datatable, required) - Priority (dropdown: Low/Medium/High, default Medium) 4. User fills fields and clicks 'Save' button 5. If validation passes: - Create task in Tasks datatable - Show success message 'Task created successfully' - Navigate back to Task List screen - New task appears at top of list 6. If validation fails: - Show error message in red below invalid field - Keep form open with entered data - Highlight invalid fields in red border Also add 'Cancel' button that returns to Task List without saving." ``` ### 2. Display Rules **Display rules** control what users see based on context. This is how you make your app smart and personalized. **Non-technical explanation**: Think of display rules like the way a restaurant menu adapts. The kids' menu only shows when you're dining with children. The happy hour menu only shows between 4-6pm. The vegan options are highlighted when you mention dietary restrictions. Your app should similarly show/hide elements based on who's using it and what they're doing. **Visual example**: ``` Task Detail Screen - What Different Users See: Admin User: ┌─────────────────────────────────┐ │ Task: Update Website │ │ Assignee: John │ │ Status: In Progress │ │ │ │ [Edit] [Delete] [Reassign] │ ← All buttons visible └─────────────────────────────────┘ Task Owner (John): ┌─────────────────────────────────┐ │ Task: Update Website │ │ Assignee: John │ │ Status: In Progress │ │ │ │ [Edit] [Mark Complete] │ ← Can edit own task └─────────────────────────────────┘ Viewer User: ┌─────────────────────────────────┐ │ Task: Update Website │ │ Assignee: John │ │ Status: In Progress │ │ │ │ (No action buttons) │ ← Read-only └─────────────────────────────────┘ ``` **Common display rule patterns**: **1. Role-based display**: * **Admin**: Sees "Delete" button, "Manage Users", system settings * **Editor**: Sees "Edit" button on any content, "Publish" button * **Viewer**: Sees content only, no action buttons * **Guest**: Sees public content only, "Sign Up" prompts **2. Ownership-based display**: * Show "Edit" only if `record.author = current_user` * Show "Delete" only if `record.owner = current_user OR user.role = admin` * Show "Transfer Ownership" only to owner **3. Status-based display**: * **Draft post**: Show "Publish" button, "Delete Draft" * **Published post**: Show "Unpublish" button, "Edit" * **Archived post**: Show "Restore" button, "Delete Permanently" * **Under review**: Show "Approve"/"Reject" buttons (for reviewers only) **4. Data-driven display**: * Show "Out of Stock" badge when `inventory_count = 0` * Show "Overdue" label (red) when `due_date < today AND status != 'Complete'` * Show "New" badge when `created_date > 7 days ago` * Show "Low Priority" in gray, "High Priority" in red **5. Relationship-based display**: * Show "Assign to Me" only if `task.assignee = null` * Show "Unfollow" if user is following, "Follow" if not * Show "Add to Cart" only if `product NOT IN user.cart` **6. Time-based display**: * Show "Early Bird Discount" only during promotional period * Show "Expires Soon" when `expiry_date < 3 days from now` * Show "Business Hours Only" message outside 9am-5pm **In Buzzy**: Use [condition fields](/the-building-blocks/datatables-fields-and-data/filter-controls/condition) with JSONata formulas and [Display Formula](/the-building-blocks/datatables-fields-and-data/display-formula). **Sample Buzzy AI prompts with display rules**: **Example 1 - Role-based buttons**: ``` "On the task detail screen, add these display rules: Delete button: - Show only if user.highestRole = 'admin' - Use condition field with JSONATA: user.highestRole = 'admin' Edit button: - Show if user is admin OR task owner - JSONATA: user.highestRole = 'admin' or task.author = user._id Mark Complete button: - Show if user is assignee, owner, or admin - JSONATA: task.assignee = user._id or task.author = user._id or user.highestRole = 'admin' All buttons should be hidden (not just disabled) when conditions aren't met." ``` **Example 2 - Status badges**: ``` "On the task list screen, add status badges with these display rules: Overdue badge (red background): - Show when due_date < today AND status != 'Complete' - JSONATA: $toMillis(due_date) < $toMillis($now()) and status != 'Complete' - Display text: 'OVERDUE' New badge (blue background): - Show when created less than 7 days ago - JSONATA: $toMillis(created_date) > $toMillis($now()) - 604800000 - Display text: 'NEW' High Priority badge (orange background): - Show when priority = 'High' or priority = 'Urgent' - JSONATA: priority = 'High' or priority = 'Urgent' - Display text: priority field value" ``` **Example 3 - Dynamic action availability**: ``` "Create a product detail screen with smart action buttons: Add to Cart button: - Show only if product.inventory_count > 0 - JSONATA: inventory_count > 0 - Hide completely when out of stock Notify When Available button: - Show only if product.inventory_count = 0 - JSONATA: inventory_count = 0 - Replace 'Add to Cart' when out of stock Pre-Order button: - Show if product.available_date is in the future - JSONATA: $toMillis(available_date) > $toMillis($now()) - Show alongside 'coming soon' label" ``` {% hint style="info" %} **Pro Tip for Beginners**: Map out display rules early in your planning. Buzzy AI often creates static UIs that show everything to everyone. You need to explicitly specify what should show/hide and when. Create a simple table: Then include these in your Buzzy AI prompts for accurate implementation. {% endhint %} | Element | Show When | JSONATA Formula | | ------------- | -------------- | ----------------------------------------- | | Delete button | User is admin | `user.highestRole = 'admin'` | | Edit button | User owns item | `author = user._id` | | Overdue badge | Past due date | `$toMillis(due_date) < $toMillis($now())` | {% hint style="warning" %} **Common Mistake**: Don't confuse display rules (what users see) with security (what users can actually do). Display rules hide UI elements, but you still need server-level security using Viewers fields and Team Viewers to prevent unauthorized data access. Display rules are for UX, not security. See: [Security and Access Control](/the-building-blocks/datatables-fields-and-data/security-and-access-control) {% endhint %} ### 3. Actions **Actions** are things users can do in your app. Every button, link, or interaction is an action that needs to be thoughtfully designed. **Non-technical explanation**: If your app is like a car, actions are all the controls—steering wheel, pedals, gear shift, turn signals. Each control does something specific, is available at the right time (can't shift to reverse while driving forward), and gives appropriate feedback (lights blink when you signal). **Action categories with examples**: **Create Actions** (Making new things): * Add new item (task, product, post) * Upload file or image * Submit form * Register account * Duplicate existing item * Import data from file **Read Actions** (Viewing and finding things): * View details of an item * Search by keywords * Filter by criteria (status, date, category) * Sort (alphabetical, by date, by priority) * Export data (CSV, PDF) * Print report * Preview before publishing **Update Actions** (Changing existing things): * Edit existing item * Change status (draft → published) * Update profile information * Modify settings or preferences * Reorder items (drag and drop) * Toggle feature on/off * Mark as read/unread, complete/incomplete **Delete Actions** (Removing things): * Delete item permanently * Archive (soft delete, can restore) * Cancel operation * Clear form data * Undo last action * Bulk delete multiple items **Navigation Actions** (Moving around the app): * Go to different screen * Open detail view (modal or new screen) * Return to list * Access menu * Open in new tab * Go back to previous screen * Jump to related item **External Actions** (Interacting outside the app): * Send email notification * Call external API * Generate PDF document * Share via social media * Trigger webhook * Export to third-party system * Send SMS message **For each action in your app, define these four aspects**: **1. WHO can perform it** (Authorization): ``` Example - Delete Task action: - Admins: Can delete any task - Task Owner: Can delete their own tasks only - Viewers: Cannot delete any tasks - Guests: No access to delete ``` **2. WHEN it's available** (Conditions): ``` Example - Mark Complete action: - Available when task.status != 'Complete' - Available only to assignee, owner, or admin - Not available on archived tasks - Disabled if required fields are empty ``` **3. WHAT happens** (Business Logic): ``` Example - Submit Order action: 1. Validate all form fields 2. Calculate total with tax 3. Process payment 4. Create order record in Orders datatable 5. Update inventory counts 6. Send confirmation email 7. Generate receipt PDF ``` **4. WHERE it goes next** (Navigation): ``` Example - After saving task: - Success: Return to task list with success message - Error: Stay on form, show error message, keep entered data - Cancel: Return to previous screen, discard changes ``` **Sample Buzzy AI prompt with detailed actions**: **Example - Task Management Actions**: ``` "Create these actions for the task management app: 1. CREATE TASK Action: Who: All logged-in users When: Always available from task list screen via 'New Task' button What: - Open create form screen - Collect: title, description, due_date, assignee, priority - Validate: title required, due_date required, assignee required - Save to Tasks datatable - Set author = current user - Add current user to Viewers field Where: On success navigate to task list, show 'Task created' message 2. EDIT TASK Action: Who: Task owner OR admin (JSONATA: author = user._id or user.highestRole = 'admin') When: Available on task detail screen via 'Edit' button What: - Open edit form pre-filled with current task data - Allow changes to title, description, due_date, assignee, priority - Validate same as create - Update task record in Tasks datatable Where: On success return to task detail screen, show 'Task updated' message 3. DELETE TASK Action: Who: Admins only (JSONATA: user.highestRole = 'admin') When: Available on task detail screen via 'Delete' button (red, bottom of screen) What: - Show confirmation dialog: 'Are you sure you want to delete this task? This cannot be undone.' - If confirmed: Delete task record from Tasks datatable - If cancelled: Do nothing, close dialog Where: On delete navigate to task list, show 'Task deleted' message 4. MARK COMPLETE Action: Who: Assignee, owner, or admin (JSONATA: assignee = user._id or author = user._id or user.highestRole = 'admin') When: Available only if status != 'Complete' What: - Update task.status = 'Complete' - Set task.completed_date = current date/time - Send notification to task owner Where: Stay on task detail screen, update display to show new status 5. ASSIGN TO ME Action: Who: All logged-in users When: Available only if task.assignee = null (unassigned) What: - Update task.assignee = current user._id - Add current user to Viewers field - Send notification to task owner Where: Stay on screen, hide 'Assign to Me' button, show current assignee" ``` **Action checklist for planning**: * [ ] Listed all actions users need to take * [ ] Defined who can perform each action (roles/permissions) * [ ] Specified when each action is available (display rules) * [ ] Documented what happens when action is triggered * [ ] Planned navigation after successful/failed actions * [ ] Designed confirmation dialogs for destructive actions * [ ] Considered error handling for each action * [ ] Planned success/error feedback messages ### 4. Context **Context** is the information available to the current screen or component. **Types of context**: **User Context**: * Who is logged in? * What's their role? * What are their preferences? **Data Context**: * Which item are we viewing? * What list are we browsing? * What search filters are active? **Navigation Context**: * Where did the user come from? * What was their previous action? * What should "back" do? **Application Context**: * Is the app online or offline? * What device are they using? * What time is it (for time-based features)? **Why context matters**: * Actions depend on context (can't edit without knowing what to edit) * Display varies by context (show relevant data, not everything) * Navigation needs context (return to previous list, not random screen) **AI's challenge with context**: Buzzy AI often generates screens in isolation without considering how context flows between them. You need to explicitly specify context flow in your prompts. **Better prompting examples**: ❌ **Bad prompt** (missing context): ``` "Create an edit form" ``` Problem: Which record are we editing? Where did we come from? Where do we go after saving? ✅ **Good prompt** (context specified): ``` "Create an edit form screen that: - Receives a task_id as context when navigating from task detail screen - Loads that task's data from Tasks datatable to pre-fill the form - Shows form with editable fields: title, description, due_date, assignee, priority - On 'Save': updates the task record and navigates back to task detail screen - On 'Cancel': discards changes and returns to task detail screen - Shows loading state while fetching task data" ``` ❌ **Bad prompt** (no context flow): ``` "Add a comments section to the task app" ``` ✅ **Good prompt** (context flow clear): ``` "Add a comments section to the task detail screen that: - Shows all comments for the currently viewed task (filtered by task_id context) - Displays comments in chronological order (oldest first) - Each comment shows: author name, comment text, timestamp - 'Add Comment' button opens a form with context of current task_id - After submitting comment, returns to task detail with new comment visible - Author context: sets comment.author = current logged-in user" ``` **Visual example of context flow**: ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%% graph TD A[Task List Screen
Context: Filter, Sort] --> B[Task Detail Screen
Context: task_id] B --> C[Edit Task Form
Context: task_id,
return_to='detail'] B --> D[Add Comment Form
Context: task_id,
return_to='detail'] C --> B D --> B A --> E[Create Task Form
Context: return_to='list'] E --> A ``` ### 5. Search, Sort, and Filter For any list of items, users need ways to find what they're looking for. This is critical for usability once your app has more than a handful of records. **Non-technical explanation**: Think of search/sort/filter like shopping on Amazon. You can **search** for "wireless headphones" (finds specific items), **filter** by price range, rating, brand (narrows down options), and **sort** by price low-to-high or customer reviews (orders results). Your app needs similar capabilities. **Three core finding features**: **1. SEARCH - Find items by text**: * **What**: Text box where users type keywords * **How**: Searches across multiple fields (name, description, tags, content) * **Types**: * Real-time search (updates as you type) - better UX, more server calls * Submit-based search (click button to search) - fewer calls, extra click * **Features**: Highlight matching text, show result count, clear search button **2. SORT - Order items by criteria**: * **What**: Dropdown or clickable column headers to change order * **Common sorts**: * Date created (newest first / oldest first) * Alphabetical (A-Z / Z-A) * Priority (High to Low / Low to High) * Status (Active first, Archived last) * Custom (user-defined order) * **Features**: Remember user's last sort preference, show active sort direction **3. FILTER - Narrow down by attributes**: * **What**: Checkboxes, dropdowns, or range selectors for specific criteria * **Examples**: * By category (Electronics, Clothing, Home) * By status (Active, Pending, Archived) * By date range (Last 7 days, Last 30 days, Custom) * By author (My Items, Team Items, All Items) * By numeric range (Price $0-50, $50-100, $100+) * **Features**: * Multiple filters combined (AND logic: status=Active AND category=Electronics) * Show count of matching items ("Showing 15 of 234 tasks") * "Clear all filters" button * Active filters clearly shown (chips/tags) **Visual example - Task list with search/sort/filter**: ``` ┌────────────────────────────────────────────────────────┐ │ [Search: "website"___________] 🔍 │ │ │ │ Filters: Sort: [Due Date ▼] │ │ Status: [✓ Active] [ Archived] │ │ Priority: [✓ High] [✓ Medium] [ Low] │ │ Assigned to: [✓ Me] [ My Team] [ Everyone] │ │ │ │ Active Filters: Status: Active × Priority: High × │ │ [Clear All Filters] │ │ │ │ Showing 8 of 124 tasks │ │ ───────────────────────────────────────────────────── │ │ ✓ Update website content [High] Due: Oct 10 │ │ ✓ Fix mobile navigation bug [High] Due: Oct 12 │ │ ✓ Review security patches [High] Due: Oct 15 │ │ ... │ └────────────────────────────────────────────────────────┘ ``` **In Buzzy**: Use [filter fields](/the-building-blocks/datatables-fields-and-data/filter-controls) and [sort fields](/the-building-blocks/datatables-fields-and-data/sort-fields) to implement these features. **Design considerations**: | Consideration | Mobile | Desktop | Why | | ----------------- | ------------------------------------ | --------------------------------------- | --------------------------------- | | **Filter Layout** | Collapsible panel or modal | Sidebar or top bar | Limited screen space on mobile | | **Performance** | Backend filtering (server-side) | Backend filtering | Don't load all records to client | | **UX** | Clear active filters, easy to remove | Show filters inline, allow multi-select | Users need to see what's filtered | | **Defaults** | Smart defaults (e.g., "My Tasks") | Allow customization | Reduce initial clicks | **Sample Buzzy AI prompt with search/sort/filter**: ``` "Create a task list screen with comprehensive finding features: SEARCH: - Add a search textbox at the top of the screen - Search across task.title and task.description fields - Real-time search (updates as user types) - Show placeholder text: 'Search tasks...' - Show search result count: 'Found X tasks' - Add clear search button (X icon) when search has text SORT: - Add sort dropdown with options: - 'Due Date (Soonest First)' - default - 'Due Date (Latest First)' - 'Priority (High to Low)' - 'Priority (Low to High)' - 'Title (A-Z)' - 'Recently Created' - Remember user's last sort selection in browser storage - Show current sort option clearly selected FILTERS: - Add collapsible filter panel (collapsed by default on mobile, open on desktop) Status Filter (checkboxes): - [ ] Active (default checked) - [ ] In Progress (default checked) - [ ] Complete - [ ] Archived Priority Filter (checkboxes): - [ ] High (default checked) - [ ] Medium (default checked) - [ ] Low Assigned To Filter (radio buttons): - (•) My Tasks - shows tasks where assignee = current user (default) - ( ) My Team Tasks - shows tasks where assignee in user's team - ( ) All Tasks - shows all tasks user has access to Due Date Filter (radio buttons): - ( ) All Dates (default) - ( ) Overdue - due_date < today - ( ) Due This Week - due_date within next 7 days - ( ) Due This Month - due_date within next 30 days Active Filters Display: - Show chips/tags above task list for each active filter - Each chip has X button to remove that specific filter - Show 'Clear All Filters' button if 2+ filters active - Show count: 'Showing X of Y tasks' Filter Behavior: - All filters use AND logic (must match all selected criteria) - Filters apply immediately when changed - Remember filter state in URL parameters for bookmarking - On mobile, filter panel slides in from side or bottom" ``` **Common mistakes to avoid**: ❌ **Filtering on client-side with large datasets**: Don't load 10,000 records and filter in the browser—use server-side filtering through Buzzy's viewFilters. ❌ **Hidden filters**: Don't hide active filters. Users need to see what's being filtered and easily remove filters. ❌ **No default smart sort**: Don't show items in random order. Pick a sensible default (usually newest first, or most relevant). ❌ **Complex filter UI**: Don't overwhelm users with 20 filter options at once. Start with 3-5 most important filters. ✅ **Best practice**: Start with simple search + 2-3 key filters. Add more based on user feedback. Every filter you add makes the UI more complex, so only add what provides clear value. ## Designing for Different Users ### User Roles and Permissions Most apps have different types of users with different capabilities. **Common role patterns**: **Admin**: * Full access to all features * Can manage users and settings * Sees all data across users **Creator/Editor**: * Can create and edit content * Sees own content and maybe team content * Limited settings access **Viewer**: * Read-only access * Can view but not modify * No admin features **Guest/Public**: * Very limited access * Often not logged in * Can view public content only **In your design**: 1. List all user types 2. Define what each type can see 3. Define what each type can do 4. Specify exceptions (e.g., editors can only edit their own content) **Document as a matrix**: ``` Feature | Admin | Editor | Viewer | Guest -----------------+-------+--------+--------+------- Create Project | Yes | Yes | No | No Edit Own Project | Yes | Yes | No | No Edit Any Project | Yes | No | No | No Delete Project | Yes | No | No | No View All Projects| Yes | Team | Team | No View Public | Yes | Yes | Yes | Yes ``` ### Mobile vs. Desktop Considerations **Design differences**: **Mobile**: * Smaller screen (prioritize essential info) * Touch interface (bigger tap targets) * Often slower connection (minimize data) * Used on the go (quick interactions) **Desktop**: * More screen space (can show more at once) * Mouse/keyboard (more precise interaction) * Usually faster connection (richer content okay) * Longer sessions (complex workflows okay) **Functional design implications**: **Navigation**: * Mobile: Hamburger menu or bottom tabs * Desktop: Sidebar or top nav bar **Forms**: * Mobile: One question per screen or short forms * Desktop: Multi-column forms okay **Lists**: * Mobile: Cards with key info, tap for details * Desktop: Tables with multiple columns **Actions**: * Mobile: Swipe actions, context menus * Desktop: Always-visible buttons, keyboard shortcuts {% hint style="success" %} **Mobile-First Design**: Design for mobile first, then expand for desktop. It's easier to add for desktop than remove for mobile. {% endhint %} ## Common Functional Patterns ### 1. Master-Detail **Pattern**: List of items → Click item → See details **Example**: Email inbox (list of emails → click → read full email) **Considerations**: * How to return to list? * Remember scroll position? * Previous/next navigation in detail view? ### 2. Create-Read-Update-Delete (CRUD) **Pattern**: Standard operations on data **Screens needed**: * List view (Read all) * Detail view (Read one) * Create form * Edit form (often same as create) * Delete confirmation **For each, specify**: * Who can access * Validation rules * Success/error messages * Where to navigate after ### 3. Multi-Step Workflows **Pattern**: Complex process broken into steps **Example**: Checkout (cart → shipping → payment → confirmation) **Considerations**: * Progress indicator (step 2 of 4) * Can user go back? * What happens if they abandon midway? * Save partial progress? ### 4. Approval/Review Workflows **Pattern**: Item goes through states requiring different people **Example**: Document review (draft → submitted → reviewed → published) **Considerations**: * Who can transition between states? * Notifications when state changes? * Comments/feedback during review? * History of state changes? ### 5. Dashboard/Overview **Pattern**: Summary view of important information **Example**: Admin dashboard (users count, recent activity, pending items) **Considerations**: * What metrics matter most? * Real-time updates or periodic? * Drill down to details? * Customizable by user? ## Functional Design Checklist Before building, verify: * [ ] **User flows mapped**: Documented main user journeys * [ ] **Actions defined**: Listed all things users can do * [ ] **Display rules specified**: Defined what shows when * [ ] **Context planned**: Thought through context flow between screens * [ ] **Search/sort/filter**: Planned how users find items * [ ] **Roles and permissions**: Defined who can do what * [ ] **Error handling**: Specified what happens when things fail * [ ] **Mobile considered**: Thought through mobile vs desktop * [ ] **Success states**: Defined confirmations and feedback * [ ] **Empty states**: Planned what shows when no data exists ## Prompting AI with Functional Design **Bad Prompt**: "Build a task app with a list and detail view" **Good Prompt**: "Build a task app with: **Flows**: * List tasks → Click task → View detail with edit button → Edit form → Save → Return to list * List tasks → Click 'New Task' → Create form → Save → Return to list with new task visible **Display Rules**: * Show 'Edit' and 'Delete' buttons only for task owner or admin * Show 'Assign to Me' button only if task is unassigned and user is not a viewer * Show 'Overdue' badge in red if due\_date < today and status != 'Complete' **Actions**: * Create task (all logged-in users) * Edit task (owner or admin only) * Delete task (admin only) * Assign task (owner or admin only) * Mark complete (assignee, owner, or admin) **Search/Filter**: * Search tasks by title and description * Filter by status (All, Pending, In Progress, Complete) * Filter by assignee * Sort by due date, priority, or created date Make it mobile-responsive with card layout on mobile and table on desktop." **Result**: AI generates much closer to what you actually need. ## Iterating on Functional Design Functional design evolves as you build and learn: **After initial build**: 1. Test the main flows yourself 2. Identify confusing or clunky parts 3. Get user feedback 4. Refine the design 5. Prompt AI to update specific flows **Common refinements**: * Reducing clicks for common actions * Adding missing error messages * Improving mobile navigation * Adding confirmation dialogs * Better empty states {% hint style="warning" %} **Don't Over-Design**: You don't need every detail figured out before starting. Define core flows, build, test, and refine. Iteration is normal and healthy. {% endhint %} ## Next Steps * **See examples**: [Building Examples](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples) * **Plan your workflow**: [Project Workflow](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow) * **Build something**: Start with [Hello World](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/hello-world) Remember: **Good functional design makes users successful without thinking about the app—they just accomplish their goals naturally.** # Project Workflow Strategic guidance for managing Buzzy app development from planning to deployment. ## The Reality of Building with Buzzy AI and Builder MCP Building with Buzzy is not a straight line from prompt to finished app. It's an iterative process that requires strategy, discipline, and understanding when to use Builder MCP, Buzzy AI prompts, the visual editor, or Figma. This section addresses the real challenges: * Choosing Builder MCP, prompt-first Buzzy AI, Figma, or manual editing * Context loss across broad AI prompts * When to use an agent, AI prompt, or visual editor * When to rollback to previous versions * Testing your Buzzy app thoroughly * Maintaining app quality over time ## The Workflow Stages ### 1. Planning & Design → [Design Fundamentals](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals) Before writing your first prompt: * Understand your data structure * Map user flows * Define roles and permissions * Set success criteria ### 2. Initial Build **Choosing your approach**: * [What to Use When](/getting-started-with-buzzy/what-to-use-when) * [One-Shot vs Iterative Development](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/one-shot-vs-iterative) **Making it happen**: * Use Builder MCP for staged serious builds, template adaptation, existing-app changes, or agent-assisted verification * Use prompt-first Buzzy AI for quick app creation or focused workspace edits * Review generated Brief, Datamodel, Flows, Blueprint, Theme, and Design tabs * Test core functionality in preview mode `Flows` are now part of the core app definition in Buzzy. Defining your app's functionality in flow diagrams gives the AI clearer behavioral context, which improves how the brief, datamodel, blueprint, and theme come together in the generated app. ### Why This Improves AI Output When flows are defined up front, Buzzy can generate app structure with better alignment to your requirements: * More accurate blueprint and screen outputs for real user journeys. * Better handling of conditional behavior and stage-based states. * Reduced context drift across prompt iterations. * Better coverage of business logic that is hard to capture in brief text alone. ### 3. Iteration & Refinement **Managing changes**: * [Making Changes Effectively](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/making-changes) * [AI vs Manual Edits](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/ai-vs-manual-edits) * [Rollback Strategies](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/rollback-strategies) **Quality assurance**: * [Testing Approaches](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/testing-approaches) ### 4. Deployment **Going live**: * [Deployment Guide](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/deployment) **Long-term**: * [Maintenance & Tech Debt](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/maintenance) ## The Core Workflow Challenges ### Challenge 1: Context Loss **The problem**: Each new Buzzy AI prompt operates with limited context. Your 5th prompt might alter what your 1st prompt created. **The solution**: * Keep prompts focused and specific * Reference previous structure explicitly * Review generated changes in Datamodel, Flows, and Design tabs * Use Buzzy's Versions tab for rollback (see [Rollback Strategies](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/rollback-strategies)) ### Challenge 2: Testing Fatigue **The problem**: Thorough testing is important but time-consuming. It's easy to get lazy or impatient. **The solution**: * Test strategically, not exhaustively * Automate repetitive tests * Focus on critical paths * Accept imperfection in early iterations → See [Testing Approaches](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/testing-approaches) ### Challenge 3: Testing with Real Data **The problem**: Your app might work with test data but have issues with real-world scenarios. **The solution**: * Test with varied data in preview mode * Review generated Datatables and field types * Test different user scenarios * Check edge cases and validation ### Challenge 4: Maintaining App Quality **The problem**: Generated apps may not follow best practices for security, performance, or user experience. **The solution**: * Review server-level security (Viewers, Team Viewers fields) * Check data model design (proper use of Subtables and Linked Fields) * Ensure display rules and actions work correctly * Test on both web and mobile → See [Best Practices](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices) ### Challenge 5: Long-Term Maintenance **The problem**: Apps need ongoing updates and improvements over time. **The solution with Buzzy**: * Buzzy maintains the Core Engine automatically * React/React Native updates handled by Buzzy * Security patches applied platform-wide * You focus on app logic and user experience → See [Maintenance & Tech Debt](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/maintenance) to learn how Buzzy solves traditional tech debt problems ## Workflow Best Practices ### 1. Start Small **Don't**: Try to build the entire app in one prompt **Do**: * Build core feature first * Test it thoroughly * Add features incrementally * Validate each addition ### 2. Be Specific **Don't**: "Fix the bug" or "Make it better" **Do**: * "The submit button doesn't validate email format before submitting" * "Add loading indicator when fetching user data" * "Make mobile menu close after selecting item" ### 3. Review Everything **Don't**: Assume AI-generated structure is perfect **Do**: * Test each change in preview mode * Review Datamodel and Flows for proper structure and behavior * Verify security settings (Viewers fields) * Check display rules and actions work correctly ### 4. Document Decisions **Don't**: Rely on memory for why things are built a certain way **Do**: * Keep notes on design decisions * Document unusual patterns * Explain business logic * Record AI limitations encountered ### 5. Use Buzzy's Version Control **Don't**: Make major changes without saving versions **Do**: * Use Buzzy's Versions tab to save stable states * Save versions before major AI prompts * Name versions clearly ("v1-before-adding-payments") * Rollback when experiments don't work → See [Rollback Strategies](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/rollback-strategies) ## When Things Go Wrong ### The App Broke 1. **Assess**: What changed? What broke? 2. **Rollback**: Use Buzzy's Versions tab to restore last working state (see [Rollback Strategies](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/rollback-strategies)) 3. **Analyze**: What went wrong in the data model or screen logic? 4. **Fix**: Address specific issue with targeted AI prompt or visual editor ### Feature Not Working as Expected 1. **Understand**: Why is it failing? 2. **Root Cause**: Is it the data model, display rules, or actions? 3. **Fix**: Targeted change using visual editor or AI prompt 4. **Verify**: Feature works and nothing else broke ### Lost Context 1. **Stop**: Don't keep prompting blindly 2. **Review**: Look at current state vs desired state 3. **Reset**: Consider rolling back to known good state 4. **Rebuild**: Small, specific changes from there ### Running Out of Time/Money 1. **Assess MVP**: What's absolutely necessary? 2. **Cut Scope**: Remove nice-to-have features 3. **Simplify**: Reduce complexity where possible 4. **Ship**: Get to working version, iterate later ## Workflow Patterns ### For Simple Apps (Hours to Days) 1. Design data structure (30 min) 2. Write comprehensive Buzzy AI prompt (15 min) 3. Review generated Brief, Datamodel, and Design tabs (30 min) 4. Review and refine Flows for key user journeys (15-30 min) 5. Polish UI in visual editor (1-2 hours) 6. Test in preview mode (30 min) 7. Final testing on live app (30 min) 8. Publish ### For Moderate Apps (Days to Weeks) 1. Design phase (2-4 hours) 2. Build core Datatables and screens with Buzzy AI (1-2 days) 3. Visual editor refinement of UX (1-2 days) 4. Feature additions with AI prompts iteratively (ongoing) 5. Regular testing in preview and live (ongoing) 6. Progressive publishing ### For Complex Apps (Weeks to Months) 1. Comprehensive design phase (days) 2. Prototype core with Buzzy AI (days) 3. Build complex features with Buzzy Functions (ongoing) 4. AI assistance for standard screens and Datatables (ongoing) 5. Continuous testing and QA (ongoing) 6. Staged publishing {% hint style="info" %} **Remember**: Complexity extends timelines exponentially, not linearly. A "twice as complex" app might take 10x longer. {% endhint %} ## Success Metrics Track these to know if your workflow is healthy: **App Quality**: * Data model issues found per iteration * User experience problems * Bug count after changes **Productivity**: * Time from prompt to working feature * Balance of AI prompts vs visual editor * Rollback frequency **User Value**: * Feature completion rate * User-reported issues * Time to fix problems **Maintainability**: * Clarity of data model * Ease of understanding app structure * Ease of making changes in Buzzy ## Next Steps Choose the topic most relevant to where you are: * **Starting out**: [One-Shot vs Iterative](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/one-shot-vs-iterative) * **Making changes**: [AI vs Manual Edits](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/ai-vs-manual-edits) * **Something broke**: [Rollback Strategies](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/rollback-strategies) * **Need to test**: [Testing Approaches](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/testing-approaches) * **Ready to launch**: [Deployment Guide](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/deployment) * **Thinking long-term**: [Maintenance & Tech Debt](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/maintenance) {% hint style="success" %} **Remember**: There's no perfect workflow. Find what works for your project, team, and timeline. The key is being intentional rather than chaotic. {% endhint %} # One-Shot vs Iterative Development Master when to build your entire Buzzy app at once versus building incrementally. Learn the pros, cons, and best practices for each approach. ## The Two Approaches Explained **Non-technical explanation**: Think of building an app like cooking a meal. One-shot is like making a complete Thanksgiving dinner from a single detailed recipe all at once. Iterative is like cooking dish by dish, tasting as you go, and adjusting. Both work, but different situations call for different approaches. **Visual comparison**: **One-Shot Approach**: ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%% graph TB A1[Write Complete Prompt] --> B1[Buzzy Generates
Full App Structure] B1 --> C1[Review Everything] C1 --> D1[Refine in Visual Editor] D1 --> E1[Test & Launch] ``` **Iterative Approach**: ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%% graph TB A2[Write Basic Prompt] --> B2[Generate Core] B2 --> C2[Review & Test] C2 --> D2[Add Feature Prompt] D2 --> E2[Generate Addition] E2 --> F2[Review & Test] F2 --> G2[Repeat Until Done] ``` ### One-Shot Development with Buzzy AI **What it is**: Writing a comprehensive, detailed prompt that describes your entire application, letting Buzzy AI generate the complete app structure at once. **Real example**: ``` "Build a complete recipe management app with: DATA MODEL: - Users (name, email, role: Cook/Admin) - Recipes Datatable with fields: - name, description, prep_time (minutes), cook_time (minutes) - difficulty (dropdown: Easy, Medium, Hard) - cuisine_type (dropdown: Italian, Mexican, Asian, etc.) - Viewers field set to recipe author - ingredients (Subtable → Ingredients Datatable) - Ingredients Datatable (Subtable of Recipes): - ingredient_name, quantity, unit - Comments Datatable: - comment_text, author (linked to Users) - recipe_id (linked to Recipes) SCREENS: 1. Recipe list with search, filter by cuisine and difficulty 2. Recipe detail showing ingredients list and comments 3. Add recipe form with nested ingredient entries 4. Edit recipe with ability to add/remove ingredients 5. My Recipes screen filtered to current user SECURITY: - Recipes visible to all users but editable only by author - Use Viewers field for recipe ownership - Comments visible to all, authored by current user Make it mobile-responsive with card layouts." ``` **Buzzy generates**: * **Brief**: Summary of what the app does * **Blueprint**: All screens and navigation flow * **Data tab**: Complete Datatables with Subtables and relationships * **Design tab**: All screen layouts with components and actions ### Iterative Development with Buzzy **What it is**: Building the app incrementally—start with core features, test thoroughly, then add more features one at a time using Buzzy AI prompts and visual editor. For current serious builds, Builder MCP is the preferred iterative path because the agent can stop at review gates, inspect persisted artifacts, use sample data, and verify screens in preview or runtime. **Real example approach**: **Phase 1** - Basic foundation: ``` Prompt: "Build a basic recipe app with: - Recipes Datatable (name, description, prep_time) - Recipe list screen - Recipe detail screen - Add recipe form - Users can only see their own recipes (Viewers field)" → Generate → Review → Test in preview mode ``` **Phase 2** - Add ingredients: ``` Prompt: "Add ingredients to the recipe app: - Create Ingredients Datatable as Subtable of Recipes - Fields: ingredient_name, quantity, unit - Update recipe detail screen to show ingredients list - Update add/edit forms to include ingredient entries" → Generate → Review → Test in preview mode ``` **Phase 3** - Add comments: ``` Prompt: "Add comments feature: - Comments Datatable linked to Recipes - Show comments on recipe detail screen - Add comment form for logged-in users" → Generate → Review → Test in preview mode ``` **Phase 4** - Polish UX (manual edits in Design tab): * Adjust layout spacing * Improve mobile responsiveness * Add helpful empty states * Enhance button styles ## When to Use One-Shot with Buzzy ### Good Use Cases **Simple, well-defined apps**: * ✅ Contact form apps * ✅ Simple CRUD apps (task lists, inventory trackers) * ✅ Internal tools (calculators, data entry forms) * ✅ Prototypes to demonstrate concepts * ✅ MVPs to validate ideas **Characteristics**: * Single or simple user roles * Clear data model (2-4 Datatables) * Standard UI patterns * Straightforward business logic * No complex external integrations ### Advantages 1. **Speed**: Get a working Buzzy app in minutes 2. **Complete vision**: Buzzy sees your full requirements 3. **Consistency**: Generated App Definition uses consistent patterns 4. **All basics covered**: Brief, Blueprint, Data, and Design all generated 5. **Safe to modify**: Can use visual editor to refine without breaking anything ### Disadvantages 1. **Generic assumptions**: Buzzy makes reasonable assumptions that may not be exactly what you want 2. **May need refinement**: Data relationships might need adjustment 3. **Less understanding**: If you don't review what was generated, you won't understand your app structure 4. **Context limits**: Very large prompts may not generate optimal results ### One-Shot Best Practices with Buzzy **1. Be extremely specific about data relationships**: ``` Bad: "Build a recipe app" Good: "Build a recipe app where: - Each recipe has a name, description, prep time in minutes, and step-by-step instructions - Each recipe has multiple ingredients (use Subtable) with name, quantity, and unit - Users can create and edit their own recipes - Recipe list screen should be searchable - Recipe detail screen shows ingredients as a list - Users should only see their own recipes unless they're shared" ``` **2. Include all requirements upfront**: * Data structure with specific mention of Subtables (1:M) or Linked Table Fields (N:M) * Security requirements (Viewers fields, Organizations/Teams) * All screens and key navigation flows * Mobile and web needs * Critical display rules **3. Review what Buzzy generated**: * **Brief**: Does it capture your app's purpose? * **Blueprint**: Are all necessary screens included? * **Data tab**: Check Datatables, Subtables, and Linked Table Fields * **Design**: Review screen layouts and components **4. Use preview mode to test**: * Navigate through all screens * Test data entry and editing * Verify display rules work correctly * Check mobile view **5. Refine using visual editor**: * Adjust screen layouts in Design tab * Fine-tune display rules * Update field labels and placeholders * Modify navigation flow {% hint style="warning" %} **Reality Check**: Even simple apps usually need refinement. The difference with Buzzy: you can safely edit in the visual editor without breaking anything. No risk of corrupting generated code. {% endhint %} ## When to Use Iterative with Buzzy ### Good Use Cases **Complex apps**: * ✅ Multi-role applications (with Organizations and Teams) * ✅ Complex data relationships (many Subtables and Linked Table Fields) * ✅ External API integrations (requiring Buzzy Functions) * ✅ Apps that will grow over time **Learning situations**: * ✅ You're new to Buzzy's platform * ✅ You're learning about Subtables and Linked Table Fields * ✅ Requirements are evolving as you explore **Production apps**: * ✅ Apps where data model design is critical * ✅ Apps where UX quality matters more than speed * ✅ Apps with specific security requirements ### Advantages 1. **Control**: Build exactly what you want, reviewing each step 2. **Learning**: Understand Buzzy's data model and structure as you build 3. **Quality**: Catch data model issues early before they cascade 4. **Understanding**: Learn how Subtables and Linked Table Fields work 5. **Flexibility**: Easy to change direction with Buzzy's visual editor ### Disadvantages 1. **Slower**: Takes more time than one-shot approach 2. **Multiple prompts**: Need to communicate clearly across iterations 3. **More decisions**: You decide the build sequence 4. **Testing overhead**: Need to test after each iteration ### Iterative Best Practices with Buzzy **1. Build using Builder MCP or a focused Buzzy AI workflow**: **Phase 1 - Foundation**: * **Prompt**: "Build basic structure with core Datatables" * **Review**: Check generated Brief, Blueprint, and Data model * **Refine**: Adjust Subtable relationships in Data tab if needed * **Test**: Use preview mode **Phase 2 - Core Features**: * **Prompt**: "Add \[specific feature] with \[data relationships]" * **Review**: Check how it integrates with existing structure * **Refine**: Use Design tab to adjust screen layouts * **Test**: Verify new workflows in preview **Phase 3 - External Integrations** (if needed): * Create Buzzy Functions for external APIs * Add Constants for API keys * Test Functions before integrating into app * Wire up Functions in app actions **Phase 4 - Polish**: * Refine UX using Design tab * Add display rules for conditional visibility * Optimize screen layouts for mobile * Test thoroughly with realistic data **2. Test between iterations**: * Use Buzzy's preview mode after each change * Test with different user roles (if applicable) * Verify data relationships work correctly * Check mobile and web views **3. Be specific about Buzzy concepts**: ``` Bad: "Add comments" Good: "Add a Comments subtable to the Tasks datatable. Each comment should have: - content (text field) - author (link to current user) - created_at (timestamp) Show comments in the Task Detail screen below the task info. Only logged-in users can add comments. Users can edit or delete their own comments only (use Viewers field for this)." ``` **4. Use visual editor strategically**: * Make small UX adjustments manually in Design tab * Use AI prompts for structural changes (new Datatables, Subtables) * Don't prompt AI for every tiny visual tweak * Leverage Buzzy's version control (Versions tab) to rollback if needed **5. Document your data model**: * Keep a data model diagram updated * Note complex Subtable/Linked Field relationships * Document security patterns (Viewers, Team Viewers) * Note any Buzzy Functions and their purpose ## Hybrid Approach with Buzzy In practice, most successful Buzzy projects use a combination: ### The Hybrid Strategy **1. One-shot for foundation**: Use Builder MCP or a focused Buzzy AI prompt to generate basic app structure with core Datatables and screens **2. Iterative for features**: Add functionality using focused prompts, testing each addition **3. Visual editor for refinements**: Use Design tab to adjust layouts, display rules, and actions **4. Buzzy Functions for complex integrations**: Create Functions for external APIs, advanced calculations, or custom logic ### Example: E-commerce App with Buzzy **One-shot (Day 1)**: Prompt: "Build an e-commerce app with: * Products datatable (name, description, price, image, inventory count) * Orders datatable with Order Items subtable (to store product, quantity, price) * Users datatable for customers * Screens: product list (searchable), product detail, shopping cart, my orders" **Review and adjust**: * Check Data tab for Subtable relationships * Verify Orders → Order Items uses Subtable correctly * Test basic navigation in preview **Iterative additions (Days 2-5)**: * Day 2: Prompt for product categories (use Linked Table Field for N:M) * Day 3: Prompt for checkout flow screens * Day 4: Create Buzzy Function for payment processing (Stripe API) * Day 5: Prompt for order history and status tracking **Visual refinements (Days 6-7)**: * Use Design tab to improve product card layouts * Add display rules for inventory warnings * Refine checkout flow UX * Optimize mobile experience **Buzzy Functions** (as needed): * Payment processing via Stripe * Inventory management logic * Order confirmation emails * Price calculations with discounts ## Switching Approaches Mid-Project Sometimes you realize the chosen approach isn't working: ### From One-Shot to Iterative **When to switch**: * Data model needs significant restructuring * Generated screens don't match your vision * Requirements have significantly changed * You need more control over the structure **How to switch with Buzzy**: 1. Use Buzzy's Versions tab to save current state 2. Identify what's working well (keep it) 3. Use focused prompts to rebuild problematic areas 4. Leverage Design tab for manual adjustments 5. Test thoroughly in preview mode **Advantage with Buzzy**: Safe to iterate because you have version control and visual editing without breaking anything ### From Iterative to One-Shot **When to switch**: * Need to add entire new section quickly * Current approach feels too slow * Adding standard, well-defined features * Want Buzzy to generate structure for a new area **How to switch with Buzzy**: 1. Document current app structure 2. Write comprehensive prompt for new section 3. Let Buzzy generate the new structure 4. Review generated Datatables, screens, and relationships 5. Test how it integrates with existing app 6. Use Design tab to refine integration points ## Decision Framework for Buzzy Ask yourself: ### Choose One-Shot with Buzzy AI if: * [ ] App is simple (< 5 Datatables, straightforward relationships) * [ ] Requirements are fully defined * [ ] Standard UI patterns work for your needs * [ ] Speed is critical (MVP, prototype, demo) * [ ] You're comfortable reviewing generated App Definitions ### Choose Iterative with Buzzy if: * [ ] App is complex (> 5 Datatables, many Subtables/Linked Fields) * [ ] Requirements are evolving * [ ] External integrations needed (Buzzy Functions) * [ ] Data model design is critical * [ ] You're learning Buzzy's platform * [ ] You want to understand every aspect of your app ### Choose Hybrid if: * [ ] Medium complexity app * [ ] Mix of standard and custom features * [ ] Some time pressure but quality matters * [ ] App will grow over time * [ ] Need external API integrations (Buzzy Functions) * [ ] Want speed of one-shot with control of iterative ## Common Mistakes with Buzzy ### Mistake 1: One-Shot for Complex Apps **Problem**: Trying to describe everything in one massive prompt for a complex Buzzy app **Result**: * Suboptimal data model with unclear relationships * Missing Subtables or incorrect Linked Table Fields * Generic screens that don't match your vision * Time wasted restructuring vs starting iteratively **Fix**: Use iterative approach for apps with complex data relationships or multiple user roles ### Mistake 2: Too Iterative (Over-Prompting) **Problem**: Using Buzzy AI prompts for every tiny change instead of Design tab **Result**: * Painfully slow progress * Wasted prompts on trivial changes * Could have used visual editor much faster * Never ship because always tweaking **Fix**: Use AI prompts for structural changes (Datatables, Subtables), use Design tab for UI refinements ### Mistake 3: No Testing Between Iterations **Problem**: Adding feature after feature without using preview mode **Result**: * Issues compound in data model * Display rules don't work as expected * Navigation becomes confusing * Don't discover problems until much later **Fix**: Use preview mode after each significant iteration, test all workflows ### Mistake 4: Ignoring Data Model Review **Problem**: Not reviewing generated Datatables, Subtables, and Linked Table Fields **Result**: * Inefficient data structure * Wrong relationship types (Subtable vs Linked Field) * Performance issues later * Hard to add features later **Fix**: Always review the Data tab after Buzzy generates structure. Verify relationships make sense. ### Mistake 5: Scope Creep **Problem**: Continuously adding "just one more thing" **Result**: * Never finished * Overwhelmed by complexity * Lost sight of MVP * App becomes unmaintainable **Fix**: Define the MVP clearly, publish it, then iterate with additional features ## Next Steps * **Need to change something?**: [Making Changes Effectively](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/making-changes) * **Deciding AI prompts vs visual editor**: [AI vs Manual Edits](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/ai-vs-manual-edits) * **Ready to test**: [Testing Approaches](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/testing-approaches) * **Choose your build path**: [What to Use When](/getting-started-with-buzzy/what-to-use-when) {% hint style="success" %} **Remember**: With Buzzy, there's less risk than traditional code generation. You have version control, visual editing, and no code to break. The best approach depends on your app's complexity and your familiarity with Buzzy's platform. Start with your best guess and adjust as you learn—Buzzy makes it safe to iterate. {% endhint %} # AI vs Manual Edits Master when to use Builder MCP, Buzzy AI prompts, or the visual Design editor. Learn decision frameworks, best practices, and efficiency strategies for optimal productivity. ## The Core Question **Non-technical explanation**: When building in Buzzy, you have several tools. Builder MCP is best for staged agent-assisted changes, Buzzy AI prompts are fast for broad workspace edits, and the visual Design editor gives you precision control for fine-tuning details. Using the right tool at the right time makes you more productive. As you build your Buzzy application, you'll constantly face this decision: * 🤖 Should I use Builder MCP or prompt Buzzy AI to make this change? * 🎨 Or should I just use the visual Design editor? Getting this right dramatically affects productivity and efficiency. **The key difference from traditional code development**: With Buzzy, there's no code to manually edit. Instead, you choose between AI prompts (for structural changes) and visual editing (for refinements). **Decision impact**: ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%% graph TB A[Need to Make a Change] --> B{What Type?} B -->|Structural/Data| C[Use Builder MCP or Buzzy AI] B -->|Visual/Polish| D[Use Design Editor] C --> E[Fast & Complete] D --> F[Precise & Quick] G[Wrong Choice] --> H[Slow & Frustrating] style E fill:#6c6,stroke:#333,color:#000 style F fill:#6c6,stroke:#333,color:#000 style H fill:#f88,stroke:#333,color:#000 ``` ## When to Use Builder MCP or Buzzy AI Prompts ### Ideal for AI Prompts **1. Creating New Datatables and Relationships** ✅ **Use AI prompts when**: * Adding new Datatables to your app * Creating Subtables (1:M relationships) * Setting up Linked Table Fields (N:M relationships) * Defining field types and structures **Example**: "Add a Categories datatable and link it to Products using a Linked Table Field so products can have multiple categories" **Why**: Builder MCP and Buzzy AI both work with Buzzy's structured app model, so they can update related data and screens more coherently than isolated manual edits. *** **2. Generating New Screens** ✅ **Use AI prompts when**: * Creating new screens from scratch * Adding standard screen types (list, detail, form) * Building complete user workflows * Setting up navigation between screens **Example**: "Create a Project Detail screen that shows project info, has an edit button, and displays the Tasks subtable below" **Why**: AI generates complete screen structures with proper components and navigation *** **3. Adding Features with Data Changes** ✅ **Use AI prompts when**: * Features require new Datatables or fields * Need to modify data relationships * Adding functionality that touches multiple screens * Implementing features with business logic **Example**: "Add user assignments to tasks - create an Assignments subtable with user and role fields, show assignments in task detail, and add an 'Assign User' button" **Why**: AI can handle the data model changes and screen updates together *** **4. Large-Scale Refactoring** ✅ **Use AI prompts when**: * Renaming Datatables throughout the app * Changing data relationships (Subtable to Linked Field, etc.) * Restructuring screen flows * Major navigation changes **Example**: "Rename the 'Items' datatable to 'Products' throughout the entire app, including all screens, relationships, and references" **Why**: AI tracks changes across the entire App Definition consistently *** **5. Implementing Standard Patterns** ✅ **Use AI prompts when**: * Adding search and filter functionality * Implementing common workflows * Setting up authentication screens * Creating typical CRUD operations **Example**: "Add search functionality to the Products list screen that searches across product name and description" **Why**: Builder MCP and Buzzy AI know how to implement common Buzzy patterns across the app definition. ## When to Use Buzzy's Visual Design Editor ### Ideal for Visual Editor **1. Small UI Adjustments** ✅ **Use Design editor when**: * Changing button labels or colors * Adjusting field placeholders * Reordering components on a screen * Changing text content **Example**: Changing "Submit" button to "Save Changes" - just click the button in Design tab and update the label **Why**: Much faster than prompting AI for tiny changes *** **2. Fine-Tuning Display Rules** ✅ **Use Design editor when**: * Adjusting when components are visible * Tweaking conditional logic for display * Testing different display rule conditions * Refining user experience based on states **Example**: Adjusting display rule from `status = "active"` to `status = "active" OR status = "pending"` **Why**: Quick to test and iterate in visual editor *** **3. Layout and Styling Refinements** ✅ **Use Design editor when**: * Adjusting component spacing * Changing layout arrangements * Updating colors and themes * Fine-tuning mobile vs desktop views **Example**: Moving a button from top of screen to bottom, or adjusting card spacing **Why**: Immediate visual feedback, no need to describe desired layout to AI *** **4. Action Configuration** ✅ **Use Design editor when**: * Configuring submit actions * Setting up navigation actions * Adjusting what happens when buttons are clicked * Fine-tuning form submissions **Example**: Changing a button action to navigate to a different screen after submit **Why**: Visual action editor is intuitive and immediate *** **5. Iterative UX Improvements** ✅ **Use Design editor when**: * Refining based on user feedback * Testing different arrangements * Polishing the user experience * Making multiple small adjustments **Example**: Rearranging form fields, adjusting labels, changing button positions based on user testing **Why**: Rapid iteration without waiting for AI ## The Hybrid Approach Often the best strategy combines both AI prompts and Visual editor: {% hint style="info" %} If the issue is not yet clear, diagnose before choosing the tool. Use the editor's **Debug** tab and AI diagnosis flow to figure out whether you are dealing with a data-binding problem, a screen-structure problem, or a simple visual refinement. {% endhint %} ### Hybrid Pattern: AI First, Visual Polish **1. Generate with AI prompts**: Get most of the way there quickly with Builder MCP or Buzzy AI **2. Review**: Test in preview mode and identify what needs refinement **3. Visual editor refinements**: Polish the remaining 20% using Design tab **Example**: ``` Step 1 (AI prompt): "Create a user registration form with email, password, confirm password, and terms acceptance. Include validation that email is properly formatted and passwords match." Step 2 (Review in preview): Form works but could be improved: - Button text should say "Create Account" not "Submit" - Form fields could use better placeholder text - Error messages appear but styling could be friendlier Step 3 (Visual editor): In Design tab: - Click button, change label to "Create Account" - Update placeholders in each field - Adjust error message styling ``` ### Hybrid Pattern: Visual Foundation, AI Expansion **1. Refine core with visual editor**: Get critical UX details right **2. Use AI to expand**: Add standard features quickly with prompts **3. Review integration**: Test in preview to ensure new parts work well together **Example**: ``` Step 1 (Visual editor): Perfect the login screen layout and error states Step 2 (AI prompt): "Add password reset flow with email verification" Step 3 (Preview test): Verify reset flow navigation works smoothly with login screen ``` ## Decision Framework Use this flowchart thinking for Buzzy: ``` Need to make a change? | ├─ Is it a simple UI tweak (button label, color, spacing)? │ └─ YES → Use Design editor (faster than prompting) │ ├─ Does it involve new Datatables or relationships? │ └─ YES → Use AI prompt │ ├─ Is it a new screen or component? │ └─ YES → Use AI prompt │ ├─ Is it repetitive across multiple screens? │ └─ YES → Use AI prompt for consistency │ ├─ Does it require understanding existing app structure? │ └─ YES → Review Data and Design tabs first, then choose │ ├─ Is it adjusting display rules or actions? │ └─ YES → Use Design editor (visual, immediate feedback) │ ├─ Is it a standard pattern (search, filter, CRUD)? │ └─ YES → Use AI prompt + review in Design tab │ └─ When in doubt → Try AI prompt first, refine with Design editor ``` ## Common Mistakes ### Mistake 1: Using AI for Everything **Problem**: prompting Buzzy AI for every tiny UI change **Issues**: * Slower than using Design editor * AI might change unintended parts of your app * You learn less about Buzzy's visual editor capabilities * Wastes time describing simple changes **Fix**: Use Design editor for simple UI tweaks (button labels, colors, spacing) ### Mistake 2: Avoiding AI Too Much **Problem**: Trying to build everything with visual editor only **Issues**: * Unnecessarily slow for complex features * Missing the speed benefits of AI generation * Manually recreating patterns AI knows well * Error-prone when building repetitive structures **Fix**: Use AI prompts for new Datatables, screens, and standard patterns ### Mistake 3: Not Reviewing AI-Generated Structure **Problem**: Accepting AI-generated App Definition without checking **Issues**: * Wrong data relationships (using Linked Field when should use Subtable) * Missing security (no Viewers fields or Team access) * Incorrect display rules * Navigation doesn't match user flow **Fix**: Always review Brief, Blueprint, Data, and Design tabs after AI generates ### Mistake 4: Wrong Prompt Granularity **Problem**: Asking AI to change too much or too little at once **Issues**: * Too much: "Rebuild my entire app with these 10 new features" → AI gets confused * Too little: "Change the Submit button to Save" → Faster to use Design editor **Fix**: Find the right granularity: * Screen level: ✅ Good for AI ("Create a project detail screen...") * Button label: ❌ Too small, use Design editor * Entire app rebuild: ❌ Too large, break into features ## Buzzy AI Prompt Quality Matters **When using Buzzy AI, prompt quality makes a huge difference**: ### Bad Buzzy Prompts ❌ "Fix the form" ❌ "Make it responsive" ❌ "Add validation" ❌ "Update the styling" **Problems**: * Vague, unclear intent * AI must guess what you want * Often generates something different than you envisioned * Requires multiple iterations ### Good Buzzy Prompts ✅ "Add email format validation to the User Registration form that displays 'Please enter a valid email' error message below the email field when the format is invalid" ✅ "Create a Tasks subtable field in the Projects datatable so each project can have multiple tasks with title, description, and due\_date fields" ✅ "Add a display rule to the Submit Report button so it's only visible when the report status = 'Draft' AND the current user is the report creator" ✅ "Create a Reports List screen that shows only reports where the current user is in the Viewers field, with search functionality across report name and description" **Why better**: * Specific about Buzzy concepts (Datatables, Subtables, display rules, Viewers) * Clear expected behavior * Uses Buzzy-specific terminology * Easier for Buzzy AI to implement correctly * Less iteration needed ## Measuring Effectiveness Track whether you're using Buzzy AI and Design editor effectively: **Good signals**: * AI-generated structure works first try 80%+ of the time * You understand the Brief, Data, and Design that AI creates * Visual editor refinements are quick and precise * Mix of AI prompts and Design editor feels natural * Productivity is high * Apps work well in preview mode **Bad signals**: * Constantly re-prompting AI to fix mistakes * Don't understand the Datatables and relationships AI created * Spending more time describing changes than Design editor would take * Always choosing only AI or only Design editor (not using both strategically) * App breaks frequently when making changes ## Quick Reference Guide | Task | AI Prompt | Design Editor | Why | | ----------------------------- | --------- | ------------- | --------------------------------- | | Fix typo in button text | | ✅ | Faster to click and edit | | Create new Datatable | ✅ | | AI understands data structures | | Change button color | | ✅ | Visual feedback immediate | | Add Subtable relationship | ✅ | | AI handles relationship setup | | Adjust display rule condition | | ✅ | Visual editor shows logic clearly | | Create search functionality | ✅ | | Standard pattern AI knows | | Reorder screen components | | ✅ | Drag-and-drop in Design tab | | Generate new screen | ✅ | | AI creates complete structure | | Set up Organizations security | ✅ | | Complex pattern, AI helps | | Change field placeholder | | ✅ | One click in Design tab | | Create Linked Table Field | ✅ | | AI handles N:M relationships | | Adjust spacing/margins | | ✅ | Visual, immediate feedback | ## Next Steps * **Need to undo changes**: [Rollback Strategies](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/rollback-strategies) * **Making changes effectively**: [Making Changes](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/making-changes) * **Ready to test your app**: [Testing Approaches](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/testing-approaches) {% hint style="success" %} **Key Takeaway**: The best Buzzy builders know when to use AI prompts and when to use the Design editor. It's not about using AI more—it's about using AI *strategically* and combining it with visual editing for maximum efficiency. {% endhint %} # Making Changes Effectively Master the art of modifying and extending your Buzzy application safely and effectively. Learn strategies for AI-powered changes vs manual edits. ## The Challenge of Changes One of the biggest struggles with building in Buzzy: **making changes after the initial build without breaking everything**. **Non-technical explanation**: Think of your Buzzy app like a house. When you want to renovate, you can't just knock down walls randomly—some walls are load-bearing and removing them could collapse the roof. Similarly, changing one part of your app can unexpectedly break other parts. This guide teaches you how to safely renovate your app. **Why making changes is challenging**: * **Context loss**: broad prompt-only changes can lose important context from earlier decisions * **Ripple effects**: Changes can affect related features you didn't think about * **Data dependencies**: Modifying data structure cascades through all screens that use that data * **Consistency maintenance**: Need to update all references when you change something * **Testing burden**: Each change requires verification that nothing else broke **Visual representation of change complexity**: ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%% graph TD A[Simple Change Request] --> B{Change Type} B -->|Additive| C[Low Risk
Add new feature] B -->|Modification| D[Medium Risk
Change existing feature] B -->|Deletion| E[High Risk
Remove feature] B -->|Restructure| F[Highest Risk
Reorganize structure] C --> G[Test new feature only] D --> H[Test changed feature
+ related features] E --> I[Test all dependencies
+ cascading effects] F --> J[Test entire app
+ data integrity] ``` **This guide helps you**: * Choose the right change strategy for your situation * Minimize risk of breaking existing functionality * Use Builder MCP, Buzzy AI prompts, and manual edits effectively for modifications * Know when to use manual edits vs AI prompts * Implement changes systematically and safely {% hint style="info" %} Before you change a screen that already looks broken, diagnose it first. In the Buzzy editor, the **Debug** tab and **Diagnose with AI** flow can help you confirm whether the problem is a binding, visibility rule, action wiring issue, or a broader screen-level error before you start editing. {% endhint %} ## Types of Changes ### 1. Additive Changes **What it is**: Adding new features without modifying existing ones—like adding a new room to your house without changing the existing rooms. **Examples**: * Add a new screen (e.g., user profile page) * Add a new field to a datatable (e.g., priority field to tasks) * Add a new datatable (e.g., comments, categories) * Add a new user role (e.g., viewer, moderator) * Add new display rules (e.g., show badges for priority) * Add new navigation options (e.g., quick actions menu) **Strategy**: Lowest risk, easiest to implement. Like adding furniture to an empty room—unlikely to break anything. **Step-by-step approach**: 1. **Plan the addition**: Clearly describe what you're adding and why 2. **Define integration points**: How does it connect to existing features? 3. **Start isolated**: Build the new feature separately first 4. **Connect gradually**: Link to existing features one connection at a time 5. **Test thoroughly**: Verify new feature works AND existing features still work **Sample Buzzy AI prompts for additive changes**: **Example 1 - Add Comments System**: ``` "Add a comments feature to the task management app: NEW DATATABLE: Comments Fields: - comment_text (long text, required) - author (linked table field → Users, required) - created_at (timestamp, auto-generated) - task_id (linked table field → Tasks, required) INTEGRATION WITH EXISTING: - Add 'comments' subtable field to existing Tasks datatable - On task detail screen, add comments section below existing task information - Show comment author name, text, and timestamp for each comment - Add 'Add Comment' button for logged-in users only - Use display rule: show comments section only if task has comments OR user is logged in PERMISSIONS: - All users can read comments on tasks they can view - Only logged-in users can add comments - Users can only edit/delete their own comments (author = current user) Keep all existing task functionality unchanged." ``` **Example 2 - Add Priority Field**: ``` "Add priority tracking to the existing task management app: MODIFY EXISTING DATATABLE: Tasks Add new field: - priority (dropdown with options: Low, Medium, High, Urgent, default: Medium) DISPLAY UPDATES: - Task list screen: Add priority column with colored badges - Low: gray badge - Medium: blue badge - High: orange badge - Urgent: red badge - Task detail screen: Show priority field below title - Task create/edit forms: Add priority dropdown field SORTING/FILTERING: - Add priority to sort options (High to Low, Low to High) - Add priority filter checkboxes to existing filter panel Keep all existing fields, display rules, and functionality exactly the same." ``` **Example 3 - Add New Screen**: ``` "Add a user profile screen to the existing app: NEW SCREEN: User Profile Fields to display: - Profile photo (from Users datatable, image field) - Name (from Users datatable) - Email (from Users datatable) - Bio (add new 'bio' field to Users datatable, long text, optional) - Join date (from Users datatable, created_at field) - Task statistics: total tasks created, total completed NAVIGATION: - Add 'Profile' option to existing navigation menu - Add profile link when clicking on user names throughout the app - Include 'Edit Profile' button for current user only PERMISSIONS: - Users can view any profile (public information) - Users can only edit their own profile - Bio field is optional and can be left blank Don't modify any existing screens or functionality." ``` **Benefits of additive changes**: * ✅ Minimal risk of breaking existing features * ✅ Easy to test (test new feature + quick regression test) * ✅ Easy to remove if it doesn't work out * ✅ Clear scope—you know exactly what you're adding * ✅ Users can continue using existing features while you build **When to choose additive approach**: * Adding optional features or enhancements * Expanding functionality without changing core workflows * When you're unsure about the change (easy to remove later) * Building iteratively (add piece by piece) * Working with limited development time ### 2. Modification Changes **What it is**: Changing existing features—like renovating a room that's already in use. More complex because you need to maintain functionality while updating. **Examples**: * Change field type (date → date-time, text → dropdown) * Modify validation rules (make optional field required, change max length) * Update UI layout (table → cards, single column → multi-column) * Alter navigation flow (redirect users to different screen after action) * Change calculations or formulas * Update display rules or conditional logic **Strategy**: Medium risk, requires careful specification and thorough testing. **Step-by-step approach**: 1. **Document current state**: How does it work now? What are all the places this feature is used? 2. **Define exact changes**: What specifically needs to change? What stays the same? 3. **Identify ripple effects**: What other features might be affected? 4. **Plan migration**: How do you handle existing data? 5. **Test comprehensively**: Changed feature + all related features **Sample Buzzy AI prompts for modification changes**: **Example 1 - Change Field Type**: ``` "Modify the Tasks datatable to include time of day for due dates: CURRENT STATE: - Tasks datatable has 'due_date' field (date type) - Displays on task list, task detail, and task forms - Used in sorting and filtering - Display rule shows 'Overdue' when due_date < today CHANGES NEEDED: - Change 'due_date' field from date to date-time type - Update display format to show both date and time (e.g., 'Oct 15, 2025 at 2:30 PM') - Update overdue logic to compare date-time, not just date SCREENS TO UPDATE: - Task list screen: Show date-time format - Task detail screen: Show date-time format - Task create form: Use date-time picker instead of date picker - Task edit form: Use date-time picker - Overdue filter: Use date-time comparison KEEP UNCHANGED: - All other task fields - Sorting by due date (should work with date-time) - All other display rules and permissions - Task creation/editing workflow MIGRATION NOTE: Default time to 11:59 PM for existing tasks that only have dates." ``` **Example 2 - Change UI Layout**: ``` "Change the task list from table layout to card layout: CURRENT STATE: - Task list displays in table format with columns: Title, Assignee, Due Date, Status, Priority - Sorting and filtering work with current table - Mobile responsive but cramped on small screens CHANGES NEEDED: - Convert to card layout where each task is a card - Each card shows: - Title (large, bold text) - Assignee with avatar (top right) - Due date with calendar icon - Status as colored badge - Priority as colored border or corner flag - Cards arranged in responsive grid (3 columns desktop, 2 tablet, 1 mobile) KEEP UNCHANGED: - All existing search, sort, and filter functionality - Same data displayed, just different layout - Click behavior (click card to open task detail) - All permissions and display rules - Task creation and editing workflows RESPONSIVE BEHAVIOR: - Desktop: 3 cards per row - Tablet: 2 cards per row - Mobile: 1 card per row, full width" ``` **Example 3 - Change Validation Rules**: ``` "Update task validation to be more strict: CURRENT STATE: - Title field: required, no length limit - Description field: optional, no length limit - Due date field: optional - Assignee field: optional CHANGES NEEDED: - Title field: required, max 100 characters, show character count - Description field: optional, max 1000 characters, show character count - Due date field: required (cannot create task without due date) - Assignee field: required (cannot create unassigned tasks) VALIDATION DISPLAY: - Show character count below title and description fields - Show red text when approaching limit (90+ characters for title, 950+ for description) - Show clear error messages for required fields: 'Title is required', 'Due date is required', etc. - Disable submit button until all validation passes EXISTING DATA: - Existing tasks that don't meet new rules should continue to work - Only enforce new validation on new tasks and when editing existing tasks - Provide migration prompt for existing tasks with missing required data KEEP UNCHANGED: - All other task functionality - Display and permission rules - Task list and detail screens (just forms affected)" ``` **Risks and mitigation strategies**: | Risk | Mitigation Strategy | | -------------------------------- | ---------------------------------------------- | | **Breaking existing data** | Test with real data, plan migration carefully | | **Affecting unrelated features** | List all places feature is used, test each one | | **User confusion from changes** | Document changes, consider gradual rollout | | **Performance degradation** | Test with realistic data volumes | | **Lost functionality** | Explicitly specify what should stay the same | **When to choose modification approach**: * Existing feature has fundamental issues that need fixing * User feedback indicates current implementation is confusing * Business requirements have changed * Performance or usability improvements needed * Compliance or security updates required ### 3. Removal Changes **What it is**: Deleting features or components **Examples**: * Remove a screen * Delete a field * Remove a feature * Deprecate a workflow **Strategy**: Highest risk due to dependencies **Approach**: 1. Identify all places using the feature 2. Remove references before removing feature 3. Consider cascading deletes 4. Test that nothing breaks **Better**: Often better to hide/disable than delete ### 4. Restructuring Changes **What it is**: Reorganizing without changing behavior **Examples**: * Rename Datatables * Reorganize navigation * Restructure data relationships * Change screen layouts **Strategy**: High risk of subtle breakage **Approach**: 1. Use Buzzy's visual editor for careful changes 2. Test after each step 3. Use AI for consistent renaming across app 4. Verify all references in Data and Design tabs updated ## Change Strategies ### Strategy 1: Surgical Precision **When to use**: Small, isolated changes **How**: 1. Identify the exact location of change 2. Make minimal modification 3. Verify change 4. Stop **Example Buzzy prompt**: "On the task detail screen, change the 'Mark Complete' button color to green and the text to 'Complete Task'" **Advantages**: * Fast * Low risk * Easy to verify * Easy to undo **Disadvantages**: * Not suitable for widespread changes * Can miss related updates needed ### Strategy 2: Iterative Expansion **When to use**: Adding related features over time **How**: 1. Add simplest version first 2. Test and refine 3. Add next layer of complexity 4. Repeat **Example**: ``` Iteration 1: "Add basic comments to tasks - just content and author" Test Iteration 2: "Add edit/delete buttons for comment authors" Test Iteration 3: "Add threading so comments can reply to comments" Test ``` **Advantages**: * Control complexity * Easy to test incrementally * Can stop when "good enough" * Learn as you go **Disadvantages**: * Takes longer * Need to maintain context between iterations ### Strategy 3: Parallel Development **When to use**: Major feature additions **How**: 1. Build new feature separately 2. Test thoroughly in isolation 3. Integrate with main app 4. Enable progressively **Example**: ``` Step 1: Build entire messaging system separately Step 2: Test messaging thoroughly Step 3: Add link from main app to messaging Step 4: Enable for beta users Step 5: Enable for all users ``` **Advantages**: * Can develop without breaking main app * Easier testing * Can abandon if needed * Controlled rollout **Disadvantages**: * More upfront work * Integration can be tricky * Potential consistency issues ### Strategy 4: Replace Not Modify **When to use**: Major changes to existing features **How**: 1. Build new version alongside old 2. Test new version 3. Switch over 4. Remove old version **Example**: ``` Problem: Current search is too slow Approach: Build new search with different algorithm Deploy: Add feature flag to switch between old/new Test: Verify new search works Switch: Enable for all users Clean up: Remove old search code ``` **Advantages**: * Can compare old vs new * Easy rollback * No downtime * Safe **Disadvantages**: * Maintain two versions temporarily * More complex deployment ## Best Practices for Changes ### 1. Understand Current State First Before changing anything: **Review**: * How does it currently work? * What will be affected? * Are there dependencies? **Test**: * Verify current behavior * Document current state * Capture before screenshots **Don't**: Start changing without understanding current implementation ### 2. Start with Clear Requirements **Define**: * What exactly needs to change? * What's the expected result? * What shouldn't change? **Document**: * Write down the change clearly * Note any assumptions * List success criteria **Bad**: "Make the form better" **Good**: "Add real-time validation to email field showing 'Invalid email format' immediately when user types an invalid email, similar to how password validation currently works" ### 3. Make One Change at a Time **Don't**: Try to fix multiple things in one prompt **Do**: * Change one thing * Test it * Move to next change **Why**: * Easier to debug if something breaks * Clearer cause and effect * Can roll back individually ### 4. Test Immediately **After every change**: * Test the changed feature * Test related features * Check for regressions * Verify data integrity **Don't wait**: Testing later makes it hard to identify which change caused issues ### 5. Keep Context Explicit **In your prompts, include**: * What exists currently * What you're changing * What should remain the same **Example**: "In the Tasks datatable (which currently has title, description, status, assignee, due\_date), add a 'priority' selectlist field with options: Low, Medium, High, Urgent. Don't change any existing fields. Display priority on the task list as a colored badge." ### 6. Document as You Go **Keep notes on**: * Changes made * Reasons for changes * Issues encountered * Workarounds used **Why**: Essential for future maintenance and debugging ### 7. Use Buzzy's Version Control **Before major changes**: * Save current version in Buzzy's Versions tab * Use descriptive version name * Document what's working **After successful changes**: * Save new version with clear description * Keep stable versions for rollback **See**: [Rollback Strategies](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/rollback-strategies) ## Handling Cascading Changes Some changes affect multiple parts: ### Example: Renaming an Entity **Scenario**: Rename "Projects" datatable to "Workspaces" **Affected areas in Buzzy**: * Datatable name in Data tab * All screen references in Design tab * Navigation menu * Form labels and field names * Related datatable references (Linked Fields, Subtables) * Display rules and actions **Strategy**: 1. List all affected areas first 2. Use Buzzy AI for consistent renaming: "Rename the Projects datatable to Workspaces throughout the application, including all screen labels, navigation, and field references" 3. Review changes in Data and Design tabs 4. Test all features that touched Projects/Workspaces 5. Test in preview mode ### Example: Changing Data Structure **Scenario**: Split "due\_date" into "start\_date" and "end\_date" **Affected areas in Buzzy**: * Datatable fields in Data tab * Forms (create/edit screens) * Display views (list, detail screens) * Sort fields * Filter fields * Date-based formulas (JSONATA) * Display rules using due\_date **Strategy**: 1. Add new fields first (don't remove old yet) in Data tab 2. Manually update existing records with data 3. Update forms to use new fields in Design tab 4. Update display screens 5. Update formulas and display rules 6. Test everything thoroughly in preview mode 7. Remove old field last {% hint style="danger" %} **Critical**: For data structure changes, always test with real data. Back up important data before major changes. {% endhint %} ## Common Change Scenarios ### Adding Validation **Bad approach**: "Add validation" **Good Buzzy approach**: "Add validation to the task creation form: * Title field: Mark as Required, set max length 100 characters * Description field: Optional, set max length 1000 characters * Due date field: Mark as Required, add display rule to show error if date is in the past * Assignee field: Mark as Required, must be valid user from Users datatable Show validation errors in red text below each field. Use condition field to disable submit button until all required fields are filled." ### Changing UI Layout **Bad approach**: "Make it look better" **Good Buzzy approach**: "Change task list screen from table layout to card layout. Each card should show: * Title field (large, bold text) * Assignee field with avatar (top right) * Status field as colored badge * Due date field with calendar icon * Description field preview (first 100 chars using JSONATA substring) Use Buzzy's responsive layout: 2 columns on desktop, 1 column on mobile, with standard card spacing." ### Adding Permission Rules **Bad approach**: "Add permissions" **Good Buzzy approach**: "Add these server-level permission rules to Tasks datatable: * Admins: Full access - no Viewers field restrictions * Team Members: Can create tasks, view all team tasks (add to Viewers field), edit/delete only their own (use display rules: owner = current\_user) * Viewers: Add to Viewers field for read-only access Use display rules to show/hide action buttons based on user.highestRole and owner field. For users without permission, hide buttons using condition fields." ## When Changes Go Wrong ### Recovery Steps **1. Stop making changes**: Don't try to "fix" with more changes **2. Assess damage**: * What broke? * What still works? * What data is affected? **3. Review recent changes**: * What did you change? * What was the prompt? * What was the result? **4. Decide recovery approach**: * Option A: Fix the specific issue using visual editor or targeted AI prompt * Option B: Rollback using Buzzy's Versions tab (see [Rollback Strategies](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/rollback-strategies)) * Option C: Restore from saved version **5. Prevent recurrence**: * Understand what went wrong * Improve change process * Add safeguards ### Prevention Better Than Cure **Before making changes**: * [ ] Saved current version in Buzzy's Versions tab * [ ] Understood current data model and screens * [ ] Planned the change clearly * [ ] Considered effects on related Datatables and screens * [ ] Ready to test in preview mode immediately ## Change Request Templates ### Template: Adding Feature ``` Add [feature name] to Buzzy app with the following: Datatables & Fields: - [Datatable names and field specifications] - [Relationships: Subtables for 1:M, Linked Fields for N:M] Screens: - [Screen names and layouts] - [Forms and display components] Display Rules & Actions: - [Conditional logic using JSONATA] - [Actions: submit, navigation, CRUD operations] Security: - [Viewers field usage] - [Role-based display rules] Integration: - [How it connects to existing Datatables and screens] Success Criteria: - [How to verify it works in preview mode] ``` ### Template: Modifying Feature ``` Modify [feature name] in Buzzy: Current Behavior: - [what it does now in Data and Design tabs] Desired Behavior: - [what it should do] Keep Unchanged: - [what should stay the same] Affected Areas in Buzzy: - [Datatables/fields/screens that might be impacted] - [Display rules and actions that reference this] Testing: - [How to verify change works in preview mode] ``` ## Next Steps * **Something broke**: [Rollback Strategies](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/rollback-strategies) * **Deciding how to make changes**: [AI vs Manual Edits](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/ai-vs-manual-edits) * **Ready to test changes**: [Testing Approaches](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/testing-approaches) {% hint style="success" %} **Remember**: Successful changes come from clear requirements, careful implementation, and immediate testing. Rush any of these and you'll spend more time fixing than if you'd been careful initially. {% endhint %} # Rollback Strategies Master when and how to restore previous versions of your Buzzy app safely. Learn rollback strategies that prevent disaster and maintain confidence while building. ## Why Rollback Matters When building with Buzzy AI or Builder MCP, things sometimes don't go as planned. Being able to safely undo changes is crucial for confident development. **Non-technical explanation**: Think of rollback like a time machine for your app. Just as you might save different versions of a Word document before making major edits, Buzzy's version control lets you jump back to any previous working state of your app if changes go wrong. **Common scenarios requiring rollback**: * A Buzzy AI prompt or Builder MCP pass causes unexpected changes to your app structure * New features accidentally break existing functionality * Performance degrades after adding features * Data model changes create cascading issues * You realize your approach was fundamentally flawed * Deadline pressure requires reverting to last stable version **Why rollback capability is essential**: ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%% graph TD A[Confident
Experimentation] --> B[Try New Approaches] B --> C{Does it work?} C -->|Yes| D[Keep Changes] C -->|No| E[Rollback Instantly] E --> A style A fill:#6c6,stroke:#333,color:#000 style D fill:#6c6,stroke:#333,color:#000 style E fill:#f88,stroke:#333,color:#000 ``` **With good rollback strategy**: * ✅ Experiment fearlessly knowing you can undo * ✅ Try ambitious features without risk * ✅ Quickly recover from mistakes * ✅ Maintain stable versions for production * ✅ Test changes without fear of permanent damage **Without rollback strategy**: * ❌ Fear of making changes * ❌ Stuck with broken versions * ❌ Wasted hours trying to fix forward * ❌ Lost work from catastrophic changes * ❌ Stress and anxiety during development ## When to Rollback Making the right decision about whether to rollback or fix forward is critical. Here's a clear decision framework: ### Decision Framework: Rollback vs Fix Forward ```mermaid graph TD A[Change Caused Issues] --> B{App Still
Functional?} B -->|No - Broken| C[🔴 ROLLBACK NOW] B -->|Yes - Has Issues| D{Can Fix in
< 30 mins?} D -->|Yes| E[🟢 FIX FORWARD] D -->|No| F{Understand
What Broke?} F -->|Yes| G{Worth the
Fix Effort?} F -->|No| C G -->|Yes| E G -->|No| C ``` ### Clear Rollback Situations **1. 🔴 Breaking Changes - ROLLBACK IMMEDIATELY** **Critical failures**: * App won't load in preview mode at all * Database/Datatable structure is corrupted * Critical security vulnerability (e.g., Viewers fields accidentally removed) * Data loss or corruption occurred * Multiple core features stopped working simultaneously **Action**: Stop everything. Go to Versions tab. Restore immediately. Don't try to fix. **Example scenario**: ``` You prompted: "Reorganize all Datatables" Result: App won't load, seeing errors everywhere Decision: ROLLBACK - trying to fix would take hours ``` **2. 🟡 Can't Fix Forward - ROLLBACK AND REASSESS** **When you're stuck**: * Tried 3+ different AI prompts, issues getting worse * Don't understand what Buzzy AI changed in the Data or Design tabs * Fix would require rebuilding 5+ screens or restructuring Datatables * Deadline is tomorrow, need working version now * Each attempted fix creates new problems **Action**: Rollback to last stable version. Take a break. Reassess your approach with fresh eyes. **Example scenario**: ``` Attempt 1: "Fix the navigation" - made it worse Attempt 2: "Undo that and fix properly" - still broken Attempt 3: "Reset navigation to default" - now homepage broken too Decision: ROLLBACK - you're digging deeper into a hole ``` **3. 🟠 Wrong Direction - ROLLBACK AND RESTART** **Strategic pivots**: * Realized data model approach is fundamentally flawed (e.g., should have used Subtables not Linked Fields) * Requirements changed significantly mid-development * App structure became over-complicated, simpler approach exists * Prototype revealed better way to organize features * Stakeholder feedback requires major architectural change **Action**: Rollback to before the wrong path. Document lessons learned. Start fresh with new approach. **Example scenario**: ``` You built: Complex many-to-many relationships with 3 linking tables Realized: Simple 1-to-many Subtables would work better and be clearer Decision: ROLLBACK - rebuild with better structure is faster than refactoring ``` ### Don't Rollback When - Fix Forward Instead **1. 🟢 Minor Issues - EASY TO FIX** **Fixable problems**: * Small bugs that are easy to fix (typo, wrong field displayed) * Cosmetic problems (colors, spacing, alignment) * Non-critical features not working perfectly * Issues you understand and can fix with targeted prompt or manual edit **Action**: Fix forward with specific prompt or use visual editor **Example scenario**: ``` Issue: Button says "Submitt" instead of "Submit" Decision: FIX FORWARD - 30 second fix, not worth rollback ``` **2. 🟢 Almost There - 90% WORKING** **Near-success situations**: * 90% of the feature works correctly * Issue is well-understood and isolated * Fix is straightforward and low-risk * Already invested significant time and most changes are good **Action**: Complete the fix. Don't waste good progress. **Example scenario**: ``` Built: Entire task management system with 8 screens Issue: Delete button missing on task detail screen Decision: FIX FORWARD - add the button, don't throw away 8 working screens ``` **3. 🟢 Learning Opportunity - VALUABLE DEBUGGING** **Educational situations**: * Debugging will teach you important lessons about Buzzy * Issue reveals a design flaw you need to understand and fix permanently * Problem is interesting and worth solving * Understanding this will help you avoid it in future **Action**: Fix and document your learnings for future reference **Example scenario**: ``` Issue: Display rule not hiding field as expected Insight: Learning JSONATA syntax and display rule logic Decision: FIX FORWARD - this knowledge will be valuable for all future work ``` ### Quick Decision Checklist Before deciding, ask yourself: * [ ] **Can the app still function?** (No = Rollback) * [ ] **Do I understand what went wrong?** (No = Rollback) * [ ] **Can I fix it in under 30 minutes?** (No = Consider rollback) * [ ] **Is most of my work still good?** (Yes = Fix forward) * [ ] **Will fixing teach me something valuable?** (Yes = Fix forward) * [ ] **Is this the 3rd+ failed fix attempt?** (Yes = Rollback) * [ ] **Do I have a deadline soon?** (Yes = Rollback to stable) ## Rollback Methods ### Primary Method: Buzzy's Built-in Version Control **What it is**: Buzzy Workspace has built-in version control in the Versions tab. Every significant change automatically creates a restore point. **Non-technical explanation**: It's like the "Undo" history in Photoshop or the version history in Google Docs—but for your entire app. You can see a list of all previous versions and jump back to any one with a single click. **Visual walkthrough**: ``` Buzzy Workspace → Your App ┌─────────────────────────────────────────────┐ │ Tabs: [Data] [Design] [Publish] [Versions] │ ← Click Versions └─────────────────────────────────────────────┘ Versions Tab: ┌────────────────────────────────────────────────────────────┐ │ Current Version: v1.5 - Added comments feature │ │ │ │ ⏱️ Version History: │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ v1.5 - Added comments feature Oct 7, 2:30 PM │ │ │ │ v1.4 - Task filtering working Oct 7, 1:15 PM │ │ │ │ v1.3 - Before navigation redesign Oct 7, 11:00AM │ │ │ │ v1.2 - Stable version - all tests pass Oct 6, 4:00 PM │ │ │ │ v1.1 - Initial task management Oct 6, 2:30 PM │ │ │ └────────────────────────────────────────────────────────┘ │ │ │ │ Select version → [Restore] [Preview] [Delete] │ └────────────────────────────────────────────────────────────┘ ``` **Step-by-step restore process**: 1. **Open your app in Buzzy Workspace** 2. **Click the Versions tab** (top navigation) 3. **Review version history** - Each entry shows description and timestamp 4. **Select the version** you want to restore (click to highlight) 5. **Preview if unsure** - See what that version looked like before restoring 6. **Click "Restore"** button 7. **Confirm** - Buzzy asks "Are you sure? This will revert to \[version]" 8. **Done** - App instantly returns to that version state **What gets restored**: * ✅ All Datatables and field definitions (Data tab) * ✅ All screens and layouts (Design tab) * ✅ Display rules and JSONATA formulas * ✅ Navigation structure * ✅ Buzzy Functions code * ✅ Constants and configuration * ✅ Security settings (Viewers, Team Viewers) **What doesn't get restored**: * ❌ Actual data records in your Datatables (user data is preserved) * ❌ Published app versions (those remain published) * ❌ External integrations or API keys (Constants are preserved) **Advantages of Buzzy's version control**: * **No setup required**: Built into Buzzy, always on * **Visual interface**: No command-line or Git knowledge needed * **One-click restore**: Instant rollback, no complex procedures * **Complete snapshots**: Entire app state saved, not just code files * **No merge conflicts**: Unlike Git, never deal with conflicting changes * **Automatic saves**: Buzzy creates snapshots at key moments * **Safe experimentation**: Try anything, knowing you can always undo **When to use**: For ALL Buzzy app structure changes. This is your primary and preferred rollback method. **See**: [Getting Started Guide (v3)](/getting-started-with-buzzy/new-buzzy-ai-v3) for detailed version control documentation {% hint style="success" %} **Buzzy Advantage**: Unlike traditional code projects that require Git expertise, branching strategies, and command-line tools, Buzzy's version control is: * Built-in and always available * Visual and intuitive * Designed specifically for no-code app development * Free from merge conflicts and complex workflows * Accessible to non-technical users You focus on building; Buzzy handles versioning complexity. {% endhint %} ### Secondary Considerations **For Buzzy Functions code**: If you're writing custom server-side code using Buzzy Functions (AWS Lambda), you may optionally use Git to track those specific JavaScript files separately. However, the Buzzy workspace still versions your Functions alongside your app structure, so Git is optional even for Functions. **For collaborative team workflows**: Buzzy's Versions tab works seamlessly for team collaboration: * Multiple team members can work on the same app * Each save creates a new version with user attribution * No branch management or merge conflicts * Simple restore process for any team member * Clear version history showing who changed what and when **Data backup separate from versions**: Remember that Buzzy versions save your app structure (Datatables definitions, screens, logic), not the data itself. For backing up actual data records: * Export data from Datatables as needed * Buzzy's infrastructure provides automatic data backups * Important: Test your rollback process to understand what gets preserved ## Rollback Best Practices in Buzzy ### 1. Save Versions Regularly **Rule of thumb**: * After each feature works in preview mode * Before starting major AI prompts or changes * End of each work session * Before experimenting with new approaches **Don't**: * Work for hours without saving a version * Wait until "perfect" * Only save "big milestones" **How to save**: Go to Versions tab → Save current state with descriptive note ### 2. Use Descriptive Version Notes **Bad version notes**: * "Update" * "Changes" * "Fix" * "Testing" **Good version notes**: * "Working authentication with Organizations" * "Task filtering by status and assignee implemented" * "Before adding payment integration" * "Stable version before navigation redesign" **Why**: Makes it easy to find the right version to restore ### 3. Mark Stable Versions Clearly **In Buzzy Versions tab**: Use clear naming conventions **Examples**: * "v1.0 - First stable production version" * "Before major data model refactor" * "Last working version before adding API integration" * "Stable - all tests passing" **Why**: Easy to find "known good" versions quickly when you need to rollback ### 4. Test Before Saving Versions **Before saving a version in Buzzy**: * [ ] App loads in preview mode without errors * [ ] Core features work correctly * [ ] No obvious issues introduced * [ ] Data integrity maintained in Datatables * [ ] Display rules and actions work correctly **Why**: Ensures you're saving a genuinely working state ### 5. Keep Version Save Points Close **Good frequency**: * Save version every 30-60 minutes of work * After each complete feature * Before and after major AI prompts **Too infrequent**: * Daily versions only * Only major milestones * Waiting for "done" **Why**: Rollback loses less work if you save versions frequently ## Selective Rollback in Buzzy Sometimes you don't want to rollback your entire app: ### Approach 1: Manual Copy from Previous Version **In Buzzy**: 1. Open your current app 2. Open a previous version (view-only) 3. Manually recreate specific screens or Datatables from the previous version 4. Copy display rules, actions, or field configurations **When**: Only part of your changes broke something (e.g., one screen layout issue) **Limitation**: Buzzy doesn't support restoring individual components, so you'll need to manually recreate them ### Approach 2: Isolate Experiments **Workflow for risky changes**: 1. Save a stable version with clear note: "Before experiment" 2. Make risky changes with AI prompts 3. Test thoroughly in preview mode 4. If it works: Save new version "Experiment successful" 5. If it fails: Restore "Before experiment" version **When**: Experimenting with major data model or navigation changes ### Approach 3: Use Display Rules as "Feature Flags" **Concept**: Features exist but are conditionally shown **In Buzzy**: * Create display rules that hide/show features based on user role or data * Can enable for testing users only * Easy "rollback" by changing display rule **Example**: * New search feature controlled by display rule * Show only to admin users initially * If it works, enable for all users * If it fails, disable via display rule (no rollback needed) **When**: Rolling out risky new features to production ## After Rolling Back ### 1. Understand What Went Wrong **Questions to ask**: * What was I trying to accomplish? * What AI prompt did I use or what manual changes did I make? * What specifically broke (screens, Datatables, relationships)? * Why did it break (data model issue, display rule problem, etc.)? **Don't**: Immediately try the same AI prompt again ### 2. Plan Different Approach **Based on what you learned**: * Break change into smaller steps? * Use different method? * Seek expert help? * Simplify requirements? ### 3. Document the Failure **Keep notes on**: * What you tried * Why it failed * What you learned * What to try next **Why**: Avoid repeating same mistakes ### 4. Consider If You Need the Change **Honestly assess**: * Is this feature necessary? * Is it worth the complexity? * Is there a simpler alternative? * Can it wait? **Sometimes**: The best answer is "don't build it" ## Common Rollback Scenarios in Buzzy ### Scenario 1: AI Prompt Cascade Failure **What happened**: * Used one AI prompt * It created unexpected changes in app structure * Tried to fix with another prompt * Made it worse * Multiple prompts later, app is very broken **Solution**: 1. Use Buzzy's Versions tab to rollback to before first prompt 2. Review what you were trying to accomplish 3. Write more specific, targeted AI prompt 4. Test in preview mode immediately ### Scenario 2: Data Model Change Gone Wrong **What happened**: * Changed Datatable structure (e.g., removed Subtable, changed Linked Field) * Data relationships broke * Screens stopped displaying data correctly * Features stopped working **Solution**: 1. Use Versions tab to rollback immediately 2. Review the data model change needed 3. Plan Datatable changes more carefully (sketch it first) 4. Consider if you need to export/migrate any critical data 5. Make changes incrementally, test after each step **Critical**: Always save a version before major Datatable structure changes ### Scenario 3: Screen Refactoring Regret **What happened**: * Asked AI to redesign navigation or screens * AI changed more than intended * Some screens broken or missing * Display rules not working correctly **Solution**: 1. Assess if easier to rollback or fix manually in Design tab 2. If mostly working: fix remaining issues in visual editor 3. If substantially broken: rollback using Versions tab 4. Next time: be more specific in AI prompts about scope ### Scenario 4: Performance Degradation **What happened**: * Added new feature (e.g., complex display rules, many Linked Fields) * App became slow to load * Preview mode showing delays **Solution**: 1. Identify what changed (check recent versions) 2. Test performance in live mode vs preview 3. If feature is critical: optimize (simplify display rules, reduce data loading) 4. If not critical: rollback to previous version, optimize separately 5. Consider simpler implementation approach ## Preventing Need for Rollback **Better than rolling back is not needing to**: ### 1. Make Changes Incrementally Small AI prompts and manual edits are easier to verify and fix ### 2. Test Immediately in Preview Mode Catch issues before doing more work ### 3. Understand Before Changing Know what app structure you're modifying and why ### 4. Save Versions Before Experiments Keep stable versions safe ### 5. Write Clear, Specific AI Prompts Vague prompts lead to unpredictable results ### 6. Review AI Changes in Data and Design Tabs Don't blindly accept generated app structures - review Datatables, screens, and relationships ## Quick Decision Guide ``` Something broke in your Buzzy app: | ├─ Can you fix it in < 15 minutes (using visual editor or quick AI prompt)? │ └─ YES → Fix it │ └─ NO → Continue... │ ├─ Is it critical (app won't load / data model broken / security issue)? │ └─ YES → Use Versions tab to rollback immediately │ └─ NO → Continue... │ ├─ Do you understand what's wrong (which Datatable, screen, or rule)? │ └─ YES → Try fixing in visual editor or with targeted AI prompt │ └─ NO → Use Versions tab to rollback, analyze, try again │ ├─ Is deadline pressure high? │ └─ YES → Rollback to stable version using Versions tab │ └─ NO → Consider debugging as learning │ └─ When in doubt → Rollback using Versions tab (better safe than sorry) ``` ## Next Steps * **Preventing issues**: [Making Changes Effectively](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/making-changes) * **Testing to catch problems early**: [Testing Approaches](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/testing-approaches) * **Deciding when to use AI**: [AI vs Manual Edits](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/ai-vs-manual-edits) {% hint style="success" %} **Remember**: Rolling back isn't failure—it's smart risk management. With Buzzy's built-in Versions tab, rollback is simple and fast. Save versions often, test changes immediately, and don't hesitate to restore when things don't work out. {% endhint %} # Testing Approaches Master strategic testing approaches for Buzzy applications. Learn how to test efficiently without burning out while maintaining app quality. ## The Testing Challenge Testing is crucial but exhausting. With Buzzy AI and Builder MCP, you can create app structure quickly, but you still need a disciplined review loop. **Non-technical explanation**: Testing your Buzzy app is like proofreading a book. You could read every single word 10 times and still miss typos (exhaustive testing), or you could focus on the most important chapters and scan the rest (strategic testing). The key is knowing what to focus on. **The AI-assisted build testing dilemma**: ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%% graph TD A[Buzzy AI Generates
App Fast] --> B[Excitement:
'Let's test everything!'] B --> C[Reality:
Testing takes forever] C --> D[Impatience:
'Good enough...'] D --> E[Issues slip through] E --> F[User complaints] F --> G[Emergency fixes] G --> H[More testing needed] H --> C ``` **The core problem**: * **Speed mismatch**: AI-assisted building can generate in minutes, testing takes hours * **Generation addiction**: Easy to generate new features, boring to test existing ones * **Over-confidence**: "The AI generated it, it must work perfectly" * **Perfectionism**: Trying to test every possible scenario * **Testing fatigue**: Repetitive testing becomes mind-numbing **The solution**: Test strategically, not exhaustively. Focus your limited testing time on what matters most. ## Understanding Testing Fatigue ### What Is Testing Fatigue? **Testing fatigue** is when you get mentally exhausted from testing and start cutting corners, leading to a downward spiral. **The classic testing fatigue cycle**: ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%% graph TD A[Generate with Buzzy AI
⚡ Fast & Exciting] --> B[Start Testing
🔍 Thorough & Careful] B --> C[Testing Takes Forever
⏰ Slower than Expected] C --> D[Get Impatient
😤 'This is taking too long'] D --> E[Test Less Carefully
📋 Skip edge cases] E --> F[Miss Critical Issues
🐛 Bugs slip through] F --> G[Issues Cause Problems
📞 Users complain] G --> H[Emergency Fixes Needed
🚨 Stress & rush] H --> I[Even More Testing Required
😫 Worse fatigue] I --> C ``` **Why testing fatigue happens**: * **Speed addiction**: Buzzy AI makes building feel instant, testing feels slow by comparison * **Boredom factor**: Repetitive testing is less exciting than creating new features * **Pressure to launch**: External deadlines or internal impatience to "be done" * **AI over-confidence**: "The AI generated it, so it probably got it right" * **Complexity underestimation**: "It's just a simple app, what could go wrong?" * **Sunk cost fallacy**: "I've spent so much time building, I can't spend more time testing" **Real-world testing fatigue warning signs**: * ⚠️ Thinking "I'll just test this quickly" for complex features * ⚠️ Skipping mobile testing because "it probably works" * ⚠️ Not testing with realistic data ("Lorem ipsum is fine") * ⚠️ Avoiding edge cases ("Users won't do that anyway") * ⚠️ Publishing before thoroughly testing user permissions * ⚠️ Making multiple changes before testing any of them ### The Cost of Skipping Tests **Immediate consequences**: * Issues reach real users (embarrassing and damaging) * Data corruption or loss (potentially irreversible) * Security vulnerabilities (serious business risk) * User frustration and lost trust (hard to recover) * Emergency fixing under pressure (stressful and error-prone) **Hidden costs**: * **Time amplification**: 1 hour of testing prevents 5 hours of fixing * **Context switching**: Fixing interrupts new development work * **Quality debt**: Quick fixes create more issues * **Team demoralization**: Constant firefighting is exhausting * **Opportunity cost**: Time fixing could have been spent on new features **Mathematical reality**: ``` Testing effort: 2 hours Bug prevention: ~80% of issues caught Total time saved: ~8 hours of fixing + user support Skipping testing: 0 hours upfront Issues encountered: ~5 critical bugs Time to fix + support: ~12 hours Net result: 10 hours wasted + user frustration ``` **Key insight**: Testing is always faster than fixing issues after they reach users. The question isn't whether to test, but how to test efficiently. ## Strategic Testing Approaches ### Approach 1: Risk-Based Testing **Concept**: Test what matters most. Like a doctor doing triage—treat the life-threatening issues first, then the important stuff, then the minor scrapes. **Risk assessment framework**: ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%% graph TD A[Feature to Test] --> B{Risk Assessment} B --> C[Critical: Test Thoroughly
🔴 High impact if broken] B --> D[Important: Test Normally
🟡 Medium impact if broken] B --> E[Low Priority: Test Lightly
🟢 Low impact if broken] C --> F[Exhaustive Testing
Multiple scenarios
Edge cases
Error conditions] D --> G[Standard Testing
Happy path
Common errors
Basic edge cases] E --> H[Smoke Testing
Basic functionality
No deep diving] ``` **Risk categories with Buzzy-specific examples**: **🔴 Critical (Test Thoroughly)**: * **User authentication & authorization**: Login, logout, password reset, permission systems * **Data security**: Viewers field restrictions, Team Viewers, role-based access * **Payment processing**: Buzzy Functions handling payments, API integrations * **Data integrity**: CRUD operations, Subtable relationships, Linked Table Fields * **Core business workflows**: The 2-3 main things your app does **🟡 Important (Test Normally)**: * **Primary user flows**: Main navigation paths users take * **Data entry & editing**: Forms, validation, saving, updating * **Search & filtering**: Finding information, sorting, filtering * **Notifications**: Email sending, in-app messages * **Basic integration**: Simple API calls, external services **🟢 Low Priority (Test Lightly)**: * **UI polish**: Animations, hover effects, styling details * **Nice-to-have features**: Optional enhancements, bonus functionality * **Admin-only features**: Tools only admins use occasionally * **Edge cases**: Unusual but non-critical scenarios * **Cosmetic issues**: Minor visual imperfections **Example - Task Management App Testing Matrix**: | Feature | Risk Level | Why | Testing Effort | | ------------------ | ------------ | -------------------------------- | ------------------------------------------- | | User login/logout | 🔴 Critical | Without this, app is unusable | 30 min: All scenarios, error cases | | Task creation | 🔴 Critical | Core app function | 20 min: Required fields, validation, saving | | Permission system | 🔴 Critical | Security vulnerability if broken | 25 min: All roles, unauthorized access | | Task editing | 🟡 Important | Users need this regularly | 15 min: Happy path, basic validation | | Search tasks | 🟡 Important | Finding tasks is important | 10 min: Basic search, filters | | Task list sorting | 🟡 Important | Users expect this to work | 5 min: Date, priority, status sorts | | Dark mode toggle | 🟢 Low | Nice but not essential | 2 min: Toggle works, doesn't break layout | | Task export to PDF | 🟢 Low | Rarely used feature | 3 min: Basic export works | | Hover animations | 🟢 Low | Pure visual enhancement | 1 min: Quick visual check | **Sample risk assessment questions**: **For any feature, ask**: 1. **Impact**: If this breaks, how badly does it affect users? 2. **Frequency**: How often do users use this feature? 3. **Recovery**: How easy is it to fix if it breaks in production? 4. **Dependencies**: How many other features depend on this working? 5. **Data risk**: Could this cause data loss or corruption? 6. **Security risk**: Could this expose sensitive information? **High risk score** = Critical testing **Medium risk score** = Important testing\ **Low risk score** = Light testing **Time allocation example for 2-hour testing session**: * 🔴 Critical features: 90 minutes (75%) * 🟡 Important features: 25 minutes (20%) * 🟢 Low priority features: 5 minutes (5%) This ensures you spend most time on what matters most. ### Approach 2: Critical Path Testing **Concept**: Test the main user journeys thoroughly **Steps**: **1. Identify critical paths**: * What are the 3-5 most important things users do? * What path do most users take? * What generates revenue or value? **2. Create test scenarios**: * Step-by-step user journey * Expected result at each step * What could go wrong? **3. Test critical paths every time**: * Before saving versions in Buzzy * After any modification * Before publishing **Example - Task Management App**: **Critical Path 1: Create and Assign Task**: 1. User logs in → Should see dashboard 2. Clicks "New Task" → Form appears 3. Fills title, description, assignee → Fields accept input 4. Clicks "Save" → Task created 5. Returns to list → New task visible 6. Assignee receives notification → Email or in-app notification sent **Critical Path 2: Complete Task**: 1. User views task list → Sees assigned tasks 2. Opens task detail → Shows full information 3. Clicks "Mark Complete" → Status updates 4. Returns to list → Task shows as complete 5. Owner receives notification → Completion notification sent ### Approach 3: Boundary Testing **Concept**: Test edge cases that AI often gets wrong **What to test**: **Empty States**: * What shows when no data exists? * Can you handle zero results? * Does the UI explain what to do? **Limit Cases**: * Maximum values (very long text, huge numbers) * Minimum values (zero, negative) * Exactly at boundaries (99 vs 100 characters) **Invalid Input**: * Wrong data types * Special characters * SQL injection attempts * Missing required fields **Permission Boundaries**: * What happens when user shouldn't have access? * Can users bypass restrictions? * Are admin features truly protected? **Data Relationships**: * What if related data is deleted? * Can you create orphaned records? * Are cascading updates handled? **Example tests**: ``` Task title field: - Empty title (should reject) - 1 character (should accept) - Exactly 100 characters (should accept if limit is 100) - 101 characters (should reject if limit is 100) - Special characters: - Emoji: 🚀 🎉 ✅ Due date: - Past date (should accept or reject based on business rules) - Today (should accept) - Future date (should accept) - Invalid date (Feb 30, should reject) - Null/blank (should reject if required) ``` ### Approach 4: Smoke Testing **Concept**: Quick tests to verify nothing is broken **When to use**: After every change, before deep testing **What to check** (5-10 minutes): * [ ] App loads without errors * [ ] User can log in * [ ] Main screens are accessible * [ ] No console errors * [ ] Critical features work at basic level **If smoke tests fail**: Don't proceed with deeper testing until fixed **If smoke tests pass**: Continue with focused testing ### Approach 5: Regression Testing **Concept**: Verify old features still work after changes **The challenge**: New features shouldn't break existing features **Strategy**: **Keep a test checklist**: ``` Core Features Checklist: - [ ] User login/logout - [ ] Create new item - [ ] Edit existing item - [ ] Delete item (with confirmation) - [ ] Search functionality - [ ] Filter/sort - [ ] Navigation between screens - [ ] Data saves correctly - [ ] Permissions work correctly ``` **Run after**: * Major changes * Refactoring * Before deployment **Time-saving**: Only test features that could be affected by your change ## Testing Workflow ### For Small Changes **1. Smoke test** (2 minutes): * App loads * No errors **2. Test the change** (5-10 minutes): * Does the changed feature work? * Try a few variations **3. Quick regression** (3-5 minutes): * Test features that could be affected **Total: 10-20 minutes** ### For New Features **1. Smoke test** (2 minutes): * Basic functionality **2. Happy path** (5 minutes): * Test main workflow **3. Boundary testing** (10 minutes): * Test edge cases **4. Error cases** (5 minutes): * Invalid input * Permission issues **5. Regression** (5 minutes): * Related features still work **Total: 25-30 minutes** ### For Major Changes **1. Full smoke test** (5 minutes): * All core features **2. Critical paths** (20 minutes): * Complete user journeys **3. New functionality** (30 minutes): * Thorough testing of changes **4. Boundary testing** (15 minutes): * Edge cases **5. Full regression** (20 minutes): * Run complete checklist **Total: 90 minutes** ## Preventing Testing Fatigue ### 1. Test as You Build **Don't**: Build everything, then test everything **Do**: Build one piece, test it, build next piece **Why**: * Catch issues when context is fresh * Prevent issue accumulation * Maintain momentum ### 2. Automate Repetitive Tests **What to automate**: * Login/logout flows * CRUD operations * Data validation * API endpoints **Tools for Buzzy apps**: * Use Buzzy's preview mode for rapid testing * Test in live mode for real-world scenarios * Document test procedures for reuse * Use browser dev tools if needed for debugging **Don't automate**: * Visual design validation (use your eyes) * UX quality (needs human judgment) * One-off tests ### 3. Use Test Data **Create realistic test data**: * Multiple users with different roles * Various data scenarios * Edge cases covered **Benefits**: * Faster testing (data already exists) * More thorough (covers more scenarios) * Repeatable (same data each time) **For Buzzy**: * Use Buzzy's data import feature to load test data * Create test records directly in Data tab * Use preview mode with test data before going live ### 4. Pair Testing **If working with others**: * Have someone else test your work * Fresh eyes catch different issues * Less fatigue when shared * Learn from each other ### 5. Take Breaks **When testing for extended periods**: * Take 5-minute break every 30 minutes * Fatigue leads to missed issues * Come back with fresh perspective ### 6. Focus on Value **Remember why you're testing**: * Protecting users * Maintaining quality * Saving time long-term * Building something you're proud of ## What NOT to Test **Don't waste time testing**: **1. Buzzy Core Engine Functionality**: * Don't test that Buzzy renders screens (it does) * Don't test that Datatables save data (they do) * Trust Buzzy's professionally maintained engine **Test instead**: Your app logic and data model design **2. Already-Working Features** (Unless Changed): * If login worked yesterday and you didn't touch it * Skip unless there's reason to suspect issues **3. Obvious Visual Issues**: * You can see the button is blue * Don't need formal test for color **Test instead**: That the button works when clicked **4. Every Possible Combination**: * Don't test all possible user inputs * Don't test every UI state combination **Test instead**: Representative samples and edge cases ## Testing Checklist Template Use this for each feature or release: ``` Feature: [Feature Name] Pre-Testing: - [ ] Reviewed Data and Design tabs - [ ] No obvious issues in preview mode - [ ] App loads without errors Happy Path: - [ ] Main user flow works end-to-end in preview mode - [ ] Success messages display correctly - [ ] Data saves and loads correctly in Datatables - [ ] Navigation works as expected Edge Cases: - [ ] Empty data state handled (display rules work) - [ ] Maximum length validation works - [ ] Required field validation works - [ ] Special characters handled correctly Permissions: - [ ] Correct features visible to each role (display rules) - [ ] Viewers field restrictions work at server level - [ ] Team Viewers field restrictions work - [ ] Display rules hide/show correctly by role Regression: - [ ] Existing features still work - [ ] No errors in preview or live mode - [ ] Data integrity maintained in Datatables Mobile: - [ ] Layout works on mobile screen (responsive design) - [ ] Touch interactions work - [ ] No horizontal scrolling issues - [ ] Mobile navigation works Issues Found: [Document any issues] Sign-off: [Date tested, who tested] ``` ## Dealing with Found Bugs ### When You Find an Issue **1. Document it immediately**: * What you did * What happened * What should have happened * How to reproduce in preview/live mode **2. Assess severity**: * Critical: Blocks use, data loss, security issue → Fix now * Important: Main feature broken → Fix soon * Minor: Cosmetic, rare edge case → Fix when convenient **3. Fix or defer**: * Critical/Important: Fix using visual editor or AI prompt before proceeding * Minor: Add to notes, continue testing **4. Retest after fix**: * Verify fix works in preview mode * Test in live mode if needed * Check for new issues introduced ### Bug Tracking **Simple approach** (small projects): * Keep a text file or document * List issues with status * Update as you fix **Example**: ``` # Issues ## Critical - [FIXED] Login fails with email containing + symbol - [FIXED] Delete action deletes wrong record ## Important - [OPEN] Search filter doesn't find partial matches - [FIXED] Mobile navigation doesn't close after selection ## Minor - [OPEN] Display rule not working perfectly on Firefox - [DEFERRED] Would be nice to have auto-save feature ``` ## Using Workspace Release Tests Buzzy Workspace includes [Release Tests](/getting-started-with-buzzy/new-buzzy-ai-v3/9.-release-tests) in the editor's **Tests** section. Use them to turn your most important manual checks into reusable smoke and regression tests. Good candidates for Release Tests: * login and account flows * the main create, edit, submit, or delete workflows * important navigation paths * permission-sensitive paths * key mobile or tablet flows that should not regress Release Tests can be created manually and recorded from supported preview interactions. AI-assisted options such as starter test generation and prompt-generated tests are shown as **Coming soon** in this workflow. Release Tests can run against Desktop, Tablet, or Mobile viewport targets, and their run history helps you see what passed or failed before publishing. Release Tests do not replace human testing. Use them for repeatable checks, then still review layout, copy, permissions, unusual data, and real user experience. ## Testing in Production **Even after thorough testing, monitor your published app**: **What to watch**: * User reports * Analytics (are users dropping off somewhere?) * Data patterns in Datatables * Feature usage **React quickly**: * Use Buzzy's Versions tab to rollback if needed * Can modify display rules to disable features temporarily * Communicate with users about issues **Learn and improve**: * What did testing miss? * How can you catch it next time? * Update test procedures ## Next Steps * **Preparing for launch**: [Deployment Guide](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/deployment) * **Long-term quality**: [Maintenance & Tech Debt](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/maintenance) * **If issues arise**: [Rollback Strategies](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/rollback-strategies) {% hint style="success" %} **Remember**: Perfect testing is impossible. Strategic testing is practical. Test the important things thoroughly in preview mode, test other things adequately, and publish with confidence. {% endhint %} # Deployment Guide Master the art of publishing your Buzzy application to production. Learn the complete deployment checklist, Buzzy's managed hosting, and app store publishing. ## Before You Publish Publishing in Buzzy isn't just clicking a button—it's ensuring your app is truly ready for real users. **Non-technical explanation**: Deploying your app is like opening a restaurant. You wouldn't just unlock the doors without first ensuring the kitchen works, the staff is trained, the menu is finalized, and health inspections pass. Similarly, your Buzzy app needs thorough verification before going live. **Why the pre-publish checklist matters**: ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%% graph TD A[Skip Checklist] --> B[Publish Hastily] B --> C[Users Find Issues] C --> D[Emergency Fixes] D --> E[Lost Trust] F[Follow Checklist] --> G[Publish Confidently] G --> H[Smooth Launch] H --> I[Happy Users] style A fill:#f88,stroke:#333,color:#000 style E fill:#f88,stroke:#333,color:#000 style F fill:#6c6,stroke:#333,color:#000 style I fill:#6c6,stroke:#333,color:#000 ``` ### Pre-Publishing Checklist Use this comprehensive checklist to ensure your Buzzy app is truly ready for production: **🧪 Testing (Critical - Don't Skip)**: * [ ] **Critical paths tested thoroughly**: Main user journeys work end-to-end in preview mode * [ ] **Edge cases handled**: Empty states, maximum values, invalid inputs all tested * [ ] **Mobile tested**: Responsive layout works on phones and tablets * [ ] **Desktop tested**: Full functionality on various screen sizes and browsers * [ ] **All user roles tested**: Admin, editor, viewer—each role sees correct features * [ ] **Performance verified**: App loads quickly, no lag when interacting * [ ] **Live mode tested**: Beyond preview, actually publish to test environment first **🔒 Security (Absolutely Critical)**: * [ ] **No credentials exposed**: Double-check Buzzy Functions don't have hardcoded API keys or passwords * [ ] **Constants properly used**: All secrets stored in encrypted Buzzy Constants, accessed via BUZZYCONSTANTS() * [ ] **Authentication works**: Login, logout, password reset all functional * [ ] **Viewers fields configured**: Server-level security in place for sensitive Datatables * [ ] **Team Viewers set up**: If using Organizations/Teams, permissions configured correctly * [ ] **Field validation works**: Required fields enforced, data types validated * [ ] **Display rules tested**: Users only see what they should see based on role/ownership * [ ] **Permission boundaries checked**: Users can't access unauthorized data or actions **💾 Data Quality**: * [ ] **Production data ready**: Real data loaded (not Lorem ipsum placeholders) * [ ] **Test data removed**: All dummy records deleted from Datatables * [ ] **Data relationships verified**: Subtables and Linked Table Fields work correctly * [ ] **Backup created**: Important data exported/backed up before going live * [ ] **Data migration tested**: If importing data, test the import process thoroughly **✍️ Content Polish**: * [ ] **Placeholder content replaced**: No "Your text here" or "Lorem ipsum" remaining * [ ] **Images optimized**: Photos compressed for web, appropriate file sizes * [ ] **Text proofread**: No typos, grammar checked, messaging clear * [ ] **Branding consistent**: Logo, colors, fonts match your brand identity * [ ] **Error messages clear**: User-friendly error messages, not technical jargon * [ ] **Help text added**: Tooltips and instructions where users might need guidance **⚖️ Legal & Compliance**: * [ ] **Terms of Service**: Legal terms page created and linked * [ ] **Privacy Policy**: Privacy policy written and accessible * [ ] **Cookie consent**: Cookie banner if collecting analytics or using cookies * [ ] **GDPR compliance**: If applicable, data handling follows regulations * [ ] **Age restrictions**: If needed, age gate or parental consent flows * [ ] **Accessibility**: Basic accessibility standards met (alt text, keyboard navigation) **📊 Monitoring & Analytics** (Optional but Recommended): * [ ] **Analytics configured**: If using Google Analytics or similar, tracking code added * [ ] **Error logging**: Plan for capturing and reviewing errors * [ ] **User feedback mechanism**: Way for users to report issues or provide feedback * [ ] **Performance monitoring**: Basic tracking of app load times and responsiveness **🚀 Launch Preparation**: * [ ] **Launch plan documented**: Know exactly what happens at go-live * [ ] **Support plan ready**: Who handles user questions? How? * [ ] **Rollback plan**: Know how to quickly revert if major issues discovered * [ ] **Announcement ready**: Communications prepared for users/customers * [ ] **Documentation available**: User guides or help content accessible **Verification timeline recommendation**: ``` 3 days before launch: - Complete functional testing - Verify security and permissions - Remove test data, add production data 2 days before launch: - Content polish and proofreading - Legal pages in place - Performance testing 1 day before launch: - Final end-to-end testing - Verify all checklist items - Sleep well! Launch day: - Publish during low-traffic hours - Monitor closely for first few hours - Be ready to respond to issues ``` ## Publishing Options for Buzzy Apps ### Buzzy Managed Hosting (Recommended) **What it is**: Publish directly through Buzzy platform **Advantages**: * Simplest option - no server management * Automatic scaling on Kubernetes infrastructure * Built-in SSL/HTTPS * CDN included * Buzzy Core Engine updates handled automatically * No dependency management or framework upgrades * Professional-grade infrastructure **Steps**: 1. **Open your app in Buzzy Workspace** 2. **Go to Publish tab** 3. **Choose publishing plan**: * Free tier (for testing) * Professional (for production) * Enterprise (for custom needs) 4. **Configure domain** (optional): * Use Buzzy subdomain (app-name.buzzy.app) * Or connect custom domain 5. **Click "Publish"** 6. **Test the live URL** **See**: [Buzzy Deployment & App Stores](/working-with-buzzy/buzzy-deployment-and-app-stores) for detailed instructions ### Custom Server Deployment **What it is**: Host on your own infrastructure **When to use**: * Specific compliance requirements * Existing infrastructure mandates * Custom networking needs **See**: [Connecting your own server](/working-with-buzzy/buzzy-deployment-and-app-stores/connecting-your-own-server) for details {% hint style="info" %} **Note**: With Buzzy's managed hosting, you don't need to worry about server setup, SSL certificates, or infrastructure maintenance. Buzzy handles all of this automatically. {% endhint %} ## Web Application Publishing ### Environment Management in Buzzy **Separate environments**: **Preview Mode**: * Test your app before publishing * Use test data in Datatables * Verify all features work * Check mobile and desktop views **Live Mode** (after publishing): * Real user traffic * Production data * Optimized performance * Monitored by Buzzy infrastructure **Buzzy Functions Configuration**: ``` Use Buzzy Constants for: - API keys (encrypted at rest) - Service credentials - Configuration values - Feature flags NEVER hard-code in Buzzy Functions: - API secrets - Passwords - Connection strings - Encryption keys Access via: BUZZYCONSTANTS('constant_name') ``` **See**: [Buzzy Functions and Constants](/the-building-blocks/buzzy-functions-and-constants) ### DNS and Domain Setup **If using custom domain**: **1. Register domain**: * Use registrar (Namecheap, Google Domains, etc.) * Choose memorable name * Consider SEO implications **2. Configure DNS**: * Follow Buzzy's domain connection instructions in Publish tab * Set up www redirect if desired **3. Wait for DNS propagation** (up to 48 hours) **4. Verify**: * Test that domain resolves * Check both www and non-www * Verify SSL certificate (automatic with Buzzy) ### SSL/HTTPS Setup **Why essential**: * Required for secure data transmission * Builds user trust * Required for modern web features * Improves SEO **For Buzzy hosting**: Automatic - SSL certificates are automatically provisioned and renewed {% hint style="success" %} **Buzzy Advantage**: No SSL certificate management needed. Buzzy handles provisioning, configuration, and renewal automatically for both Buzzy subdomains and custom domains. {% endhint %} ## Mobile App Deployment ### Deploying to App Stores **Requirements**: * Apple Developer Account ($99/year) for iOS * Google Play Console Account ($25 one-time) for Android * App icon and screenshots * App description * Privacy policy **Process overview**: **1. Prepare assets**: * App icon (various sizes) * Screenshots for different devices * Marketing graphics * App description * Keywords for search **2. Build app**: * Use Buzzy's mobile build service * Or build native apps yourself **3. Submit to stores**: * Apple App Store (1-7 days review) * Google Play Store (hours to days review) **4. Wait for approval** **5. Manage releases**: * Staged rollout recommended * Monitor for issues * Update as needed **See**: [Apple & Google App Stores](/working-with-buzzy/buzzy-deployment-and-app-stores/apple-and-google-app-stores) ### App Store Guidelines **Apple App Store requirements**: * Functional and bug-free * Complete information * Appropriate content * Privacy policy * No placeholder content * Follows Human Interface Guidelines **Google Play Store requirements**: * Functional core features * Stable performance * Appropriate content * Privacy policy * Proper permissions * Follows Material Design (recommended) **Common rejection reasons**: * Crashes on launch * Broken features * Misleading description * Missing privacy policy * Inappropriate content * Copyright violations ## Publishing Process ### Standard Publishing Workflow in Buzzy **1. Final Pre-Publishing Testing**: ``` - Test all features in preview mode one final time - Have someone else test - Check mobile and desktop in preview - Verify all Datatables and screens work - Test different user roles ``` **2. Prepare for Publishing**: ``` - Save current version in Buzzy's Versions tab - Document any important notes - Have rollback plan ready (can restore previous version) - Schedule publishing time (off-peak if possible) - Notify stakeholders ``` **3. Publish**: ``` - Go to Publish tab in Buzzy Workspace - Click "Publish" or update existing deployment - Buzzy handles the deployment automatically - Wait for confirmation ``` **4. Post-Publishing Verification**: ``` - Test critical paths on live URL - Verify data integrity in Datatables - Check performance - Test from different devices/locations - Verify custom domain works (if configured) ``` **5. Monitor and Respond**: ``` - Watch for user reports - Monitor app behavior - Check usage patterns - Use Buzzy's Versions tab to rollback if needed ``` ### Publishing Timing **Best times to publish**: * Off-peak hours (when fewer users active) * Early in week (Monday/Tuesday) * When team available for monitoring * Not right before weekends/holidays **Worst times to publish**: * Friday afternoon (no monitoring over weekend) * Peak usage times * Right before vacation * During major events ## Rollback Planning **Always have a rollback plan**: **Before publishing**: * Save current version in Buzzy's Versions tab * Document version notes * Know how to restore previous version * Have communication plan **If something goes wrong**: 1. Assess severity 2. Decide: Fix forward or rollback? 3. Use Buzzy's Versions tab to restore previous version if needed 4. Notify users if affected 5. Investigate and fix root cause 6. Publish again when ready **See**: [Rollback Strategies](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/rollback-strategies) {% hint style="success" %} **Buzzy Advantage**: Rollback is simple using the Versions tab. No complex deployment scripts or database migrations to manage. {% endhint %} ## Post-Publishing ### Monitoring Your Buzzy App **Essential monitoring**: **App Health**: * Buzzy infrastructure handles uptime automatically * Monitor user reports for issues * Track app usage patterns **User Experience**: * Collect feedback through in-app forms * Monitor user behavior * Track feature usage **Data Integrity**: * Periodically review Datatables for anomalies * Ensure data relationships working correctly * Check for unexpected data patterns **Usage Analytics**: * Active users * Popular features * Conversion rates * User flows **Tools you can integrate**: * Google Analytics (usage tracking) * Custom analytics via Buzzy Functions * Third-party feedback tools * User behavior analytics {% hint style="info" %} **Note**: Buzzy's managed infrastructure handles uptime, performance, and error monitoring at the platform level. You can focus on monitoring user experience and app usage. {% endhint %} ### User Communication **Launch announcement**: * Email users (if you have list) * Social media announcement * Blog post * Show in-app announcement **Gather feedback**: * Feedback form in app * User surveys * Monitor support requests * Track feature requests **Stay responsive**: * Respond to user issues quickly * Fix critical bugs immediately * Communicate about known issues * Thank users for feedback ## Common Publishing Issues ### Issue: Custom Domain Not Working **Symptoms**: Domain doesn't resolve to app, SSL errors **Solution**: * Verify DNS records configured correctly in Publish tab * Wait for DNS propagation (up to 48 hours) * Check domain registrar settings * Contact Buzzy support if persisting ### Issue: Data Not Showing Correctly **Symptoms**: Missing data, incorrect relationships **Solution**: * Verify data exists in Datatables (Data tab) * Check Subtable and Linked Field relationships * Verify display rules and filters in screens * Check Viewers field permissions ### Issue: Buzzy Functions Not Working **Symptoms**: Features using Functions fail, timeouts **Solution**: * Check Function code for errors * Verify Constants are configured correctly * Test Function locally if possible * Review Function logs for errors * Check API rate limits for external services ### Issue: Mobile Layout Issues **Symptoms**: App doesn't display correctly on mobile **Solution**: * Test in preview mode on mobile device * Adjust responsive layout settings in Design tab * Simplify complex layouts for mobile * Use Buzzy's mobile-friendly components ### Issue: Permission Problems **Symptoms**: Users see or can't access features they shouldn't **Solution**: * Review Viewers and Team Viewers fields in Datatables * Check display rules based on user roles * Verify server-level security properly configured * Test with different user accounts ## Publishing Checklist Template ``` Pre-Publishing: - [ ] All features tested in preview mode - [ ] Security configured (Viewers fields, display rules) - [ ] Performance acceptable in live mode - [ ] Buzzy Functions tested (if used) - [ ] Constants configured (if needed) - [ ] Version saved in Versions tab - [ ] Rollback plan documented - [ ] Team notified of publishing Publishing: - [ ] Publishing time scheduled - [ ] Maintenance notice sent (if updating) - [ ] Current version saved in Versions tab - [ ] Publish via Publish tab - [ ] Verify publishing successful - [ ] SSL working (automatic with Buzzy) Post-Publishing: - [ ] Critical paths tested on live URL - [ ] Data integrity verified in Datatables - [ ] Users can access app - [ ] Custom domain working (if configured) - [ ] Team monitoring for issues - [ ] Launch announcement sent First 24 Hours: - [ ] Monitor user feedback - [ ] Check app behavior - [ ] Review usage patterns - [ ] Fix any critical issues - [ ] Document lessons learned Sign-off: [Date, Name] ``` ## Multi-Environment Workflows For professional development workflows, Buzzy supports Software Config Management (SCM) which allows you to maintain separate environments and push changes between them. **Typical setup**: **Development Environment**: Where you build and experiment with new features. Test thoroughly before promoting changes. **Staging Environment**: A production-like environment for final testing and user acceptance. Catch issues before they reach real users. **Production Environment**: Your live application serving real users. Only promote tested, approved changes here. **How it works**: 1. Build and test features in your Development environment 2. Save a version when ready for promotion 3. Use the Publish panel to push the version to Staging 4. Perform final testing in Staging 5. Push the approved version to Production **Benefits**: * Safe experimentation without affecting production users * Thorough testing before release * Controlled release timing * Easy rollback if issues discovered **See**: [Software Config Management](/working-with-buzzy/buzzy-deployment-and-app-stores/software-config-management) for detailed setup and usage instructions. ## Progressive Deployment For larger apps or when cautious: **Phase 1: Beta Launch** (1-2 weeks): * Small group of users * Gather feedback * Fix issues * Refine features **Phase 2: Soft Launch** (1-2 weeks): * Larger user group * Monitor performance at scale * Fix scaling issues * Optimize based on real usage **Phase 3: Full Launch**: * All users * Full marketing push * Continuous monitoring * Ongoing improvements **Advantages**: * Lower risk * Real-world feedback early * Can catch issues before full launch * Builds anticipation ## Next Steps * **Maintaining your app**: [Maintenance & Tech Debt](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/maintenance) * **If something breaks**: [Rollback Strategies](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/rollback-strategies) * **Planning ongoing development**: [Making Changes](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/making-changes) {% hint style="success" %} **Remember**: Publishing isn't the end—it's the beginning. Your app will need updates, fixes, and improvements. The good news: with Buzzy, the Core Engine maintenance is handled for you, so you can focus on improving your app's functionality and user experience. {% endhint %} # Maintenance & Tech Debt Discover how Buzzy's no-code platform solves maintenance and technical debt nightmares. Learn what you maintain vs what Buzzy handles automatically. ## The Maintenance Problem with Traditional Vibe Coding **Non-technical explanation**: Traditional vibe coding (where AI generates actual code files) is like buying a car that needs constant repairs. The initial purchase is exciting, but then you're stuck with oil changes, brake replacements, engine tune-ups, and dealing with recalls. Over time, maintenance costs exceed the original purchase price. **The traditional vibe coding maintenance nightmare**: ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%% graph TB A[AI Generates Code] --> B[Works Initially! 🎉] B --> C[Month 1: Framework Update] C --> D[Breaking Changes 💔] D --> E[Spend Hours Fixing] E --> F[Month 2: Security Patch] F --> G[More Breaking Changes] G --> H[More Hours Fixing] H --> I[Month 3: Dependency Updates] I --> J[Everything Breaks Again] J --> K[Give Up or Hire Developer] style B fill:#6c6,stroke:#333,color:#000 style D fill:#f88,stroke:#333,color:#000 style G fill:#f88,stroke:#333,color:#000 style J fill:#f88,stroke:#333,color:#000 style K fill:#f88,stroke:#333,color:#000 ``` When using traditional AI coding tools (Cursor, Claude Code, Devin for code generation, etc.), maintenance becomes a nightmare: **The typical scenario**: 1. You vibe-code an app with React 17 and various packages 2. App works great at launch 3. 6 months later: Security vulnerabilities in dependencies 4. You prompt AI to update everything 5. AI changes thousands of lines of code with different patterns 6. Everything needs retesting 7. Things that worked now behave differently 8. You're stuck maintaining code you didn't write **The vibe coding maintenance trap**: * Thousands of lines of AI-generated code to maintain * Dependencies constantly need updating * Each update risks breaking everything * Testing burden grows exponentially * Original AI might use different patterns than current AI * You didn't write it, so understanding is difficult * Tech debt accumulates rapidly ## How Buzzy Solves the Maintenance Problem **Non-technical explanation**: Buzzy is like renting a professionally maintained apartment instead of buying a house. The landlord (Buzzy) handles all the infrastructure, plumbing, electrical, heating—you just live in it and customize the interior. If something breaks in the building's systems, Buzzy fixes it, not you. **Visual comparison**: **Traditional Vibe Coding**: ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%% graph TB A1[AI Generates Code Files] --> B1[You Own/Maintain Code] B1 --> C1[Framework Updates] C1 --> D1[You Fix Breaking Changes] D1 --> E1[Security Patches] E1 --> F1[You Fix Again] F1 --> G1[Endless Maintenance] style G1 fill:#f88,stroke:#333,color:#000 ``` **Buzzy's No-Code Approach**: ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%% graph TB A2[Buzzy AI Generates App Definition] --> B2[Buzzy Engine Interprets It] B2 --> C2[Buzzy Updates Engine] C2 --> D2[Your App Still Works] D2 --> E2[Buzzy Handles Security] E2 --> F2[Your App Still Works] F2 --> G2[No Maintenance for You] style G2 fill:#6c6,stroke:#333,color:#000 ``` ### No Code to Maintain **Traditional approach**: AI generates code → You maintain the code → Updates break things → Tech debt accumulates → Endless cycle **Buzzy approach**: Buzzy AI generates App Definition → Buzzy Core Engine interprets it → Buzzy maintains the engine → No maintenance burden for you → Freedom! **What this means for you**: * ✅ You're NOT maintaining React or React Native code (Buzzy does that) * ✅ You're NOT managing npm dependencies (no package.json to worry about) * ✅ You're NOT dealing with framework upgrades (Buzzy handles React updates) * ✅ You're NOT fixing security vulnerabilities in packages (Buzzy patches them) * ✅ You're NOT testing after every framework update (your App Definition stays stable) * ✅ You're NOT debugging "works on my machine" issues (consistent Buzzy environment) ### Professionally Maintained Core Engine Buzzy's Core Engine is professionally developed and maintained: **What Buzzy handles for you**: * React and React Native updates * Security patches for all dependencies * Framework upgrades without breaking your apps * Performance optimizations * Bug fixes in the rendering engine * iOS and Android platform updates * Web browser compatibility **Your apps automatically benefit**: * No action required from you * Apps keep working with latest platforms * Security stays up to date * Performance improvements propagate * No retesting needed (Buzzy tests the engine) [Learn more about Buzzy's architecture](https://docs.buzzy.buzz/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/pages/1zqIoZP0tLjXKKhztJ2Y#code-generation-vs.-buzzys-no-code-architecture-why-it-matters) ### Focus on What Matters: Your App Logic With Buzzy, your maintenance focuses on: **Your app's evolution**: * Adding new features users request * Refining UX based on feedback * Adjusting business logic * Updating content and data * Improving security rules for your specific data **Not infrastructure maintenance**: * Not React version upgrades * Not dependency security patches * Not framework breaking changes * Not mobile platform updates * Not browser compatibility fixes ## Understanding Technical Debt in Buzzy ### What Technical Debt Means with Buzzy **Not tech debt in Buzzy**: * Framework and dependency maintenance (handled by Buzzy) * Security patches (handled by Buzzy) * Platform updates (handled by Buzzy) * Breaking changes from library updates (handled by Buzzy) **Potential tech debt in Buzzy**: * Poorly designed data model (inefficient Subtables/Linked Fields) * Complex Buzzy Functions that need refactoring * Confusing screen layouts * Overly complex display rules * Insufficient testing of your app logic **The difference**: In Buzzy, tech debt is about your app's design decisions, not about maintaining underlying code frameworks. ## What You Still Maintain with Buzzy ### Your App's Logic and Design While Buzzy eliminates infrastructure maintenance, you're still responsible for: **Data Model Evolution**: * Adding new Datatables as requirements change * Refining Subtable and Linked Table Field relationships * Adjusting field types and validation * Improving data structure based on usage patterns **User Experience Refinement**: * Updating screen layouts based on user feedback * Adjusting display rules for better UX * Improving navigation flows * Optimizing mobile experience **Business Logic Updates**: * Modifying JSONATA formulas * Updating Buzzy Functions for new integrations * Adjusting security rules (Viewers, Team Viewers) * Implementing new feature requests **Content and Configuration**: * Updating app content and copy * Adjusting Constants for Buzzy Functions * Managing Organizations and Teams * Configuring deployment settings ### Buzzy Functions Maintenance If you use Buzzy Functions for external integrations: **What you maintain**: * The Lambda function code you write * API integrations in your functions * Constants (encrypted, but you manage values) * Function logic and error handling **What Buzzy handles**: * Lambda runtime environment (Node.js 22) * Deployment infrastructure * Scaling and availability * Security and encryption of Constants **Maintenance pattern**: * Update function code when APIs change * Refactor complex functions for clarity * Update Constants when API keys change * Test functions after major changes **This is manageable**: * Functions are focused and specific * No framework updates to worry about * No dependency hell (minimal dependencies) * Clear separation of concerns ## Maintenance Planning with Buzzy ### Regular Maintenance Tasks **Weekly**: * [ ] Review user feedback and support requests * [ ] Check Buzzy Function logs for errors * [ ] Test any new features added * [ ] Monitor app usage patterns **Monthly**: * [ ] Review data model efficiency * [ ] Optimize slow-loading screens * [ ] Update Buzzy Functions if external APIs changed * [ ] Review security settings (Viewers, Teams) * [ ] Check mobile app performance **Quarterly**: * [ ] Major UX improvements based on feedback * [ ] Data model refactoring if needed * [ ] Performance audit with realistic data * [ ] User testing sessions * [ ] Review and update documentation **Annually**: * [ ] Comprehensive app review * [ ] Major feature additions * [ ] Organization and Teams structure review * [ ] Deployment and hosting review ### Maintenance Budget with Buzzy **Significantly reduced costs compared to traditional vibe coding**: **Traditional vibe coding yearly costs**: * Framework updates: 20-40 hours * Dependency updates: 10-20 hours * Security patches: 10-30 hours * Breaking change fixes: 20-60 hours * Testing after updates: 30-60 hours * **Total: 90-210 hours/year** just keeping code up to date **Buzzy yearly costs**: * App logic updates: As needed * Feature additions: As needed * Buzzy Functions updates: 5-10 hours (only if APIs change) * UX refinements: As needed * **No framework maintenance required** **Cost factors with Buzzy**: * Buzzy subscription (covers hosting, infrastructure) * Custom domain (optional) * Third-party API costs (if using external services) * Development time for new features * **No infrastructure engineers needed** * **No DevOps maintenance** ## Managing App Complexity in Buzzy ### Assessing Your App's Health **Critical** (Fix ASAP): * Data integrity issues * Security problems (incorrect Viewers setup) * Breaking bugs affecting users * Severe performance problems **Important** (Fix Soon): * Confusing user flows * Inefficient data model * Slow-loading screens * Poor mobile experience **Nice to Have** (Fix When Possible): * Visual polish * Minor UX improvements * Optimization of fast-enough features * Additional convenience features ### Strategies for Improvement **Strategy 1: Incremental Improvement**: * Improve app while adding features * Fix UX issues as users report them * Refine data model when needed * Continuous polish **Advantages**: Sustainable, no dedicated cleanup time **Strategy 2: Focused Improvement Sprints**: * Dedicate time to major improvements * Focus on user feedback themes * Data model refactoring * Performance optimization **Advantages**: Significant improvements quickly **Strategy 3: User-Driven Priorities**: * Fix what users actually complain about * Optimize what users use most * Add features users request most * Data-driven decisions **Advantages**: Resources spent where they matter most ### Preventing Complexity **1. Review Buzzy AI Outputs**: * Verify data model makes sense * Check screen layouts are intuitive * Test display rules work correctly * Validate security settings **2. Maintain Design Standards**: * Consistent navigation patterns * Similar screen layouts * Predictable user flows * Clear naming conventions **3. Regular Refactoring**: * Simplify complex display rules * Consolidate similar screens * Improve data relationships * Remove unused fields/screens **4. Keep Documentation Updated**: * Document data model decisions * Explain complex business logic * Note known limitations * Plan future improvements **5. Test with Real Users**: * Regular user testing sessions * Watch how users actually use the app * Identify pain points early * Iterate based on real feedback ## Improving Existing Buzzy Apps ### When to Redesign **Redesign when**: * Data model causing frequent issues * Users consistently confused * Performance poor with real data * Adding features requires workarounds **Don't redesign when**: * Working well for users * Performance acceptable * Just personal preference * Small iterative improvements would work **Rule of thumb**: "If users are happy AND it's maintainable, don't redesign it" ### Redesign Approach with Buzzy **1. Understand Current State**: * What works well (keep it) * What causes problems (fix it) * What users want (prioritize it) * What data looks like (important for model) **2. Use Buzzy's Safety Features**: * Versions tab for rollback capability * Preview mode for safe testing * Incremental changes rather than big bang * Keep old version available during transition **3. Redesign Incrementally**: * Start with data model if needed * Update screens one at a time * Test each change with real users * Monitor after each update **4. Document Changes**: * Why you changed it * What the new approach does * Migration notes for data * User communication plan ### When to Start Fresh **Consider starting a new Buzzy app when**: * Data model fundamentally wrong * Complete rethinking of user experience * Different target users * Significantly different requirements **Before starting fresh**: * Export existing data (Buzzy REST API) * Document what current app does * Plan data migration strategy * Consider phased rollout **Advantage with Buzzy**: No code to throw away, just App Definitions. Starting fresh is less risky than with traditional code. ## Long-Term Success with Buzzy ### Documentation for Your Buzzy App **Essential documentation**: **Data Model Documentation**: * List all Datatables and their purpose * Document Subtable relationships * Explain Linked Table Field connections * Note any complex JSONATA formulas * Security model (Organizations, Teams, Viewers) **User Flow Documentation**: * Key user workflows * Screen navigation map * Display rule logic for complex cases * Action sequences **Buzzy Functions Documentation** (if applicable): * Purpose of each function * External APIs used * Constants required * Error handling approach **Integration Documentation**: * Third-party services used * API keys and where stored (Constants) * Webhook configurations * External dependencies ### Succession Planning **If you leave the project**: * Can someone else maintain it? (Much easier with Buzzy) * Is data model documented? * Are Constants documented (not values, but what they're for)? * Are user flows clear? **For handoff**: * Data model diagram * Screen navigation map * Buzzy Functions documentation * Third-party service accounts and credentials * Organization and Teams structure explanation **Advantage with Buzzy**: New maintainers don't need to understand React, React Native, or complex codebases. They just need to understand your app's logic and Buzzy's visual editor. ### Cost Management **Ongoing costs with Buzzy**: **Fixed**: * Buzzy subscription * Custom domain (if used) * Third-party API subscriptions **Variable**: * Database storage (grows with data) * Buzzy Functions usage (AWS Lambda costs) * External API usage * App store fees (if publishing to stores) **Significantly lower than traditional apps**: * No server management costs * No DevOps engineer needed * No framework update time * No security patch management * Built-in scaling (no infrastructure engineering) ### Transition Planning **If shutting down**: * Export data via Buzzy REST API * Notify users (built-in messaging) * Follow data retention/deletion policies * Cancel Buzzy subscription **If transferring ownership**: * Transfer Buzzy account ownership * Update Organization owners * Transfer third-party service accounts * Update Constants with new owner's credentials * Provide documentation to new owner **Much simpler than code-based apps**: No codebase to transfer, no infrastructure to migrate, just change ownership in Buzzy platform. ## No "Modernization" Needed ### The Buzzy Advantage **With traditional vibe-coded apps**: * React 17 → React 18 → React 19 migrations * Breaking changes in dependencies * Months of work for updates * High risk of breaking things * Testing everything again **With Buzzy apps**: * Buzzy updates the Core Engine * Your App Definitions keep working * No breaking changes for you * Automatic modernization * **Zero migration work required** This is the core value proposition of Buzzy's architecture. You're not maintaining code; you're maintaining app logic. ## Metrics to Track for Buzzy Apps ### App Health Metrics **Data quality**: * Data integrity (orphaned records, invalid data) * Data model efficiency * Formula complexity * Relationship clarity **User experience**: * User satisfaction scores * Support ticket volume * Feature usage analytics * User retention **Performance**: * Screen load times * Search/filter response times * Buzzy Function execution times * Mobile app responsiveness **Security**: * Access control coverage (Viewers/Teams) * Data exposure review * External API security * Organization/Teams structure health ### Maintenance Metrics **Time spent**: * New feature development * Bug fixes * UX improvements * Buzzy Function updates * User support **Costs**: * Buzzy subscription * Third-party APIs * Custom domain * Development time **User impact**: * Features added per month * Issues resolved * User requests addressed * Performance improvements made ## The Buzzy Advantage Summarized ### Traditional Vibe Coding Maintenance **Year 1**: Build app with AI-generated code **Year 2**: Security updates needed, 40+ hours of work, retesting **Year 3**: Framework deprecated, major migration needed, 100+ hours **Year 4**: Multiple dependencies outdated, security vulnerabilities **Year 5**: Consider rewrite because maintenance too expensive **Total maintenance**: Hundreds of hours just keeping code up to date ### Buzzy App Maintenance **Year 1**: Build app with Buzzy **Year 2**: Focus on new features, UX improvements (Buzzy handles core updates) **Year 3**: Focus on business logic evolution (Buzzy handles framework updates) **Year 4**: Focus on scaling and growth (Buzzy handles infrastructure) **Year 5**: Still maintainable, no rewrite needed **Total maintenance**: Focus on YOUR app, not on frameworks ## Keys to Long-Term Success with Buzzy **1. Understand What You're Building**: * Know your data model * Understand user workflows * Document business logic * Keep data model diagram updated **2. Test with Real Users**: * Regular user feedback * Watch how people actually use it * Iterate based on real needs * Don't guess what users want **3. Keep It Simple**: * Simple data models easier to maintain * Clear navigation easier for users * Fewer Buzzy Functions means less maintenance * Start simple, add complexity only when needed **4. Leverage Buzzy's Strengths**: * Let Buzzy handle infrastructure * Use Organizations/Teams for multi-tenancy * Use Buzzy Functions only when necessary * Trust the platform for security and scaling **5. Plan for Growth**: * Design data model for scale * Test with realistic data volumes * Consider mobile experience * Think about future features ## Next Steps Now that you understand maintenance with Buzzy: * **Starting a project**: [Design Fundamentals](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals) * **Understanding workflow**: [Project Workflow](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow) * **Building examples**: [Hello World App](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/hello-world) * **Quality practices**: [App Quality & Performance](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/app-quality-performance) {% hint style="success" %} **Remember**: Buzzy eliminates the technical debt nightmare of traditional vibe coding. You focus on your app's logic and user experience. Buzzy focuses on the infrastructure, frameworks, and security. This is the future of sustainable AI-assisted development. {% endhint %} # Building Examples Practical Buzzy examples for building, adapting, extending, testing, and governing real apps with Builder MCP, Buzzy Functions, code widgets, and upcoming agent/data-connector capabilities. Building examples should show the way Buzzy apps are actually built now: start from a semantic app definition, use Builder MCP or Buzzy AI to shape it, add functions and code widgets where the app needs custom behavior, then test and review the result before release. These examples are not a gallery of toy prompts. They are reusable patterns for building apps that teams can own. The key ownership point is simple: AI can help write or modify the app, but the maintainable asset should be the Buzzy app definition and the governed runtime around it. Builder MCP is useful because it works with that definition directly instead of leaving the team with another large generated codebase to secure, patch, test, and explain. ## Recommended Examples ### [Short Stay to Care Connect](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/short-stay-template-adaptation) **Use this when:** you have a working template or app pattern that is close to the new app you want. This is the most important example for Builder MCP. A short-stay rental marketplace already has search, listings, providers, availability, bookings, pricing, admin review, and role-based access. Builder MCP can inspect that app definition and adapt it into a new domain such as care booking, where the same broad workflow has different data, wording, risk, and privacy requirements. This is the pattern behind the [Care Connect tutorial](/the-building-blocks/mcp/buzzy-builder-mcp/tutorial-carer-app-from-a-template). ### [Secure and Compliant Workflow App](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/secure-compliance-workflow) **Use this when:** the app handles sensitive records, review queues, role-based access, field-level privacy, or audit evidence. This example is still a strong reference. It shows how to combine row access, Field view/edit, Private Data, teams, and audit trails. Use it for legal review, compliance review, HR case management, clinical triage, finance approvals, vendor onboarding, and similar workflows. ### [Builder MCP Change and Extension Workflow](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/builder-mcp-change-workflows) **Use this when:** an app already exists and you need to change it safely. Use Builder MCP to inspect the current brief, flows, data model, blueprint, screens, functions, and code widgets before making changes. This is the right pattern for adding a custom dashboard, generating a code widget, creating a Buzzy Function, wiring an external API, or fixing a screen without losing the structure of the app. ### [External API Integration](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/external-api-integration) **Use this when:** the app needs data or actions from another service. This example covers Buzzy Functions, Constants, external HTTP APIs, secure API key storage, and error handling. It remains useful, but for production work you should now combine it with Builder MCP review, Release Tests, and Security Review. ### [AI-Powered App Features](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/ai-powered-app) **Use this when:** you want AI inside the app, not just AI helping build the app. This example now focuses on adding AI features through Buzzy Functions and, where needed, code widgets. It covers safe prompting, constants, function inputs/outputs, cost controls, review UX, and testing. ### [Hello World App](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/hello-world) **Use this when:** someone is new to Buzzy and needs a simple first build. This is still useful as a beginner exercise, but it is not the main path for production-minded app creation. For current Builder MCP practice, start with the template adaptation or change-workflow examples above. ## Coming Next ### [Buzzy Agents](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/buzzy-agents-placeholder) Buzzy Agents will bring app-side agent workflows into Buzzy. Keep this separate from Builder MCP: Builder MCP helps create and edit apps; Buzzy Agents will run inside app experiences and workflows. ### [Universal Data Connector](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/universal-data-connector-placeholder) The Universal Data Connector will be the pattern for connecting external data sources into Buzzy app workflows. Until the dedicated capability is documented, use Buzzy Functions, REST API, and Custom MCP depending on whether the app needs server-side integration, external programmatic access, or assistant-facing tools. ## How to Choose an Example | Goal | Start with | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Adapt a proven app pattern into a new domain | [Short Stay to Care Connect](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/short-stay-template-adaptation) | | Build a sensitive review or approval workflow | [Secure and Compliant Workflow App](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/secure-compliance-workflow) | | Modify an existing app safely with an AI coding agent | [Builder MCP Change and Extension Workflow](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/builder-mcp-change-workflows) | | Add a custom UI, chart, map, or advanced interaction | [Builder MCP Change and Extension Workflow](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/builder-mcp-change-workflows), then [Code Widget Examples](/the-building-blocks/code-widget-custom-code/examples) | | Call an external service | [External API Integration](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/external-api-integration) | | Add AI behavior inside the app | [AI-Powered App Features](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/ai-powered-app) | | Learn basic Buzzy app structure | [Hello World App](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/hello-world) | ## Standard Build Loop For serious apps, use this loop: 1. Start from the closest useful template or app pattern. 2. Review the brief and make the product intent explicit. 3. Review flows, data model, security posture, and blueprint before screen work. 4. Use Builder MCP for structural changes and app-aware edits. 5. Add Buzzy Functions for server-side logic, external APIs, webhooks, and AI calls. 6. Add code widgets only when standard Buzzy UI cannot express the interaction. 7. Generate sample data early so screens can be reviewed realistically. 8. Run Release Tests for key paths. 9. Run Security Review when the app exposes sensitive data, roles, APIs, MCP tools, or external integrations. ## What Good Examples Should Prove A good Buzzy example should show: * the app pattern and why it fits Buzzy * the brief, roles, data, and flow decisions * what Builder MCP changes and what Buzzy runtime owns * where functions, constants, code widgets, or APIs are used * how the app is tested * how privacy, permissions, and release risk are reviewed # Hello World App Build your first complete Buzzy application from scratch. Follow this step-by-step tutorial to create a functional task list app and learn Buzzy AI fundamentals. ## Overview **What we're building**: A simple but complete task list application where users can add, view, mark complete, and delete their personal tasks. **Non-technical explanation**: Think of this as your "Hello World" for Buzzy—just like programmers start with printing "Hello World," you'll start by building a simple task app to learn the fundamentals of Buzzy AI development. **Time commitment**: 1-2 hours total * Planning: 10 minutes * Initial build with Buzzy AI: 15 minutes * Review and refinement: 30 minutes * Testing: 20 minutes * Publishing: 10 minutes **Difficulty**: 🟢 Beginner - Perfect for your first Buzzy app **Prerequisites**: * ✅ Buzzy account (sign up free at [buzzy.buzz](https://buzzy.buzz)) * ✅ Read [System Thinking](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/system-thinking) basics * ✅ Reviewed [Buzzy AI Guide](/getting-started-with-buzzy/new-buzzy-ai-v3) * ✅ 1-2 hours of focused time **What you'll learn**: * ✍️ Writing effective Buzzy AI prompts with clear specifications * 🔍 Reviewing Buzzy-generated Brief, Blueprint, Data, and Design tabs * 🎨 Using Buzzy's visual editor in the Design tab * 🧪 Testing your app in Buzzy's preview mode * 🚀 Publishing your first Buzzy app to production * 🔒 Implementing basic security with Viewers fields * 🔄 Using Buzzy's Versions tab for rollback safety **End result**: A working, published task management app you can share with others and use as a foundation for more complex projects. ## The Application We're Building **Core features** (keep it simple for first app): * 📋 View list of all your tasks * ➕ Add new tasks with title and description * ✅ Mark tasks as complete/incomplete * 🗑️ Delete tasks you no longer need * 🔒 Personal task list (each user sees only their own tasks) **Visual preview** of what we're building: ``` ┌─────────────────────────────────────┐ │ My Tasks [+ Add]│ ├─────────────────────────────────────┤ │ │ │ ☐ Buy groceries │ │ Get milk, bread, eggs │ │ Created: Oct 7, 2025 │ │ │ │ ☑ Call dentist │ │ Schedule teeth cleaning │ │ Created: Oct 6, 2025 │ │ │ │ ☐ Finish project report │ │ Due by end of week │ │ Created: Oct 5, 2025 │ │ │ └─────────────────────────────────────┘ Click any task → See details → Mark complete or delete ``` **Data structure**: ```mermaid erDiagram TASKS { string title string description boolean completed date created_at string viewers_field } ``` **One Datatable**: Tasks * title (text, required) * description (long text, optional) * completed (yes/no, defaults to no) * created\_at (date, automatic) * Viewers field (security - users see only their tasks) **Three screens**: 1. **Task List** (main screen): Shows all your tasks in a list 2. **Add Task Form**: Enter title and description to create new task 3. **Task Detail**: View full task, mark complete, or delete **User flow**: ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%% graph TD A[Open App] --> B[Task List] B --> C[Click '+ Add'] C --> D[Fill Form] D --> E[Save] E --> B B --> F[Click Task] F --> G[Task Detail] G --> H[Mark Complete] H --> B G --> I[Delete] I --> B ``` ## Step 1: Planning (10 minutes) Before prompting AI, think through what you need. ### Data Design **Entity**: Tasks **Fields**: * title (text, required) * description (text, optional) * completed (boolean, defaults to false) * created\_at (date, automatic) **Relationships**: None (simple single table) ### User Flow ``` User opens app ↓ Sees list of tasks ↓ Can click "Add Task" → Form → Save → Back to list ↓ Can click on task → See details → Mark complete or Delete ↓ Completed tasks show differently (crossed out or grayed) ``` ### Success Criteria **The app works if**: * I can add a new task * I can see all my tasks * I can mark tasks as complete * I can delete tasks I don't need * The UI is usable on mobile and desktop ## Step 2: Initial Build with Buzzy AI (15 minutes) ### The Prompt **In Buzzy Workspace, click "Create New App" and enter this prompt**: ``` Create a task list application with the following: Data Model: - Tasks Datatable with fields: - title (text field, required, max 100 characters) - description (long text field, optional) - completed (yes/no field, defaults to no) - created_at (date field, automatic) - Viewers field set to current user (so users only see their own tasks) Screens: 1. Task List screen showing all tasks: - Display title and creation date for each task - Use display rules to show completed tasks with strikethrough - "Add New Task" button at top - Empty state message: "No tasks yet. Click 'Add New Task' to get started" 2. Add Task screen with form: - Title field (required) - Description field (optional) - Submit action to save the task - Cancel button to navigate back to list 3. Task Detail screen showing: - Task title (large heading) - Description text - Created date - "Mark Complete" button with action to update completed field (if not complete) - "Mark Incomplete" button with action to update completed field (if complete) - "Delete" button with confirmation popup - Back navigation to list Design: - Mobile-responsive layout - Clean, simple interface - Use card layout for task list items - Primary color for action buttons Security: - Use Viewers field on Tasks to ensure users only see their own tasks Make it simple and intuitive for a beginner. ``` {% hint style="info" %} **Tip**: Notice how the prompt uses Buzzy-specific terms like "Datatable", "display rules", "Submit action", and "Viewers field". These help Buzzy AI understand exactly what you want. {% endhint %} ### What Buzzy AI Will Generate **Buzzy will create**: 1. **Brief**: Summary of your app concept 2. **Blueprint**: List of screens and navigation flow 3. **Data Model**: Tasks Datatable with specified fields 4. **Design**: Initial screens with components and actions **Processing time**: * Buzzy AI typically takes 1-2 minutes to generate the full app structure * You'll see progress as each section is completed * Brief appears first, then Blueprint, then Data, then Design **What you'll see in the Workspace**: * **Brief tab**: Your app description * **Blueprint tab**: Screen list and navigation * **Data tab**: Tasks Datatable with fields * **Design tab**: Visual screens you can edit ## Step 3: Review the Generated Structure (10 minutes) ### Check the Data Model **Go to**: Data tab in Buzzy Workspace **Verify the Tasks Datatable**: * [ ] Tasks Datatable exists * [ ] Title field is "text" type * [ ] Description field is "long text" type * [ ] Completed field is "yes/no" type * [ ] created\_at field is "date" type * [ ] Viewers field exists and is set to current user {% hint style="info" %} **Understanding Datatables**: In Buzzy, your data is stored in Datatables (formerly called Microapps). Each Datatable has fields, and the Viewers field controls who can see each record. [Learn more about Buzzy data model](/the-building-blocks/datatables-fields-and-data/buzzy-datamodel-overview). {% endhint %} **If something's wrong**: * **Option 1 - Use Buzzy AI chat**: "Update the Tasks Datatable to include a priority field" * **Option 2 - Manual edit**: Click "Edit" in Data tab, add/modify fields directly * **Recommended**: Use manual editing for small tweaks, it's faster than AI prompts ### Check the Blueprint **Go to**: Blueprint tab in Buzzy Workspace **Verify screens are listed**: * [ ] Task list screen * [ ] Add task screen * [ ] Task detail screen * [ ] Navigation flow makes sense **If screens are missing**: * **Use Buzzy AI chat**: "Create the missing task detail screen that shows full task information with title, description, created date, and buttons to mark complete or delete" ### Review Initial Screens in Design Tab **Go to**: Design tab in Buzzy Workspace **Check each screen**: * [ ] Task list screen exists with Tasks Datatable component * [ ] Add task screen has form with title and description fields * [ ] Forms have Submit actions configured * [ ] Navigation buttons exist **Don't worry yet about**: * Perfect styling (you'll polish this later) * Every feature working exactly right * Complete functionality (test in next step) {% hint style="success" %} **Buzzy's Visual Editor**: The Design tab is where you can see and edit your screens visually. You can drag components, adjust styling, configure actions, and set display rules—all without writing code. {% endhint %} ## Step 4: Test the App in Preview Mode (15 minutes) ### Open Preview Mode **In Buzzy Workspace**: 1. Look for the "Preview" or eye icon in the top toolbar 2. Click it to open your app in preview mode 3. The app opens in a new browser tab {% hint style="info" %} **Preview vs Live**: Preview mode lets you test your app before publishing. Changes you make in the Design tab appear immediately in preview mode after refreshing. {% endhint %} ### Test Core Functionality **Test 1: Add a Task**: 1. Click "Add New Task" button 2. Fill in: Title = "Test Task", Description = "This is a test" 3. Click the Submit button 4. **Expected**: Return to task list, see new task in the list 5. **If it doesn't work**: Check the Submit action in Design tab **Test 2: View Task Details**: 1. Click on the task you just created 2. **Expected**: Navigate to task detail screen showing title, description, and buttons 3. **If it doesn't work**: Check navigation actions in Design tab **Test 3: Mark Complete**: 1. From task detail, click "Mark Complete" button 2. Return to task list 3. **Expected**: Task appears with strikethrough (if display rule is set) 4. **If it doesn't work**: Check the action updates the completed field, and display rules show strikethrough **Test 4: Delete Task**: 1. Open a task 2. Click "Delete" button 3. **Expected**: Confirmation popup, then task removed after confirming 4. **If it doesn't work**: Check the Delete action has a confirmation popup configured **Test 5: Empty State**: 1. Delete all tasks 2. **Expected**: Message like "No tasks yet" 3. **If it doesn't work**: Add empty state message in Design tab ### Document Issues **Keep a list of what needs fixing**: ``` Issues Found: - [ ] Delete button doesn't show confirmation popup - [ ] Completed tasks don't show strikethrough (display rule missing) - [ ] Add button not prominent enough - [ ] Mobile: form fields too small (check responsive settings) - [ ] Task list doesn't refresh after adding task ``` {% hint style="warning" %} **Common Issue**: If data doesn't appear in preview mode, make sure your Viewers field is set correctly in the Data tab. Records should be visible to the current user. {% endhint %} ## Step 5: Iterate and Fix (30 minutes) ### Choose Your Fix Method **Option 1 - Visual Editor (Faster for small fixes)**: * Go to Design tab * Click on the screen/component to edit * Adjust settings, styling, actions directly * Refresh preview to see changes **Option 2 - Buzzy AI Chat (Better for multiple changes)**: * Write specific prompts describing what to fix * Buzzy AI updates the app structure * Review changes in Design tab {% hint style="success" %} **When to use each method**: * **Visual Editor**: Styling tweaks, adjusting single component, adding simple actions * **Buzzy AI**: Adding new features, changing multiple screens, complex logic {% endhint %} ### Fix Critical Issues **Example: Delete Confirmation (Use Visual Editor)**: **Manual fix in Design tab**: 1. Go to Design tab → Task detail screen 2. Click on the Delete button 3. In button properties, find "Action" settings 4. Enable "Confirmation Popup" 5. Set popup text: "Are you sure you want to delete this task? This cannot be undone." 6. Save changes 7. Refresh preview and test **Or use Buzzy AI prompt**: ``` On the task detail screen, update the Delete button to: 1. Show a confirmation popup when clicked 2. Popup text: "Are you sure you want to delete this task? This cannot be undone." 3. Popup should have "Cancel" and "Delete" buttons 4. Only delete the task if user confirms ``` **Example: Completed Task Display Rules (Use Visual Editor)**: **Manual fix in Design tab**: 1. Go to Design tab → Task list screen 2. Click on the task title text component 3. Add a Display Rule: "When completed field = yes" 4. In this rule, set text style to strikethrough 5. Optionally add gray background to card when completed 6. Save and refresh preview **Or use Buzzy AI prompt**: ``` On the task list screen, add display rules for completed tasks: - When completed field is yes, show title with strikethrough - Add gray background to completed task cards - Add a green checkmark icon next to completed tasks ``` **Example: Mobile Responsive Improvements (Use Visual Editor)**: **Manual fix in Design tab**: 1. Go to Design tab → Add task screen 2. Click on form fields 3. Adjust responsive settings for mobile: * Minimum touch target: 44px height * Font size: 16px (prevents zoom on iOS) * Padding: 12px 4. Make Submit button full width on mobile 5. Test in preview mode using browser mobile view ### Test After Each Fix **Testing workflow**: 1. Make ONE change (visual editor or AI prompt) 2. Refresh preview mode 3. Test the specific thing you changed 4. Quick check that nothing else broke 5. Move to next fix **Don't**: * Make 5 changes and then test everything * Assume AI prompts worked perfectly * Skip testing in preview mode **Do**: * Test immediately after each change * Use browser dev tools for mobile testing * Verify fix addresses the issue * Check related functionality still works ## Step 6: Polish with Visual Editor (20 minutes) ### Add Nice-to-Have Features **Sort Options (Use Buzzy AI prompt)**: ``` Add sorting to the task list screen: - Add a dropdown at top to sort by: Created date (newest first), Title (A-Z), Completed status - Use Buzzy's sort functionality on the Datatable component - Default sort: Created date, newest first ``` **Then in Design tab**: * Find the Tasks Datatable component on list screen * Configure "Sort" settings in component properties * Add available sort fields **Search (Use Visual Editor)**: 1. Go to Design tab → Task list screen 2. Add a "Search" component above the task list 3. Configure search to filter Tasks Datatable by title and description fields 4. Test in preview mode **Task Count (Use Formula Fields)**: 1. Go to Data tab → Tasks Datatable 2. You can create calculated fields or use Buzzy's count features 3. Or add text components in Design tab showing count of records {% hint style="info" %} **Buzzy's Built-in Features**: Buzzy provides sort, search, and filter capabilities on Datatable components. Check the component properties in Design tab to enable these features without custom code. {% endhint %} ### Visual Polish Using Theme and Design Tab **Improve styling in Design tab**: 1. **Task cards**: * Click on task card component * Adjust border radius for rounded corners * Add box shadow for depth * Increase margin between cards 2. **Consistent spacing**: * Select components and adjust padding settings * Use Theme tab for app-wide spacing standards 3. **Color scheme**: * Go to Theme tab * Set primary color for buttons and highlights * Ensure text colors have good contrast 4. **Hover effects** (for web): * In component properties, add hover state styling * Slight elevation on hover for cards **Or use Buzzy AI for multiple styling changes**: ``` Update task list styling: - Add 8px border radius to task cards - Add subtle shadow: 0 2px 4px rgba(0,0,0,0.1) - Increase spacing between cards to 16px - Use consistent 16px padding throughout - Primary color for action buttons should be from theme ``` ## Step 7: Final Testing (20 minutes) ### Complete Test Suite **Test all features**: * [ ] Add task * [ ] View task * [ ] Edit task (if you added this) * [ ] Mark complete * [ ] Mark incomplete * [ ] Delete task * [ ] Search (if added) * [ ] Sort (if added) **Test edge cases**: * [ ] Add task with very long title (test max length) * [ ] Add task with empty description * [ ] Try to save task with no title (should prevent) * [ ] Delete last task (see empty state) * [ ] Add task with special characters: `&, <, >, ", '` **Test on different devices**: * [ ] Desktop browser * [ ] Mobile browser (or use browser dev tools mobile view) * [ ] Different screen sizes **Test different scenarios**: * [ ] Start with no tasks (empty state) * [ ] Have many tasks (10+) * [ ] Mix of completed and incomplete * [ ] Very long task titles/descriptions ### Performance Check **Verify**: * [ ] App loads quickly * [ ] No lag when adding tasks * [ ] Smooth navigation between screens * [ ] No errors in browser console ## Step 8: Publish Your Buzzy App (15 minutes) ### Pre-Publication Checklist * [ ] All features work in preview mode * [ ] No obvious bugs * [ ] Looks good on mobile and desktop (test browser responsive mode) * [ ] Tested with multiple tasks and edge cases * [ ] Security: Viewers field set correctly on Tasks Datatable * [ ] Happy with the design ### Publish Your App on Buzzy **In Buzzy Workspace**: 1. Go to **Publish tab** 2. Choose deployment option: * **Buzzy Hosted** (recommended for first app): Free hosting on Buzzy's infrastructure * **Custom Domain**: If you have your own domain configured 3. Review app settings (name, icon, etc.) 4. Click "Publish" button 5. Wait for deployment (typically 1-2 minutes) 6. Copy your live app URL {% hint style="success" %} **Buzzy Hosting**: Your app runs on Buzzy's managed Kubernetes infrastructure with automatic scaling. No server maintenance required! [Learn more about deployment](/working-with-buzzy/buzzy-deployment-and-app-stores). {% endhint %} ### Test Published Version **Important**: Always test the live published version * [ ] Open the published URL in a new browser window * [ ] Create a new account or log in * [ ] Test all features again (add, view, complete, delete tasks) * [ ] Verify data saves correctly * [ ] Test on actual mobile device if possible * [ ] Share with a friend to test multi-user functionality **Differences from Preview**: * Published version uses live database * Multiple users can access simultaneously * Performance may differ slightly from preview ## What You've Learned **Core Buzzy skills**: * ✅ Writing effective Buzzy AI prompts * ✅ Reviewing generated Brief, Blueprint, Data, and Design * ✅ Using Buzzy's visual Design editor for refinements * ✅ Testing in preview mode * ✅ Publishing a Buzzy app **Buzzy development patterns**: * ✅ Start with clear Datatable design * ✅ Use Buzzy-specific terms in prompts (Datatable, display rules, actions) * ✅ Test immediately in preview after changes * ✅ Fix issues using visual editor or AI prompts * ✅ Understand when to use visual editor vs AI * ✅ Polish after core features work **Key Buzzy concepts used**: * ✅ Datatables and fields * ✅ Viewers field for security * ✅ Display rules for conditional styling * ✅ Submit actions for forms * ✅ Navigation actions between screens * ✅ Confirmation popups for destructive actions ## Common Issues and Solutions ### Issue: Buzzy AI Didn't Create All Screens **Solution 1 - Prompt Buzzy AI**: ``` Create the task detail screen with: - Large task title heading - Description text - Created date display - "Mark Complete" button that updates the completed field - "Delete" button with confirmation popup - Back button to navigate to task list ``` **Solution 2 - Create manually in Design tab**: * Click "Add Screen" in Design tab * Build the screen using components * Configure actions and navigation ### Issue: Styling Not What You Want **Solution 1 - Use visual editor** (recommended for styling): 1. Go to Design tab 2. Click the component you want to style 3. Adjust properties: colors, sizes, spacing, borders 4. Use Theme tab for app-wide colors and fonts **Solution 2 - Prompt Buzzy AI**: ``` Update the task card component styling: - Background color: white - Border: 1px solid #e0e0e0 - Border radius: 8px - Padding: 16px - Box shadow: 0 2px 4px rgba(0,0,0,0.1) ``` ### Issue: Actions Don't Work (Button Does Nothing) **Solution - Check action configuration**: 1. Go to Design tab 2. Click the button/component 3. Check "Actions" section in properties 4. Verify action is configured (e.g., Submit, Navigate, Update) 5. Check action parameters (which field to update, where to navigate) **Common action fixes**: * **Submit not working**: Check form has field mappings to Datatable * **Delete not working**: Check action targets correct record * **Navigation not working**: Verify screen name is correct ### Issue: Data Not Showing in Preview **Solution - Check Viewers field**: 1. Go to Data tab 2. Click on Tasks Datatable 3. Find "Viewers" field 4. Set to "Current User" or appropriate viewer setting 5. This ensures users can see their own records [Learn more about security](/the-building-blocks/datatables-fields-and-data/security-and-access-control) ### Issue: Too Complex for First Try **Solution**: Simplify scope * Remove optional features (search, sort, categories) * Focus on core CRUD: Create, Read, Update (mark complete), Delete * Skip advanced styling initially * Get basic functionality working first * Add features one at a time later {% hint style="warning" %} **Remember**: You can always use Buzzy's Versions tab to save your current state, experiment, and rollback if needed. Don't be afraid to try things! {% endhint %} ## Next Steps **Now that you've built your first Buzzy app**: ### Extend This App Add more features to your task list (good practice): * **Due dates**: Add date field, display rules for overdue tasks * **Priority levels**: Add dropdown field (High/Medium/Low), sort by priority * **Categories**: Add text field or create Categories Datatable with Linked Table Field * **Task lists**: Create Lists Datatable, use Subtable for tasks within lists * **Recurring tasks**: Add yes/no field and date logic **Practice using both**: * Buzzy AI prompts for new features * Visual editor for refinements ### Try a New Project Build something different to practice Buzzy concepts: * **Recipe collection**: Images, ingredients (Subtable), categories (Linked Table Field) * **Book tracking**: Rating fields, reading status, notes * **Expense tracker**: Amount fields, categories, date ranges, calculations * **Contact list**: Multiple phone numbers (Subtable), tags (Linked Table Field) ### Learn More Advanced Topics **Ready for more complex apps?** * [External API Integration](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/external-api-integration) - Connect to external services using Buzzy Functions * [AI-Powered App Features](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/ai-powered-app) - Add AI capabilities via Buzzy Functions * [Data Design](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals/data-design) - Master Subtables and Linked Table Fields **Want to understand Buzzy better?** * [Buzzy Data Model Overview](/the-building-blocks/datatables-fields-and-data/buzzy-datamodel-overview) * [Buzzy AI Tips](/working-with-buzzy/buzzy-ai/tips) * [Buzzy Project Guide](/working-with-buzzy/buzzy-project-guide) {% hint style="success" %} **Congratulations!** You've built and published your first Buzzy app. You now understand the core Buzzy AI workflow: prompting, reviewing generated structure, using the visual editor, and testing. Every future Buzzy project will use these same patterns—you'll just apply them to more complex problems. {% endhint %} # Short Stay to Care Connect Adapt a proven Short Stay marketplace template into a new app domain with Buzzy Builder MCP. The Short Stay to Care Connect example shows why Builder MCP matters. Instead of asking AI to generate a new standalone codebase from a blank prompt, Builder MCP can inspect and adapt an existing Buzzy app definition. The Buzzy runtime stays maintained by Buzzy; the durable artifact is the app definition: brief, flows, data model, theme, blueprint, screens, functions, widgets, and settings. ## Why Short Stay is a Strong Source Template A short-stay rental marketplace already contains many patterns that other service marketplaces need: * public search * listing cards * provider profiles * availability * booking or request flows * pricing * client and provider roles * admin review * support and policy screens * role-based access That structure can be adapted into another domain. In the public Buzzy case study, Short Stay becomes Care Connect, a care booking app. ## Semantic Mapping | Short Stay concept | Care Connect concept | | ---------------------- | -------------------------------------- | | Property listing | Carer profile | | Guest or rental client | Care client | | Host | Carer or care provider | | Nightly booking | Hourly care booking | | Rental availability | Care availability windows | | Property search | Provider, service, and location search | | Platform admin | Care operations admin | This is not just a copy change. The domain semantics change. A care booking app has stronger privacy and governance requirements than a rental marketplace. Addresses, care needs, identity details, support information, and operational notes need more careful access design. ## Builder MCP Workflow Use this workflow when adapting a template: 1. Export or inspect the source app. 2. Read the source brief, flows, data model, blueprint, theme, screens, functions, and widgets. 3. Write an adaptation plan that maps source concepts to target concepts. 4. Rewrite the target brief first. 5. Adapt flows to the new domain. 6. Adapt the data model, including privacy and permission decisions. 7. Adapt theme and blueprint. 8. Ensure screens from the blueprint. 9. Adapt screen content, bindings, navigation, and actions. 10. Generate sample data. 11. Run Release Tests on search, detail, request/booking, admin, and permission paths. 12. Run Security Review before sharing sensitive workflows. ## What to Review Carefully * Domain terminology: every source-domain label should be adapted or removed. * Data sensitivity: the target app may need Private Data, field-level access, and stricter row access. * Booking logic: nightly stays and hourly care visits do not behave the same way. * Location display: a public property address and a care provider's private address have different risk. * Roles: host, guest, client, provider, carer, admin, and reviewer are not interchangeable. * Custom code: code widgets and functions may contain source-domain assumptions. * Tests: old test paths may still click through but prove the wrong business behavior. ## Related Reading * [How We Turned a Short Stay Rental App into a Care Booking App with Buzzy Builder MCP](https://www.buzzy.buzz/post/short-stay-to-care-connect-buzzy-builder-mcp/) * [Tutorial: Build a carer app from a template](/the-building-blocks/mcp/buzzy-builder-mcp/tutorial-carer-app-from-a-template) * [Buzzy Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp) * [Security Review](/the-building-blocks/security-review) * [Release Tests](/the-building-blocks/release-tests) # Builder MCP Change and Extension Workflow Use Builder MCP to modify existing Buzzy apps, generate code widgets, add Buzzy Functions, and verify changes. Use this example when an app already exists and you need to change it safely. Builder MCP gives an AI coding agent access to the app definition, not just screenshots or vague prose. That means the agent can inspect the current brief, flows, data model, blueprint, theme, screens, functions, constants, and code widgets before proposing or applying a change. ## Good Change Requests Builder MCP is useful for: * adding a new dashboard or workflow screen * changing the data model and then updating dependent screens * creating or updating a code widget * creating a Buzzy Function for an external API * adding constants and secrets for server-side integrations * wiring a function to a screen action * fixing broken bindings or stale navigation * adding Release Tests for important flows * reviewing security before exposing data through REST API or Custom MCP ## Change Loop 1. Pull or inspect the current app definition. 2. Identify the accepted source of truth: brief, flows, data model, blueprint, theme, and screens. 3. Decide whether the requested change affects upstream artifacts. 4. Update the smallest correct artifact first. 5. Push the artifact. 6. Re-read and verify the saved result. 7. Update dependent screens, functions, widgets, or navigation. 8. Test with preview, screenshots, Release Tests, or browser verification. 9. Run Security Review if the change touches sensitive data, roles, APIs, MCP, functions, or external systems. ## Example: Add a Code Widget Ask Builder MCP to inspect the target screen, accepted data model, and current layout before creating the widget. Example instruction: ``` Add a compact service-availability calendar widget to the Carer Profile screen. Use the accepted data model fields for carer availability, do not invent field IDs, and keep the widget scoped to the selected carer row. The widget should show available time windows, unavailable days, and a request-care action that passes the selected slot back to the screen. ``` The agent should update the screen placement first, then the code widget internals, then verify row context, field bindings, shared-state keys, and action output. ## Example: Add a Buzzy Function Use Buzzy Functions for server-side behavior such as external APIs, webhooks, AI provider calls, and privileged logic. Example instruction: ``` Create a Buzzy Function that checks service-area eligibility for a booking request. Inputs: client suburb, requested service type, requested date/time, and selected carer ID. Use constants for any external API keys or base URLs. Return a structured eligibility result with allowed, reason, and suggestedAlternatives. Wire the function to the booking request screen and show a user-friendly message. ``` The agent should declare constants, write the function, align sample payloads to the caller, wire the screen action, and test allowed and denied cases. ## Verification Checklist * The brief still describes the app accurately. * The data model contains the real fields used by screens, functions, and widgets. * Screen bindings use persisted table and field IDs. * Navigation targets exist. * Function inputs match the screen action payload. * Constants do not expose secrets. * Code widgets do not contain stale source-app IDs or labels. * Release Tests cover the changed workflow. * Security Review findings have been read and acted on where relevant. ## Related Pages * [Buzzy Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp) * [Code Widget Examples](/the-building-blocks/code-widget-custom-code/examples) * [Buzzy Functions & Constants](/the-building-blocks/buzzy-functions-and-constants) * [Release Tests](/the-building-blocks/release-tests) * [Security Review](/the-building-blocks/security-review) # External API Integration Master connecting your Buzzy app to external services. Learn Buzzy Functions, API integration, secure key storage, and error handling with step-by-step examples. ## Overview **What we're building**: A weather dashboard app that fetches real-time data from an external weather API using Buzzy Functions. **Non-technical explanation**: Think of APIs like electrical outlets—they provide power (data) that your app can use. Your Buzzy app is like a device that plugs into these outlets to get what it needs. Buzzy Functions act as safe adapters that handle the connection securely. **Time commitment**: 4-6 hours total * Setup and API access: 30 minutes * Building Buzzy Function: 1-2 hours * App interface: 1-2 hours * Testing and refinement: 1-2 hours **Difficulty**: 🟡 Moderate - Requires understanding of APIs and server-side code **Prerequisites**: * ✅ Completed [Hello World App](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/hello-world) * ✅ Understanding of [Data Design](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals/data-design) * ✅ Basic API concepts (HTTP requests, JSON responses) * ✅ Reviewed [Buzzy Functions documentation](/the-building-blocks/buzzy-functions-and-constants) * ✅ Free API key from weather service (we'll get this together) **What you'll learn**: * 🔧 Creating Buzzy Functions (AWS Lambda) for API integrations * 🔒 Using Buzzy Constants for secure API key storage (AES encryption) * 📞 Calling Buzzy Functions from your app actions * 📊 Handling API responses and displaying data in Buzzy apps * ⚠️ Error handling for network failures and API limits * 💾 Caching strategies to improve performance and reduce API calls ## Understanding APIs ### What Is an API? **API** (Application Programming Interface): A way for your app to communicate with external services. **Example uses**: * Get weather data (OpenWeatherMap) * Process payments (Stripe) * Send emails (SendGrid) * Get map data (Google Maps) * AI features (OpenAI) ### API Communication **Your app** → **API Request** → **External Service**\ **External Service** → **API Response** → **Your app** **Request includes**: * Endpoint URL * HTTP method (GET, POST, PUT, DELETE) * Headers (authentication, content type) * Body data (for POST/PUT) **Response includes**: * Status code (200 = success, 404 = not found, 500 = error) * Response data (usually JSON) * Headers (metadata) ## The Weather Dashboard Project **Features**: * Search for city weather * Display current temperature, conditions, humidity * Show 5-day forecast * Save favorite cities * Auto-refresh data **APIs we'll use**: * OpenWeatherMap API (free tier) **Alternative free weather APIs**: * WeatherAPI.com * Tomorrow\.io * Open-Meteo (no API key needed) ## Step 1: Setup (30 minutes) ### Get API Access **OpenWeatherMap**: 1. Go to [openweathermap.org](https://openweathermap.org/) 2. Sign up for free account 3. Go to API keys section 4. Copy your API key 5. Test it works in your browser: ``` https://api.openweathermap.org/data/2.5/weather?q=London&appid=YOUR_API_KEY&units=metric ``` **API limits (free tier)**: * 60 calls per minute * 1,000,000 calls per month * Current weather + 5-day forecast ### Buzzy Integration Strategy **The right way**: Use **Buzzy Functions** for external API calls: **Architecture**: 1. **Buzzy Constants**: Store API key securely with AES encryption 2. **Buzzy Function**: AWS Lambda function (Node.js 22) that calls weather API 3. **Buzzy App**: Buttons/actions call your Function, which returns weather data **Why Buzzy Functions**: * API keys stay secure (never exposed to client) * Server-side execution (no CORS issues) * Can add caching and rate limiting * Professional architecture * Scales automatically on AWS Lambda * Buzzy manages the infrastructure {% hint style="success" %} **Buzzy Functions** are AWS Lambda functions that run server-side. Your Buzzy app calls them via actions, and they can access external APIs, databases, and other services securely. [Learn more about Buzzy Functions](/the-building-blocks/buzzy-functions-and-constants). {% endhint %} ### Plan the Buzzy Application **Data Model in Buzzy**: **Cities Datatable**: * city\_name (text, required) * country\_code (text, e.g., "GB", "US") * latitude (number, optional) * longitude (number, optional) * favorited (yes/no, default no) * last\_updated (date/time, automatic) **WeatherData Datatable** (Subtable of Cities, optional for caching): * temperature (number) * conditions (text, e.g., "Sunny") * humidity (number) * wind\_speed (number) * fetched\_at (date/time) **Weather Data** (not stored, fetched on demand): * temperature * conditions * humidity * wind speed * forecast **Why not store weather data?**: * Changes frequently * Would be outdated quickly * Better to fetch fresh each time ### User Flow ``` User opens app ↓ Sees search bar ↓ Enters city name → Searches ↓ App calls weather API ↓ Displays current weather + forecast ↓ User can save as favorite ↓ Favorite cities show on home screen ``` ## Step 2: Initial Build with Buzzy AI (45 minutes) ### The Prompt **In Buzzy Workspace, create a new app with this prompt**: ``` Create a weather dashboard application: Data Model: - Cities Datatable: - name (text field, required) - country (text field) - latitude (number field) - longitude (number field) - favorited (yes/no field, defaults to no) - last_checked (date/time field) - cached_weather (JSON field, optional, for caching API responses) - Viewers field set to current user Screens: 1. Home screen: - Search input field for city names - Search button - List of favorited cities below search (if any) - Empty state message: "Search for a city to get started" when no favorites - Each favorited city card shows: name, country, last checked time - Click on city card to view weather 2. Weather Detail screen: - City name and country (heading) - Current temperature (large, prominent) - Weather condition description - Additional details: humidity, wind speed - "Add to Favorites" / "Remove from Favorites" button (depending on favorited status) - "Refresh Weather" button - Back button to home Features: - Search functionality (we'll add Buzzy Function call in next step) - Save favorite cities to Cities Datatable - Mobile-responsive design - Clean, modern interface Security: - Use Viewers field so users only see their own favorited cities Note: We'll add the actual API integration using Buzzy Functions in the next step. ``` {% hint style="info" %} **Build UI first**: We're creating the app structure before adding Buzzy Functions. This lets us test navigation and layout, then add the API integration to a working foundation. {% endhint %} ## Step 3: Create Buzzy Function for API Integration (60-90 minutes) ### Step 3a: Store API Key in Buzzy Constants **Security first**: Never hard-code API keys in your app or Buzzy Functions **Create a Buzzy Constant**: 1. In Buzzy Workspace, go to **Settings tab** 2. Click **Constants** section 3. Click **Add Constant** 4. Name: `WEATHER_API_KEY` 5. Value: \[paste your OpenWeatherMap API key] 6. Description: "OpenWeatherMap API key for weather data" 7. Save {% hint style="warning" %} **Buzzy Constants** are encrypted and stored securely. Your Buzzy Functions can access them using the `BUZZYCONSTANTS()` syntax, but they're never exposed to the client. [Learn more about Constants](/the-building-blocks/buzzy-functions-and-constants). {% endhint %} ### Step 3b: Create Buzzy Function for Weather API **Create a new Buzzy Function**: 1. In Buzzy Workspace, go to **Settings tab** 2. Click **Functions** section 3. Click **Add Function** 4. Name: `getWeatherData` 5. Description: "Fetches current weather data from OpenWeatherMap API" 6. Runtime: Node.js 22 **Lambda function code** (minimal example): ```javascript export const handler = async (event) => { try { const cityName = event.cityName; if (!cityName) { return { statusCode: 400, body: JSON.stringify({ error: 'City name is required' }) }; } const apiKey = BUZZYCONSTANTS('WEATHER_API_KEY'); const url = `https://api.openweathermap.org/data/2.5/weather?q=${cityName}&appid=${apiKey}&units=metric`; const response = await fetch(url); if (!response.ok) { if (response.status === 404) { return { statusCode: 404, body: JSON.stringify({ error: 'City not found' }) }; } throw new Error(`API error: ${response.status}`); } const data = await response.json(); return { statusCode: 200, body: JSON.stringify({ city: data.name, country: data.sys.country, temperature: Math.round(data.main.temp), conditions: data.weather[0].main, description: data.weather[0].description, humidity: data.main.humidity, windSpeed: data.wind.speed, lat: data.coord.lat, lon: data.coord.lon }) }; } catch (error) { console.error('Error fetching weather:', error); return { statusCode: 500, body: JSON.stringify({ error: 'Failed to fetch weather data' }) }; } }; ``` **Key points**: * Uses `BUZZYCONSTANTS('WEATHER_API_KEY')` to access secure API key * Returns structured response with statusCode and body * Handles errors appropriately * Node.js 22 runtime (uses fetch natively) {% hint style="info" %} **Buzzy Functions Tips**: * Keep functions focused on one task * Return consistent response format (statusCode + body) * Handle errors gracefully * Use Constants for sensitive data * Test functions before integrating with your app {% endhint %} ### Step 3c: Call Buzzy Function from Your App **In Buzzy Workspace, update your app**: **Option 1 - Use Buzzy AI to integrate**: ``` Update the search functionality to call the getWeatherData Buzzy Function: 1. When user clicks Search button: - Show loading indicator - Call the getWeatherData Function with the city name from search input - Wait for response 2. On successful response: - Hide loading indicator - Navigate to Weather Detail screen - Pass weather data to the detail screen - Optionally save city to Cities Datatable if user wants to favorite it 3. On error response: - Hide loading indicator - Show error message based on error type: * 404: "City '[name]' not found. Please check the spelling." * 500: "Unable to fetch weather data. Please try again later." * Other: "An error occurred. Please try again." 4. Add loading state: - Disable search button while loading - Show spinner or "Loading..." text ``` **Option 2 - Manual configuration in Design tab**: 1. Go to Design tab → Home screen 2. Click on Search button 3. In button properties, add Action: **Call Function** 4. Select Function: `getWeatherData` 5. Set Parameters: `{ "cityName": "[value from search input]" }` 6. Configure success action: Navigate to Weather Detail screen 7. Configure error action: Show error message 8. Add loading indicator component ### Step 3d: Display Weather Data **Update Weather Detail screen**: 1. Go to Design tab → Weather Detail screen 2. Add text components for each piece of weather data 3. Bind components to the data passed from the Function response: * Temperature → `weatherData.temperature` * Conditions → `weatherData.conditions` * Description → `weatherData.description` * Humidity → `weatherData.humidity` * Wind Speed → `weatherData.windSpeed` 4. Add "Add to Favorites" button that saves to Cities Datatable **Test the integration**: 1. Go to Preview mode 2. Search for a city (e.g., "London") 3. Verify weather data displays correctly 4. Test error cases (invalid city name) 5. Check loading indicators work ## Step 4: Add Caching in Buzzy (45 minutes) ### Why Cache? **Problems without caching**: * API calls cost money (or count against limits) * Slow user experience for repeat views * Wastes bandwidth * Risk of hitting rate limits **Caching strategy in Buzzy**: * Store weather data in Cities Datatable (JSON field) * Refresh only if data is old (e.g., > 30 minutes) * Much faster for favorited cities * Reduces Buzzy Function calls by 90%+ ### Implement Caching in Your Buzzy App **The Cities Datatable already has**: * `cached_weather` (JSON field) - stores the weather data * `last_checked` (date/time field) - tracks when data was fetched **Caching logic approach**: **Option 1 - Add cache check to Buzzy Function**: Update your `getWeatherData` Function to accept a `lastChecked` parameter and return cached data if fresh: ```javascript export const handler = async (event) => { try { const { cityName, cachedWeather, lastChecked } = event; // Check if cache is fresh (< 30 minutes old) if (cachedWeather && lastChecked) { const cacheAge = (Date.now() - new Date(lastChecked).getTime()) / 1000 / 60; if (cacheAge < 30) { return { statusCode: 200, body: JSON.stringify({ ...cachedWeather, fromCache: true }) }; } } // Fetch fresh data (same as before) const apiKey = BUZZYCONSTANTS('WEATHER_API_KEY'); const url = `https://api.openweathermap.org/data/2.5/weather?q=${cityName}&appid=${apiKey}&units=metric`; const response = await fetch(url); if (!response.ok) { throw new Error(`API error: ${response.status}`); } const data = await response.json(); return { statusCode: 200, body: JSON.stringify({ city: data.name, country: data.sys.country, temperature: Math.round(data.main.temp), conditions: data.weather[0].main, description: data.weather[0].description, humidity: data.main.humidity, windSpeed: data.wind.speed, lat: data.coord.lat, lon: data.coord.lon, fromCache: false }) }; } catch (error) { return { statusCode: 500, body: JSON.stringify({ error: 'Failed to fetch weather data' }) }; } }; ``` **Option 2 - Handle caching in Buzzy app logic**: Use Buzzy AI to implement caching in your app: ``` Add caching logic to the weather feature: 1. When viewing a favorited city's weather: - Check if cached_weather field has data - Check if last_checked is less than 30 minutes ago - If yes: Display cached weather data without calling Function - If no: Call getWeatherData Function and update cached_weather and last_checked fields 2. Add "Refresh" button on Weather Detail screen: - When clicked, force call to getWeatherData Function - Update cached_weather and last_checked fields - Show "Refreshed just now" message 3. Display cache status: - Show "Updated X minutes ago" on weather screen - Show small indicator when using cached data 4. When favoriting a city: - Save weather data to cached_weather field - Set last_checked to current time 5. When unfavoriting a city: - Optionally clear cached_weather field ``` ### Benefits of Caching **User experience**: * Instant weather display for favorited cities * Less waiting for API responses * Works better on slow connections **Cost savings**: * Fewer Buzzy Function invocations * Fewer external API calls * Better rate limit management **Implementation tips**: * Keep cache duration reasonable (15-30 minutes for weather) * Always provide manual refresh option * Show user when data is cached vs fresh * Clear cache if data becomes stale ## Step 5: Error Handling in Buzzy (30 minutes) ### Comprehensive Error Handling **Error types to handle**: **Network errors**: * Buzzy Function timeout * External API server down * Connectivity issues **API errors**: * Invalid API key (401) * City not found (404) * Rate limit exceeded (429) * Server error (500) **User input errors**: * Empty search * Invalid city name * Special characters ### Implementation in Buzzy **Update your Buzzy app using the Design tab or Buzzy AI**: ``` Improve error handling throughout the app: 1. Search validation on Home screen: - Add validation rule: search field must not be empty - Show error message: "Please enter a city name" - Disable search button if input is empty - Trim whitespace from input - Require minimum 2 characters 2. Function call error handling: - Configure error action on Search button - Based on statusCode from Function response: * 404: Show message "City '[name]' not found. Please check the spelling." * 500: Show message "Unable to fetch weather data. Please try again later." * Timeout: Show message "Request timed out. Please try again." - Add "Try Again" button that re-triggers the search 3. Loading states: - Show loading spinner while Function is executing - Disable search button during loading - Show "Fetching weather data..." message - Hide loading after response (success or error) 4. User feedback: - Use clear, friendly error messages - Avoid technical jargon (don't show "statusCode 500") - Suggest actions to fix (e.g., "Check spelling" or "Try again") - Show errors in popup or banner, not blank screens 5. Graceful degradation: - If Function fails, show cached data if available - Display "Showing cached data - unable to refresh" message - Allow user to retry or view other favorited cities ``` {% hint style="info" %} **Error Handling in Buzzy**: Configure error actions in the Design tab for each Function call. You can show popups, navigate to error screens, or display inline error messages based on the response from your Buzzy Function. {% endhint %} ## Step 6: Testing in Buzzy Preview Mode (60 minutes) ### Test Your Buzzy Function Integration **Test happy path in Preview mode**: * [ ] Search for known city (London, New York, Tokyo) * [ ] Verify loading indicator appears * [ ] Weather data displays correctly on detail screen * [ ] Temperature shows in correct units (metric) * [ ] Can save city to favorites * [ ] Favorited city appears on home screen **Test error cases**: * [ ] Search for invalid city ("Faketown") * Should show "City not found" error message * [ ] Try to search with empty string * Search button should be disabled or show validation error * [ ] Search with special characters ("City!!!") * Should either sanitize or show appropriate error **Test Buzzy Function directly** (in Settings → Functions): * [ ] Test with valid input: `{ "cityName": "London" }` * [ ] Verify successful response with weather data * [ ] Test with invalid input: `{ "cityName": "InvalidCityXYZ123" }` * [ ] Verify 404 error response * [ ] Check function logs for any errors **Test caching (if implemented)**: * [ ] Add city to favorites and view weather * [ ] Note the "last checked" time * [ ] Exit and return within 30 minutes * [ ] Weather should load instantly from cache * [ ] Verify "Updated X minutes ago" displays * [ ] Click "Refresh" button - should fetch fresh data * [ ] Return after 30+ minutes - should fetch fresh data automatically **Test edge cases**: * [ ] City names with spaces ("Los Angeles") * [ ] City names with accents ("São Paulo") * [ ] Multiple searches in quick succession * [ ] Favoriting and unfavoriting cities * [ ] Search for "London" vs "london" (case sensitivity) ### Performance Testing in Preview * [ ] Time how long Buzzy Function calls take (typically 1-3 seconds) * [ ] Compare cached vs non-cached load times * [ ] Test on actual mobile device (use live app URL) * [ ] Verify app remains responsive during Function calls (loading indicators work) * [ ] Check that multiple Function calls don't block the UI {% hint style="success" %} **Testing Buzzy Functions**: You can test Functions independently in Settings → Functions before integrating them into your app. This helps debug issues faster by isolating the Function logic from the app UI. {% endhint %} ## Common Buzzy Function Integration Issues ### Issue: Function Timeout **Symptom**: Function call times out in Buzzy app **Cause**: External API is slow or Function is taking too long **Solution**: * Optimize your Function code * Increase Function timeout in Settings (max 30 seconds) * Add timeout handling to external API calls * Consider breaking complex operations into multiple Functions ### Issue: Constant Not Found **Symptom**: Function returns error about missing BUZZYCONSTANTS **Cause**: Constant name misspelled or not created **Solution**: * Verify Constant exists in Settings → Constants * Check exact spelling in Function code: `BUZZYCONSTANTS('WEATHER_API_KEY')` * Constants are case-sensitive * Redeploy Function after creating/updating Constants ### Issue: Function Returns 500 Error **Symptom**: Function call always returns statusCode 500 **Cause**: Error in Function code or external API **Solution**: * Test Function directly in Settings → Functions with test input * Check Function logs for error messages * Verify external API key is valid * Add try-catch blocks to handle errors gracefully * Return proper statusCode and error message ### Issue: Data Not Passing to Function **Symptom**: Function receives empty or undefined parameters **Cause**: Incorrect parameter configuration in Buzzy app action **Solution**: * In Design tab, check Function call action parameters * Verify parameter names match what Function expects * Use correct syntax to reference form/input values * Test with hardcoded values first to verify Function works ### Issue: Slow Performance **Symptom**: App feels laggy when calling Functions **Cause**: Waiting for Function + external API responses **Solution**: * Add loading indicators immediately when Function is called * Implement caching in Datatables (JSON fields) * Show cached data instantly, refresh in background * Optimize Function code to return quickly * Consider async patterns where appropriate ## Extending the Buzzy Weather App **Additional features to add**: **5-Day Forecast** (Create new Buzzy Function): * Create `getWeatherForecast` Function * Use OpenWeatherMap forecast endpoint * Display forecast cards on weather detail screen * Store forecast in cached\_weather JSON field **Weather Alerts** (Enhance Buzzy Function): * Fetch severe weather alerts in Function * Show alerts on weather detail screen with warning icon * Add alerts field to Cities Datatable * Highlight cities with alerts on home screen **Multiple Units** (App-level preference): * Add "units" field to user profile or app settings * Pass units preference to Buzzy Function * Function converts data based on preference * Toggle between Celsius/Fahrenheit in app **Location Detection** (Use browser geolocation): * Add "Use My Location" button on home screen * Capture latitude/longitude from browser * Create Buzzy Function that accepts coordinates * Fetch weather by coordinates instead of city name **Weather History** (Store in Subtable): * Create WeatherHistory Subtable under Cities * Each Function call saves a history record * Display temperature trends over time * Show graph using Buzzy's chart components or Code Widget **Share Weather** (Export feature): * Format weather data as shareable text * Use browser share API or copy to clipboard * Generate weather card image (via Buzzy Function or external service) * Share to social media ## Best Practices Summary **Buzzy Functions for API Integration**: * ✅ Always use Buzzy Functions for external API calls (never call from client) * ✅ Store API keys in Buzzy Constants (AES encrypted) * ✅ Handle errors gracefully with proper statusCodes * ✅ Implement caching to reduce Function calls and API costs * ✅ Show loading states while Functions execute * ✅ Provide user-friendly error messages (not technical errors) * ✅ Test Functions independently before integrating into app * ✅ Use consistent response format (statusCode + body) **What to avoid**: * ❌ Never expose API keys in app or Function code * ❌ Don't call external APIs directly from Buzzy app (use Functions) * ❌ Don't skip error handling in Functions * ❌ Don't call Functions without showing loading indicators * ❌ Don't assume Functions always succeed * ❌ Don't show raw error messages to users **Buzzy Functions Architecture Benefits**: * Secure API key storage with Constants * Server-side execution (no CORS issues) * Automatic scaling on AWS Lambda * Managed infrastructure by Buzzy * Easy to test and debug independently * Reusable across multiple apps ## Next Steps **Now that you understand Buzzy Functions for API integration**: **Try integrating different APIs**: * [AI-Powered App Features](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/ai-powered-app) - Use Buzzy Functions with OpenAI/Anthropic or other AI providers * Payment APIs - Stripe integration via Buzzy Functions * Email APIs - SendGrid for notifications * SMS APIs - Twilio for text messages * Map APIs - Google Maps or Mapbox **Learn more about**: * [Buzzy Functions & Constants](/the-building-blocks/buzzy-functions-and-constants) - Full documentation * [Security Best Practices](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/compliance-security) - Secure your apps * [App Quality & Performance](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/app-quality-performance) - Optimize your apps **Pattern to remember**: 1. Store secrets in Buzzy Constants 2. Create Buzzy Function to call external API 3. Configure app action to call Function 4. Handle loading states and errors 5. Display results in your app {% hint style="success" %} **Congratulations!** You now know how to connect your Buzzy apps to external services using Buzzy Functions. This pattern works for almost any API—payments, AI, maps, emails, and more. You've learned the professional, secure way to integrate third-party services without exposing credentials or dealing with CORS issues. {% endhint %} # AI-Powered App Features Add AI-powered behavior to a Buzzy app with Buzzy Functions, Constants, code widgets, Builder MCP, tests, and security review. This example is about adding AI behavior inside a Buzzy app. It is different from using AI to build the app. Builder MCP and Buzzy AI help create and edit the app definition. AI-powered app features are runtime capabilities that users interact with, such as summarising a record, drafting a response, classifying a submission, extracting fields from text, or chatting with domain-specific context. ## Pattern Overview Use Buzzy Functions for AI service calls. Keep API keys in Constants. Use standard Buzzy screens and actions for simple workflows. Add code widgets only when the interaction needs a richer UI than standard Buzzy components provide. | Need | Buzzy capability | | -------------------------------------------------------------------- | ------------------------------------------ | | Store API keys and model config | Constants | | Call OpenAI, Anthropic, Gemini, or another provider | Buzzy Function | | Capture user input and selected row context | Buzzy screen action | | Display simple output | Standard fields, modals, or result records | | Display streaming, chat, advanced review, or side-by-side comparison | Code widget | | Change the app definition safely | Builder MCP | | Verify the workflow | Release Tests | | Review sensitive data and access | Security Review | ## Example Use Cases * Summarise a support ticket or case record. * Draft a reply for a reviewer to approve. * Classify an inbound request by type, urgency, or risk. * Extract structured fields from pasted text. * Generate a first-pass checklist or action plan. * Compare two records and highlight differences. * Provide a domain-specific assistant over approved app data. ## Recommended Build Flow 1. Update the brief to describe the AI feature, who uses it, and what the output is allowed to do. 2. Confirm the data model has fields for input, output, status, review, and audit notes where needed. 3. Create Constants for provider keys, model names, base URLs, and safe configuration. 4. Create a Buzzy Function with a clear input and output contract. 5. Wire the function to a screen action. 6. Add a code widget only if the UI needs chat, streaming, rich comparison, or custom controls. 7. Add Release Tests for happy path, error path, and permission-sensitive path. 8. Run Security Review if the feature can access personal, operational, financial, health, education, customer, or internal data. ## Function Contract Keep the function contract explicit. A good AI function declares: * required inputs from the screen or row * constants it depends on * the model/provider it calls * maximum input and output size * what data must never be sent to the provider * structured JSON output * user-facing error messages * sample payloads for tests Example output shape: ```json { "status": "ok", "summary": "Short generated summary for review.", "confidence": "medium", "needsHumanReview": true, "warnings": ["Contains sensitive data; review before sharing."] } ``` ## Prompt and Data Safety Do not send more data to an AI provider than the feature needs. For sensitive apps: * filter row data before calling the function * exclude Private Data unless there is a clear approved reason * keep prompts server-side * avoid placing secrets or private policy text in code widgets * store generated output where the same field-level access rules apply * require human approval for actions that affect users, money, compliance, or records of authority ## Builder MCP Instructions Builder MCP can help generate the function, constants, widget, and screen wiring. Example instruction: ``` Add an AI-assisted case summary feature to the Case Detail screen. Use a Buzzy Function for the model call and Constants for provider configuration. The function should accept case ID, safe case metadata, and non-private review notes only. It should return structured JSON with summary, riskLevel, missingInformation, and suggestedNextSteps. Add a reviewer-only action on Case Detail that calls the function and stores the output in reviewer-visible fields. Add release tests for reviewer success, unauthorized user denial, and provider error handling. Run Security Review after wiring the feature. ``` ## When to Use a Code Widget Use a code widget when standard Buzzy UI is not enough: * conversational chat * streaming response display * side-by-side diff or compare UI * token/cost meters * rich prompt controls * interactive review workflows Do not use a code widget just to call the AI provider directly from the browser. The provider call should stay in a Buzzy Function so keys and sensitive logic stay server-side. ## Testing Checklist * Function succeeds with realistic input. * Function fails safely when the provider is unavailable. * Function rejects missing or malformed input. * Unauthorized users cannot trigger the action. * Sensitive fields are not sent unexpectedly. * Generated output is stored in fields with correct access rules. * Release Tests cover the main workflow. * Security Review findings are addressed before release. ## Related Pages * [Builder MCP Change and Extension Workflow](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/builder-mcp-change-workflows) * [Buzzy Functions & Constants](/the-building-blocks/buzzy-functions-and-constants) * [Code Widget Examples](/the-building-blocks/code-widget-custom-code/examples) * [Security Review](/the-building-blocks/security-review) * [Release Tests](/the-building-blocks/release-tests) # Secure and Compliant Workflow App Use Buzzy field security, viewer policies, Private Data, and audit trails to build secure review workflows. **Complexity**: Advanced\ **Time**: 6-10 hours\ **Purpose**: Build an app that routes sensitive records through controlled review steps while limiting who can see and change each field. Buzzy can support sophisticated workflows where different people see different parts of the same record. This is useful for legal review, compliance review, health record triage, employee case management, financial approvals, vendor onboarding, and other data-processing workflows. The goal is not to make the app "compliant" by turning on one feature. The goal is to combine Buzzy controls so the app supports least privilege, data minimization, auditability, and controlled disclosure. ## Pattern Overview Use this pattern when a row moves through stages and each stage needs a different access profile. Example roles: * **Submitters** create a record and see only their own safe fields. * **Legal reviewers** see contract, dispute, or regulatory fields. * **Compliance reviewers** see risk, evidence, and approval fields. * **Managers** see status and decision fields, but not every sensitive detail. * **Admins** configure the app and review audit evidence. Example structure: | Control | Buzzy capability | | ------------------------------- | ------------------------------------------------------- | | Who can open the app | App privacy and app roles | | Who can see a row | Row Viewers and Team Viewers | | Who can see a field | Field view | | Who can change a field | Field edit | | Who can see sensitive values | Private Data plus Field view | | Who can reveal sensitive values | Sensitive Private Data reveal controls | | What happened | Private Data audit trail | | What integrations receive | REST API, MCP, and Async API server-side output shaping | ## Build the Workflow ### 1. Model the review groups Create teams or organizations that match the real review boundaries. Examples: * Legal Reviewers * Compliance Reviewers * Clinical Reviewers * HR Case Managers * Finance Approvers Use teams when membership is managed inside a single organization. Use organizations when the app separates users by tenant, department, customer, region, or external partner. ### 2. Configure row-level access Use row access to decide who can see the record at all. For example, a case row might include: * the creator or submitter * the assigned reviewer * a Legal Reviewers team * a Compliance Reviewers team * a Team Viewers field that changes as the workflow stage changes Row access is the first gate. A user must be allowed to see the row before field access or Private Data reveal is considered. ### 3. Configure field-level access Use **Field view** and **Field edit** to make each stage least-privilege. Use **Workspace > Data > Fields** to review the selected datatable's field policies in a grid. This helps you check that Legal, Compliance, Manager, and Submitter fields have the expected View, Edit, and Private Data settings before testing the workflow. When a View or Edit option includes **Viewers**, select the relevant **Viewer teams / organizations** in the field editor. This is how a field becomes visible to a concrete group such as Legal Reviewers or Compliance Reviewers. The selected team or organization is still evaluated after row access, so it does not make the row visible by itself. Example field policy: | Field | Field view | Field edit | | -------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------- | | Request summary | All participants | Creators & Viewers only | | Legal notes | Admins, Authors, Creators & Viewers only, with Legal Reviewers selected | Same option, with Legal Reviewers selected | | Compliance finding | Admins, Authors, Creators & Viewers only, with Compliance Reviewers selected | Same option, with Compliance Reviewers selected | | Final approval | Admins, Authors, Creators & Viewers only, with Managers selected | Same option, with Managers selected | | Internal audit notes | Admins, Authors, Creators & Viewers only, with Compliance Reviewers selected | Same option, with Compliance Reviewers selected | Field edit should never be broader than Field view. If a user cannot view a field, they should not be able to edit it. For common policy meanings and examples, see [Private Data field access settings](/the-building-blocks/datatables-fields-and-data/private-data#field-access-settings). ### 4. Mark sensitive fields as Private Data Use **Basic Private Data** for personal identifiers or contact details that should be minimized in normal output. Use **Sensitive Private Data** for values that should be hidden by default and revealed only by authorized users. Examples: | Field | Private Data classification | | -------------------------- | --------------------------- | | Customer email | Basic Private Data | | Patient date of birth | Sensitive Private Data | | Legal advice | Sensitive Private Data | | Compliance evidence | Sensitive Private Data | | Employee medical note | Sensitive Private Data | | Uploaded identity document | Sensitive Private Data | Private Data applies to scalar fields and file/image fields. For denied users, file names, metadata, storage keys, and signed URLs are not exposed. ### 5. Keep safe workflow metadata separate Private Data is intentionally not a good place for search, sort, or vector search. Keep safe operational fields separate, such as: * status * priority * assigned reviewer * due date * region * risk category * review outcome This lets builders create dashboards and queues without exposing sensitive raw values. ### 6. Use audit trail for evidence Sensitive Private Data reveal attempts are audited. Admins can inspect reveal activity for a row from **Workspace > Data**: 1. Open the datatable row. 2. Expand **Metadata**. 3. Select **Load audit trail**. The audit trail records who attempted access, which row and field were involved, the classification, purpose, time, and outcome. It does not store the revealed value. Use this evidence for access reviews, incident investigations, and compliance checks. ### 7. Test every surface Test as each user type: * runtime app screens * Workspace data view * REST API calls * MCP tools * Async API or Code Widget reads * exports and AI-generated contexts The server should shape output before data leaves Buzzy. A denied user should see masked or hidden values, not raw values hidden only by client-side display logic. ## Example Prompt ``` Create a compliance case review app. The app should let employees submit cases, then route cases to Legal Reviewers and Compliance Reviewers. Use teams for Legal Reviewers and Compliance Reviewers. Create a Case datatable with: - summary, status, priority, due date, assigned reviewer, and review outcome as non-private workflow fields - submitter email as Basic Private Data - legal notes, compliance findings, evidence summary, and uploaded evidence files as Sensitive Private Data Use row viewers and team viewers so only the submitter, assigned reviewers, and relevant review teams can open each case. Use Field view and Field edit so: - Legal Reviewers can view and edit legal notes - Compliance Reviewers can view and edit compliance findings and evidence summary - Managers can view final approval fields - Submitters cannot view internal legal or compliance notes Include screens for submitter case creation, reviewer queues, case detail, legal review, compliance review, manager approval, and admin audit review. ``` ## Related Topics * [Security and Access Control](/the-building-blocks/datatables-fields-and-data/security-and-access-control) * [Private Data](/the-building-blocks/datatables-fields-and-data/private-data) * [Building Compliance-Ready Apps](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/compliance-security) * [REST API microappdata](/developing-and-extending-buzzy/buzzy-rest-api/rest-api/microapp-data-operations/microappdata) * [MicroAppChild API](/developing-and-extending-buzzy/buzzy-rest-api/rest-api/microapp-data-operations/microappchild) * [Async API + React HTML Components](/the-building-blocks/code-widget-custom-code/new-async-api-+-react-html-components) * [MCP](/the-building-blocks/mcp) # Buzzy Agents Placeholder for Buzzy Agents examples. Buzzy Agents examples are coming soon. Use this placeholder to distinguish future in-app agents from the current Builder MCP workflow: * **Builder MCP** helps an AI agent build, adapt, inspect, and edit the app definition. * **Custom MCP** exposes an existing app to external MCP clients. * **Buzzy Agents** will cover agent workflows that run inside Buzzy app experiences. When Buzzy Agents examples are ready, this section should show: * how an app-side agent is configured * what data, tools, and functions it can access * how users interact with it * how permissions, Private Data, and audit evidence work * how to test and review agent behavior before release For now, use [Buzzy Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp), [Buzzy Functions](/the-building-blocks/buzzy-functions-and-constants/buzzy-functions), and [Code widgets](/the-building-blocks/code-widget-custom-code) for agent-assisted and AI-powered app work. # Universal Data Connector Placeholder for Universal Data Connector examples. Universal Data Connector examples are coming soon. This section will cover how Buzzy apps connect to external data sources through a reusable connector pattern. Until the dedicated docs are available, use the current extension options: * [Buzzy Functions](/the-building-blocks/buzzy-functions-and-constants/buzzy-functions) for server-side API calls, transformations, and webhooks. * [Buzzy REST API](/developing-and-extending-buzzy/buzzy-rest-api) when external systems need to read or update Buzzy app data. * [Buzzy Custom MCP](/the-building-blocks/mcp/buzzy-custom-mcp) when an existing app should expose governed tools to MCP clients. * [Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp) when an AI agent should change the app definition itself. When Universal Data Connector examples are ready, include: * source setup and authentication * mapping external objects to Buzzy datatables and fields * sync direction and conflict rules * permissions and Private Data handling * error handling and retry behavior * testing and release guidance # Best Practices Master essential best practices for building production-quality Buzzy applications. Learn what to avoid, quality standards, and sustainable development approaches. ## Why Best Practices Matter Buzzy AI and Builder MCP can help create apps quickly, but **fast doesn't automatically mean good**. Without following best practices, you risk creating apps with poor data models, security vulnerabilities, and future maintenance nightmares. **Non-technical explanation**: Building an app with Buzzy AI is like cooking with a high-powered blender. The tool is fast and powerful, but you still need to follow recipes (best practices) to create something delicious rather than an inedible mess. Speed without technique leads to problems. **The speed trap**: ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%% graph TD A[Buzzy Builds Fast] --> B{Follow Best
Practices?} B -->|Yes| C[Quality App
✓ Secure
✓ Maintainable
✓ Scalable] B -->|No| D[Problem App
✗ Security holes
✗ Data issues
✗ Tech debt] style C fill:#6c6,stroke:#333,color:#000 style D fill:#f88,stroke:#333,color:#000 ``` **This section covers**: * **What NOT to build**: Learn to recognize unsuitable projects before wasting time * **App quality & performance**: Standards for production Buzzy applications * **Security & compliance**: Protect users and meet legal requirements * **Sustainable practices**: Build apps you can maintain and grow **Who benefits from best practices**: * 🎯 **Novices**: Avoid common pitfalls that experienced developers already know * 🚀 **Intermediate builders**: Level up from "it works" to "it works well" * 👥 **Teams**: Establish consistent standards across projects * 📈 **Product managers**: Understand quality tradeoffs and requirements ## The Four Core Principles ### 1. Quality Over Speed ⚡→✨ **The temptation**: "Just ship it as fast as possible!" **The reality**: Fast today = slow, painful debugging tomorrow **The danger**: AI-assisted building makes it easy to move faster than your planning, testing, and review process. **Visual comparison**: ``` Fast Without Quality: Day 1: Ship app (2 hours) 🚀 Day 2: Users find bugs 🐛 Day 3: Emergency fixes (4 hours) 🔧 Day 4: More bugs found 🐛🐛 Day 5: Reputation damaged 😞 Total: 6+ hours + lost trust Fast With Quality: Day 1: Build with best practices (3 hours) 🏗️ Day 2: Launch smoothly 🎉 Day 3: Happy users ✅ Day 4: Minor tweaks (30 mins) 🔧 Day 5: Growing user base 📈 Total: 3.5 hours + gained trust ``` **The balance**: * ✅ Ship MVP quickly using the right build path * ✅ But don't skip security (Viewers fields, authentication) * ✅ Test critical paths in preview mode before publishing * ✅ Plan for growth (good data model design from start) * ❌ Don't obsess over perfection (ship and iterate) **Practical example**: ``` Building a task management app: TOO SLOW (Perfectionism): - Spend 2 days on pixel-perfect design - Build 20 features nobody asked for - Never ship because "not ready" TOO FAST (Reckless): - Accept first AI-generated output without review - Skip testing in preview mode - Publish without security (no Viewers fields) - Users access each other's data BALANCED (Best Practice): - Spend 30 mins reviewing Buzzy AI output - Test core features in preview (1 hour) - Configure Viewers fields for security - Ship with 5 essential features - Iterate based on user feedback ``` ### 2. Understand What You Build 🧠 **The temptation**: "Buzzy AI generated it, so it must be perfect!" **The reality**: YOU are responsible for your app, not the AI. Buzzy AI is a powerful assistant, but you're the architect. **The danger**: Blindly accepting AI output without understanding the data model leads to problems later **Why you must review**: ```mermaid graph TD A[Buzzy AI Generates App] --> B{Do you
understand it?} B -->|Yes| C[Good Foundation
Can modify confidently
Can fix issues
Can explain to others] B -->|No| D[Blind Dependency
Can't modify safely
Can't debug issues
Tech debt accumulates] style C fill:#6c6,color:#333 style D fill:#f88,color:#333 ``` **What to review** (takes 10-15 minutes, saves hours later): * **Brief**: Does the AI understand your requirements correctly? * **Blueprint**: Are all needed screens listed? Is navigation logical? * **Data tab**: * Do the Datatables make sense? * Are relationships correct (Subtables for 1:M, Linked Fields for N:M)? * Are Viewers fields configured for security? * Any redundant or missing fields? * **Design tab**: * Do screens display the right data? * Are display rules hiding/showing correctly? * Are actions configured properly (submit, navigation)? **Practice checklist**: * [ ] Review Buzzy AI's Brief - correct understanding? * [ ] Check Blueprint - all screens needed? * [ ] Inspect Data model - relationships make sense? * [ ] Verify Viewers fields - security configured? * [ ] Test in preview mode - does it work? * [ ] Refine using visual editor - fix issues * [ ] Document complex parts - notes for later **When to use visual editor vs AI prompts**: * Visual editor: Quick fixes, layout tweaks, field adjustments * AI prompts: Adding features, restructuring, complex changes * See: [AI vs Manual Edits](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/ai-vs-manual-edits) ### 3. Security Is Not Optional 🔒 **The temptation**: "I'll add security later, just want to get it working first" **The reality**: Security added later is like installing a foundation after building the house—expensive, incomplete, and dangerous **The catastrophe waiting to happen**: ``` Common scenario without security: Day 1: Build task app, skip Viewers field setup Day 2: Publish to production Day 3: User A can see User B's private tasks Day 4: Data breach discovered Day 5: Panic mode, emergency fixes Day 6: User trust destroyed Day 7: Legal issues emerging Could have been prevented: 5 minutes configuring Viewers fields ``` **Security best practices for Buzzy**: | Security Layer | Implementation | Time Cost | Skip Risk | | ------------------------- | ---------------------------- | --------------- | -------------------------- | | **Viewers fields** | Add to sensitive Datatables | 2 min per table | HIGH - Users see all data | | **Team Viewers** | For Organizations/Teams | 5 min setup | MEDIUM - Wrong team access | | **Authentication** | Buzzy handles automatically | 0 min | LOW - Built-in | | **Input validation** | Required fields, field types | 5 min per form | MEDIUM - Bad data | | **Constants for secrets** | Store API keys securely | 2 min per key | HIGH - Credentials exposed | **Non-negotiable security rules**: 1. **NEVER expose credentials**: Use Buzzy Constants, not hardcoded values 2. **ALWAYS use Viewers fields**: For any data users shouldn't share 3. **VALIDATE all input**: Required fields, data types, max lengths 4. **TEST permissions**: Verify users can't access unauthorized data 5. **ENCRYPT sensitive data**: Use Buzzy Constants for API keys **Practical implementation**: ``` Example: Building a healthcare appointment app BAD (Insecure): - Patients Datatable: No Viewers field - Result: All users see all patient records - HIPAA violation, lawsuit risk GOOD (Secure): - Patients Datatable: Viewers field = current user + assigned doctor - Team Viewers field = patient's care team - Result: Users only see their own records or those they're authorized for - Compliant, secure, trustworthy ``` See: [Compliance & Security](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/compliance-security) for comprehensive security guide ### 4. Think Long-Term 🔮 **The temptation**: "This is just a quick prototype, doesn't need to be perfect" **The reality**: Today's "quick prototype" becomes tomorrow's production app serving thousands of users **The trap**: ``` Week 1: "It's just a prototype" (sloppy data model) Week 2: "Let's test with real users" (gaining traction) Week 3: "People love it!" (100 active users) Week 4: "Let's officially launch" (now it's production) Week 5: "Why is it so slow?" (data model issues) Week 6: "We need to rebuild it" (expensive) Wish we had: Designed it properly from the start (30 extra minutes) ``` **Long-term thinking pays off**: **Short-term mindset** (costs more later): * ❌ Quick, messy data model → Hard to add features later * ❌ No documentation → Can't remember why things work * ❌ Skip Buzzy Versions → Can't rollback when needed * ❌ Hardcode everything → Can't adapt to changes * ❌ No testing → Discover bugs in production **Long-term mindset** (saves time overall): * ✅ Clean data model → Easy to extend and modify * ✅ Document decisions → Future you understands past choices * ✅ Use Buzzy Versions → Safe experimentation and rollback * ✅ Use Constants → Easy configuration changes * ✅ Test properly → Catch issues before users do **The Buzzy advantage** for long-term success: * Buzzy maintains the Core Engine automatically (React, dependencies, security) * YOU maintain: Your data model, business logic, and user experience * Focus your long-term thinking on what matters: your app's unique value **Practical long-term practices**: 1. **Good data model design**: Think about growth and relationships 2. **Clear naming**: Use descriptive Datatable and field names 3. **Document complexity**: Note why you made specific decisions 4. **Use Buzzy Versions**: Save snapshots before major changes 5. **Plan for scale**: Will this work with 1000 users? 10,000? See: [Maintenance & Long-Term Success](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/maintenance) ## The Three Pillars ### [What Not to Build](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/what-not-to-build) Learn to recognize: * Ideas unsuitable for Buzzy's no-code platform * Projects that need traditional development * When to say "no" * How to scope appropriately **Read this first** to avoid wasting time on impossible projects. *** ### [App Quality & Performance](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/app-quality-performance) Ensure your Buzzy applications: * Follow best practices for data modeling * Perform well under load * Are maintainable and scalable * Use resources efficiently **Critical for** production Buzzy applications. *** ### [Compliance & Security](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/compliance-security) Protect your users and business: * Buzzy's server-level security fundamentals * Data protection with Organizations/Teams * Legal compliance * Privacy requirements **Non-negotiable** for any Buzzy application handling user data. ## Common Anti-Patterns ### Anti-Pattern 1: "Move Fast and Break Things" **Problem**: Prioritizing speed over everything **Result**: * Security vulnerabilities * Data loss * User trust issues * Technical debt **Better approach**: Move fast AND build well ### Anti-Pattern 2: Trusting Buzzy AI Blindly **Problem**: Accepting all Buzzy AI output without review **Result**: * Poor data model design * Missing security fields (Viewers, Team Viewers) * Inefficient Datatable structures * Issues in production **Better approach**: Review generated structure, refine in visual editor ### Anti-Pattern 3: No Testing **Problem**: Skipping testing in preview/live modes to save time **Result**: * Bugs reach users * Broken workflows * Data issues * Emergency fixes **Better approach**: Strategic testing (see [Testing Approaches](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/testing-approaches)) ### Anti-Pattern 4: Ignoring Feedback **Problem**: Not listening to users or app testers **Result**: * Building wrong features * Poor user experience * Missing critical data model issues **Better approach**: Seek and incorporate feedback ### Anti-Pattern 5: Feature Bloat **Problem**: Adding features without considering complexity **Result**: * Overcomplicated data models * Slow app performance * Confused users * Never shipping **Better approach**: Focus on core value, iterate with Buzzy ## Quality Checklist Before considering your app "done": ### Functionality * [ ] All core features work * [ ] Edge cases handled * [ ] Error messages clear * [ ] Data saves correctly * [ ] Navigation makes sense ### Performance * [ ] Loads in < 3 seconds * [ ] Responsive to user actions * [ ] No lag or stuttering * [ ] Works on slow connections * [ ] Handles expected user volume ### Security * [ ] No exposed credentials * [ ] Input validation in place * [ ] Authentication working * [ ] Authorization enforced * [ ] HTTPS configured ### User Experience * [ ] Mobile-friendly * [ ] Intuitive interface * [ ] Clear instructions * [ ] Helpful error messages * [ ] Consistent design ### App Quality * [ ] Clear data model structure * [ ] Proper use of Subtables and Linked Fields * [ ] Security fields properly configured (Viewers, Team Viewers) * [ ] Critical workflows documented * [ ] No redundant Datatables or fields ### Maintenance * [ ] Deployment process documented * [ ] Buzzy's built-in Versions feature understood * [ ] Rollback plan using Versions tab * [ ] Known issues documented * [ ] Team access properly configured ## Progressive Enhancement ### Start With Basics **Version 1.0** (MVP): * Core features only * Basic security * Simple design * Essential functionality **Ship it, get feedback** ### Add Quality **Version 1.1**: * Polish user experience * Add error handling * Improve performance * Fix reported bugs **Iterate based on real usage** ### Scale and Optimize **Version 2.0**: * Advanced features * Optimization * Analytics * Scaling infrastructure **Build what users actually need** ## Learning from Mistakes ### When Things Go Wrong **Don't**: * Hide mistakes * Blame the AI * Rush fixes without understanding * Repeat same errors **Do**: * Acknowledge the issue * Understand root cause * Fix properly * Document lesson learned * Prevent recurrence ### Post-Mortem Practice After major issues: **1. What happened?** * Timeline of events * What broke? * Who was affected? **2. Why did it happen?** * Root cause * Contributing factors * Warning signs missed **3. How to prevent?** * Process changes * Technical improvements * Monitoring additions **4. Action items** * Specific, assignable tasks * Deadlines * Verification method ## Continuous Improvement ### Regular Reviews **Weekly**: * Review user feedback * Check error logs * Assess performance * Plan fixes **Monthly**: * App structure review (data model, screens) * Buzzy handles core engine updates automatically * Security configuration review * Feature prioritization **Quarterly**: * Data model architecture review * Major restructuring if needed (with Buzzy Versions backup) * Strategic planning * Team retrospective ### Metrics That Matter **Track**: * User satisfaction (NPS, ratings) * Error rates * Performance metrics * Security vulnerabilities * Time to fix issues * Feature adoption **Don't obsess over**: * Number of Datatables (focus on good design) * Number of features (focus on useful ones) * Deployment frequency (for its own sake) ## Working With Buzzy AI Effectively ### Better Prompting **Vague**: * "Make it better" * "Fix the bug" * "Add security" **Specific**: * "Improve error message for invalid email field to say 'Please enter valid email address like '" * "Fix the bug where clicking Save twice creates duplicate records - add display rule to disable button after first click" * "Add Viewers field to the Documents Datatable so users can only see their own documents" ### Iterative Refinement **Process**: 1. Generate with Buzzy AI 2. Review Brief, Blueprint, Data, Design 3. Test functionality in preview mode 4. Refine specific issues (AI prompts or visual editor) 5. Test again in preview/live 6. Accept when good enough **Don't**: * Accept first output without reviewing data model * Over-iterate on perfection * Make changes without testing in preview mode ## When to Get Help ### Seek Expert Review For: **Critical systems**: * Payment processing (use Buzzy Functions for secure API integration) * Healthcare data (HIPAA compliance) * Financial applications * Identity management beyond Buzzy's built-in auth **Complex features**: * Advanced Buzzy Functions integration * Complex data model relationships * Performance optimization at scale * Advanced security beyond standard Viewers/Team Viewers **Stuck situations**: * Tried multiple Buzzy AI prompts * Data model not working as expected * Security configuration questions * Buzzy Functions architecture decisions ### Don't be afraid to ask **Resources**: * Buzzy community * Stack Overflow * Developer forums * Security experts * Professional developers ## Summary Principles **1. Build Responsibly** * Security first * User privacy * Data protection * Ethical considerations **2. Build Maintainably** * Clear data model design * Good documentation of workflows * Buzzy handles core updates automatically * Managed integrations (Buzzy Functions, APIs) **3. Build Iteratively** * Start simple * Ship and learn * Improve continuously * Listen to users **4. Build Smartly** * Right tool for job * Know limitations * Recognize when to stop * Balance speed and quality ## Multi-Environment Development For production applications, consider using multiple deployment environments to separate development work from what your users see. Buzzy's Software Config Management (SCM) feature enables professional development workflows where you can build and test in a Development environment, then push changes to Staging for QA, and finally to Production when ready. **Why use multiple environments?** Separating your environments provides several benefits: you can experiment freely in Development without affecting production users, perform thorough QA testing in a Staging environment that mirrors production, and control exactly when changes go live. This approach reduces risk and gives you confidence that what works in testing will work for your users. **Typical workflow**: 1. Build and test new features in your Development environment 2. Save a version when the feature is ready 3. Push the version to Staging for QA testing 4. After approval, push to Production **Key consideration**: When pushing between environments, all configuration including URLs and API endpoints are transferred as-is. Before pushing upstream, verify that any environment-specific settings (like Lambda function URLs or webhook addresses) are set to their production values. For detailed setup instructions and best practices, see [Software Config Management](/working-with-buzzy/buzzy-deployment-and-app-stores/software-config-management). ## Next Steps Choose your focus area: * **Planning a project?** → [What Not to Build](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/what-not-to-build) * **Building a Buzzy app?** → [App Quality & Performance](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/app-quality-performance) * **Handling user data?** → [Compliance & Security](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/compliance-security) {% hint style="success" %} **Remember**: Best practices aren't about perfection—they're about making good decisions consistently. Build well enough for your current needs, but always with an eye toward future maintainability and user trust. With Buzzy's no-code platform, you benefit from a professionally maintained core engine that handles updates automatically, letting you focus on your app's unique value. {% endhint %} # What Not to Build Master how to recognize unsuitable projects for Buzzy before wasting time. Learn what works, what doesn't, and why—saving months of frustration. ## The Harsh Truth About No-Code Limits Not every idea is suitable for Buzzy's no-code platform. Some projects will waste your time, money, and enthusiasm if you try to build them with Buzzy, no matter how capable the AI-assisted build path is. **Non-technical explanation**: Buzzy is like a Swiss Army knife—incredibly versatile and powerful for many tasks, but you wouldn't use it to cut down a tree or perform surgery. Similarly, Buzzy excels at business applications, internal tools, and data-driven apps, but it's not designed for real-time games, blockchain, or operating systems. **Why this guide matters**: ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%% graph TD A[Recognize Wrong Projects Early] --> B[Save Time & Money] C[Try Wrong Projects] --> D[Months of Frustration] D --> E[Give Up or Start Over] style A fill:#6c6,stroke:#333,color:#000 style B fill:#6c6,stroke:#333,color:#000 style C fill:#f88,stroke:#333,color:#000 style E fill:#f88,stroke:#333,color:#000 ``` **This guide helps you**: * ✅ Recognize unsuitable projects **before** you start * ✅ Understand **why** they won't work with Buzzy * ✅ Find better alternatives for those projects * ✅ Save months of frustration and wasted effort * ✅ Focus on projects where Buzzy excels {% hint style="info" %} **Important context**: Buzzy's no-code approach eliminates many traditional development problems: * ✅ No tech debt from AI-generated code (Buzzy doesn't generate code) * ✅ No dependency management nightmare (Buzzy handles the Core Engine) * ✅ No framework update hell (Buzzy maintains React, infrastructure) However, Buzzy still has appropriate use cases. This guide helps you identify projects beyond Buzzy's scope or any no-code platform's capabilities. {% endhint %} ## Red Flags: Don't Build This ### 1. 🎮 Real-Time Competitive Games **Examples of what NOT to build**: * First-person shooters (FPS games) * Fighting games (like Street Fighter) * Racing games (like Mario Kart) * Fast-paced platformers (like Super Mario) * Rhythm games (like Guitar Hero) * Real-time strategy with hundreds of units * Multiplayer battle royale games **Why it won't work with Buzzy**: * Requires 60+ frames per second (FPS) performance for smooth gameplay * Frame-perfect timing essential (millisecond precision) * Complex physics engines for realistic movement and collisions * Sophisticated real-time networking for multiplayer synchronization * Specialized rendering pipelines for 3D graphics * Custom game loops and update cycles * Low-level performance optimization required **Non-technical explanation**: Building a fast-paced game in Buzzy is like trying to run a 100-meter sprint in snowshoes. The tool wasn't designed for speed and precision at that level. Games that require split-second reactions and smooth 60 FPS performance need specialized game engines built specifically for that purpose. **What you'd actually get if you tried**: * ❌ Laggy, unresponsive experience (choppy movement) * ❌ No proper game loop (can't update 60 times per second) * ❌ Poor performance (slow loading, stuttering) * ❌ Broken physics (objects don't behave realistically) * ❌ Unusable for competitive play * ❌ Frustrated users expecting smooth gameplay **Use these instead**: * **Unity** (most popular, great for 2D/3D games) * **Godot** (free, open-source, beginner-friendly) * **Unreal Engine** (high-end 3D graphics) * **GameMaker Studio** (great for 2D games) **Current docs focus**: The Building Examples section now focuses on business apps, workflow apps, template adaptation, integrations, code widgets, security review, and release testing. For game-specific projects, use a dedicated game engine unless the experience is mainly a simple data-backed quiz, puzzle, or turn-based workflow. *** ### 2. Enterprise-Scale Applications (Initially) **Examples**: * Full ERP systems * Hospital management systems * Banking platforms * Large-scale CRM **Why it won't work (as first project)**: * Extreme complexity * Thousands of business rules * Regulatory compliance * Mission-critical reliability * Years of traditional development **What you'd get with Buzzy**: * Simplified toy versions * Missing critical features * Potentially inadequate for enterprise scale * Cannot meet all regulatory requirements **Reality check**: These take teams of experienced developers years to build **Better approach**: Start with ONE module in Buzzy, validate, expand gradually. Buzzy excels at individual business process apps, not entire ERPs. *** ### 3. Apps Requiring Advanced Computer Vision **Examples**: * Facial recognition systems * Medical image analysis * Autonomous vehicle software * Quality control inspection * AR applications with object tracking **Why it won't work with Buzzy**: * Requires specialized ML models * Needs training data and expertise * Performance-critical processing * Specialized hardware often needed **What you'd get**: * Generic API calls (via Buzzy Functions) * No real computer vision capability * Poor performance * Unreliable results **Use instead**: Specialized CV frameworks, pre-trained models, hire ML engineers **Note**: Buzzy CAN integrate pre-trained APIs (like OpenAI Vision) via Buzzy Functions for simple use cases. *** ### 4. Blockchain/Cryptocurrency Applications **Examples**: * Custom cryptocurrencies * NFT marketplaces * DeFi protocols * Smart contract platforms **Why it won't work with Buzzy**: * Requires deep blockchain expertise * Security is absolutely critical * Complex cryptographic concepts * Regulatory minefield * Not Buzzy's design purpose **What you'd get**: * Insecure implementations * Fundamental misunderstandings * Potential for losing money * Legal issues **Reality**: Blockchain development requires specialized knowledge and specialized platforms. Don't learn with real money at stake. *** ### 5. Operating Systems or Low-Level System Software **Examples**: * Custom operating systems * Device drivers * Kernel modules * Embedded firmware **Why it won't work with Buzzy**: * Requires systems programming expertise * Memory management critical * Hardware-specific knowledge needed * Debugging extremely difficult * Completely outside Buzzy's scope **Reality**: This is expert-level programming requiring specialized languages (C, Rust, Assembly). No-code platforms like Buzzy aren't designed for this. *** ### 6. 🏥 Mission-Critical Medical/Aviation/Industrial Control **Examples**: * Medical device software * Aviation control systems * Industrial safety systems * Life support systems **Why you absolutely cannot**: * Lives depend on it * Regulatory requirements * Certification needed * Liability issues * Requires formal verification **Legal reality**: You likely cannot legally build these without certifications, teams, and formal processes **Don't even try**: Seriously, don't. *** ### 7. "Facebook/Instagram/TikTok Killer" **Examples**: * Social network to replace Facebook * Video platform to replace YouTube * Marketplace to replace Amazon **Why it won't work with Buzzy**: * Network effects are real * Requires millions of users * Massive infrastructure costs * Years of development * Huge marketing budget **What you'd get**: * Basic CRUD app * No recommendation engine * Missing 99% of features * Cannot compete on scale **Reality**: These companies have thousands of engineers and billions in investment **Better**: Build for a specific niche with Buzzy, not "replace \[giant company]" *** ## Yellow Flags: Proceed with Caution ### 1. Marketplace Platforms (Two-Sided) **Examples**: * Uber for X * Airbnb for Y * Freelancer marketplace **Challenges**: * Chicken-and-egg problem (need buyers and sellers) * Payment processing complexity * Dispute resolution * Trust and safety * Marketing to two audiences **Can work if**: * You have one side already (sellers or buyers) * Very specific niche * Simple to start * MVP is truly minimal **Reality**: Most fail due to business, not technical, issues *** ### 2. Content Platforms (YouTube/Medium-like) **Examples**: * Video hosting platform * Podcast hosting * Image sharing site **Challenges**: * Storage costs scale quickly * Bandwidth expensive * Content moderation required * Copyright issues * Discovery/recommendation systems **Can work if**: * Very small, specific audience * Users pay for hosting * Start with tiny storage limits * Use third-party hosting initially *** ### 3. Real-Time Collaboration Tools **Examples**: * Google Docs competitor * Collaborative design tools * Real-time whiteboarding **Challenges**: * Operational transformation complexity * Conflict resolution * Performance at scale * Offline sync **Can work if**: * Use existing libraries (Yjs, Automerge) * Simple use case * Small number of simultaneous editors * Can tolerate some lag *** ### 4. Complex ML/AI Features **Examples**: * Custom recommendation engines * Advanced NLP * Computer vision features * Predictive analytics **Challenges**: * Requires ML expertise * Need training data * Model training infrastructure * Ongoing maintenance **Can work if**: * Use pre-trained APIs (OpenAI, etc.) * Simple use cases * Willing to pay for API usage * Don't need custom models *** ## Green Flags: Good Ideas for AI Development ### ✅ Internal Business Tools **Examples**: * Team task management * Internal dashboards * Simple CRM for small team * Inventory tracking **Why it works**: * Small user base * Forgiving users (your team) * Can iterate quickly * Clear requirements * Immediate feedback *** ### ✅ Niche Community Apps **Examples**: * Local sports league tracker * Book club organizer * Recipe sharing for specific diet * Neighborhood event calendar **Why it works**: * Specific, well-defined need * Small, engaged audience * Simple feature set * Personal connection to users *** ### ✅ Personal Productivity Tools **Examples**: * Habit tracker * Expense logger * Reading list manager * Learning progress tracker **Why it works**: * You're the user (fast feedback) * Simple data model * Clear success criteria * Low pressure *** ### ✅ Simple SaaS Tools **Examples**: * Invoice generator * Simple form builder * Appointment scheduler * Simple survey tool **Why it works**: * Well-understood problem * Many successful examples * Can start simple * Clear business model *** ## The Reality Check Questions Before starting any project, honestly answer: ### 1. Complexity Reality Check **Ask**: "How many screens will this need?" * < 10 screens: Probably doable with Buzzy * 10-30 screens: Challenging but possible with Buzzy * 30+ screens: Very difficult, requires excellent planning ### 2. User Base Reality Check **Ask**: "How many users do I need for this to work?" * Just me: Great! * < 100: Doable * 100-1000: Challenging * 1000+: Need professional development ### 3. Revenue Reality Check **Ask**: "Will users pay for this?" * If no: Why are you building it? * If yes: How much? Is it worth your time? * If "ads": Need massive scale (probably not suitable) ### 4. Competition Reality Check **Ask**: "What do competitors have?" * None: Might be no market, or great opportunity * A few small ones: Good validation * Giant companies: Are you sure? ### 5. Time Reality Check **Ask**: "How long will this take?" * Hours-days: Probably realistic * Weeks: Possible with good planning * Months: Are you sure you understand the scope? * Years: This is not an AI project ### 6. Skill Reality Check **Ask**: "Do I need expertise I don't have?" * No: Great! * Yes, but I can learn basics: Okay (Buzzy documentation can help) * Yes, need deep expertise: Buzzy might not be the right tool ## The Simplification Test Take your idea and answer: **"What's the absolute minimum version that's still useful?"** **Example transformations**: "Social network for artists" → "Gallery where artists can post and comment" "Uber for dog walking" → "Directory of dog walkers with booking calendar" "AI-powered investment platform" → "Portfolio tracker with basic insights" "Video editing platform" → "Simple video trimming tool" **If the simplified version**: * Still sounds complex: Not ready for Buzzy * Sounds too simple to be useful: Original idea too ambitious * Sounds about right: Good candidate for Buzzy! ## When to Stop **Stop immediately if**: 1. **You're losing money fast** * Cloud costs spiraling * Not generating revenue * Can't afford to continue 2. **It's taking 10x longer than expected** * Original estimate: 2 weeks * Current status: 5 months in, still broken * This is a sign the idea is too complex 3. **You keep hitting fundamental walls** * Can't make core feature work * Performance is terrible * Keep having to compromise on essentials 4. **Users consistently don't want it** * Can't get people to use it * Feedback is "I don't need this" * You're the only user 5. **Legal/compliance issues** * Lawyers telling you to stop * Regulatory requirements you can't meet * Liability concerns ## Pivot Strategies **When your idea isn't working**: ### Option 1: Simplify Radically * Remove 80% of features * Focus on one thing * Make it really simple ### Option 2: Change Audience * From general public to specific niche * From consumers to businesses * From global to local ### Option 3: Change Scope * From platform to tool * From marketplace to directory * From social network to community ### Option 4: Stop and Learn * This idea doesn't work (yet) * What did you learn? * What would you do differently? * What's the next project? ## Success Stories: Simple Ideas That Worked **Real examples of successful "simple" apps**: **Wordle**: One puzzle per day, very simple **Notion templates**: Pre-built templates, not the platform **Carrd**: Simple one-page websites **Buffer**: Just schedule social posts (initially) **Calendly**: Just schedule meetings **What they have in common**: * Solve one specific problem * Do it simply and well * Started very small * Grew based on user feedback ## Final Wisdom ### Build What You Can Actually Build **Not**: "I want to build the next Facebook" **Yes**: "I want to build a directory of local coffee shops with ratings" ### Start Smaller Than You Think **Your first instinct** is probably still too big. **Halve it**: That's probably still too big. **Halve it again**: Now you might be close. ### The Goal Isn't the Idea **Wrong goal**: Build the perfect, complete application **Right goal**: Ship something useful, learn, iterate ### Know When to Walk Away Some ideas don't work. That's okay. You learned: * What doesn't work * How to evaluate ideas * What to try next **Failure is data**, not a verdict on your abilities. ## Next Steps * **Have a good idea?**: [Design Fundamentals](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/design-fundamentals) * **Need to build quality**: [App Quality & Performance](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/app-quality-performance) * **Need to stay secure**: [Compliance & Security](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/compliance-security) * **Ready to start building**: [Building Examples](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples) {% hint style="success" %} **Remember**: Saying "no" to bad ideas makes room for good ones. The best developers aren't those who can build anything—they're those who know what to build and what to skip. Buzzy's no-code platform is powerful for the right projects, but it's not magic—it still requires good judgment about scope and complexity. {% endhint %} # App Quality & Performance Master app quality and performance for Buzzy. Learn data model efficiency, display rules optimization, and performance best practices for great user experiences. ## Why Quality Matters with Buzzy **Non-technical explanation**: Building an app is like cooking a meal. Even with professional kitchen equipment (Buzzy's Core Engine), you can still create a bad meal if your recipe (app design) is poor. Good ingredients arranged badly still taste bad. Similarly, even though Buzzy handles the technical infrastructure, you control the user experience through your design decisions. While Buzzy handles the underlying code quality automatically through its professionally-maintained Core Engine, you're still responsible for your app's design quality and performance. **The cost of poor app design**: ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'16px'}}}%% graph TB A[Poor App Design] --> B[Slow Loading] A --> C[Confusing Navigation] A --> D[Inefficient Data] B --> E[Users Leave] C --> E D --> E E --> F[App Fails] G[Quality App Design] --> H[Fast Performance] G --> I[Clear Navigation] G --> J[Efficient Data] H --> K[Happy Users] I --> K J --> K K --> L[App Succeeds] style F fill:#f88,stroke:#333,color:#000 style L fill:#6c6,stroke:#333,color:#000 ``` Poor app design leads to: * ❌ Slow user experiences (pages take too long to load) * ❌ Confusing navigation (users can't find what they need) * ❌ Inefficient data structures (queries take too long) * ❌ Poor user adoption (people don't use the app) * ❌ Frustrated users (negative feedback, abandonment) **This guide covers**: * 🏗️ Data model quality (Subtables and Linked Table Fields best practices) * 🎯 Display rules and actions optimization * ⚡ Buzzy Functions performance tuning * 📊 Performance considerations for Buzzy apps * ✅ Complete app quality checklist (focused on design, not code) ## Data Model Quality ### 1. Efficient Use of Subtables **Subtables** are Buzzy's implementation of one-to-many relationships. Design them well: **Good Subtable design**: * Invoices → Invoice Lines (each invoice has multiple line items) * Blog Posts → Comments (each post has multiple comments) * Projects → Tasks (each project has multiple tasks) * Organizations → Departments → Teams → Members (multiple nested levels) **Common mistakes**: * Using Linked Table Fields when you should use Subtables * Loading many nested levels all at once (creates expensive queries and joins) * Not considering query performance for large Subtables **Best practices for nested Subtables**: * Use Subtables for true parent-child relationships * **Deep nesting is OK** - you can nest more than 2-3 levels * **The key**: Use progressive disclosure - don't load all levels at once * **Good approach**: First screen shows 1-2 levels, then user drills down to see next level * **Bad approach**: Loading 10 items in a tree with 5+ nested levels all at once (monster queries!) * **Example pattern**: * Screen 1: Show Organizations list * Screen 2: Show selected Organization → Departments (1 level) * Screen 3: Show selected Department → Teams (1 level deeper) * Screen 4: Show selected Team → Members (1 level deeper) * Consider pagination for Subtables with many records * Use meaningful names for Subtable fields * Test query performance when nesting deeply - drill down progressively rather than showing everything ### 2. Proper Use of Linked Table Fields **Linked Table Fields** enable many-to-many relationships. Use them correctly: **Good Linked Field design**: * Products ↔ Categories (products in multiple categories) * Students ↔ Classes (students take multiple classes) * Articles ↔ Tags (articles have multiple tags) * Projects ↔ Team Members (members work on multiple projects) **Common mistakes**: * Using Subtables when you need Linked Table Fields * Not storing additional relationship data when needed * Creating circular dependencies **Best practices**: * Use Linked Table Fields for true many-to-many relationships * Consider using a junction table (Subtable + Linked Field) when you need to store relationship metadata * Use meaningful field names that indicate the relationship * Set appropriate display labels for the linked field ### 3. Field Validation and Formulas Use Buzzy's built-in validation and JSONATA formulas effectively: **Field validation**: * Mark required fields appropriately * Use field type validation (email format, number ranges) * Set appropriate min/max lengths for text fields **JSONATA formula examples**: **Calculations**: ``` quantity * price ``` **Conditional logic**: ``` user.highestRole = "admin" ? "Full Access" : "Limited Access" ``` **Date validation**: ``` dueDate > $now() ? "Valid" : "Date must be in future" ``` **Best practices**: * Use formulas for calculations rather than storing computed values * Validate data at the field level when possible * Use clear, readable formula expressions * Test formulas with edge cases [Learn more about Formula fields](/the-building-blocks/datatables-fields-and-data/advanced-fields/formula) ### 4. Display Rules Best Practices Display rules control when UI elements are visible in Buzzy. Use them wisely: **Good display rule patterns**: * Show "Edit" button only for record owners: `viewers contains $currentUser._id` * Show admin features for admins: `$currentUser.highestRole = "admin"` * Show subtable when parent has data: `invoice.invoice_lines.$count() > 0` * Conditional field display: `status = "approved"` **Common mistakes**: * Overly complex nested conditions * Not testing all user scenarios * Forgetting to test with different user roles * Using display rules for security (use Viewers fields instead) **Best practices**: * Keep display rules simple and readable * Use display rules for UX, not security * Test with different user roles and data states * Document complex display rule logic ### 5. Actions Best Practices Actions in Buzzy control what happens when users interact with your app: **Common action types**: * **Submit actions**: Save form data to Datatables * **Navigation actions**: Move between screens * **CRUD actions**: Create, read, update, delete operations * **Function calls**: Execute Buzzy Functions **Good action patterns**: * Validate before submit (use required fields) * Provide user feedback (success/error messages) * Clear navigation flows (back buttons, home navigation) * Confirmation for destructive actions (delete confirmations) **Common mistakes**: * No feedback after actions complete * Confusing navigation (users get lost) * No undo for destructive operations * Missing error handling **Best practices**: * Always provide user feedback * Use consistent action patterns throughout your app * Test all action paths thoroughly * Show loading states for slow operations ## Performance Best Practices for Buzzy Apps ### 1. Data Model Performance **Efficient data relationships**: * Design Subtables with performance in mind * Avoid deeply nested relationships (more than 3 levels) * Use Linked Table Fields appropriately * Consider query patterns when designing data model **Query optimization**: * Use filters at the Datatable level * Implement pagination for large datasets * Limit Subtable record counts when possible * Use indexes effectively (Buzzy handles this automatically for common fields) **Example patterns**: * ✅ Good: Orders datatable with OrderItems subtable (1-2 levels) * ❌ Bad: Company → Department → Team → Projects → Tasks (5 levels) **Best practices**: * Design flat data structures when possible * Use Linked Table Fields to avoid deep nesting * Test with realistic data volumes * Monitor query performance in production ### 2. Screen Design Performance **Efficient screen layouts**: * Limit the number of components on a single screen * Use pagination for large lists * Implement search and filter features * Load data progressively when possible **Mobile performance**: * Buzzy's React Native apps include offline-first architecture * Test on actual mobile devices * Optimize images for mobile bandwidth * Consider data usage for mobile users **Best practices**: * Show 20-50 items per page (not thousands) * Use infinite scroll or "Load More" buttons * Implement search for large datasets * Test with slow network connections * Optimize image sizes (compress before uploading) ### 3. Buzzy Functions Performance When using Buzzy Functions (AWS Lambda), optimize for performance: **Function best practices**: * Keep functions focused and small * Minimize dependencies (reduces cold start time) * Use environment variables for configuration * Implement error handling and retries * Set appropriate timeout values **Example efficient function**: ```javascript export const main = async (event) => { // Validate input quickly if (!event.body?.email) { return { statusCode: 400, body: { error: "Email required" } }; } // Do work const result = await processEmail(event.body.email); // Return promptly return { statusCode: 200, body: result }; }; ``` **Performance tips**: * Cache API responses when appropriate * Use Promise.all() for parallel operations * Return errors quickly (don't waste time) * Test function performance before deploying [Learn more about Buzzy Functions](/the-building-blocks/buzzy-functions-and-constants/buzzy-functions) ### 4. Caching Strategies **Where to cache**: **Browser cache**: * Static assets (images, CSS, JS) * API responses (for appropriate duration) **Server cache**: * Database query results * External API calls * Computed values **Example**: ```javascript const cache = new Map(); async function getWeatherData(city) { const cacheKey = `weather:${city}`; const cached = cache.get(cacheKey); if (cached && Date.now() - cached.timestamp < 30 * 60 * 1000) { return cached.data; // Use cache if < 30 minutes old } const data = await fetchWeatherFromAPI(city); cache.set(cacheKey, { data, timestamp: Date.now() }); return data; } ``` ## Reviewing Buzzy Functions Code When you use Buzzy Functions (AWS Lambda) for external integrations, you write minimal Lambda code. Here's what to review: ### Common Issues in Buzzy Functions **1. Hard-Coded API Keys (Critical Security Issue)** ❌ **Never do this**: ```javascript export const main = async (event) => { const apiKey = "sk-abc123..."; // EXPOSED! const response = await fetch(`https://api.service.com/data`, { headers: { 'Authorization': `Bearer ${apiKey}` } }); return { statusCode: 200, body: await response.json() }; }; ``` ✅ **Always use Buzzy Constants**: ```javascript export const main = async (event) => { const apiKey = process.env.API_KEY; // From Buzzy Constants if (!apiKey) { return { statusCode: 500, body: { error: "API key not configured" } }; } const response = await fetch(`https://api.service.com/data`, { headers: { 'Authorization': `Bearer ${apiKey}` } }); return { statusCode: 200, body: await response.json() }; }; ``` **2. Missing Error Handling** ❌ **Assumes everything works**: ```javascript export const main = async (event) => { const data = JSON.parse(event.body); const result = await externalAPI(data.email); // What if email is missing? return { statusCode: 200, body: result }; }; ``` ✅ **Validates input and handles errors**: ```javascript export const main = async (event) => { // Validate input const data = JSON.parse(event.body || '{}'); if (!data.email) { return { statusCode: 400, body: { error: "Email required" } }; } try { const result = await externalAPI(data.email); return { statusCode: 200, body: result }; } catch (error) { console.error('API call failed:', error); return { statusCode: 500, body: { error: "Service unavailable" } }; } }; ``` **3. Missing Timeout Handling** Buzzy Functions have execution time limits. Handle slow operations: ```javascript export const main = async (event) => { const timeout = 5000; // 5 seconds const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), timeout); try { const response = await fetch(url, { signal: controller.signal }); clearTimeout(timeoutId); return { statusCode: 200, body: await response.json() }; } catch (error) { if (error.name === 'AbortError') { return { statusCode: 504, body: { error: "Request timeout" } }; } throw error; } }; ``` **4. Poor Response Structure** Buzzy expects consistent response formats from Functions: ✅ **Good pattern**: ```javascript return { statusCode: 200, body: { success: true, data: result } }; ``` [Learn more about Buzzy Functions best practices](/the-building-blocks/buzzy-functions-and-constants/buzzy-functions) ## Buzzy App Review Checklist Before publishing your Buzzy app: **Data Model**: * [ ] Subtables used correctly for 1:M relationships? * [ ] Linked Table Fields used correctly for N:M relationships? * [ ] Field types appropriate (text, number, date, etc.)? * [ ] Required fields marked properly? * [ ] Formula fields working correctly? **Security**: * [ ] Viewers fields configured for sensitive data? * [ ] Team Viewers set up for team-based access? * [ ] Organizations configured for multi-tenant apps? * [ ] Server-level security (not just display rules)? * [ ] No sensitive data exposed inappropriately? **User Experience**: * [ ] Navigation clear and intuitive? * [ ] Empty states handled (what shows when no data)? * [ ] Error messages helpful to users? * [ ] Loading states shown for slow operations? * [ ] Mobile experience tested? **Functionality**: * [ ] All core features work correctly? * [ ] Actions provide user feedback? * [ ] Display rules working as intended? * [ ] Forms validate input appropriately? * [ ] Destructive actions require confirmation? **Performance**: * [ ] Large lists use pagination? * [ ] Search/filter available for large datasets? * [ ] Images optimized and compressed? * [ ] Buzzy Functions respond quickly? * [ ] Tested with realistic data volumes? **Buzzy Functions** (if applicable): * [ ] Constants used for API keys (not hardcoded)? * [ ] Error handling implemented? * [ ] Functions tested before deployment? * [ ] Timeout values appropriate? * [ ] Return values structured correctly? ## Improving Your Buzzy App Over Time ### When to Redesign **Redesign when**: * Data model is causing problems * Users find navigation confusing * Performance is poor with real data * Adding features is difficult due to design **Don't redesign when**: * App works well for users * Performance is acceptable * Just cosmetic preferences * Time better spent on new features ### Improvement Process for Buzzy Apps **1. Test current functionality** (ensure you don't break what works) **2. Make one change at a time** (data model first, then screens, etc.) **3. Test after each change** (use Buzzy's preview mode) **4. Use Buzzy's version control** (Versions tab for safe rollback) **Example: Improving a Buzzy app's data model** **Before (Poor design)**: * Single "Orders" Datatable with text fields for items * Manual calculation of totals in display rules * Difficult to query individual items * Can't report on product popularity **After (Better design)**: * "Orders" Datatable with order metadata * "OrderItems" Subtable (child of Orders) for line items * Formula fields for automatic total calculations * Easy to query and report on products **Benefits of improved Buzzy data model**: * Better data integrity * Automatic calculations via formulas * Easier to extend with new features * Better reporting capabilities * Follows Buzzy best practices (Subtables for 1:M relationships) **For Buzzy Functions refactoring**: * Keep functions small and focused * Extract complex logic into helper functions * Use Constants for all configuration * Add comprehensive error handling * Test thoroughly before deploying ## Monitoring Your Buzzy App ### What to Monitor **User Experience**: * How users navigate your app * Where users get stuck * Error reports from users * Feature usage patterns * Session duration **Performance**: * App load times (web and mobile) * Screen navigation speed * Buzzy Function response times * Data query performance **Data Quality**: * Data integrity issues * Missing required fields * Invalid data entries * Orphaned records ### Monitoring Approaches **User feedback**: * Built-in feedback mechanisms * User testing sessions * Support ticket analysis * Direct user conversations **Buzzy platform monitoring**: * Check Buzzy Function logs * Review error reports * Monitor deployment status * Track usage statistics **Testing with real scenarios**: * Test with production-like data volumes * Simulate real user workflows * Test on actual mobile devices * Test with slow network connections ## Performance Optimization Process **1. Measure First** * Use Buzzy's preview mode to test app speed * Test with realistic data volumes * Check on actual mobile devices * Monitor Buzzy Function execution times **2. Focus on Biggest Impact** * Optimize screens users visit most * Fix slowest data queries first * Improve most complex Buzzy Functions **3. Make One Change at a Time** * Test each optimization in preview * Use Buzzy's version control to rollback if needed * Document what you changed and why **4. Set Performance Goals** * Screen load < 3 seconds * Buzzy Functions < 1 second * Search results < 2 seconds * Mobile app responsive and smooth ## Buzzy App Organization ### Datatable Organization **Good organization**: * Group related Datatables logically * Use clear, descriptive names * Document complex relationships * Keep data model diagram updated **Example structure**: ``` Users (main user table) Organizations (multi-tenant) Teams (within organizations) Projects (linked to teams) └─ Tasks (subtable of projects) └─ Comments (subtable of projects) Products (main products table) Categories (linked via Linked Table Field) Orders └─ Order Items (subtable) ``` ### Screen Organization **Good patterns**: * List → Detail → Edit flow * Clear navigation hierarchy * Consistent naming conventions * Group related screens **Example**: * Project List * Project Detail * Project Edit * Project Tasks (subtable view) * Task Detail * Task Edit ## Testing for Quality in Buzzy ### Testing Approach **Functional testing**: * Test all user workflows * Verify display rules work correctly * Confirm actions complete successfully * Test with different user roles **Data testing**: * Test with empty state (no data) * Test with large datasets * Test edge cases (very long text, special characters) * Verify Subtables and Linked Fields work correctly **User testing**: * Have real users try the app * Watch where they get confused * Note what they expect vs. what happens * Iterate based on feedback ## Continuous Improvement **Regular activities for Buzzy apps**: **Weekly**: * Review user feedback * Check Buzzy Function logs * Test new features added * Monitor app performance **Monthly**: * Review data model efficiency * Optimize slow screens * Update Buzzy Functions if needed * Review security settings **Quarterly**: * Major UX improvements * Data model refactoring if needed * Performance optimization * User testing sessions ## Next Steps * **Security best practices**: [Compliance & Security](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/best-practices/compliance-security) * **Understanding maintenance**: [Maintenance with Buzzy](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/maintenance) * **Testing strategies**: [Testing Approaches](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/testing-approaches) * **Building examples**: [Hello World App](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/hello-world) {% hint style="success" %} **Remember**: App quality in Buzzy isn't about code quality—it's about design quality. Buzzy handles the code. You handle the data model, user experience, and business logic. Focus on making your app intuitive, performant, and valuable to users. Quality compounds over time. {% endhint %} # Compliance & Security Build compliance-ready Buzzy apps with server-side access control, Private Data, audit trails, API/MCP governance, and deployment controls. Buzzy gives app builders platform-level security controls for protecting data. These controls can help support compliance programs such as SOC 2, GDPR, HIPAA, and internal security policies, but they do not make an app compliant by themselves. Compliance depends on the complete system: app configuration, deployment controls, policies, procedures, contracts, staff training, incident response, backups, monitoring, and legal review. {% hint style="warning" %} This documentation explains Buzzy capabilities that can support compliance and security requirements. It is not legal, privacy, or compliance advice. {% endhint %} ## Deployment and Data Residency Options Private Data controls protect values before they leave the Buzzy server, but compliance also depends on where that server, database, storage, backups, and logs run. Buzzy supports deployment models that can help organizations meet data residency, isolation, and operational control requirements: * **Single-tenant Buzzy Deployments**: run apps on a dedicated Buzzy deployment with its own URL, database cluster, storage, and service endpoints. You can choose an available deployment region for the database cluster and deployment. See [Create and manage Deployments](/working-with-buzzy/buzzy-deployment-and-app-stores/create-and-manage-deployments). * **Enterprise deployments**: run Buzzy on your own infrastructure, including your own cloud environment or on-premise infrastructure, when your organization needs deeper control over network, hosting, security, or operational requirements. See [Introduction to deployment](/advanced-deployment-settings/installation/deployment/introduction-to-deployment). Plan availability and commercial options are listed on the [Buzzy pricing page](https://www.buzzy.buzz/pricing#deployment). Use this deployment choice alongside app-level Private Data, row access, field access, audit retention, and organizational security processes. ## What Buzzy Provides Buzzy helps app builders configure security without writing custom authorization code. Core capabilities include: * app privacy and role controls * row-level access using creators, Viewers, Team Viewers, teams, and organizations * field-level view and edit controls * Private Data classification and redaction * encryption at rest for sensitive Private Data * audited reveal of Sensitive Private Data * server-shaped REST API and MCP output * attachment gating for Private Data files and images * configurable audit retention The key design principle is server-side enforcement. Data that a user should not access should not be sent to that user. ## Capability Mapping | Control need | Buzzy capability | App-builder responsibility | | ---------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | Access control | App privacy, roles, row access, Field view/edit | Choose restrictive defaults and test with different users | | Least privilege | Field view/edit and team/org viewer policies | Give users access only to the rows and fields required for their work | | Data minimization | Private Data classification and server-side output shaping | Mark fields correctly and avoid exposing data in unnecessary screens, APIs, prompts, or exports | | Encryption at rest | Sensitive Private Data encryption | Configure encryption keys and run repair when settings change | | Audit evidence | Private Data reveal audit trail | Review row audit trails from Workspace Data and define operational review procedures | | API governance | REST responses follow row, field, and Private Data rules | Authenticate integrations as the correct user and avoid over-broad service accounts | | MCP governance | MCP tools follow the same data shaping rules | Enable MCP only for apps and users that should expose data to AI assistants | | Retention | TTL-based Private Data audit retention | Set retention to match organizational and legal requirements | | Data residency and isolation | Single-tenant Deployments and Enterprise deployment options | Choose the deployment model, region, infrastructure, and contracts that match the compliance target | ## Recommended Security Model Use these layers together: 1. Make the app private unless it truly needs public access. 2. Use Organizations and Teams for customer, department, or tenant boundaries. 3. Configure datatable "Who can view" so users only fetch rows they should see. 4. Use Viewers or Team Viewers for row-specific sharing. 5. Use Field view/edit for least privilege inside each row. 6. Mark personal, sensitive, regulated, or confidential fields as Private Data. 7. Keep searchable/sortable operational metadata separate from encrypted Private Data. 8. Test runtime, workspace, REST API, and MCP access as multiple users. 9. Review audit trail entries for Sensitive Private Data reveals. ## Private Data for Compliance-Ready Apps Private Data is the main Buzzy capability for reducing accidental exposure of sensitive fields. * **Basic Private Data** is masked or redacted by the server before output. * **Sensitive Private Data** is hidden by default, can be revealed only by permitted users, and records audit entries. * Sensitive Private Data is encrypted at rest. * Private Data file and image fields hide attachment metadata and signed URLs from denied users. Use Basic Private Data for personal contact or identifier fields. Use Sensitive Private Data for fields that would create higher risk if exposed, such as health details, financial information, government identifiers, or confidential notes. See [Private Data](/the-building-blocks/datatables-fields-and-data/private-data) for configuration steps. ## Secure Review Workflows Compliance-ready apps often need more than a single "private" switch. Use Buzzy row access, field access, teams, organizations, and Private Data together. For example: * a submitter creates a case and sees only safe status fields * the Legal Reviewers team can view and edit legal analysis fields * the Compliance Reviewers team can view and edit risk and evidence fields * managers can approve outcomes without seeing every sensitive detail * admins can inspect Private Data audit entries from Workspace Data Use row Viewers and Team Viewers to decide who can open each record. Use Field view and Field edit to decide which fields those users can see or change. Use Private Data for fields that need server-side masking, hidden-by-default reveal, encryption, file URL gating, or audit evidence. See [Secure and Compliant Workflow App](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/secure-compliance-workflow) for a complete app-builder example. ## API, MCP, AI, and Export Considerations Compliance-oriented apps need the same protection outside the visual app runtime. Buzzy applies Private Data output shaping to normal outbound paths, including REST API responses, MCP tools, exports, generated previews, and AI prompt/context builders. Design guidance: * Do not assume an integration should receive all row fields. * Authenticate REST and MCP calls as the actual user or a narrowly scoped integration user. * Avoid using broad Admin accounts for integrations unless the integration genuinely needs Admin access. * Do not place Sensitive Private Data in search, sort, or vector fields. * Test denied users through REST and MCP, not only through the browser UI. ## Example Compliance-Oriented Patterns ### Healthcare Notes * Restrict patient note rows to clinicians and care teams. * Mark patient identifiers as Basic Private Data. * Mark clinical observations and health details as Sensitive Private Data. * Require purpose text for reveals. * Review audit logs for reveal activity. ### Customer Data Platform * Use Organizations to separate customers. * Use Team Viewers for account teams. * Mark customer emails and phone numbers as Basic Private Data. * Keep customer status, lifecycle stage, and account owner as non-private fields for reporting. ### HR Case Management * Restrict rows by creator, HR team, or assigned case team. * Mark employee contact details as Basic Private Data. * Mark salary, leave, performance, and medical details as Sensitive Private Data. * Use Field edit so only HR can update protected fields. ## Compliance Notes by Framework ### SOC 2 Buzzy controls can support access control, logical access review, audit evidence, change control, and data protection requirements. Your organization still needs operational evidence, review procedures, incident response, vendor management, and deployment controls. ### GDPR Buzzy controls can support data minimization, access restriction, auditability, and protection of personal information. Your organization still needs a lawful basis, notices, data subject request processes, retention policy, and processor/controller agreements. ### HIPAA Buzzy controls can support technical safeguards such as access control, audit controls, encryption, and transmission security. HIPAA use also requires appropriate deployment, policies, business associate agreements, risk analysis, and administrative safeguards. For regulated workloads, review deployment model and region choices early. Private Data is one application-layer control; single-tenant or Enterprise deployment choices determine where the supporting infrastructure, database, object storage, and operational controls run. ## Security Checklist * [ ] App privacy is appropriate for the data being stored. * [ ] Datatable row access is restrictive by default. * [ ] Viewers or Team Viewers are used for row-specific sharing. * [ ] Field view and edit policies follow least privilege. * [ ] Field edit is not broader than field view. * [ ] Private Data fields are classified as Basic or Sensitive where needed. * [ ] Sensitive Private Data has a clear purpose. * [ ] Private Data file/image fields are tested with denied users. * [ ] Search, sort, export, REST API, MCP, and AI paths have been tested. * [ ] Audit retention is configured for the deployment. * [ ] Datatable repair has been run after changing classification or encryption settings. * [ ] The app security model is documented for reviewers and operators. ## Related Docs * [Accessibility at Buzzy](/accessibility) * [Security and Access Control](/the-building-blocks/datatables-fields-and-data/security-and-access-control) * [Private Data](/the-building-blocks/datatables-fields-and-data/private-data) * [REST API microappdata](/developing-and-extending-buzzy/buzzy-rest-api/rest-api/microapp-data-operations/microappdata) * [MicroAppChild API](/developing-and-extending-buzzy/buzzy-rest-api/rest-api/microapp-data-operations/microappchild) * [Model Context Protocol](/the-building-blocks/mcp) * [Create and manage Deployments](/working-with-buzzy/buzzy-deployment-and-app-stores/create-and-manage-deployments) * [Enterprise deployment](/advanced-deployment-settings/installation/deployment/introduction-to-deployment) * [Buzzy pricing](https://www.buzzy.buzz/pricing#deployment) # Overview Buzzy gives you several ways to create and keep improving an application. You can start from a prompt, a Figma design, a Builder MCP workflow, or the no-code Workspace. All paths create or edit the same underlying Buzzy app definition: brief, flows, data model, blueprint, theme, screens, functions, widgets, people, settings, tests, and security configuration. The important idea is that Buzzy does not leave you with a one-off pile of generated code. Buzzy stores a structured app definition that the Buzzy runtime can render, test, secure, publish, and keep maintaining. ## Ways to Create an App | Starting point | Best when | How to start | How to keep iterating | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | [Buzzy AI prompt workflow](/working-with-buzzy/buzzy-ai) | You have an app idea and want a working first version quickly. | Describe the app, audience, core data, roles, and workflows. | Use the Workspace to refine brief, flows, data, screens, theme, tests, security, functions, widgets, and settings. | | [Buzzy for Figma](/working-with-buzzy/buzzy-for-figma) | You have a designed UI, a design team, or want direct design control. | Mark up a Figma file with the Buzzy plugin and publish it as a working app. | Keep editing in Figma, publish updates, and use Buzzy Workspace for data, access, testing, security, and extensions. | | [Buzzy Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp) | You want an AI coding agent such as Codex or Claude Code to build, adapt, inspect, or modify a Buzzy app in stages. | Connect the agent to Builder MCP and follow the staged workflow. | Let the agent inspect current artifacts, make bounded changes, validate, test, and open reviewable updates. | | No-code Workspace editing | You want to build or maintain directly in Buzzy without using Figma or an external agent. | Open the Workspace and edit Data, Design, Theme, People, Settings, Functions, MCP, Tests, and Security. | Use the left navigation as the app control surface for ongoing changes. | ## The Common Iteration Loop Most Buzzy work follows the same loop, even if the starting point is different: 1. Clarify the product goal, users, roles, and core workflows. 2. Shape the data model around the records the app needs to store and secure. 3. Define or refine the screen map and navigation. 4. Build or edit screens that bind to the right datatables and fields. 5. Apply a coherent theme. 6. Add functions, constants, widgets, APIs, or MCP when the app needs extension points. 7. Configure People, Teams, Organizations, and Settings. 8. Create Tests for important workflows. 9. Run Security Review before exposing sensitive data or wider access. 10. Publish, monitor, and continue iterating. ## Where to Go Next * New to the app model: [The Building Blocks](/the-building-blocks/the-building-blocks) * Unsure where to start: [What to Use When](/getting-started-with-buzzy/what-to-use-when) * Building with an AI agent: [Buzzy Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp) * Starting from a prompt: [Buzzy AI](/working-with-buzzy/buzzy-ai) * Starting from design: [Buzzy for Figma](/working-with-buzzy/buzzy-for-figma) * Planning a project: [Buzzy Project Guide](/working-with-buzzy/buzzy-project-guide) * Common questions: [FAQs](/working-with-buzzy/faqs) # Buzzy AI Buzzy AI helps you start from a prompt and get to a working Buzzy app definition quickly. It is best for early product discovery, MVPs, internal tools, workflow apps, and cases where you want Buzzy to infer an initial brief, flows, data model, theme, blueprint, screens, and sample data. Buzzy AI is not a one-shot substitute for product thinking. Treat the first generated app as a structured starting point that you can inspect, test, refine, and extend. ## Start with a Prompt A good prompt explains: * what the app is for * who will use it * the main records the app needs to store * the core workflows users need to complete * roles or access boundaries * whether the app needs login, approvals, notifications, files, payments, AI, or external integrations For a full prompt-first workflow, use [Buzzy AI Prompt Workflow](/getting-started-with-buzzy/new-buzzy-ai-v3). ## Keep Iterating in Buzzy After the first version exists, continue from the Workspace: | Workspace area | What to refine | | ----------------------- | ------------------------------------------------------------------------------------ | | Brief | Product intent, roles, capabilities, and external-function requirements. | | Flows | User journeys, approval paths, lifecycle states, and edge cases. | | Blueprint | Screen map and navigation. | | Design | Screen-level views, forms, fields, actions, widgets, and responsive layout. | | Data | Datatables, fields, relationships, permissions, sample data, and Private Data. | | Theme | Visual identity, colors, typography, spacing, borders, shadows, and dark/light mode. | | Functions and Constants | Server-side logic, secrets, integrations, AI calls, and reusable configuration. | | MCP | Builder MCP for app editing, or Custom MCP for exposing app-specific tools. | | People and Settings | Users, roles, teams, organizations, app privacy, and authentication posture. | | Tests and Security | Repeatable workflow tests and security review before release. | ## When to Use Another Path * Use [Buzzy for Figma](/working-with-buzzy/buzzy-for-figma) when visual design fidelity or an existing Figma file is the starting point. * Use [Buzzy Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp) when an AI coding agent should build or change the app in staged, reviewable steps. * Use normal no-code Workspace editing when you already know the change and want to edit data, screens, theme, people, settings, functions, tests, or security directly. ## Related Pages * [Kickstart with AI](/working-with-buzzy/buzzy-ai/kickstart-with-ai) * [Example prompts](/working-with-buzzy/buzzy-ai/example-prompts) * [Tips](/working-with-buzzy/buzzy-ai/tips) * [Troubleshooting Buzzy AI](/working-with-buzzy/buzzy-ai/troubleshooting-buzzy-ai) * [The Building Blocks](/the-building-blocks/the-building-blocks) # About Buzzy AI Understand how Buzzy AI fits into the Buzzy app lifecycle. Buzzy AI helps you create and refine a structured Buzzy app definition from natural-language instructions. It can give you a strong first version, but the best results come from reviewing and iterating the app through the Workspace. ## The Buzzy AI Process {% stepper %} {% step %} ### [Kickstart with AI](/working-with-buzzy/buzzy-ai/kickstart-with-ai) Start from a prompt. Describe the app goal, users, core data, workflows, and roles. Buzzy AI creates an initial app definition and working runtime. {% endstep %} {% step %} ### Review and Refine in Workspace Inspect the generated brief, flows, data model, blueprint, theme, screens, sample data, people, settings, tests, and security posture. Fix the app definition before spending time on polish. {% endstep %} {% step %} ### [Enhance with Figma](/working-with-buzzy/buzzy-ai/enhance-with-figma) Use Figma when visual design, layout refinement, or design-team collaboration is the main iteration path. {% endstep %} {% step %} ### [Extend with Code](/working-with-buzzy/buzzy-ai/extend-with-code) Use code widgets, Buzzy Functions, constants, REST API, or MCP when the app needs custom UI, server-side logic, integrations, or assistant-facing tools. {% endstep %} {% endstepper %} ## How Far Can AI Get You? Buzzy AI is an accelerator, not a replacement for product judgement. It can create a working first version with a data model, screens, and core functionality. You still need to review workflows, permissions, field choices, screen behavior, tests, security, and deployment readiness. For more structured agent-assisted work, use [Buzzy Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp). # Kickstart with AI Instantly generate a working app from a simple idea. **Purpose**: Quickly transform ideas into a foundational app. **How It Works**: Provide a simple prompt to Buzzy AI, which generates a fully functional application prototype, complete with pages, forms, workflows, and database structures. Make quick minor changes with AI. **Key Features**: Create a working first iteration of your app in minutes. This is a massive headstart over planning and developing a minimum viable product (MVP) manually. **Outcome**: A working MVP that you can immediately interact with, test, and iterate on! *** ## New to Buzzy? Use the [demo form on our website](https://www.buzzy.buzz) to try it out for free - use one of our example prompts, or enter your own. Proceeding will create a Buzzy account for you automatically, and you'll be guided through a simple onboarding process while we create your example app. You can also simple [sign up ](https://app.buzzy.buzz/login/signup)or [log in](https://app.buzzy.buzz/login) here - this will take you to your [Buzzy Workspace](https://app.buzzy.buzz/workspace), where you can manage your Buzzy apps or create new ones. ## Already using Buzzy? To create a new app with Buzzy AI, simply go to the 'My Apps' section of your [Buzzy Workspace](https://app.buzzy.buzz/workspace) and click the 'Create new app' button. ## Tips for prompting #### Do this: * **Be clear and specific**: Clearly describe the app you want to create, including its purpose, audience, and key features. For example, "Create a task management app for teams to track projects and deadlines." * **Focus on core features**: Start with the essential functionality. For example, mention features like forms, dashboards, or user profiles, and leave advanced features for later refinement. * **Think 'User Flow':** Describe how users will interact with the app, such as "Users can sign up, create profiles, add tasks, and mark them as complete. #### Some things to avoid: * **Avoid detailed visual references:** Buzzy AI is limited in its design options out of the box - but you can go to town in the 'Enhance' stage. * **Avoid external examples and references:** Buzzy AI has limited knowledge of the world and other apps so asking it to make your app 'like Pinterest but with community reviews' is unlikely to delight as Buzzy AI has no idea what Pinterest is. # Enhance with Figma Refine and customize the app’s design, functionality, and workflows. **Purpose**: Refine and improve the initial prototype. **How It Works**: Customize the app design, functionality, and workflows by porting your app into Figma. Edit your app with Figma's design-centric interface and use the Buzzy Figma plugin to manage your apps functionality, data model and behaviour. . **Key Features**: Add more advanced logic, improve UI/UX, manage your design and optimize for user-specific needs. **Outcome**: A more polished app ready for initial user testing or soft launch. {% hint style="info" %} It helps to be familiar with Figma, and have an understanding of how the Buzzy plugin works via our [Buzzy Figma plugin getting started guide](/getting-started-with-buzzy/getting-started-with-figma). If you are working with a designer or implementation partner, point them to [Buzzy Accreditation](/working-with-buzzy/buzzy-accreditation) so they understand the expected Buzzy/Figma workflow. {% endhint %} *** ## Import your AI-generated Buzzy app into Figma You'll need to import your AI-generated app into Figma. You can then edit and republish the app directly from Figma using the Buzzy Figma plugin. **Make sure you have a Figma account with the same email address as you've used for Buzzy.** {% embed url="" %} Note - the plugin now defaults to Wizard mode, so this is all a lot easier now! {% endembed %} {% hint style="info" %} Get the [Buzzy AI Toolkit v2.2](https://www.figma.com/community/file/1466412289660685275/buzzy-ai-toolkit-v2-2) here! {% endhint %} {% hint style="info" %} Prefer step-by-step written instructions? [See the full process here](/archive/archive-stuff/getting-your-buzzy-ai-app-into-figma-full-description). {% endhint %} *** ## Edit your AI-generated Buzzy app in Figma You'll need to get familiar with how the Buzzy Figma plugin works. Start with the [current Buzzy Figma plugin guide](/getting-started-with-buzzy/getting-started-with-figma), then use the toolkit examples below for AI-generated app refinement. Buzzy AI apps are based on the [Buzzy Figma toolkit](https://www.figma.com/community/file/1466412289660685275/buzzy-ai-toolkit-v2-2), a design system built in Figma. It leverages Figma's awesome design capabilities such as reusable and customizable components, variables to control themes, flex-based autolayouts and more. It also includes additional interface components, layouts and entire screen design examples you can use to quickly add to and extend your app. Once you're done editing, simply publish your changes to your live app, directly from Figma. {% embed url="" %} Note: this video shows the v1 Buzzy AI toolkit - the new v2 has a simpler layout and even more design options! {% endembed %} ### Swapping your app's theme {% embed url="" %} ### Modifying a theme {% embed url="" %} ### Customizing UI components {% embed url="" %} *** ## New to Figma? New to Figma, or don't have design skills? You have two options: [learn Figma](/working-with-buzzy/buzzy-for-figma/learning-figma), or work with a designer who can learn the Buzzy plugin and accreditation workflow. {% content-ref url="/pages/B1n4MS11onwcanp8UGCH" %} [Learning Figma](/working-with-buzzy/buzzy-for-figma/learning-figma) {% endcontent-ref %} {% content-ref url="/pages/MoyBJeuncQWHUKerofBt" %} [Buzzy Accreditation](/working-with-buzzy/buzzy-accreditation) {% endcontent-ref %} {% content-ref url="/pages/jxH8xn1PEjixcWvOKs0R" %} [Getting Started with Figma](/getting-started-with-buzzy/getting-started-with-figma) {% endcontent-ref %} # Extend with Code Scale the app with advanced features, integrations, and customizations. **Purpose**: Expand the app's capabilities and scale for production. **How It Works**: Utilize custom code widgets, Buzzy Functions, constants, REST APIs, or MCP to connect with other tools and services. Buzzy AI and Builder MCP can help generate code widgets or functions, but production integrations should still be reviewed and tested. **Key Features**: Scalability, third-party integrations, advanced security, and compliance features. **Outcome**: A full-stack, production-ready application hosted on a secure Kubernetes infrastructure. {% hint style="info" %} For more complicated integrations and extensions, it helps to have development skills or access to someone who can review the implementation. Use [API and Extension Surfaces](/developing-and-extending-buzzy/api-and-extension-surfaces) to choose the right extension point before building. {% endhint %} *** ## Custom code widgets Custom code widgets allow you to embed custom code in your Buzzy app. Use **embedded markup** for static html or SVG, a **sandboxed iframe** if you have custom code (eg JavaScript), or a **trusted iframe** to embed media such as Youtube or Vimeo. There are three different ways of using code widgets in your app when it comes to having them present or process app data: 1. Using data from the current row 2. Using data from a child table in a custom format 3. Using data from another table or tables Learn more about using Buzzy code widgets here: {% content-ref url="/pages/f4DDPjjRh53ntgsH7wxJ" %} [Code widget (custom code)](/the-building-blocks/code-widget-custom-code) {% endcontent-ref %} ### Examples {% content-ref url="/pages/rC6jDlAwZFbmV97rvRXz" %} [Image Galley Slideshow](/the-building-blocks/code-widget-custom-code/examples/image-galley-slideshow) {% endcontent-ref %} {% content-ref url="/pages/NHXPealkMyameOcdYluI" %} [Ratings Average and Distribution](/the-building-blocks/code-widget-custom-code/examples/ratings-average-and-distribution) {% endcontent-ref %} {% content-ref url="/pages/2tovlgva23UvBQwazXv6" %} [Event Locations Map](/the-building-blocks/code-widget-custom-code/examples/event-locations-map) {% endcontent-ref %} *** ## Rest API The Buzzy REST APIs (which are a type of web API) involve requests and responses. You make a request to a resource stored on the server, and the server responds with the requested information. The protocol used to transport the data is HTTP(S). “REST” stands for Representational State Transfer. Learn more about The Rest API here: {% content-ref url="/pages/MrUIbfAzPgMlOy6qhpcb" %} [Buzzy REST API](/developing-and-extending-buzzy/buzzy-rest-api) {% endcontent-ref %} ### Examples {% content-ref url="/pages/9sF5zZa0dRZyaemUnuve" %} [Integrating 3rd party applications](/developing-and-extending-buzzy/buzzy-rest-api/integrating-3rd-party-applications) {% endcontent-ref %} {% content-ref url="/pages/OoEFQmIhuI4QTiim8QBt" %} [Integrating with Mailchimp](/developing-and-extending-buzzy/buzzy-rest-api/integrating-with-mailchimp) {% endcontent-ref %} *** ## Datatable Rules Datatables provide the ability to fire rules on events (eg update, click , new row created) that allow Actions to be called. ### Examples {% content-ref url="/pages/TVlMtbS8M1FPawC9vg4h" %} [Datatable to Datatable Relationships](/the-building-blocks/datatables-fields-and-data/datatable-to-datatable-relationships) {% endcontent-ref %} *** ## A real live app example - with code snippets! Beginning life as an idea turned into a prompt turned into a simple MVP via Buzzy AI, which was extended with an AI-powered recommendations engine, the [AI Strategy Plan App](https://app.aistrategyplan.com/) is a great example of the Buzzy **Kickstart/Enhance/Extend process**. Get the low-down here: {% embed url="" %} {% embed url="" %} # Example prompts Some prompts to try with Buzzy AI, based on the current capabilities and features of the platform. Crafting the right prompt for the AI is essential for achieving the desired outcome in your generated app, and finding the perfect wording can be a challenging task. Here are some example prompts that you should take inspiration from and tweak to fit your app's needs. ## Initial app prompt * "Create a recipe review app that allows users to read recipes and leave reviews on the recipes. Recipes should have a photo, title, three rich text fields for description, ingredients and instructions, as well a fields for difficulty, serving size, total preparation time as a number, and a set of reviews. Reviews should have a rating and a comment and record the submitter and submitted time of the review." * "Create an event planning app that allows users to create and manage events. Events have a name, description, location, start and end date, information, an image and a set of sessions. Sessions have a name, description, location, date, start and end time, an image, and a set of speakers and attendees. Speakers, attendees and event organizers are different types of users, all of which have a name, title, photo and organization." * "Create a simple movie repository app that allows users to browse movies. Each movie should have a cover image, title, description, release year, director, genre, rating, duration in minutes, and image stills from the movie." * "Create a task tracking app for projects with multiple tasks. Each project has an image, title and description. Each task should have an image, title, description, due date, status and priority. A task only belongs to a single Project. Users should be able to add, edit and delete tasks on projects and should be able to mark them with a completed status. Projects can be marked as done when all tasks are complete." ## Changing the data model You can add or remove tables, add or remove fields, change field types, etc. all through prompts to the AI. Note that data model changes will typically require rebuilding app screens. * "Add a notes text field to the recipes so that people can add more context to their recipe" * "Remove the notes field from the recipes" * "Add another option to the difficulty selection field in Recipes, call it 'Novice'" * "Add an Admin user type" * "Remove reviews from recipes" ## Changing the layout or functional behaviours Using the AI editor in the workspace, you can switch to edit mode and select specific parts of your app to update or target. For instance: * Select a field and prompt "Make this the first field on the screen" * Select a form and prompt "Change this to a 3-screen wizard" * Select a list or card menu and prompt "Change this to use a table layout" (or vice versa) * Select a submit button and change the navigation behaviour, e.g.\ "Do not navigate to another screen after the submit", "Navigate back to the event after submitting the new session" ## Changing the design For changes to text, images and icons, switch to edit mode, select the appropriate item and enter the change you want to make, for example: * "Change this button to say LET'S COOK!" * "Change this icon to a fork and knife" * "Replace this with an image of a kitchen" For changing the theme you don't need to select specific items as the theme is applied universally across the app, however it can help if you're not clear what part of the theme you are trying to modify: * "Create an orange and black theme for my site" * "Update my theme to use a light background" * "Swap back to the Dark theme" * "Give the cards square corners" * "Change the branded bottom bar to a grey colour." #### What exactly can I prompt the AI to change in my theme? The AI Assistant is capable of making some visual modifications to your app, including background and content colours, corner radius, padding, and spacing. You can prompt the AI to change the appearance of the following components: * **Nav Drawer** - The popup navigation that opens when you click the menu button. * **Top Bar** - The header across the top of the screen, which has two versions the “Brand” version which appears on top level and screens and a “Default version” which is used in all the overlay screens. * **Bottom Bar** - The footer access the bottom of the screens, with the “Brand” version having the main navigation bar and appearing on top level screens and the “Default” version having screen specific actions and is used in all the overlay screens. * **Card** - For card views, besides a background and content colour, this includes a radius for setting the corner style, where 0 means square, an a very large value like 999 will make it completely round. * **List** - For list views, this is like cards except there is separate header and item colors, as well as a border colour for items. Lists also have a gap variable that can control the spacing between entries. * **Table** - Similar to cards, but with a border colour. * **Badge** - Has a radius, and various sets of colour pairings - default, inverted, brand, success and danger. * **Input** - For all input fields, background, content and border colours, in both enabled and disabled modes. {% hint style="info" %} If your AI Assistant does not seem to understand your theme change request, try prefixing your request with "Update the theme with...". {% endhint %} ## Adding advanced features * "Add a custom code widget, called 'otherRestaurantsWidget', create a map using Open Street maps that shows all the restaurants in the restaurants data table on the map." * "Add a button on each recipe that adds the recipe to the users favourites. Make a new page called 'Favourites' where users can view their favourited recipes." * "Enable login on my app" - this will set the app privacy to "Private", which means users will need to log into your app, this can also be set manually in the Settings tab * "Disable login on my app" - this will set the app privacy to "Unlisted", disabling the requirement for a login to your app See the next section for detailed examples of adding code widgets and using the AI to write the code for the widgets. # Tips ## Optimising your initial prompt When generating your app brief, try to include some basic description of your data relationships in your prompts. This will help make sure your data model includes the relevant relationships. This is especially important if the app requires complex many-to-many relationships. Some examples of prompts you could use: * Each recipe can have multiple reviews. Each review is linked to one recipe. * A customer can have multiple projects, and a project can have multiple customers. * Each dog has only one breed, but a breed can be associated with multiple dogs. Good questions to ask yourself when creating your prompt: * What kind(s) of users will be using the app? Is there one general user type or do I need to distinguish multiple users (e.g. customer vs admin, patient vs practitioner, teacher vs student etc.) * What are the relationships among my data? Can one object be linked to multiple other objects? Can one object be linked to only one other object? * What concrete actions would a user be expected to perform when using the app? What verbs can I use to describe those actions (e.g. “Users should be able to submit a review/deactivate a program/book an appointment…”)? ## Optimising your change requests The AI Assistant can help you make some changes to your app including editing the data modal, the app name or even do some simple design changes. To help the AI Assistant understand your change request, explore these [example prompts](/working-with-buzzy/buzzy-ai/example-prompts) to get an idea of what to ask and how to ask it. ## Understanding the Brief tab (Workspace & Figma plugin) The functions in the app brief represent the main features of the app and the actions that a user would be expected to take in the app. In this context, the functions do not relate to UI specifications (e.g. “The app should have a navigation bar”, “The user should be able to access a dashboard”). ## Identifying the handover point between the AI assistant and the user In using Buzzy AI, we want to emphasise the importance of collaboration between you - the user - and the Buzzy AI assistant. It is crucial to understand that the AI assistant serves as a powerful co-design partner, enhancing and streamlining the app creation process. But for most complex use cases, it does not encompass the entirety of the process and is not a substitute for your creative input. It is important to recognise the handover moment - the point where you have maximized the AI assistant's capabilities and are ready to take the reins manually. After you've published the first version of the app, which features the core functionalities, it is generally time to start iterating and refining using your own expertise. Fine-tuning such as UI improvements and customisation will fall under your purview as the app's designer and will have to be implemented manually. You'll find some guidance on that topic [here](/working-with-buzzy/buzzy-ai/troubleshooting-buzzy-ai#how-can-i-edit-the-look-of-an-app-created-with-buzzy-ai). # Troubleshooting Buzzy AI Getting stuck with Buzzy AI? Your answer might be here. ## My Buzzy Workspace is frozen or blank. Occasionally you might run into a bug or situation where the Buzzy Workspace stops working. It may be loading a blank screen or otherwise frozen. ### Step 1: Refresh the page The first thing to try is refreshing the current page in the browser. How you do this will depend on your device and browser, but generally there will be a refresh icon or button at the top near the url bar.
Screenshot showing refresh button in the Chrome browser on a Mac.

The refresh button in Chrome (shown in MacOS).

### Step 2: Clear your cache If a simple refresh doesn't work, try clearing the cache. Again, how you do this will depend on your browser. Here's how to do this in some common browsers: #### Safari (Desktop) To clear the Safari cache on a Mac, go to the Develop menu and select Empty Caches, or go to Settings > Privacy > Manage Website Data and click Remove All. The "Develop" method is faster for cache only, while the "Privacy" method clears both cache and cookies for all websites. #### Chrome (Desktop) To clear the cache in Chrome, open the browser, click the three dots in the top-right corner, and select **More tools > Clear browsing data**. Next, choose a time range from the dropdown menu (select "All time" to delete everything) and ensure the "Cached images and files" box is checked, then click **Clear data**. **BONUS: Chrome also has a shortcut to do this:**
#### Microsoft Edge To clear the cache in Microsoft Edge, go to Settings and more (...) > Settings > Privacy, search, and services, then select Clear browsing data and choose the types of data and time range you want to delete before clicking Clear now\.Alternatively, you can use the keyboard shortcut `Ctrl+Shift+Del` or type `edge://settings/clearbrowserdata` in the address bar for a quicker method. #### Firefox To clear the cache in Firefox, click the menu button (three horizontal lines) in the top-right corner, go to "History," then "Clear Recent History." In the pop-up window, set the "Time range to clear" to "Everything," check the box for "Cache," and click "Clear Now". #### Internet Explorer To clear Internet Explorer's cache, open the browser, press Ctrl + Shift + Delete, uncheck "Preserve Favorites Website Data," ensure "Temporary Internet Files and website files" and "Cookies and website data" are selected, and then click Delete. Close and reopen Internet Explorer for the changes to take effect. (Also, why are you still using this?!) ## I purchased a subscription but Buzzy still says I don't have access {% hint style="warning" %} Before contacting Buzzy Support, check your receipt or invoice and confirm that the subscription is identified as `BUZZY.BUZZ`. Services branded or billed as `buzzy.now`, `buzzy.ai`, or another similar name are not affiliated with Buzzy. Contact the company named on the receipt or invoice for help with those subscriptions. {% endhint %} 1. Check Your Logged-in Email: If you're logged into the Buzzy workspace at [Buzzy Workspace](https://app.buzzy.buzz/workspace), click the profile icon in the top-right corner to verify which email address you're using. After successfully completing your payment through Stripe, you'll be prompted to fill out a form. This form will ask for your Stripe, Buzzy, and (if applicable) Figma email addresses. It's important to ensure these emails match, as Buzzy uses them to confirm your subscription. 2. Refresh Your Access: After activating your subscription, if the changes don't automatically update, refresh your browser. Please do not start another checkout flow, as it may create a separate Buzzy account unnecessarily. If you are still unsuccessful, please email and include both emails and any extra info like screenshot that can help diagnose the problems. Please include a screenshot of your Buzzy profile page. {% embed url="" %} ## I have purchase Buzzy AI tokens but they are not showing up in my account The email address that you purchase your Buzzy AI tokens **MUST** match the email address of the your Buzzy account. To confirm the email of our Buzzy account login to the [Buzzy Workspace](https://app.buzzy.buzz/workspace), click the profile icon (top right) and you'll see your email address. If you need to move over your tokens from one account to another or are still having issues, please contact with the details and way to identify each account, like the last 4 digits of your credit card and date of transaction. For more info about Buzzy tokens and subscriptions, please see [this page](/working-with-buzzy/buzzy-ai/ai-tokens-and-pricing) ## Cancel a subscription First, check your receipt or invoice and confirm that the subscription is identified as `BUZZY.BUZZ`. Buzzy Support cannot access or cancel subscriptions for unaffiliated services such as `buzzy.now` or `buzzy.ai`; contact the company named on the receipt or invoice instead. If the subscription is from `BUZZY.BUZZ`, you can cancel it by: 1. **Via** [**Buzzy Workspace**](https://app.buzzy.buzz/): Log in to the Buzzy Workspace and click the profile icon in the top right corner. This will open your profile and account management settings, and display a link to any currently active subscriptions you have. Click on the subscription link to manage or cancel it via Stripe. Note: if you cancel and the changes aren't automatically reflected in your Buzzy profile view, simply refresh your browser.
2. **Via** [**Stripe’s Buzzy Subscription Portal:**](https://billing.stripe.com/p/login/aEU29EaLI96J42AdQQ) Log in to Stripe using the same email address with which you originally purchased Buzzy via Stripe. This email may be different to the one you use when logging in to Buzzy! If you cannot remember this email, please refer to the invoice or receipt from Stripe sent you. Once logged in, follow the instructions to cancel your subscription.
3. **Via Email**: Send a cancellation request to [support@buzzy.buzz](mailto:support@buzzy.buzz?subject=Cancellation) from the email address you used to originally purchase Buzzy via Stripe. This email may be different to the one you use when logging in to Buzzy! Please include: * A brief explanation of why you wish to cancel * The `BUZZY.BUZZ` receipt or invoice details, such as name, transaction ID, last four digits of the card, and billing date. Never send your full card number. * Your registered email address and login name * Any other information needed for identity verification or authentication For more on cancellations and refund policy, [check out this page](https://www.buzzy.buzz/cancellations).\\ ## When I click "Connect to Buzzy" in the plugin, it takes me to a blank page When you click the "Connect to Buzzy" it should redirect you to a Figma page, that looks like
Sometimes, due to timeouts, you may need to "Allow access" twice. If you get a blank page, it is most likely a web browser security/session issue. Please check your browser for an security warning/popup blockers and allow them to open the Buzzy and Figma page. If the problem still persists, if you're using Chrome, please try use the default Chrome session, not one logged in as a specific user Chrome profile (usually a colored tab). ## I **purchased an AI Creator license, why can't I see the AI features in the plugin?** * Make sure you are logged in Figma with the same email address as the one you provided in the form after your purchase. * Close the plugin, and rerun it. * In the plugin settings, disconnect from Buzzy then connect to Buzzy again. {% hint style="info" %} You can check which email address you are signed in with by going to the plugin settings (cog icon). {% endhint %} ## I can't see the option to import an app into Figma in my plugin Make sure you have a Buzzy AI license, and that the Buzzy Figma plugin has wizard mode enabled. To enable this, click on the 'sparkle' icon at top left of the plugin tabs.
## I have the plugin opened and the AI features unlocked, why can't I generate screens? To generate your app design and create your screens with Buzzy AI, you need to be in the Markup tab of the plugin. Click on the "Generate app design" to create your screens. Make sure that: * You have successfully generated your app brief (in the Brief tab) and your data model (in the Model tab) first. * You are working in one of the Buzzy AI toolkits. If you are not using a toolkit, you will see the following error message: "Buzzy toolkit not found, cannot generate screens" ## Where can I find the Buzzy AI toolkit? You need to work in a Buzzy AI enabled toolkit if you are using Buzzy AI to create your app. Get it at ## Previewing my Buzzy app in a browser shows a blank screen Make sure you are using a standard modern browser such as Chrome, Safari, Edge or Firefox. We have had reports of issues with the Brave browser - if this applies to you, try using the 'Shields down' option to see if it's one your settings (eg disabling scripts) that might be the cause. ## How can I edit the look of an app created with Buzzy AI? All Figma files created with Buzzy AI are fully editable in Figma. Buzzy AI generates apps based on a tool kit that you can modify as you wish to change the look and feel of your app. For current guidance on working with Buzzy AI and Figma, see [Enhance with Figma](/working-with-buzzy/buzzy-ai/enhance-with-figma). For additional guidance on how to customise a Buzzy AI app, watch this video: [Buzzy Figma Plugin: Editing a Buzzy AI Figma app](https://youtu.be/sLimZfhThxM) ## How do I get my Buzzy AI app into Figma to edit it? If you've used Buzzy AI to generate a new app via the Buzzy website or Buzzy Workspace, you can import the app into a Figma file. You can then edit and republish the app directly from Figma using the Buzzy Figma plugin. 1. Grab a copy of the [Buzzy AI toolkit file](https://www.figma.com/community/file/1466412289660685275/buzzy-ai-toolkit-v2-2) 2. Follow the instructions in the toolkit file to run the Buzzy Figma plugin 3. Follow the instructions in the Buzzy Figma plugin to connect your Figma and Buzzy accounts 4. Use the Buzzy Figma plugin to find and import your app into Figma [**See Enhance with Figma for more guidance.**](/working-with-buzzy/buzzy-ai/enhance-with-figma) ## What if I want to change something in the app brief? You can edit your app brief in 2 ways, from the Brief tab. 1. You can edit the brief manually by clicking on the Edit app brief button. You’ll then be able to add/edit/remove specific words or phrases from the brief. This is generally a good approach when you need to refine a few things and add small details to your brief. 2. You can ask the AI to change the brief based on a new prompt. Simply write a new prompt in the chat window that outlines the changes you want to make. This is generally a good approach if you want to make significant or numerous changes to the brief. Depending on which step of the app creation process you’re at, you might need to rerun some AI functions. If you have only created your app brief, you can edit the brief without any concerns. If you have already generated a data model, you will need to generate an updated version of it by clicking the Regenerate data model button, once your new brief is completed. If you have already created your app design, you will need to regenerate the app design in the Markup tab. If you have already created some screens in Figma, you will need to clear the screens, regenerate the app design and recreate the screens. ## How do I edit the data model? Editing the data model works the same way as editing the brief. You can manually edit each data field by clicking on it or you can write a new prompt for the AI to do it for you. If you make changes to the data model, you will need to regenerate the app design and recreate the screens in Figma. ## I got an error message, what can I do to resolve it? All failures related to the AI assistant feature could be caused by any of the following: * Timeout * Token limit exceeded in the prompt * Token rate limit exceeded in request * OpenAI servers experiencing delays or failures If you come across any of these issues, a general recommendation is to ensure that your input is not overly lengthy and give it another attempt. | Message | Meaning | Suggested solution | | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Error interpreting prompt |

Something went wrong with your prompt.
If you are using your own API key, this can mean that the key you have inputed is not enabled with GPT-4.

| Check your GPT-4 API access (see [here ](/working-with-buzzy/buzzy-ai/tips#getting-your-own-gpt-4-api-key)for more information). | |

Error updating app brief
Error generating app brief

| Something went wrong when you tried to create or edit your app brief. |

Try a shorter prompt.
Run the action again.

| |

Error updating data model
Error generating data model

| Something went wrong when you tried to create or edit your data model. |

Try a shorter prompt.
Run the action again.

| |

Error asking question on app brief
Error asking question on data model

| Your question could not be answered to by the AI assistant. | Buzzy AI is specifically designed to assist you in creating apps, which means its capabilities are focused on providing app development support. It will not be able to engage in conversations unrelated to this particular domain. | |

Error generating screen theme bundle.
Error generating data theme bundle for table: \[table.name]

| Something went wrong when you tried to generate your app design. |

Run the action again.
Relaunch the plugin.

| | Screen creation timed out |

The Figma plugin took too long to create the app screens.
This may be due to your machine running slowly or Figma experiencing delays or failures.

|

Run the action again.
Reload Figma.

| | Screen clear timed out |

The Figma plugin took too long to clear screens from the canvas.
This may be due to your machine running slowly or Figma experiencing delays or failures.

|

Run the action again.
Reload Figma.

| | Error generating sample data | Something went wrong when you tried to generate sample data to populate your app. |

Run the action again.
Relaunch the plugin.

| | Error searching for sample images |

The AI assistant failed to search for images on Unsplash.
This may be due to a timeout issue or the Unsplash AI experiencing delays or failures.

|

Run the action again.
Relaunch the plugin.

| {% hint style="info" %} Can't find your answer here? [Contact the Buzzy team for support](mailto:support@buzzy.buzz). {% endhint %} # AI tokens and pricing ## About **Buzzy AI tokens** Processing AI requests is expensive; to help us manage the costs associated with this, we've introduced an AI token system. Note that using Buzzy to manually create, edit and publish an app (for instance via the Figma plugin) uses no tokens and incurs no fee beyond the standard subscription. ## **FAQ** ### **How does Buzzy AI pricing work?** Buzzy AI is available through subscription plans. You can subscribe to a **Small**, **Medium**, or **Large** plan and get a quote based on your needs. See [Buzzy pricing](https://www.buzzy.buzz/pricing) for current details. ### **What plans are available?** Buzzy offers **Small**, **Medium**, and **Large** subscription plans. For the latest inclusions and quote details, see [Buzzy pricing](https://www.buzzy.buzz/pricing). ### **Are token charges profit-driven?** No, token costs simply cover the expenses of processing AI requests. We aim to keep costs low and are working to reduce token usage wherever possible. ### **Can I use my own OpenAI API key to generate apps?** Yes. We now support BYO OpenAI API key for generating apps, including on [app.buzzy.buzz](https://app.buzzy.buzz). This means you do not have to pay Buzzy app-generation fees when using your own key. ### **Why use tokens instead of a single fee?** We have made Buzzy a lot better, but it does use a lot more tokens, which costs us more. Also the number of tokens used will be dependent on the specific application being built. The token model allows flexible, affordable access without high upfront costs. It supports both light and heavy users, with additional tokens available only if needed. We are also working to reduce the number of tokens used and when cheaper models that produce the right level of quality, your tokens will get you more bang for you buck. ### **Can I cancel anytime?** Yes. You can cancel your subscription any time. Before contacting Buzzy Support, check your receipt or invoice and confirm that the subscription is identified as `BUZZY.BUZZ`. Services branded or billed as `buzzy.now`, `buzzy.ai`, or another similar name are not affiliated with Buzzy, so you will need to contact the company named on the receipt or invoice. For a `BUZZY.BUZZ` subscription, see [how to cancel a Buzzy subscription](/working-with-buzzy/buzzy-ai/troubleshooting-buzzy-ai#cancel-a-subscription) and review the [cancellation and refund policy](https://www.buzzy.buzz/cancellations). # Buzzy for Figma Design, test, and publish working Buzzy apps from Figma. Buzzy for Figma lets you turn a marked-up Figma design into a working Buzzy app with real data, live forms, navigation, user-generated content, and responsive layouts. Use this path when the design file is the source of truth, when a designer is leading the app experience, or when you want to keep iterating visually in Figma after an app has been created. ## Start from Figma The usual Figma path is: 1. Design the screens in Figma. 2. Use Buzzy markup conventions to identify screens, forms, fields, buttons, menus, data-driven lists, images, galleries, and responsive behavior. 3. Use the Buzzy Figma plugin to connect to Buzzy. 4. Publish the marked-up design as a Buzzy app. 5. Test the live app with real data and real forms. For a hands-on walkthrough, start with [Getting Started with Figma](/getting-started-with-buzzy/getting-started-with-figma). ## Keep Iterating with Figma and Buzzy After the app exists, Figma remains useful for visual and structural changes: * update layouts, sections, responsive behavior, and visual hierarchy * refine themes, typography, colors, and components * add or adjust screens and navigation * update forms, fields, galleries, images, menus, and data-driven content * publish changes back to the Buzzy app Use Buzzy Workspace alongside Figma for the parts that are better managed as app configuration: * datatables, fields, relationships, sample data, and row permissions * People, Teams, Organizations, and app settings * functions, constants, APIs, MCP, and Custom MCP exposure * tests, security review, publishing, and deployment ## Figma, AI, and Builder MCP Together Figma is not isolated from the other creation paths. * Start with [Buzzy AI](/working-with-buzzy/buzzy-ai), then refine the generated app in Figma. * Start with Figma, then use Buzzy AI or the Workspace to refine data, flows, screens, and theme. * Use [Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp) for staged agent-assisted changes when you need deeper inspection, code widgets, functions, validation, or test-oriented edits. ## Table of Contents * [About Buzzy for Figma](/working-with-buzzy/buzzy-for-figma/about-buzzy-for-figma) * [Learning Figma](/working-with-buzzy/buzzy-for-figma/learning-figma) * [Creating a New App Directly in Figma](/working-with-buzzy/buzzy-for-figma/creating-a-new-app-directly-in-figma) * [Automarkup](/working-with-buzzy/buzzy-for-figma/automarkup) * [Responsive layouts](/working-with-buzzy/buzzy-for-figma/responsive-layouts) * [Responsive layout checklist](/working-with-buzzy/buzzy-for-figma/responsive-layout-checklist) * [Overflow and scrolling](/working-with-buzzy/buzzy-for-figma/overflow-and-scrolling) * [Forms and fields](/working-with-buzzy/buzzy-for-figma/forms-and-fields) * [Images and galleries](/working-with-buzzy/buzzy-for-figma/images-and-galleries) * [Logging users in to your app](/working-with-buzzy/buzzy-for-figma/logging-users-in-to-your-app) * [Theming](/working-with-buzzy/buzzy-for-figma/theming) * [Troubleshooting Buzzy for Figma](/working-with-buzzy/buzzy-for-figma/troubleshooting-buzzy-for-figma) * [Plugin error messages](/working-with-buzzy/buzzy-for-figma/plugin-error-messages) ## Resources * [The Buzzy Figma plugin](https://www.figma.com/community/plugin/980407395621457657) * [Buzzy Figma templates and files](https://www.figma.com/@buzzy) * [The Building Blocks](/the-building-blocks/the-building-blocks) ## Support * [Discord community forum](https://discord.gg/qt7svhCMbj) * [Email support@buzzy.buzz](mailto:support@buzzy.buzz) {% hint style="info" %} **What is Figma?** [Figma](https://www.figma.com/about/) is a collaborative interface design tool used by product, design, and development teams. {% endhint %} # About Buzzy for Figma Buzzy includes a Figma plugin that allows you to develop and publish a working Buzzy app straight from Figma. ## How it works The Buzzy Figma plugin works by allowing you to mark up a design in Figma - when you 'publish' your app, Buzzy extracts your screens and designs from the Figma file and converts them into a Buzzy app using your design, coupled with the functionality, data and behaviours you told Buzzy to use via the plugin. Best of all, you can keep working in Figma. Make changes to your app in Figma, and simply republish via the plugin.
## Get a Figma account & login to Figma You're going to need a Figma account, so if you don't already have one, go sign up (it's free), then come back here and continue below. **Already have a Figma account? Login to Figma and continue.** {% embed url="" %} ## Basic steps 1. [Install the Buzzy Figma plugin](#install-the-buzzy-figma-plugin) 2. [Connect to Buzzy](#connect-to-buzzy) 3. [Mark up your design in Figma](#mark-up-your-design-in-figma) 4. [Publish your app from Figma](#publish-your-app-from-figma) {% hint style="info" %} We **really** recommend you start with [Getting Started with Figma](/getting-started-with-buzzy/getting-started-with-figma), and work through the Buzzy Figma plugin basics there. {% endhint %} {% hint style="info" %} To successfully use Buzzy, you should have [Figma](https://www.figma.com) skills and be able to create high-quality designs using Figma's tools and features. For some hints on best practices please see [this article](https://medium.com/buzzy-blog/8-figma-tips-for-ease-of-use-developer-handoff-and-production-bliss-694b5ed5364a). {% endhint %} ### Install the Buzzy Figma plugin There are several ways to install and run Figma plugins - for now we just want to run the Buzzy plugin and connect it.
Get the pluginGo to the Buzzy Figma plugin page in the Figma community and click the 'Try it out' button./files/PWTx2WRAAeR2S1Q1YtCL
New Figma tab opensFigma will open a new tab, with a default Buzzy 'start' file - but it won't have opened the plugin for you! It instead shows a tooltip that indicates where you can find and launch the plugin in the Figma workspace./files/EwjzCEDcRu495pXWmen4
Run the pluginClick the Figma button indicated above, and it opens a plugin panel, populated with the Buzzy Figma plugin. Click the 'Run' button to launch the plugin./files/cgeJ9hDVvSupIQb5hEOu
### Connect to Buzzy The first time you run the Buzzy plugin, you'll need to connect to Buzzy using your Figma ID.
Connect to BuzzyIn Figma, open the Buzzy plugin, and click Connect. You’ll only need to do this the first time you run the plugin, unless you sign out./files/ywIz6QFg0qGQROAeaYXK
Allow Figma accessA new browser window will open; allow access when prompted. Buzzy needs this to access your Figma files and generate your apps./files/Vdrg6TqgTcuBW2v4OeHI
Return to FigmaA success screen will appear in the browser. That's it - simply return to Figma and your Buzzy plugin will be connected and running./files/BJlic2XSlTpUrAdKrwq6
{% hint style="info" %} Hint: if the plugin appears stuck on a 'processing screen' after you return to Figma, simply close and reopen the plugin {% endhint %} ### Mark up your design in Figma The Buzzy Figma plugin works by letting you select elements in Figma, and assigning roles, actions, data and functionality to them. #### Overview of the Buzzy plugin The Buzzy plugin is divided into the following main tabs:
BRIEF: This tab is used only if generating a new app from scratch using the [Buzzy AI](/working-with-buzzy/buzzy-ai). MODEL (Previously called 'Data'): This is where you define your app's data model. MARKUP (Previously called 'Design'): This is where you link your Figma design to functionality, roles, data and behaviour. PUBLISH: This is where you publish your app to a server for previewing and deployment. **The Buzzy plugin applies to whichever page of a Figma file is currently visible.** The markup and Buzzy app definitions are saved to that Figma page. One Figma page equals one Buzzy app. You may have several Buzzy apps defined in one Figma file - for instance a public app and an admin app on separate pages of a single file, sharing a common Figma design library. As you switch between Figma pages while keeping the plugin open, you'll see the plugin reflect the Buzzy markup (and thus app definition) of each page. {% hint style="danger" %} **If you've opened the Buzzy plugin on a Figma file you've been working on, and it appears the Buzzy markup has gone missing, make sure you're on the right page of your Figma file - ie the one that contains your app screens and designs!** {% endhint %} ### Using the Buzzy plugin **To convert a Figma design into a single Buzzy app**, place all your app interface screen designs onto a single Figma page, and open the Buzzy plugin. ([Using Buzzy AI? Start here](/working-with-buzzy/buzzy-for-figma/creating-a-new-app-directly-in-figma/step-by-step-version)) **Use the plugin 'Model' tab to define your app data model, data tables and field definitions.** Once you have a data model defined, you can assign those fields and values to your Figma UI elements via the 'Markup' tab of the plugin. **Use the plugin 'Markup' tab to assign functional roles and behaviours to your Figma screens and elements.** Select your Figma layers (via the Figma canvas or in the normal Figma layers panel), and assign functional roles and behaviours to those elements. {% hint style="info" %} **Recommended approach:** We recommend picking key areas of your app and working on your app section by section, beginning with simple functionality first, and then progressing from there, testing as you go. For instance, start by defining your app screens and basic navigation actions first, and getting your core layouts working correctly, before working into them with data. For more detailed examples of what this means, see the [article on responsive layouts and design](/working-with-buzzy/buzzy-for-figma/responsive-layouts). An iterative approach is best - work on a part of your app, publish and test, then iterate. {% endhint %} ### Publish your app from Figma **Use the 'Publish' tab of the Figma plugin to publish your app.** Simply give your app a name (it will default to the page name) and hit the publish button. **The first time you publish a Buzzy app from a Figma file, you'll need to enter the file key.** The Buzzy plugin will prompt you for this. Simply open the 'Share' dialog in Figma, and copy the file link. Paste this into the plugin and hit Next. **Once your app has been published, you can preview it in a browser.** There are 3 buttons/links we provide - one to a 'debug' mode preview, which wraps the app in a Buzzy inspector/debugger; one to a 'live' preview of your app, and one to the Buzzy platform, where you can better manage your apps' settings and data. There's also a QR code, which you can use to preview your app in a browser on your mobile device.

Publish, preview and test, then iterate!

*** ## External Resources * [The Buzzy website (pricing info and more)](https://www.buzzy.buzz/) * [The Buzzy Figma plugin](https://www.figma.com/community/plugin/980407395621457657) * [Templates and demo apps](https://www.figma.com/@buzzy) * [Youtube getting started demos and tutorials](https://www.youtube.com/playlist?list=PL-a7B5lYx12D9p1-AQkFDC9yQUGWCJfcK) * [Release notes](https://www.buzzy.buzz/release-notes) ## Support * [Discord community forum](https://discord.gg/qt7svhCMbj) * [Email support@buzzy.buzz](mailto:support@buzzy.buzz) # Learning Figma Figma is a powerful design tool that allows you to design and build full stack apps when used with the Buzzy plugin. It offers a wide array of functionalities giving you full control over your app's look and feel. Here are some tips to efficiently and meaningfully learn Figma. ## Figma's own tutorials, tips and resources New to Figma? It's probably best to go straight to the source and learn directly from Figma. Here's some good starting points: {% embed url="" fullWidth="false" %} {% embed url="" %} {% embed url="" %} ## Looking for more advanced Figma articles? The good folk at UIPrep have a great blog chock-full of articles covering more advanced Figma stuff, from using variables to colour systems and all the way up to implementing full design systems. {% embed url="" %} ## Buzzy's own Figma tips Figma is an incredibly powerful and versatile design tool, with a raft of features designed specifically to streamline production handover — but these features only work if they're used correctly. Moving from design into a prototype or production phase? Handing over to a developer, other designers or using the Buzzy plugin to develop directly in Figma? You'll struggle if you have a messy, inconsistent, and poorly structured Figma file. Bad enough and it'll be of no more use than a flattened jpeg. ### A general approach Unless you're working with a rigidly-defined design system, visual exploration and ideation is always going to be a messy, ad-hoc process, and that's fine. Once you've moved beyond that and are ready to work on files that will carry over into production, here's our recommended approach. If you're using a design system or UI kit with shared Components, assets and style libraries, you already have a head start here. 1. **Define your core theme and styles** (colours, typography and other styles). Use Figma's styles and asset library capabilities to do this. Be consistent — 15 shades of red or 11 different content text styles on a single screen are unlikely to be deliberate decisions, but a developer (and Buzzy!) can only take your file at face value. 2. **Build up your design screens.** As you reuse items and design elements, turn them into Figma Components where appropriate. This lets you maintain consistency, and changes are a breeze. 3. **Use frames (not groups!) and auto layouts** to create a consistent, logical hierarchy for your layouts and design elements. Is that button meant to be positioned inside that panel with the text, or float over the top of it and be positioned relative to the screen edge? Be consistent with your positioning and spacing of items. 4. **Think about interactions and content behaviour** such as alignment, constraints, overflow and scroll settings. If you intend for the screens to resize, drag your screen (frame) corners in Figma, and make sure your design elements behave as expected — a developer (and Buzzy!) can then understand positioning behaviours: is that icon meant to align to the left edge of the text, or the left edge of the button containing it? Is that button meant to resize if the text changes? Figma's native layout tools give you the option to define all of this, even if your Figma designs and prototypes are fixed in size. 5. **Use the Buzzy plugin to mark up your screens and navigation.** Focus on a small section of your app or a few screens to start with. Publish your app, and test to make sure it's all rendering and behaving as expected; fix what you need to before moving on to the more complex production mark up. Make sure you've designed all the screens and elements you might need (alerts, dialogs, error messages, empty states for menus, etc). 6. **Use the Buzzy plugin to mark up your views, menus and dynamic content.** Define your forms, fields, data and complex behaviours — but break it into manageable chunks, and work on a single small or simple section at a time. 7. **Publish, test, refine and iterate as you go!** That's it! The first 4 steps above are just good Figma practice, even if you never use Buzzy — your fellow designers and devs will thank you for it. ### Tips and examples Let's dive into some more detailed examples that build on the general approach outlined above. A lot of these tips overlap, and a lot will fall into the 'be consistent and thorough' basket. #### Nesting matters — a lot If you look at your design and multiple items are surrounded by or floating on top of a larger item, it's usually a sign they should be nested in that larger item, not floating on top of it.

This isn't great

A common occurrence for this problem is buttons. In a poorly structured design, the button shape and the text are completely independent of each other. This leads to problems with both layout and functionality. * **Layout:** the text should be positioned relative to the button shape — but right now, it's positioned relative to whatever parent container or screen they are both in. If anything resizes or moves, the text and the button will no longer align. * **Functionality:** which of the 2 objects should have the button action applied? If you put it on the shape, then the text renders the middle of the button unusable, since it floats above (not inside) the shape, and blocks the click action. There's a reason html button elements contain their label text. **Fixing the issue:** Turn the button into a Frame which contains the Text layer. The Text layer now gets its positioning and constraints from the button Frame, which can now safely have an action assigned to it — the text label is part of the button and thus clickable. Even better, the Frame can have its own styling applied (fills, strokes, effects, rounded corners and so on) meaning you can do away with an unnecessary 'button shape background' vector layer.

Yay! The button is now a single item.

{% hint style="info" %} **Pro tip:** Turn the Frame into an Auto layout to get automatic control of its size, content alignment and padding. We can now easily control the button padding and behaviour both as its container resizes, or its content (for instance if the text changes, or you decide to add an icon). {% endhint %}

Moar yay! We can now easily control the button padding and behaviour both as its container resizes, or its content (for instance if the text changes, or you decide to add an icon).

#### Use Frames not Groups This directly relates to the nesting problem outlined above — generally, if you find yourself 'Grouping' something in Figma, it's a sign you should be using a Frame or Auto layout. This has functional, ease of use and performance implications — Frames can have styles applied to them, negating the need for a bunch of background vectors floating around behind things. {% hint style="info" %} For a brilliant explanation of Frames vs Groups, check out [this article by UI Prep](https://www.uiprep.com/blog/ultimate-guide-to-frames-vs-groups-in-figma). {% endhint %}
**Tip:** Right-click a Group in Figma and choose 'Frame selection'. Then drag the contained layers up out of the Group so they're under the frame, and delete the Group. Next, ensure the items are positioned / constrained appropriately within the frame. #### Item layout, positioning and constraints matter — a lot When looking at your design in Figma, your screens and layouts are fixed in size, and you can drag UI elements around to where-ever you want them to be — but behind the scenes, all those items have specific position settings, which become critically important when moving to production.

Resize your design in Figma - what happens?

For instance, is that icon meant to stay a consistent distance from the left, or should it align to the right edge? Should that graphic stay a fixed size and centred on the screen, or expand as the screen resizes? Try resizing your screen Frame in Figma, and see what happens to your UI elements — that's roughly how they would behave in a browser or at different sizes of device viewports if your developer takes your file at face value and builds each item to the layout constraints you've provided in Figma. ![Figma's layout controls](/files/96dzOvKSXucRcldS5SBH) **Fixing the issue:** Use Figma's layout controls in the right hand design panel — depending on the layer you select, adjust width, height, X and Y position, alignment and resizing options. But only do this once you've sorted out the nesting of your layers — see above! {% hint style="info" %} **Buzzy tip:** Use the 'fixed' layout screen mode to avoid having to deal with your design resizing. While not really recommended for production apps, it's a handy shortcut for prototypes or MVPs. {% endhint %} {% hint style="info" %} For more detailed guidance on responsive layouts, see our [responsive layouts guide](/working-with-buzzy/buzzy-for-figma/responsive-layouts). {% endhint %} #### Plan and define your responsive layout, overflow and scroll behaviours As the amount of content on each screen changes, think about how you want to handle scrolling and overflow clipping. Ideally your layouts should have a consistent approach across similar screens so navigation and other behaviours remain predictable for users.

Consistent navigation and scroll behaviour is much easier for users to understand, and easier to develop.

**Fixing the issue:** Figma provides you with controls for overflow clipping in the Design tab, and scrolling behaviours in the Prototype tab, even if you don't use them in Figma itself — a developer (or a production tool like Buzzy) can use these to determine styling and behaviour in production. If you've designed your app for only one screen size, plan ahead and think about how you want your layout to respond at other screen or viewport sizes. {% hint style="info" %} For detailed information on setting up overflow and scrolling, see our [overflow and scrolling guide](/working-with-buzzy/buzzy-for-figma/overflow-and-scrolling). {% endhint %} #### Consistency and precision matters This sounds like common sense, but bears mentioning. Make deliberate design decisions. If an element is meant to consistently be 20px from the top of the screen, make sure it's always 20px, not 22px on one, 23px on another and 19px on yet another — a user will see it jumping around as they navigate from screen to screen. If an item is meant to align with another item, make sure they actually align. This also has consequences for item nesting, and development decisions in production.

Are these spacings deliberate? Probably not, but I’m just the developer…

In the example above, if the items are meant to align on their left edges and have consistent vertical gaps, the Figma parent container could be a single Auto layout, which is far easier to control than 3 separate items floating independently of each other. In production, a single containing element and some simple styling would handle this. If the items are being deliberately misaligned as a design decision, your developer may need to deliberately add additional styling and/or wrapping elements to achieve this positioning, which can add complexity and time. #### Repetition matters When things are re-used consistently, turn them into Components (or Styles) to simplify both the design and markup complexity. A navigation bar or button re-used on multiple screens can be turned into a single reusable component. This simplifies the design process, makes changes a breeze and prevents niggling inconsistencies and errors from creeping into your Figma file.

Reduce, reuse, recycle. We can all get behind that. Master Component with Instances.

{% hint style="info" %} Another area where Components are highly recommended is for icons — UI Prep has a [comprehensive guide to using icons in Figma](https://www.uiprep.com/blog/ultimate-guide-to-using-icons-in-figma). {% endhint %} #### Avoid unnecessary transforms, flips and rotations This is critical if using Buzzy at the moment (publishing of transformed elements is only partially supported), but also good practice generally. For instance, a Layer that is rotated 180 degrees makes no difference to its appearance, but is an unnecessary performance hit for a published app, and makes figuring out its positioning difficult without rotating it back. How far off the left screen edge is it? It's not 280px, as that's referring to what is now the right edge.

This is not 280px from the left edge, but that's its x position due to the transform.

### Buzzy-specific tips The following tips are specific to using Buzzy with Figma: #### Avoid strokes, especially on complex vector shapes and icons Buzzy only partially handles borders and strokes on publish, especially on complex vector shapes. This is usually an issue in the context of icons; best practice is to outline all strokes, combine and merge complex shapes (eg union, difference etc) and then flatten the vector down to a single object.

Diff’rent strokes. Or preferably none.

**Fixing the issue:** Go to Figma's top menu bar, and choose `Object > Outline Stroke`. #### Flatten vector shapes This is specific to Buzzy — complex vector shapes (such as polygons, stars and so on) need to be flattened in order to render correctly on publish. Plain old frames, rectangles and ellipses work fine as is.

Outline strokes, combine yer shapes, flatten and rename. Done!

**Fixing the issue:** Go to Figma's top menu bar, and choose `Object > Flatten Selection`. #### Use auto layouts where possible, especially for dynamic content Buzzy lets you add dynamic content, menus and more, and publish directly from Figma. In this context, it's critical that your design allows for these items to occupy flexible containers — for instance, there's no point rendering a list of 10 cards or thumbnails directly over the top of each other; they need to render sequentially, whether that's horizontally or vertically. Luckily, Figma lets us define flexible areas like this via Auto layouts. {% hint style="info" %} Here's a [great introduction to Auto layouts by UI Prep](https://www.uiprep.com/blog/ultimate-guide-to-mastering-auto-layout-in-figma). {% endhint %} #### Typographic limitations Buzzy has been developing in leaps and bounds; that said, we're a tiny team, and there's only so many hours in a day. At the moment, there's some basic typographic limitations: * Fonts are limited to Google Fonts (as provided within Figma by default). If you have an identical font installed on your device locally, try to make sure you're specifying the Figma-provided version, not the local one. * Inline text formatting/styling is now supported at a basic block level including transforms, underlines, letter-spacing and indents BUT nested inline styles (eg a section of bold within a regular text block) are stripped out. * Lists within text blocks are not supported yet. #### Using variables or dynamic content in text Implementing dynamic content (eg using variables and values in text) means you have render the value as its own discrete text item — you can't combine a label and dynamic value in one text block.

Splitting the text into separate chunks lets us assign dynamic content or variables to each bit as needed. Note the use of an Auto layout to control position and sizing!

In this example, the user name can be passed in as a variable, but it needs to be defined on its own Text layer, meaning you have to split the 'Hello,' text into a separate, static Text layer. Note the use of an Auto layout to control position and sizing! #### Multiple fills and background images Buzzy currently doesn't support multiple fills or background images on a single item; a workaround is to create a set of Layers to build up the desired outcome — for instance, a base Layer with a background image, and another one with a coloured gradient fill to use as an overlay.

Shiny blue tint! We could dynamically change the image, and the tint effect persists too.

#### Image transforms Image transforms are not currently supported in Buzzy. We get the images as source files basically as Figma receives them (unprocessed), so any transforms or colour shifts need to be done and saved on the original image itself. As a workaround, you can always use Figma to transform your image, export the transformed image using Figma's export settings, and reimport the final image for publication via Buzzy.

Might be time to hit that ’Export’ panel, methinks.

{% hint style="info" %} For more specific troubleshooting guidance, see our [Troubleshooting Buzzy for Figma](/working-with-buzzy/buzzy-for-figma/troubleshooting-buzzy-for-figma) page. {% endhint %} *** ## Figma Video Course If you're eager to delve deeper, take advantage of Supercharge's Advanced Figma Course. This series of video lessons and exercises offers a comprehensive yet easy-to-follow guide that cover Figma's fundamentals and beyond. Highly recommended for hands-on learning, at your own pace. {% hint style="info" %} Use code **BUZZY20AI** to claim 20% off the Core or Extended version of the course. {% endhint %} {% embed url="" %} Click to learn more about the course {% endembed %} *** ## Buzzy Tip: Name your layers! Think of your Figma layers as the backbone of your app's design—keep them clean and clearly named. It's not just about neatness; it's also about making collaboration a breeze, turning handoffs into smooth transitions, and ensuring that tweaking a design is an effortless process. Layer naming can also affect the behaviour of your app components when marked up in Buzzy. Here's an example! {% embed url="" fullWidth="false" %} # Creating a new app directly in Figma Prefer videos? Here's a sequence of short clips that take you through the whole process of using Buzzy AI to create a new app, with tips and explanations. {% hint style="warning" %} Buzzy AI is undergoing daily development and improvement - some of the UI or steps described below may change as we improve the product! {% endhint %} ## Introduction {% embed url="" %} An introduction to Buzzy AI, and overview of the entire process {% endembed %} ## The brief {% embed url="" %} The first step to creating an app - define a brief {% endembed %} ## The data model {% embed url="" %} After the brief comes the data model {% endembed %} ## The screens and publishing {% embed url="" %} Lastly, the AI can generate your screens, ready to publish {% endembed %} # Step by step version The Buzzy Figma plugin now includes an AI assistant that can help you turn an idea into an app design brief, a working data model, an app design from a Figma toolkit, and finally a working app. {% hint style="info" %} Prefer videos? Here's the [same process as some video tutorials](/working-with-buzzy/buzzy-for-figma/creating-a-new-app-directly-in-figma). {% endhint %} ## How it works Having an understanding of what Buzzy AI is and how it works is important to getting the most out of it. 1. The Buzzy AI assistant begins by getting an app description from you, which it uses to create an app brief. 2. This brief acts as a functional specification (a list of functions and user roles) that is then used by the Buzzy AI assistant to generate the app's data model (the data tables, fields and data relationships implied by the brief). 3. The data model is then used by the Buzzy AI assistant to assemble the app screens and user interface design in Figma, using a template system ('toolkit') of prebuilt interface components and layouts. 4. These Figma screen designs are already marked up with Buzzy tags, and are ready to be published and previewed as a Buzzy app, straight from Figma. 5. Brand, style and visual specifications are not part of what the AI can handle at the moment. For this, the idea is to use Figma's existing capabilities. The toolkit uses Figma styles for colours and fonts, and Figma components for interface elements - these make it easy for a Figma designer to quickly edit and refine the app design in Figma once it's been generated, and simply republish. ### How far can AI get you? Buzzy AI isn't a magic, automated app creation tool. It still requires collaboration, oversight and input from you, but does give you a massive head start and saves a huge chunk of time in getting to an initial working version of an app, complete with a data model and core functionality. This can then be tested, branded and refined for production via Figma and Buzzy. {% embed url="" %} ## Before you start Before you start using Buzzy AI, you should: * Have a Figma account, and be able to create high-quality designs using Figma's [tools and features](https://help.figma.com/hc/en-us) * Have installed the[ Buzzy Figma plugin](/working-with-buzzy/buzzy-for-figma/about-buzzy-for-figma) and worked through the demos and videos on the [Getting Started guides and tutorials page](/working-with-buzzy/buzzy-ai/about-buzzy-ai). * [Watch the demo and tech preview videos of Buzzy AI ](https://www.buzzy.buzz/)so you get an idea of what to expect, and how it works ## Get the Buzzy AI-enabled toolkit The Buzzy Figma plugin works on whichever current page of a Figma file you are running the plugin on. The Buzzy AI assistant has an extra requirement - to generate your app screens, it needs access to the AI-enabled Buzzy Figma toolkit. This toolkit is available as a Figma community file, and contains the framework and customisable Figma UI elements the AI will use to construct your app.
Buzzy AI Toolkit v2..2/files/a2ogvpEBhTrVn7UrGbCAhttps://www.figma.com/community/file/1466412289660685275/buzzy-ai-toolkit-v2-2
Grab the toolkit from the [Buzzy Figma community page](https://www.figma.com/@buzzy), and click the 'Open in Figma' button. This will copy the chosen file into your Figma 'Drafts' folder, and open it for you. ## Run the Buzzy plugin in the toolkit file With your copy of a Buzzy AI-enabled toolkit file open, navigate to the page in the file called '**Your App Here**'. This is an empty page, but the file contains all the UI components and themes the AI assistant will use to generate your app. **Now open (run) the Buzzy plugin.** The AI-enabled Buzzy plugin includes an AI assistant chat panel (open it via the robot icon), and tabs for Brief, Model (ex-Data), Theme, Markup (ex Design), Publish, and Settings (Cog icon). You can minimise the plugin via the arrows icon.

Run the plugin and AI assistant on the blank page provided!

{% hint style="info" %} Everything you do with the Buzzy plugin while it is running on a Figma page is associated with that page - so if you generate an app brief, it is saved on this page. Switching to a different page (even in the same file) with the plugin open will change what is displayed in the plugin - for instance, no brief is defined. Switching back to this page will show the brief that was created for this page. **In short: one Buzzy app = one Figma page.** {% endhint %} ## Option: Using your own OpenAI key with Buzzy AI You can speed things up by providing your own ChatGPT-4 enabled OpenAI key ([learn how to get one here](https://docs.buzzy.buzz/buzzy-ai/tips-to-use-buzzy-ai#getting-your-own-gpt-4-api-key)). Click the 'Settings' (cog icon) tab in the plugin and go to 'Manage OpenAI API key'. {% hint style="warning" %} Note: ChatGPT access and GPT-4 API access are different. Having access to the GPT-4 models in ChatGPT does NOT necessarily mean you have access to a GPT-4 API key. {% endhint %}

You can use your own OpenAI key - this could speed things up for you.

## Using the Buzzy AI Assistant The Buzzy AI assistant can help you generate a working app from a basic idea - but to do so it needs to follow a logical sequence of steps, beginning with defining a functional brief, then developing a data model before moving on to generating screen and UI elements in Figma and finally publishing the app. The Buzzy plugin tabs reflect this sequence of steps in a left to right order - Brief > Model > Design + Markup > Publish. ### 1. Define a brief The brief is a text description of your app - it outlines the basic functionality, and is used to define the data model and eventually the user interface. In the Buzzy plugin, go to the 'Brief' tab and open the Buzzy AI assistant panel. Enter a prompt into the AI chat to begin defining your app brief. Some points to remember: * The AI handles simpler, granular requests better; like trying to explain to a child. * Brand and visual UI is not part of what the AI can handle at the moment. * The goal for the brief is to describe your app's data relationships and core functionality in simplistic terms, so the AI can generate your data model. {% code title="An example AI prompt" overflow="wrap" %} ``` Create a recipe app where a user can browse food recipes; each recipe includes an image, a list of ingredients and method. ``` {% endcode %}
The AI assistant will define a brief for you, which will appear in the 'Brief' tab of the plugin. You can ask the AI assistant to modify the brief for you, or you can manually edit the brief itself. Once you are happy that the brief describes your app accurately, you can move on to defining the data model. ### 2. Define your data model Switch the plugin to the 'Model' tab. Provided a brief has been defined, you have the option to generate the data model, either via a button on this tab or by asking the AI assistant to generate it via the chat panel.
The AI will attempt to define a the data model (ie the data tables and fields) required for you app. Again, the more detailed the brief, the better the result is likely to be at this point. You should review the resulting data model and adjust it as needed. For instance, the AI may not have included a product image field in a product table, or it may define an address field as being of type 'text', not 'location'. You can manually modify the fields in the 'Model' tab, or you can prompt the AI assistant to do so via the chat panel. ### 3. Generate your app design Open the 'Markup' tab in the plugin. This is where the interface elements (screens, forms, fields and more) are defined. Provided you have a brief and a data model defined, you can get the AI assistant to generate a working app design and set of screens for you. Trigger this either via a chat prompt (eg 'generate app design') or by clicking the button provided. The AI assistant uses the Figma components of the Buzzy toolkit (on the 'Components' page of the toolkit file you should currently be working within) to automatically generate your app's screens and interface elements. Note this step may take several minutes - the time will vary and depends on your app's complexity.
The page will populate with all the Figma screen designs and UI elements required to build your app. These will have already been marked up by the Buzzy plugin and are ready to publish. ### 4. Publish your app Switch to the 'Publish' tab of the plugin; the app name as defined in the brief you generated above should be pre-populated. Simply hit 'Convert to new Buzzy app'.
{% hint style="info" %} **The first time you publish a Buzzy app from a Figma file, you'll need to enter the file key.** The Buzzy plugin will prompt you for this. Simply open the 'Share' dialog in Figma, and copy the file link. Paste this into the plugin and hit Next. {% endhint %} ### 5. Preview your app When Buzzy has finished publishing your app, you can preview the app. View it in debug mode or a live mode in a browser, or you can use the provided QR code to open the app in a browser on your mobile device.
The plugin also provides a link to manage the app in the Buzzy - this will open the app in the Buzzy workspace (think of it as a CMS). This is where you can configure more advanced settings, view the data tables and manage the app data. ### 6. Generate sample data (optional) Chances are, your app preview will appear rather empty or devoid of content - sure, the interface is there and working, and the data tables, forms and fields are defined, but there's no data available yet. The Buzzy AI assistant can populate your new app with sample data - return to the Figma and the 'Publish' tab of the Buzzy plugin, and you should have the option to generate sample data for your new app via a simple button click.
Note: This step may take several minutes. If it times out, the Buzzy plugin will alert you to this, and you may need to try again. On success, return to your app preview - it should now be populated with example content. ### 7. Tweak your design At this point you should have:
A Figma file containing your app screen and interface elements, marked up with Buzzy functionality/files/SEwdpRYGw08tAhUAmZM5
A live, working web app, populated with example content for you to test/files/NctHfFphgbCUCxR9Ih1p
From here on in, working with your app and the Buzzy plugin follows normal (non-AI) Buzzy patterns: * Edit the Figma design as needed - whether that's changing visual styles or design elements, or adding entirely new screens and functionality * Use the 'Markup' tab of the Buzzy plugin to define Buzzy elements, functionality and behaviours * Use the plugin's 'Publish' tab to re-publish your app {% embed url="" %} # Automarkup **Buzzy Automarkup: Transforming Figma Designs into Functional Apps** **Overview:** Buzzy Automarkup is a groundbreaking capability that allows users to transform Figma designs into fully functional, full-stack applications in just a few steps. Dramatically reduce the time it takes to bring a concepts to life, bridging the gap between design and development. *** **How Automarkup Works:** 1. **Prepare Your Figma Design:** * Use Figma to design your app's interface, following standard Figma design practices. * Ensure your layers, components, and naming conventions are organized for clarity. 2. **Apply Buzzy Automarkup:** * Run the Buzzy Figma plugin,. * Utilize Buzzy’s Automarkup feature to automatically tag your design elements with corresponding data and interaction behaviors. * Automarkup identifies UI components (e.g., buttons, input fields, containers) and assigns functional attributes, saving you the need for manual configuration. 3. **Refine and Customize:** * Adjust the automarked components to meet your specific requirements. * Add additional functionality, business logic, or integrations as needed through the Buzzy editor. 4. **Publish Your App:** * With just a few clicks, deploy your app as a working prototype, a full-stack web app, or even a mobile application. *** **Why Automarkup is a Game-Changer:** * **Faster Development:** Automarkup cuts down hours of manual work by intelligently interpreting your design elements and mapping them to functional app components. * **No Coding Required:** Designers without coding experience can now create complex applications directly from their Figma files. * **Iterate Seamlessly:** Make changes in Figma, reapply Automarkup, and see your updates reflected instantly in your app. * **End-to-End Solution:** From design to deployment, Buzzy handles the entire workflow, enabling rapid prototyping and agile development. ### More info and examples {% embed url="" %} {% embed url="" %} # Responsive layouts Responsive design ensures that your design adjusts to different screen sizes, and is a critical part of modern web and app design ## Before we start Be familiar with Figma - know how its layout constraints work, fully understand auto layouts, understand the importance of nesting and element hierarchy, and know when to use Frames instead of Groups (hint: just about always). {% hint style="warning" %} **Do not go any further until you have read** [**this article**](https://medium.com/buzzy-blog/8-figma-tips-for-ease-of-use-developer-handoff-and-production-bliss-694b5ed5364a)**, and have gone through** [**Getting Started with Figma**](/getting-started-with-buzzy/getting-started-with-figma)**.** {% endhint %} ## What we're doing Here are the basic steps we'll be covering here to make your Figma design responsive with Buzzy: 1. Understand Figma and Buzzy best practices and key concepts 2. Plan your design's responsive behaviours and needs 3. Test your design in Figma - resize, reposition and adjust as needed 4. Ensure your design is working in Figma before moving on to Buzzy 5. Turn on Buzzy responsive mode for your screens 6. Adjust Buzzy responsive settings as needed - min/max, overflow clip, scroll, wrap 7. Publish, test and iterate in a browser ## Key concepts Working with Figma and Buzzy is not like hand-coding an interface - it's easier, but comes with some ground rules: * Neither Figma nor Buzzy currently support `@media` or device queries, or breakpoints * One screen in Figma equals one app screen - you can't dynamically swap screens or views based on screen size or device type * Figma's auto layouts are very similar to CSS flex layouts * Figma's layout constraints (positioning, sizing etc) and auto layouts provide the basics of getting a design to behave responsively as the viewport (browser or device) resizes * Figma lets you define 'fixed' position elements for your screens, such as navigation bars that will remain permanently in view * Figma lets you define [overflow and scrolling behaviours](/working-with-buzzy/buzzy-for-figma/overflow-and-scrolling) that Buzzy will use for your app * ~~Buzzy adds handy additional layout options such as minimum and maximum widths~~\ **NEW: Buzzy now supports Figma's newly-released** [**min-width, max-width and wrapping**](https://help.figma.com/hc/en-us/articles/360040451373-Explore-auto-layout-properties#h_01HB9Q1371C7FP7ZPSEHDN1A9B) **options you can apply to Figma autolayout frames. Simply apply these to your Figma design and Buzzy will render accordingly when published.** Got it? Right, lets dive in. ## Plan your design Assuming you already have a Figma design ready, or are working on one, stop. Take a deep breath and consider it from a layout perspective. Here's some questions to ask yourself: * What screen size have you designed at? Why? * What should happen for users on other screen sizes? * Does any part of a screen need to remain always in view? * Which part (or parts) of the design should scroll if content is longer than the container? * As the screen is resized (for instance, on different devices, or as a user rotates a device to horizontal), which elements should also get resized? Should they stop resizing after a particular point? * As the screen is resized, where should elements be anchored? Is that floating button meant to stay a consistent distance from the left, or should it align to the right edge? Depending on your design, some of the answers to these questions will be self-evident. Others might not become apparent until you do some testing. ## Test in Figma Figma's own layout constraints and settings get you a whole lot of responsive behaviours without leaving Figma. To get a quick idea of how your design resizes, just grab a corner of one of your screens in Figma, and drag it; as it resizes, what happens to your design elements?

Resize your design in Figma - what happens?

## Adjust in Figma Fix any issues using Figma’s layout controls in the right hand design panel — depending on the layer you select, adjust X and Y position and alignment, size and resizing options (for instance `Fill` or `Hug` for items in an auto layout). **Getting your Figma design behaving correctly in Figma itself is key to avoiding problems later. Only when this is done should you add Buzzy to the mix.** ## Add Buzzy settings #### **Required: Turn on 'responsive mode' in Buzzy** To make a Buzzy screen responsive, select the screen in Figma and turn on the 'Make screen responsive' toggle in the Buzzy plugin. This will also give you the option of setting a min- or max-width on the screen itself.

The first step - make the screen responsive via the Buzzy plugin

{% hint style="info" %} Because responsive design is such a tricky concept for novice users, Buzzy defaults to a 'static' layout for screens (meaning a screen is published as a container within the viewport with the exact same dimensions as the Figma frame). This is great for a quick demo or preview, but not for production. [Here's a video explaining it](https://youtu.be/k38Rds2hUYw). {% endhint %} #### Required: Turn on screen scrolling, and set overflow clipping and internal scroll on frames as needed Buzzy supports overflow clipping and internal scrolling settings, including horizontal scrolls. You’ll need to define them on your Figma design using Figma's own settings, the same way you do for your Figma designs and prototypes. [Check this article for details](/working-with-buzzy/buzzy-for-figma/overflow-and-scrolling). {% hint style="info" %} **NEW: Buzzy now supports Figma's newly-released** [**min-width, max-width and wrapping**](https://help.figma.com/hc/en-us/articles/360040451373-Explore-auto-layout-properties#h_01HB9Q1371C7FP7ZPSEHDN1A9B) **options. Simply apply these to your Figma design and Buzzy will render accordingly when published.** {% endhint %} #### Optional: Set min and max widths on individual elements ~~Defining a Figma element as a Buzzy 'Layout' component lets you set a min- or max-width just on that element. This means it will resize as needed (in the published app) until it hits the min or max limit - even if it has a fixed width in Figma.~~ **NEW: Simply use Figma's own min- and max-width options to apply this - no need for a dedicated additional Buzzy wrapper.** In the example below, we want the screen itself and the purple background to be full width, and the content to resize - on small screens it will shrink to fit the viewport, on larger screens it will remain fixed at 940px.

We can set min or max widths on specific elements

#### Optional: Turn on flex wrap ~~Buzzy 'Layout' components also allow you to turn on flex wrapping - this is the equivalent of setting CSS`flex-wrap: wrap;`and means nested elements will wrap as needed. Note this only works with Figma 'auto layout' frames.~~ **NEW: Simply use Figma's own wrap option to apply this - no need for a dedicated additional Buzzy wrapper.** In the example below, we want the 3 feature items to wrap as the viewport shrinks. Note that the other auto layout settings such as the center alignment of elements still applies.

Toggle 'Enable flex wrapping' on...

... et voila! The items wrap as needed

## Publish, test and iterate Work through your design as needed and test as you go - publish your app with the Buzzy plugin, and test your key layouts and screens. Get the basics right in one spot before moving on to the next screen or section of your app. Using the simple techniques above in combination, you can build up some fairly complex responsive designs, including forms that shift from horizontal to vertical layouts as needed. ## Examples Most of the [Buzzy templates and files](https://www.figma.com/@buzzy) available in the Figma community are set up to be responsive. Here's some relevant ones:
Buzzy AI toolkitThe 'Examples' page includes a bunch of common page layouts and examples!https://www.figma.com/community/file/1431169980750969791/buzzy-ai-toolkit-v2-1
Responsive sign up pageThe landing page example shown above; includes flex wrap and a resizing signup form.https://www.figma.com/community/file/1133266300427393119
Overlays, modals & alertsWorking examples showing how Buzzy handles a variety of overlay or modal elements.https://www.figma.com/community/file/1094275656072948640
# Responsive layout checklist Use this to ensure your design works as intended in various systems and resolutions. ## Learn the basics 1. Follow the tips on [Buzzy article on Figma best practices](https://medium.com/buzzy-blog/8-figma-tips-for-ease-of-use-developer-handoff-and-production-bliss-694b5ed5364a) 2. Make sure you understand how to work with [auto layouts and constraints](https://www.uiprep.com/blog/ultimate-guide-to-mastering-auto-layout-in-figma) in Figma 3. Complete [Getting Started with Figma](/getting-started-with-buzzy/getting-started-with-figma) to learn how to mark up and publish an app with Buzzy and Figma ## Apply what you learn 1. Make sure your Figma design is laid out and structured according to best practices as per the articles above 2. Test your screen designs in Figma by resizing them: all your design elements should reposition, resize or scale as intended (within Figma) 3. Turn on **'Responsive Mode'** in the Buzzy Figma Plugin for all the screens that require it ([learn more](/working-with-buzzy/buzzy-for-figma/responsive-layouts#required-turn-on-responsive-mode-in-buzzy)) 4. Define **overflow clipping and scrolling** for all screens and elements that need it (via Figma's Design and Prototype panels) ([learn more](/working-with-buzzy/buzzy-for-figma/responsive-layouts#required-turn-on-screen-scrolling-and-set-overflow-clipping-and-internal-scroll-on-frames-as-needed)) 5. Buzzy now supports Figma's newly-released [min-width, max-width and wrapping](https://help.figma.com/hc/en-us/articles/360040451373-Explore-auto-layout-properties#h_01HB9Q1371C7FP7ZPSEHDN1A9B) options you can apply to Figma autolayout frames. Simply apply these to your Figma design and Buzzy will render accordingly when published.\ (Note: prior to these settings being available in Figma, Buzzy implemented its own responsive settings. Older Buzzy apps and files may still contain these.) 6. Publish and test each screen in a browser # Overflow and scrolling The Buzzy Figma plugin supports overflow and scroll settings. You’ll need to define them on your design in Figma, the same way you do for your Figma designs and prototypes. ## Overflow Show/hide overflow behaviour is set in the Figma ‘Design’ tab, via the ‘Clip content’ checkbox. Select your screen or layer in Figma, and toggle the checkbox: ![](/files/Z4Pw0MLzPZB2cI3PRerZ) ## Scroll Overflow scroll behaviour is set in the Figma ‘Prototype’ tab. Select your screen or layer in Figma, then select the scroll behaviour you need: ![](/files/XnovDleYUz0jIR4InhrJ) {% hint style="info" %} If you can’t scroll a screen in your published app, make sure you have turned scrolling ‘on’ in the Figma settings. {% endhint %} # Forms and fields Core to Buzzy's ability to work with data is how you define forms and fields in your Figma file. {% hint style="info" %} This is a high-leve introduction to working with Buzzy forms and fields only. For a detailed look, check out [Datatables, Fields & Data](/the-building-blocks/datatables-fields-and-data) Also be sure to go through [Getting Started with Figma](/getting-started-with-buzzy/getting-started-with-figma) - this introduces the core Buzzy Figma plugin workflow. {% endhint %} ## Forms The Buzzy plugin lets you define forms and fields directly in your Figma design. When you publish your app, they render as working forms, fields and real data. Just as with other markup languages, a Form is simply a wrapper around a collection of editable fields and data. If you want to render simply app data as (non-editable) content and values, you can do so without a Form. You can either rely on the currrent screen context, or to render a specific subset of results from a repeating set of data (eg a list of articles), you would use View (see below) instead. *** ## Fields Buzzy fields are the containers for data nested inside a Buzzy datatable. They include a variety of attributes (based on their type) and each includes an interface that will display in your published app to act as a way to capture, edit and read the data values contained in your data table. You use the Buzzy Figma plugin to define the elements in your design that will act as these fields when published. ## Field modes {% hint style="info" %} As a general rule-of-thumb, when rendering the data value of a field, use 'Summary' mode, except for date fields, where you'd use 'Value'. {% endhint %} ### Summary Use this inside Views or anywhere you want to render the field data as a simple preformatted value. This is the simplest version, and is what you'll mainly use when rendering data from most fields. ### Value Similar to Summary, but depending on the field type you may get options to format how it renders - for instance date fields can be formatted as a string using a structure such as `` ` ``D MMM, h:mm a`` ` ``. ### Read This renders the field as a disabled input. You'd generally only use this in a form alongside other edit or insert fields, with the difference being you don't want the user to be able to edit this particular one. ### Edit Edit mode can only be applied to fields/inputs where they exist inside a layer defined as a Form in Edit mode. This will render the inputs in an editable format. Buzzy updates the data model instantly when a form is in Edit mode - meaning in this case the fields update their data values instantly (on blur) and the parent Edit form does not need to be submitted. ### Insert Insert mode can only be applied to fields/inputs where they exist inside a layer defined as a Form in Capture mode. This will render the inputs in an editable format, but the form must be submitted for then values to be saved to the data table (see below). ### Additional mode: Filter Filter mode is a special type of field mode that is only available for Text and Formula fields when they are wrapped in a Buzzy Filter component. This is like a special type of form used to construct a search or filtering interface. The fields (Text or Formula) render as editable inputs that are used to assign a search (or filter) term to the Filter component. ### Additional mode: Image This is a special mode available only to Buzzy plain text fields, where you may want to add an image to your design via an external url to the image file. In this case, Buzzy will convert the value of the text field (assumed to be a url to an image file) and render it as an image object, rather than as an input or string. *** ## Views Views are used to obtain a specific set of results from a datatable, for instance to build up a dynamic navigation menu. You might define a View that pulls a subset of data from an 'Articles' data table, and use this to create a dynamic menu of articles in your app. *** ## Submitting a form A Buzzy action of type 'Submit' is generally added to a button nested inside a Form container in Capture mode. The action will submit the current form to the Buzzy datatable. # Images and galleries Dynamic images can be added from a datatable - either as a single image, or as multiple images in a gallery. Working with dynamic images in Figma can be a bit tricky - image fields can render in multiple modes such as insert, edit, read, and summary, and each has different ways of displaying. To see the various options and how they render, grab a copy of our template file below and publish it as a new Buzzy app. {% embed url="" %} # Logging users in to your app Buzzy supports a wide range of logging in and onboarding scenarios. ## Login Action Types ### **Email direct login link (Passwordless Login)** Email the user a link that will log them in. Use this option to enable passwordless login to your app. ### **Login with email and password** Submits the credentials (email and password) for authentication. If successful, navigate to a specified screen. ### **Create password** Creates a new password for a user. Used when an account was created by an admin or when the user was passwordless and now upgrades to a password account. ### **Change password** Change the user’s password; requires the correct current password and a new password. ### **Email reset password link** Email the user a link to reset their password. Your app must have a Reset Password Screen defined. To define a Reset Password Screen, go to the Settings page and enter the name of your Reset Password Screen into the corresponding field. Please note, this action requires you to define a **Confirmation Screen**. A **Confirmation Screen** is the screen that the app navigates to while waiting for the user to complete an out-of-app action (e.g. clicking a link sent on email or sms). A C**onfirmation Screen** should let the user know that the action was performed (e.g. the email or sms was sent) and that they need to complete the action as instructed. ### **Create account (with email verification)** Creates an account with an email and a password, then email the user a link to verify their email address. ### **Invite user** Sends a user’s email an invitation link that allows them to create an account. ### **Reset password** After a user clicks the Reset Password Link sent on email, this action is used to change their password and log them in. ### **Demo login (e.g for App Store approval)** Use this for providing access to Apple or Google app store reviewers to bypass the need to receive an email. ### **Logout** Logs the user out of all sessions (web, mobile, and testing (for developers)) ## Setting up a Login and Registration Flow A login flow typically requires at least a login screen, and a login confirmation screen if passwordless logins are being used. If your login flow also requires registration then a user registration screen, also with a confirmation, would be required as well. Typically there would also be post registration steps for accepting a license and going through some kind of onboarding flow. ### Enabling Logins Login is controlled by Buzzy apps by the Privacy setting. If the app is set to 'Private' a login is required and the user will need to be a assigned to have access to the app. If the Privacy is set to 'Unlisted' or 'Public', no login is required. ### Buzzy AI Toolkit The Figma Buzzy AI Toolkit has examples for each of the screens that would appear in a login flow. If you use the AI app generation in the Buzzy plugin, it will setup the login flow for you, and on publishing to Buzzy, you can test this flow by enabling login on the app. ### AI-Generated Apps All AI-generated apps are ready for logins to enabled: they have login and registration screens as well as license and onboarding screens; the screens are set up in the app settings, and a group has been created for registered users to be added to. All that needs to be done to enable this is to set the app privacy setting to Private, which will typically also already be set up unless you asked for the app to be anonymous in your prompt. ### Login Flow Template Besides the login flow in the AI toolkit, there is also a more comprehensive login demo available here: ## Common Patterns for User Flows When implementing user authentication in your Buzzy apps, there are several common patterns that can help you structure your application effectively. Here are two of the most frequently used patterns: ### User Flow Pattern (Personal Data Pattern) This pattern aligns with the [Personal Data Pattern](https://docs.buzzy.buzz/the-building-blocks/datatables-fields-and-data/security-and-access-control#personal-data-pattern) security model, where users primarily interact with their own data: * When a user logs in, a **User View** filters by the current logged-in user to find their record * **Results View**: If the user has an existing record, you can display their data including any subtables (like projects, tasks, etc.) * **No Results View**: If the user doesn't have a record yet, this indicates they need to create one - typically through a form or set of onboarding screens **Implementation details:** * Set "Who Can View" to "Admins, Authors, Creators & Viewers Only" to allow controlled sharing * Users can view other users' profiles when needed, but typically can't edit them * Use the Viewers field to explicitly allow specific users to view records * Create a view that filters by the current logged-in user (e.g., `Current User = {Current User}`) This pattern is used in many Buzzy templates, including: * [Chat App](https://docs.buzzy.buzz/working-with-buzzy/buzzy-app-examples/buzzy-ai-chat-app) - Users create chats and primarily see their own conversations, but can participate in shared chats * [Locations Report App](https://docs.buzzy.buzz/working-with-buzzy/buzzy-app-examples/) - Users submit location data with admin users able to see all reports * [Course Quiz App](https://docs.buzzy.buzz/working-with-buzzy/buzzy-app-examples/) - Students take quizzes and see their own progress, while instructors can view all results The key advantage of this pattern is that it automatically handles both new and returning users with a single view, simplifying your app's structure. ``` User Flow Pattern Diagram: +----------------+ | User Login | +-------+--------+ | v +----------------+ | User View | | (Filter by | | Current User) | +-------+--------+ | v +---+---+ | | +---v---+ | +---v---+ | No | | |Results| |Results| +-->| View | | View | | | +-------+ +-------+ (Onboarding) (Show User Data) Security: "Who Can View" set to "Admins, Authors, Creators & Viewers Only" Users can view other profiles but typically can't edit them ``` ### Organizations Pattern (SaaS Application Pattern) This pattern implements the [SaaS Application Pattern](https://docs.buzzy.buzz/the-building-blocks/datatables-fields-and-data/security-and-access-control#saas-application-pattern) security model for multi-tenant solutions: * Users first onboard and sign up for a subscription * Once subscribed, they can create an Organization and add users to it * Adding users sends invite messages to new users * When a new user clicks the invite link, they are onboarded to the organization * Users are added to Buzzy Organization or Team structures, which control secure access to information **Implementation details:** * Create an Organization datatable with "Who Can View" set to "Admins, Authors, Creators & Viewers Only" * Use sub-tables for organization-specific data * The organization admin is the "Creator" and manages team membership * Team members can be added as "Viewers" or using "Team Viewers" fields to control access through Buzzy Organization and Team objects * Use hierarchical security with sub-tables to ensure data isolation between organizations The [AI Strategy Plan app](https://docs.buzzy.buzz/working-with-buzzy/buzzy-app-examples/ai-powered-strategy-app) demonstrates this pattern with: 1. Users signing up and creating organizations 2. Organizations having multiple team members 3. Each organization only seeing their own strategies 4. Team members only accessing their organization's data ``` Organizations Pattern Diagram: +----------------+ | User Signup & | | Subscription | +-------+--------+ | v +----------------+ | Create | | Organization | +-------+--------+ | v +----------------+ +----------------+ | Add Team |---->| Buzzy | | Members | | Organization & | | (Send Invites) | | Team Objects | +-------+--------+ +----------------+ | v +----------------+ | New User | | Onboarding | | (via Invite) | +-------+--------+ | v +----------------+ | REST API | | Automation | +----------------+ Security: "Who Can View" set to "Admins, Authors, Creators & Viewers Only" Team members added as "Viewers" or using "Team Viewers" fields ``` **REST API Automation** Both patterns can be automated using the Buzzy REST API, allowing you to programmatically: * Create organizations and teams * Manage team membership * Handle user invitations and onboarding * Control access permissions The AI Strategy Plan app demonstrates this automation capability, making it easier to scale your application as your user base grows. For more detailed information on implementing security for these patterns, see the [Security and Access Control](https://docs.buzzy.buzz/the-building-blocks/datatables-fields-and-data/security-and-access-control#common-security-patterns) documentation. # Theming By default, apps generated with Buzzy AI include a pre-defined collection of themes that you can use to customise the look and feel of your app using Figma. You can also create your own themes. ## Switching between themes Every app generated with Buzzy AI can be imported into Figma for advanced customisation. Once imported, the file will include a set of pre-defined themes including colours, shadows, spacing variables. To swap your current theme to another theme, find the Theme selection menu in the right side panel of your Figma window. Then, select the theme you want to switch to. It may take a few seconds for Figma to update your design with the new theme variables. Once your design is updated on your Figma canvas, hit 'Update the app' from the Publish tab of your Buzzy plugin to update your live Buzzy app. {% embed url="" %} How to swap between themes in Figma and change the look of your Buzzy app in a few clicks {% endembed %} ## Modifying a theme You can also customise one of the pre-defined themes to make it your own. A theme is composed of a set of variables that control different aspects of your app's design such as colours, spacing or other effects (shadows for example). You can modify these variables to make up your own theme. Open the 'Local variables' panel in your Figma file to start modifying. Figma may take a few minutes to update your theme with the new variables. {% hint style="info" %} Can't see the 'Local variables' section in the right-side panel in Figma? Click anywhere on the Figma canvas and make sure you are not selecting any layers, then you should see the 'Local variables' section appear. {% endhint %} {% hint style="warning" %} At this time, Figma only allows one theme to be modified if the file is stored in the user's drafts. To work around this, you can simply delete the themes you are not using to only keep the one you will be modifying. Watch the tutorial video for an example! {% endhint %} {% embed url="" %} How to customise a theme using the Figma variables {% endembed %} ## Customising UI components In addition to the colours and spacing, you can also modify more specific aspects of your design. You can customise the look and feel of any UI elements of your Buzzy app simply by leveraging the UI toolkit included in any Buzzy AI-generated file. By default, once imported into Figma, the apps generated with Buzzy AI will have a 'Components' page which contains a range of Figma components used throughout the app's design. The master components are stored in the 'Components' page of your Figma file, while instances of those components are present in your app's design. This allows you to quickly and easily give your app its own unique look, without the need to change each individual UI element in your design. {% embed url="" %} How to customise specific UI elements using master Figma components {% endembed %} # Troubleshooting Buzzy for Figma ## Common problems Not everything you do in Figma will translate as expected, and Buzzy handles some things you can't do in Figma. Here's some common problems and their solutions.
I can't connect the Buzzy Figma plugin to my Buzzy server or cannot publish as it keeps asking me for the filekey (stuck in a loop) If you're stuck in a loop while reconnecting to [your Buzzy server](/working-with-buzzy/buzzy-deployment-and-app-stores/connecting-your-own-server) and it continually prompts for a file key, follow these steps to resolve the issue: 1. Disconnect by going to the settings (cog icon) in Buzzy. 2. Reconnect to the main Buzzy server at app.buzzy.buzz. 3. Optionally, remove the file key and delete the publishing history. 4. Attempt to reconnect to your Buzzy server again. If the issue persists, please contact support at .
I keep getting stuck in a loop when authenticating with the Buzzy plugin and Figma. It keeps asking me to sign in again. Here’s how to fix it: 1. **Check your system clock** – Make sure your computer’s date, time, and timezone are set correctly. 2. **Enable automatic time sync** – On most systems, you can set your clock to update automatically from the internet. 3. **Try again** – Once your system time is accurate, restart the authentication process. If your clock is set ahead (in the future) or outside the allowed range, Buzzy will ask you to authenticate with Figma repeatedly in order to refresh the token.
My Buzzy app is blank * Make sure you have defined an app 'Start' screen in your Figma design using the Buzzy plugin * See [Getting Started with Figma](/getting-started-with-buzzy/getting-started-with-figma) for basic guidance * See our [responsive layout checklist](/working-with-buzzy/buzzy-for-figma/responsive-layout-checklist) for a detailed breakdown
My Buzzy app doesn't look like my Figma design * If your app UI is rendering but things are shifted, cut off or repositioned, it's likely due to responsive layout issues. Make sure you follow Figma best practices, including use of frames (not shapes or groups), autolayouts and more. For more information check out: * [this article on best practices](https://medium.com/buzzy-blog/8-figma-tips-for-ease-of-use-developer-handoff-and-production-bliss-694b5ed5364a) * [this article on autolayouts](https://www.uiprep.com/blog/ultimate-guide-to-mastering-auto-layout-in-figma) * [this page on responsive layouts](/working-with-buzzy/buzzy-for-figma/responsive-layouts) * [this checklist for responsive layouts](/working-with-buzzy/buzzy-for-figma/responsive-layout-checklist) * Not everything you can do in Figma will translate well to a production Buzzy app. Some design elements won't render at all, and some might not render as expected, some may require workarounds. Some obvious things to watch out for: * Complex vector shapes - flatten these where possible * Layout constraints - use autolayouts * Tyopography - stick to the core free (Google) fonts available in Figma by default * Layer effects - stick to single, simple effects * Vector masks - avoid these; the majority of usecases are better served by using Figma frames with overflow clipped * Image transforms - avoid these. * Animations and video embeds - avoid and handle these as Buzzy data or content.
My Buzzy app is cutting off the content and won't let me scroll * You’ll need to define scroll behaviours on your design in Figma, the same way you do for your Figma designs and prototypes. [See this page for more information](/working-with-buzzy/buzzy-for-figma/overflow-and-scrolling).
My Buzzy app is missing icons or graphics * Complex vector shapes or strokes may not render - simplify and flatten these where possible. * See below for more details, examples and workarounds.
{% hint style="info" %} Make sure you've gone through [Getting Started with Figma](/getting-started-with-buzzy/getting-started-with-figma). If the suggestions on this page don't address your issue, please contact for help {% endhint %} *** ## Layout **Figma's clip content and overflow scrolling settings** need to be used to control your screen's behaviour, as they are in Figma's own prototype views. **By default, screens now publish in a 'fixed size' layout mode.** This means that screens are now going to render at the exact fixed size you define in Figma, and if you want the app to resize in the device or browser viewport you can manually turn on a more advanced 'responsive' mode. [Watch a demo video.](https://youtu.be/k38Rds2hUYw) **Responsive layouts:** To make your designed screens fill your browser or device viewport, turn on 'responsive mode' via the switch below your screen name in the Markup (ex-Design) tab of the Buzzy plugin. Unless you've created your Figma design with this in mind, your layout will look broken the first time you publish. The viewport of your app screen (eg the browser viewport, or device screen) is not the same as a fixed size Figma frame representing a screen - it resizes, and content reflows. Things will be positioned weirdly, or don't resize or reposition at all. [Learn more here.](/working-with-buzzy/buzzy-for-figma/responsive-layouts) **Fixed position screen elements** need to be anchored relative to their appropriate side - for instance, don't anchor a bottom nav bar off the top of the screen and rely on the fixed height of your container to push it to the right spot. ​**Overlay screens such as alerts and dialogs** can't be positioned the same way they are in Figma. To control their position, nest the overlay inside a 'screen' frame, and position it relative to that. [Check out a video demo](https://youtu.be/BHoYPxN3OlY) and grab the [sample file](https://www.figma.com/community/file/1094275656072948640/Buzzy-Plugin%3A-Overlays%2C-modals-and-alerts). **Auto layouts are required for dynamic content and menus** - they need to be laid out in a way that they can handle rendering multiple sequential items. Depending on your design, make sure users can get to the content (eg enable overflow scrolling). **Prototype transitions** (eg between screens) aren't supported (this includes smart animations). ## Typography **Fonts are currently limited to Google Fonts** (as provided within Figma by default). If you have an identical font installed on your device locally, try to make sure you're specifying the Figma-provided version, not the local one. **Inline text formatting/styling** is now supported at a basic block level including transforms, underlines, letter-spacing and indents. Inline styles and nested elements are still stripped out. **Lists within text blocks** are not supported yet (see above - they're a nested element inside a Figma text block). **Borders on text** are not yet supported - if needed, convert the border to an outline (Object > Outline); note that this flattens your text layer. ## Design **Complex vector shapes** (such as polygons, stars etc) need to be flattened in order to render (Object > Flatten Selection). Plain old frames, rectangles and ellipses work fine as is. **Vector lines and arrows** should be outlined in order to render correctly (Object > Outline Stroke). **Fills are limited to one colour or image.** This means colour styles that consist of multiple fills (eg a base colour, then a black or white opacity fill over the top of that) won't render correctly; a workaround is to flatten the styles by sampling the generated colour. **Gradient fills** currently (mostly) work with linear gradients. Non-linear gradient fills (eg radial or angular gradients) aren't supported yet. **Layer rotation** is partially supported. If you're getting unexpected results, you can try to flatten the rotated item (Object > Flatten Selection). **Background blur and inner shadow layer effects** are not yet supported. **Borders** are partially supported; border position always renders inside, and dashed or dotted styles are limited to the html versions (ie you can't control dash or gap widths). Non-solid border fills (eg gradients) are not supported yet. **Image transforms** are not currently supported in Buzzy. We get the images as source files basically as Figma receives them (unprocessed), so any transforms or colour shifts need to be done and saved on the original image itself. As a workaround, you can always use Figma to transform your image, export the transformed image using Figma’s export settings, and reimport the final image for publication via Buzzy. **Animated gifs or Lottie animations** are are not yet supported. # Plugin error messages The Buzzy Figma plugin and the debug/preview mode of your app provide warnings and error messages if something isn’t quite right. Here’s a list of the messages and what they might mean. ## Filter fields must be in a filter element **What it means:** Certain Buzzy field types need to be nested inside a wrapping element like form, view or filter. **How to fix it:** You need to wrap the filter field in a filter element. ## Insert and edit fields must be in a form component **What it means:** Certain Buzzy field types need to be nested inside a wrapping element like form, view or filter. **How to fix it:** You need to wrap ‘insert’ and ‘edit’ mode fields in a form element. ## Insert mode fields can only be used on capture mode form **What it means:** Your field is in ‘insert’ mode, but not wrapped in a form element in ‘capture’ mode. **How to fix it:** You need to wrap ‘insert’ mode fields in the ‘capture’ mode layout of a form element. ## Field must be in ‘insert’ mode on an capture mode form **What it means:** Your field is in a mode other than ‘insert’, but nested inside a form element in ‘capture’ mode. **How to fix it:** All of the fields inside a the ‘capture’ mode layout of a form must be in ‘insert’ mode. ## No row data is available for the field to show; ensure a row is being passed to the screen **What it means:** No data table row was available for the field to read data from. This typically means an action that navigated to this screen was not set up to send data table row data. **How to fix it:** Make sure the relevant navigation action is set to ‘pass current data’ to this target screen. ## Field does not exist in the current row; ensure the correct field has been selected **What it means:** The available data table row did not have the field on it. This typically means either the wrong field was selected, or there is an action that navigated to the screen using a row from the wrong data table view. **How to fix it:** Make sure this field exists in the data table you are currently targeting, and that when navigating to this screen that you are passing data from the correct data table to this screen. ## Field does not match the form data table (microapp) **What it means:** The specified field is not from the same data table as defined on its wrapping form element. A field always belongs to a single parent data table. In this case, you appear to be referring to a field that is not in the data table that the form refers to. **How to fix it:** Make sure your field is in the data table you have created your form for, or your form refers to the data table which contains this field. ## Field does not match the filter data table (microapp) **What it means:** The specified field is not from the same data table defined on the wrapping filter element. A field always belongs to a single parent data table. In this case, you appear to be referring to a field that is not in the data table that your filter refers to. **How to fix it:** Make sure your field is in the data table you are trying to filter, or your filter applies to the data table which contains this field. ## JSONATA error: (specific error message) **What it means:** The JSONATA formula has an error in it as specified in the message. **How to fix it:** Make sure your JSONATA formula uses the correct syntax. See our [docs](/the-building-blocks/datatables-fields-and-data/formulas) and [jsonata.org](https://jsonata.org/) for help on formulas. Use backticks for labels with spaces & special characters. *** # Buzzy Deployment & App Stores ## Table of Contents * [Create and manage Deployments](/working-with-buzzy/buzzy-deployment-and-app-stores/create-and-manage-deployments) * [Publish your app to your Deployment](/working-with-buzzy/buzzy-deployment-and-app-stores/publish-to-deployment) * [Software Config Management](/working-with-buzzy/buzzy-deployment-and-app-stores/software-config-management) * [Setting Up Your Custom Buzzy App](/working-with-buzzy/buzzy-deployment-and-app-stores/setting-up-your-custom-buzzy-app) * [Email Deliverability Guide](/working-with-buzzy/buzzy-deployment-and-app-stores/email-deliverability-guide) * [Email Customization](/working-with-buzzy/buzzy-deployment-and-app-stores/email-customization) * [Connecting Your Own Server](/working-with-buzzy/buzzy-deployment-and-app-stores/connecting-your-own-server) * [Apple & Google App Stores](/working-with-buzzy/buzzy-deployment-and-app-stores/apple-and-google-app-stores) ## Overview If you're looking to run your Buzzy web app on your own domain or publish it to the Apple and/or Google stores you'll need a Buzzy Deployment. You can now self‑service the creation and purchase of a Deployment (including the Small plan) directly from app.buzzy.buzz. See pricing and plans: * ## Server Configuration Each Buzzy app has its own compute, database cluster and storage within your Deployment. This keeps each app's data and configuration separate. Configuration can be tailored to performance and other options such as domain, mail (SMTP), and Maps API keys. ## Multi-Environment Workflows For professional development workflows, Buzzy supports Software Config Management (SCM) which allows you to push app changes between deployment environments. This enables you to develop and test in a Development environment, then promote changes to Staging and Production when ready. See [Software Config Management](/working-with-buzzy/buzzy-deployment-and-app-stores/software-config-management) for details. ## Next Steps * Create and manage Deployments * Publish your app to your Deployment * Software Config Management (push changes between environments) * Setting Up Your Custom Buzzy App * Connecting Your Own Server * Apple & Google App Stores # Create and manage Deployments A Deployment is your own Buzzy server environment with its own URL, database cluster and service endpoints. A single Deployment can host multiple apps (many-to-one: multiple apps → one Deployment). A Deployment is also a prerequisite for publishing native iOS and Android apps to the app stores. ## Self‑service overview You can now create and manage Deployments yourself from app.buzzy.buzz. If you don’t already have an active Deployment subscription, you’ll be guided through the purchase flow during creation. See plan options (including the Small plan) on the pricing page: * ## Plans and purchasing * The Small plan is available alongside other Deployment tiers; choose the plan that best fits your needs. * If you don’t have a Deployment subscription yet, you can purchase one as part of the creation flow. * After purchase, your Deployment will begin provisioning and move to Active when ready. ## Create a Deployment Typical steps: 1. Choose a Deployment name (e.g., your organization or project name). 2. Select a Region: * NA1 – North America (USA) * EU1 – Europe (Germany) * AP1 – Asia Pacific (Australia) 3. Choose your domain option: * Use a buzzy.buzz subdomain (e.g., yourname.buzzy.buzz) * Or use your own domain/subdomain via DNS (CNAME) settings * See domain/DNS setup details in Setting up your custom Buzzy app. 4. Confirm plan/purchase if needed, then create the Deployment. Status lifecycle: * Provisioning → Active (usable) * During provisioning, some settings may be read‑only until the environment is ready. For DNS, SMTP/mail, or Maps configuration, see: * Setting up your custom Buzzy app ## Manage your Deployment From the Deployments area you can: * View your Deployment URL and endpoints * Configure domain settings (switch between buzzy subdomain and your own domain) * Configure Mail (SMTP) settings * Provide a Google Maps API key Detailed configuration guidance: * Setting up your custom Buzzy app ## Publish apps to your Deployment Once you have a Deployment, you can publish apps from app.buzzy.buzz to that Deployment: * See Publish your app to your Deployment Tip: After publishing, it often makes sense to continue creating and iterating your apps directly on your Deployment. ## Use with the Buzzy Figma plugin Buzzy for Figma can connect to your Deployment’s server so you can publish directly to it from Figma. * See Connecting your own server for plugin connection steps ## Multi‑environment setups (Dev/UAT/Prod) You can operate multiple environments by purchasing multiple Deployments (e.g., Development, UAT, Production). After you have the required number of Deployments, contact the Buzzy team to help configure multi‑environment workflows: * ## Troubleshooting and support * Purchasing issues, domain validation, or provisioning delays: contact * For domain/DNS, SMTP/mail, or Maps configuration specifics, see: * Setting up your custom Buzzy app # Publish your app to your Deployment You typically start building your app on app.buzzy.buzz. When you’re ready to host it under your own URL, publish it to your Deployment. A Deployment is required before publishing. ## Prerequisite * You must have an active Deployment. If you don’t have one yet, see: * Create and manage Deployments ## Publish steps (high‑level) 1. In app.buzzy.buzz, open your app in the editor/workspace. 2. Choose Publish. 3. Select your target Deployment from the list. 4. Confirm publishing. Once complete, your app will be available on your Deployment’s URL. ## Continue building on your Deployment After publishing, you may prefer to keep building on the Deployment (especially for team access, data locality, and testing under your own domain). In the UI, select your Deployment environment where applicable when editing or publishing updates. ## Use with the Buzzy Figma plugin If you work from Figma, you can connect the Buzzy plugin to your Deployment server and publish directly there. * See Connecting your own server for plugin connection instructions ## App Stores Publishing to the Apple App Store and Google Play Store requires a Deployment. Initial setup is currently handled via the Buzzy team; automation is coming. * See Apple & Google App Stores * Contact for the initial setup ## Troubleshooting * Don’t see your Deployment in the selector? Ensure it’s Active: * Create and manage Deployments * Domain not resolving after publish? Verify your DNS/CNAME is set correctly and has propagated: * Setting up your custom Buzzy app # Software Config Management Software Config Management (SCM) enables you to push your Buzzy app changes from one deployment environment to another, such as from Development to Staging or from Staging to Production. This feature supports professional development workflows where you build and test in a safe environment before promoting changes to live users. ## Why Use Software Config Management? When building production applications, you typically want to separate your development work from what your users see. SCM allows you to maintain multiple environments (Development, Staging, Production) and control when changes move between them. This approach provides several benefits: **Safe Development**: Make changes, experiment with new features, and fix bugs in your Development environment without affecting production users. Test thoroughly before promoting changes. **Quality Assurance**: Use a Staging environment to perform final testing with real-world conditions before releasing to Production. Catch issues before they reach your users. **Controlled Releases**: Decide exactly when changes go live. Push updates during low-traffic periods, coordinate releases with your team, and maintain full control over your deployment schedule. **Version History**: Every push creates a version snapshot, allowing you to track what changed and when. If something goes wrong, you can reference previous versions. ## How It Works SCM operates on top of Buzzy's versioning system. When you push to another environment, Buzzy packages your app definition (screens, components, fields, actions, display rules) along with any associated files (images, assets) and applies them to the target environment. ### Environment Flow Overview The following diagram shows how changes flow from Development through Staging to Production: ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'14px'}}}%% flowchart LR subgraph DEV["Development Environment"] D1[Build & Test Features] D2[Save Version] end subgraph STAGING["Staging Environment"] S1[QA Testing] S2[User Acceptance] end subgraph PROD["Production Environment"] P1[Live Users] end D1 --> D2 D2 -->|Push Version| S1 S1 --> S2 S2 -->|Push Version| P1 style DEV fill:#e1f5fe,stroke:#01579b style STAGING fill:#fff3e0,stroke:#e65100 style PROD fill:#e8f5e9,stroke:#1b5e20 ``` ### What Gets Pushed When you push a version between environments, the app definition and assets are always transferred. By default, user-related data stays in each environment, but you can optionally choose to include it: **Always pushed:** * App Definition (screens, components, fields, actions, display rules) * Files & Assets (images, documents) **Optionally pushed (typically excluded):** * Users * Teams * Organizations * Organization Membership * User Data (Datatables) In most cases, you'll want to exclude user-related data so that each environment maintains its own users and data. This is the recommended approach for Development to Production workflows. ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'14px'}}}%% flowchart TB subgraph SOURCE["Source Environment"] SA[App Definition
Screens, Components,
Fields, Actions, Rules] SF[Files & Assets
Images, Documents] SD[User Data
Users, Teams, Orgs,
Datatables] end subgraph TARGET["Target Environment"] TA[App Definition] TF[Files & Assets] TD[User Data
Preserved] end SA -->|Always Pushed| TA SF -->|Always Copied| TF SD -.->|Optional
Typically Excluded| TD style SA fill:#c8e6c9,stroke:#2e7d32 style SF fill:#c8e6c9,stroke:#2e7d32 style SD fill:#fff9c4,stroke:#f57f17 style TA fill:#c8e6c9,stroke:#2e7d32 style TF fill:#c8e6c9,stroke:#2e7d32 style TD fill:#fff9c4,stroke:#f57f17 ``` ### The Two-Stage Process The process works in two stages: **Initial Setup**: The first time you connect two environments, Buzzy performs a full setup that clones the database structure and creates a secure link between the environments. This is a one-time operation per environment pair. **Version Push**: After setup, you can push specific versions of your app to the target environment. This transfers only the app definition and assets, not user data, allowing you to update the app while preserving the data in each environment. ```mermaid %%{init: {'theme':'default', 'themeVariables': {'fontSize':'14px'}}}%% flowchart TD A[Start] --> B{First time pushing
to this environment?} B -->|Yes| C[Run Setup] C --> D[Database structure cloned] D --> E[Secure link established] E --> F[Ready for version pushes] B -->|No| F F --> G[Select version to push] G --> H[Push to target environment] H --> I[Target creates backup] I --> J[Changes applied] J --> K[Verify in target] style C fill:#fff3e0,stroke:#e65100 style H fill:#e8f5e9,stroke:#1b5e20 ``` ## Prerequisites Before using SCM, ensure you have the following: 1. **At Least Two Buzzy Deployments with Separate Database Clusters**: SCM requires each deployment to have its own dedicated database cluster. To have a separate database cluster, you need either: * A **Medium Deployment** with the "Database Upgrade" add-on (contact for more information) * A **Large Deployment** which includes a dedicated database cluster by default See [Buzzy Pricing](https://www.buzzy.buzz/pricing) for plan details and [Create and manage Deployments](/working-with-buzzy/buzzy-deployment-and-app-stores/create-and-manage-deployments) for setup instructions. 2. **App on Source Deployment**: Your app must be associated with a source deployment. This is typically where you do your development work. 3. **Appropriate Access**: You must be either a global admin on the deployment or an owner/admin of the specific app you want to push. 4. **Target Environment Configured**: The target deployment must be configured to receive pushes (this is handled during the initial setup process). ## Setting Up Your First Environment The first time you want to push to a new environment, you need to run the Setup process. This creates the connection between your source and target deployments. ### Step-by-Step Setup 1. Open your app in the Buzzy editor on your source deployment (for example, your Development server). 2. Navigate to the **Publish** panel in the editor sidebar. 3. Scroll to the **Setup New Environment** section. 4. Select your target deployment from the dropdown. The list shows all active deployments except your current one. 5. Configure optional exclusions if needed (see below). 6. Click **Setup** and confirm when prompted. The setup process will clone your database structure to the target environment and establish a secure connection for future pushes. This may take a few minutes depending on the size of your database. ### Optional Exclusions During Setup When setting up a new environment, you can choose to exclude certain data from the initial copy: | Option | What It Excludes | When to Use | | ----------------------------------- | --------------------- | ---------------------------------------------- | | Exclude Users | User accounts | When target has its own user base | | Exclude Organizations | Organization records | When target has different organizations | | Exclude Teams & Team Members | Team structures | When target has different team setup | | Exclude Micro App Data & Child Data | All user-entered data | When you only want the app structure, not data | For a typical Development to Production setup, you might exclude user data so that your production environment starts fresh while receiving the app structure and configuration. ## Pushing a Version to an Environment Once setup is complete, you can push versions of your app to the target environment whenever you're ready to release changes. ### Step-by-Step Push 1. Ensure you have saved a version of your app that you want to push. Use the **Versions** tab in the editor to create a version if needed. 2. Navigate to the **Publish** panel in the editor. 3. Scroll to the **Push Version to Environment** section. 4. Select the **Version** you want to push from the dropdown. 5. Select the **Target Environment** from the dropdown. Only environments that have been set up will appear here. 6. Click **Push Version** and confirm when prompted. Buzzy will package your app definition, copy any associated files (images, assets), and apply the changes to the target environment. The target environment automatically creates a backup version before applying changes, so you can roll back if needed. ## Viewing Push History The Publish panel includes a **Push History** section where you can view all setup and push operations. This helps you track what was pushed, when, and whether it succeeded. ### Understanding the History The history shows three types of operations: | Operation | Description | | ------------------------ | ----------------------------------------------------- | | Setup Environment | Initial setup that cloned the database to a target | | Push Version (Sent) | A version push you initiated from this environment | | Apply Version (Received) | A version push this environment received from another | Click on any entry to expand details including timestamps, metadata, and any error information if the operation failed. ## Typical Workflow Example Here's how a typical three-environment workflow might look: **Development Environment** (dev.yourcompany.buzzy.buzz) * This is where you build new features and fix bugs * Test changes thoroughly in preview mode * Save versions when features are ready **Staging Environment** (staging.yourcompany.buzzy.buzz) * Push versions from Development when ready for QA * Perform user acceptance testing * Verify everything works with production-like conditions **Production Environment** (app.yourcompany.buzzy.buzz) * Push versions from Staging after QA approval * This is what your end users see * Schedule pushes during maintenance windows if needed ### Example Release Process 1. **Build in Development**: Create a new feature, test it in preview mode, fix any issues. 2. **Save a Version**: In the Versions tab, save a version with a descriptive name like "v2.3 - New dashboard feature". 3. **Push to Staging**: Use the Publish panel to push this version to your Staging environment. 4. **Test in Staging**: Have your QA team or stakeholders test the changes in the Staging environment. 5. **Push to Production**: Once approved, push the same version from Staging to Production (or push directly from Development if you don't use Staging). 6. **Verify in Production**: Confirm the changes are live and working correctly. ## Working with Versions SCM works hand-in-hand with Buzzy's versioning system. Understanding versions helps you use SCM effectively. **Creating Versions**: Before pushing, save a version in the Versions tab. Give it a meaningful name that describes what changed. **Selecting Versions to Push**: When pushing, you select which version to send. This lets you push a specific, tested version rather than your current work-in-progress. **Automatic Backup**: When a target environment receives a push, it automatically creates a version snapshot before applying changes. This means you can always roll back if something goes wrong. **Version Independence**: Each environment maintains its own version history. A version pushed from Development becomes a new version in Staging, independent of the source. For more on versioning, see the Versions documentation in the editor guide. ## Troubleshooting ### "Target deployment is not configured as an environment" This means you haven't run the initial Setup for this target deployment. Go to the Setup New Environment section and complete the setup process first. ### "Source deployment ID is missing" Your app isn't associated with a deployment. Ensure you're working on an app that's been published to a deployment, not just on app.buzzy.buzz. ### Push succeeded but changes aren't visible Try refreshing the target environment's browser. If using cached assets, you may need to clear your browser cache. Also verify you're looking at the correct environment URL. ### Setup or push is taking a long time Large databases or many assets can take several minutes to process. Check the Push History for status updates. If an operation seems stuck, contact . ### "Invalid shared secret token" error The secure connection between environments may have become invalid. Contact your administrator to use the Validate & Fix feature in the environment management tools. ## Limitations ### Configuration is Pushed "As-Is" When you push a version from Development to Staging or Production, all configuration including action rules, URLs, and endpoints are transferred exactly as they exist in the source environment. This means: **External URLs and Endpoints**: If your Development environment uses different URLs for external services (such as Lambda functions, webhooks, or third-party APIs), those Development URLs will be pushed to the target environment. Before pushing upstream, ensure you update any environment-specific URLs back to their production endpoints. **Example scenario**: You're testing a new feature in Development that calls a Lambda function at `https://dev-api.example.com/function`. When you push to Production, that Development URL will be included. Your Production app would then call the Development API instead of the Production API. **Before pushing upstream, always review**: * API endpoint URLs in your actions * Webhook URLs * External service configurations * Any hardcoded URLs that differ between environments {% hint style="warning" %} **Important**: Always verify that environment-specific configurations (URLs, API endpoints, webhook addresses) are set to their production values before pushing to Staging or Production environments. {% endhint %} ## Best Practices **Always test before pushing**: Use preview mode in your source environment to verify changes work correctly before pushing to another environment. **Use meaningful version names**: When saving versions, use descriptive names that help you identify what changed. This makes it easier to select the right version to push. **Document your releases**: Keep notes about what each push includes, especially for production releases. This helps with troubleshooting and team communication. **Schedule production pushes**: For production environments with active users, consider pushing during low-traffic periods to minimize any potential disruption. **Maintain environment parity**: Try to keep your environments as similar as possible in terms of configuration. This helps ensure that what works in Staging will work in Production. **Review environment-specific settings before pushing**: Check that any URLs, API endpoints, or external service configurations are appropriate for the target environment before pushing upstream. ## Related Documentation * [Create and manage Deployments](/working-with-buzzy/buzzy-deployment-and-app-stores/create-and-manage-deployments) - Set up the deployments you need for multi-environment workflows * [Publish your app to your Deployment](/working-with-buzzy/buzzy-deployment-and-app-stores/publish-to-deployment) - Initial publishing from app.buzzy.buzz to your deployment * [Setting up your custom Buzzy app](/working-with-buzzy/buzzy-deployment-and-app-stores/setting-up-your-custom-buzzy-app) - Configure domains, email, and other deployment settings # Setting up your custom Buzzy app Using your own domain, publishing to the app stores and more This page covers the configuration details you may need after creating your Deployment via self‑service (domain/DNS, mail SMTP, Google Maps). If you haven’t created a Deployment yet, see “Create and manage Deployments”. Once you have a Deployment, you can publish from app.buzzy.buzz—see “Publish your app to your Deployment”. ## Setting up your server Configuration options for your own Buzzy server: ### **App name** This just needs to be something unique in the realm of Buzzy deployment names. We recommend something like the name of your organization or project. ### Region You need to choose the region you'd like to deploy in, at the moment, these options are available: * NA1 - North America (in the USA) * EU1 - Europe - (in Germany) * AP1 - Asia Pacific - (in Australia) Based on the chose region, this is where you app's data will reside and be served from. ### Domain name You have two options to configure the domain name setup: #### 1. Use Buzzy's domain with your own custom sub-domain Use your custom sub-domain with a Buzzy domain - as an example: `somethingcustom.buzzy.buzz` The sub-domain here is `somethingcustom`. Constraints it needs to be unique and not anything offensive, aligned with Buzzy's terms and conditions. #### 2. Your own domain Setup your own sub-domain to point to the Buzzy deployment, for example "app.\.com " where "app" is the sub-domain. You will need to go to your DNS provider, like Godaddy, and setup a CNAME record to the details below. As an example, of how to setup on Godaddy please see [here](https://au.godaddy.com/help/add-a-cname-record-19236). If you need help, please reach out to your DNS provider to get help on how to do this. The CNAME record will need to be setup to point to one of the following servers depending on the region your Buzzy server will be in: 1. NA1 point to `communication-k8s.buzzycompany.com` 2. EU1 point to eu1-cluster.buzzy.buzz 3. AP1 point to `communication-sydney-cluster.buzzycompany.com` Once setup you should be able to validate it's been done correctly a `nslookup` web site like [CNAME lookup](https://www.nslookup.io/cname-lookup/). You can also do a `nslookup` or `dig` on your computer via the Terminal/Command prompt. {% hint style="info" %} If you want to have your own domain but need more time to set it up, we can set up your server with the Buzzy domain to start with and switch to your custom domain once it is ready. {% endhint %} ### Mail Settings To send mail from you own servers we'll need return users eg `info@yourdomain.com`a SMTP url in the format of `smtps://USERNAME:PASSWORD@HOST:PORT` you will need to get this from your mail provider (get Sendgrid, Mailchimp etc)\ \ in addition the the mail SMTP url, as part of this setup you will need to supply the following: * Mail Logo (recommend keeping it under 280px wide) * Mail sender email address * Mail `donotreply` email address please send these through to {% hint style="info" %} For detailed email deliverability best practices, provider-specific configurations, and anti-spam setup instructions, see our comprehensive [Email Deliverability Guide](/working-with-buzzy/buzzy-deployment-and-app-stores/email-deliverability-guide). {% endhint %} ### Google Maps API Key To enable Google Maps functionality in your Buzzy app, you'll need to set up a Google Maps API key and provide it to us. Follow these steps: #### 1. Sign in to Google Cloud Console * Go to * Sign in with your Google account (or create one if you don't have one). #### 2. Create a new project * In the top-left, click the project dropdown, then New Project. * Give it a name like "My Maps Demo", choose your organisation (if prompted), and click Create. * Wait a few seconds for it to finish. #### 3. Enable billing * Google Maps APIs require a billing account, though you get a free monthly credit. * In the left menu, go to Billing. * Follow prompts to add a credit card. * Once set up, billing will be linked to your project. #### 4. Enable the required Maps APIs * In the left menu, go to APIs & Services » Library. * Search for and Enable each of these APIs: * Maps JavaScript API * Geocoding API * Directions API * Places API #### 5. Create your API key * Still under APIs & Services, click Credentials. * Click + CREATE CREDENTIALS and choose API key. * Google generates a long string—that's your key. #### 6. Secure your key (strongly recommended) * Unrestricted keys can be abused if someone finds them. Let's lock it down: * On the Credentials page, click your new key's name. * Under Application restrictions, choose HTTP referrers (web sites). * Add your site's URL(s), e.g. * \* * \* * Under API restrictions, select Restrict key, then select only the four APIs you enabled: * Maps JavaScript API * Geocoding API * Directions API * Places API {% hint style="info" %} You'll need to provide this API key to us when setting up your Buzzy deployment. This allows your app to use Google Maps features while maintaining security and usage control. {% endhint %} # Email Deliverability Guide Comprehensive guide to email deliverability and SMTP configuration for Buzzy apps When setting up email for your Buzzy app, proper configuration is crucial to ensure your emails reach recipients' inboxes rather than being filtered as spam. This guide provides detailed configuration instructions for popular email providers and essential anti-spam best practices. ## Overview Email deliverability depends on several factors: * **SMTP Configuration**: Proper server settings and authentication * **Domain Authentication**: SPF, DKIM, and DMARC records * **Sender Reputation**: Consistent sending practices and monitoring * **Content Quality**: Professional email content and formatting ## Generic Anti-Spam Best Practices ### SPF (Sender Policy Framework) SPF prevents email spoofing by specifying which servers can send email for your domain. **Action**: Add a TXT record to your domain's DNS: ``` v=spf1 include:[your-provider-spf] -all ``` Replace `[your-provider-spf]` with your email provider's SPF record (see provider sections below). ### DKIM (DomainKeys Identified Mail) DKIM digitally signs your emails to prove authenticity and prevent tampering. **Action**: 1. Enable DKIM in your email provider's settings 2. Add the provided CNAME records to your domain's DNS 3. Verify DKIM is active before sending production emails ### DMARC (Domain-based Message Authentication, Reporting, and Conformance) DMARC tells receiving servers what to do when SPF or DKIM fails and provides reporting. **Action**: Add a TXT record to your domain's DNS: ``` _dmarc.yourdomain.com IN TXT "v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com" ``` **Policy Options**: * `p=none`: Monitor only (recommended for testing) * `p=quarantine`: Send suspicious emails to spam folder * `p=reject`: Reject emails that fail authentication (strictest) ### General Best Practices * **Use a real "From" address**: Avoid generic addresses like noreply@ * **Maintain consistent sending patterns**: Avoid sudden volume spikes * **Monitor bounce rates**: Keep bounce rates below 5% * **Use professional email content**: Avoid spam trigger words and excessive formatting * **Implement proper unsubscribe mechanisms**: Honor unsubscribe requests promptly ## Provider-Specific Configurations ### Microsoft Office 365 **Recommended for**: Organizations already using Microsoft 365 for email #### SMTP Settings | Setting | Value | | -------------- | ----------------------------------------------------------------------------------- | | SMTP server | `smtp.office365.com` | | SMTP port | `587` (STARTTLS) | | Encryption | STARTTLS (sometimes called "TLS") | | Authentication | Username + Password (user's O365 email and password or App Password if MFA enabled) | | Username | `user@yourdomain.com` | | Password | O365 password (or App Password) | **SMTP URL Format**: `smtps://user@yourdomain.com:password@smtp.office365.com:587` **Note**: Microsoft requires SMTP AUTH to be enabled for the mailbox. [Reference](https://learn.microsoft.com/en-us/exchange/clients-and-mobile-in-exchange-online/authenticated-client-smtp-submission) #### Domain Authentication Setup **SPF Record**: ``` v=spf1 include:spf.protection.outlook.com -all ``` **DKIM Setup**: 1. Go to [Microsoft 365 Defender portal](https://security.microsoft.com/dkimv2) 2. Follow [Microsoft's DKIM instructions](https://learn.microsoft.com/en-us/microsoft-365/security/office-365-security/use-dkim-to-validate-outbound-email?view=o365-worldwide) 3. Add the two CNAME records shown in the portal to your DNS **DMARC Record**: ``` _dmarc.yourdomain.com IN TXT "v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com" ``` #### Office 365 Specific Notes * **Sending Limits**: Check [Microsoft 365 sending limits](https://learn.microsoft.com/en-us/exchange/recipients-in-exchange-online/mailbox-limits#sending-limits) * **Message Trace**: Use Microsoft 365 Message Trace to monitor email delivery * **MFA Considerations**: If Multi-Factor Authentication is enabled, use App Passwords instead of regular passwords ### SendGrid **Recommended for**: High-volume transactional emails and advanced analytics #### SMTP Settings | Setting | Value | | -------------- | ------------------------------- | | SMTP server | `smtp.sendgrid.net` | | SMTP port | `587` (STARTTLS) or `465` (SSL) | | Encryption | STARTTLS or SSL | | Authentication | Username + API Key | | Username | `apikey` | | Password | Your SendGrid API Key | **SMTP URL Format**: `smtps://apikey:your_api_key@smtp.sendgrid.net:587` #### Domain Authentication Setup **SPF Record**: ``` v=spf1 include:sendgrid.net -all ``` **DKIM Setup**: 1. In SendGrid dashboard, go to Settings > Sender Authentication 2. Authenticate your domain 3. Add the provided CNAME records to your DNS **DMARC Record**: ``` _dmarc.yourdomain.com IN TXT "v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com" ``` #### SendGrid Specific Notes * **API Key Security**: Use API keys with minimal required permissions * **Dedicated IP**: Consider dedicated IP for high-volume sending * **Suppression Management**: SendGrid automatically manages bounces and unsubscribes ### Mailgun **Recommended for**: Developers who need programmatic email control and detailed APIs #### SMTP Settings | Setting | Value | | -------------- | ------------------------------------ | | SMTP server | `smtp.mailgun.org` | | SMTP port | `587` (STARTTLS) or `465` (SSL) | | Encryption | STARTTLS or SSL | | Authentication | Username + Password | | Username | `postmaster@your-domain.mailgun.org` | | Password | Your Mailgun SMTP password | **SMTP URL Format**: `smtps://postmaster@your-domain.mailgun.org:password@smtp.mailgun.org:587` #### Domain Authentication Setup **SPF Record**: ``` v=spf1 include:mailgun.org -all ``` **DKIM Setup**: 1. In Mailgun dashboard, go to Sending > Domains 2. Add your domain and verify ownership 3. Add the provided TXT records to your DNS **DMARC Record**: ``` _dmarc.yourdomain.com IN TXT "v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com" ``` #### Mailgun Specific Notes * **Domain Verification**: Verify domain ownership before sending * **EU Region**: Use `smtp.eu.mailgun.org` for EU region * **Webhook Integration**: Set up webhooks for delivery tracking ### Amazon SES **Recommended for**: AWS-integrated applications and cost-effective high-volume sending #### SMTP Settings | Setting | Value | | -------------- | ----------------------------------------------------- | | SMTP server | `email-smtp.us-east-1.amazonaws.com` (or your region) | | SMTP port | `587` (STARTTLS) or `465` (SSL) | | Encryption | STARTTLS or SSL | | Authentication | SMTP Username + SMTP Password | | Username | Your SES SMTP Username | | Password | Your SES SMTP Password | **SMTP URL Format**: `smtps://smtp_username:smtp_password@email-smtp.us-east-1.amazonaws.com:587` #### Domain Authentication Setup **SPF Record**: ``` v=spf1 include:amazonses.com -all ``` **DKIM Setup**: 1. In AWS SES console, go to Configuration > Verified identities 2. Select your domain and enable DKIM 3. Add the provided CNAME records to your DNS **DMARC Record**: ``` _dmarc.yourdomain.com IN TXT "v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com" ``` #### Amazon SES Specific Notes * **Sandbox Mode**: New accounts start in sandbox mode with sending restrictions * **Region Selection**: Choose the region closest to your users * **Reputation Monitoring**: Monitor bounce and complaint rates in SES console ### HubSpot **Recommended for**: Marketing automation and CRM integration #### SMTP Settings | Setting | Value | | -------------- | --------------------- | | SMTP server | `smtp.hubspot.com` | | SMTP port | `587` (STARTTLS) | | Encryption | STARTTLS | | Authentication | Username + Password | | Username | Your HubSpot email | | Password | Your HubSpot password | **SMTP URL Format**: `smtps://your_email:password@smtp.hubspot.com:587` #### Domain Authentication Setup **SPF Record**: ``` v=spf1 include:_spf.hubspot.com -all ``` **DKIM Setup**: 1. In HubSpot, go to Settings > Website > Domains & URLs 2. Connect your domain 3. Add the provided CNAME records to your DNS **DMARC Record**: ``` _dmarc.yourdomain.com IN TXT "v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com" ``` #### HubSpot Specific Notes * **Connected Domain**: Domain must be connected in HubSpot settings * **Marketing Hub**: Some features require Marketing Hub subscription * **Contact Management**: Integrates with HubSpot CRM for contact tracking ### Generic SMTP Providers For other SMTP providers not listed above, follow this general configuration pattern: #### SMTP Settings Template | Setting | Value | | -------------- | ------------------------------- | | SMTP server | `smtp.yourprovider.com` | | SMTP port | `587` (STARTTLS) or `465` (SSL) | | Encryption | STARTTLS (preferred) or SSL | | Authentication | Username + Password or API Key | | Username | Your email or username | | Password | Your password or API key | #### Domain Authentication Template **SPF Record**: Contact your provider for their SPF include directive **DKIM Setup**: Enable in provider settings and add required DNS records **DMARC Record**: Use the standard DMARC format shown above ## Troubleshooting & Monitoring ### Common Issues **Authentication Failures**: * Verify username and password are correct * Check if two-factor authentication requires app passwords * Ensure SMTP AUTH is enabled for the account **Connection Issues**: * Verify SMTP server address and port * Check firewall settings allow outbound connections * Test with telnet: `telnet smtp.provider.com 587` **Delivery Issues**: * Check SPF, DKIM, and DMARC records are properly configured * Monitor bounce rates and spam complaints * Verify sender reputation with tools like mail-tester.com ### Monitoring Tools **Email Testing**: * [mail-tester.com](https://www.mail-tester.com/): Test spam score * [MXToolbox](https://mxtoolbox.com/): DNS and deliverability testing * [DMARC Analyzer](https://www.dmarcanalyzer.com/): DMARC report analysis **Provider-Specific Monitoring**: * **Office 365**: Message Trace in admin center * **SendGrid**: Email Activity dashboard * **Mailgun**: Logs and analytics in dashboard * **Amazon SES**: Sending statistics in AWS console ### Best Practices for Monitoring * Set up DMARC reporting to monitor authentication failures * Regularly check bounce and complaint rates * Monitor sender reputation scores * Test email delivery to major providers (Gmail, Outlook, Yahoo) * Set up alerts for delivery issues ## Summary Checklist Before going live with your email configuration: ### Technical Setup * [ ] SMTP credentials configured in Buzzy * [ ] SPF record includes your provider's directive * [ ] DKIM enabled and DNS records added * [ ] DMARC record added (start with `p=none` for testing) * [ ] Test email delivery to major providers ### Monitoring Setup * [ ] DMARC reporting configured * [ ] Provider-specific monitoring enabled * [ ] Bounce and complaint tracking set up * [ ] Regular deliverability testing scheduled ### Content and Compliance * [ ] Professional "From" address configured * [ ] Unsubscribe mechanism implemented * [ ] Email templates tested for spam triggers * [ ] Sending volume gradually ramped up ### Documentation * [ ] SMTP settings documented for your team * [ ] DNS records backed up * [ ] Provider account credentials securely stored * [ ] Monitoring procedures documented ## Additional Resources ### Official Documentation Links * [Microsoft: DKIM in Microsoft 365](https://learn.microsoft.com/en-us/microsoft-365/security/office-365-security/use-dkim-to-validate-outbound-email?view=o365-worldwide) * [Microsoft: SPF in Microsoft 365](https://learn.microsoft.com/en-us/microsoft-365/security/office-365-security/set-up-spf-in-office-365-to-help-prevent-spoofing?view=o365-worldwide) * [Microsoft: DMARC in Microsoft 365](https://learn.microsoft.com/en-us/microsoft-365/security/office-365-security/use-dmarc-to-validate-email?view=o365-worldwide) * [SendGrid: Domain Authentication](https://docs.sendgrid.com/ui/account-and-settings/how-to-set-up-domain-authentication) * [Mailgun: Domain Verification](https://documentation.mailgun.com/en/latest/user_manual.html#verifying-your-domain) * [Amazon SES: Authenticating Email](https://docs.aws.amazon.com/ses/latest/dg/send-email-authentication.html) ### Email Deliverability Resources * [Return Path Email Deliverability Guide](https://returnpath.com/) * [DMARC.org](https://dmarc.org/) - Official DMARC specification * [Email on Acid](https://www.emailonacid.com/) - Email testing platform * [Litmus](https://www.litmus.com/) - Email testing and analytics *** {% hint style="info" %} Email deliverability is an ongoing process. Start with basic authentication (SPF, DKIM, DMARC) and gradually implement advanced monitoring and optimization based on your sending volume and requirements. {% endhint %} # Email Customization Customize the emails Buzzy sends from your deployment Buzzy allows administrators to customize the emails sent from their deployment, including branding, sender information, and content. This feature provides a user-friendly interface to configure email settings without modifying server configuration files. ## Prerequisites Before you can customize emails, you need: 1. **Your own Buzzy Deployment** - Email customization is only available for self-hosted deployments 2. **Secure SMTP configured** - Set up email delivery following the [Email Deliverability Guide](/working-with-buzzy/buzzy-deployment-and-app-stores/email-deliverability-guide) ## Accessing Email Customization Settings 1. Log in to your Buzzy deployment as an administrator 2. Navigate to **Settings** 3. Expand the **Email Customization** section ## Configuration Options ### App Name (in emails) Override the application name that appears in email communications. This allows you to brand emails with your organization's name rather than the default deployment name. **Example**: If your deployment is named "Acme Corp Buzzy" but you want emails to simply say "Acme Portal", enter "Acme Portal" here. ### Reply-To Email Set the email address that recipients will reply to when they respond to Buzzy emails. This is useful when you want replies to go to a support inbox rather than a no-reply address. **Example**: `support@yourcompany.com` ### Reply Name Set the display name associated with the Reply-To email address. This name appears in email clients alongside the reply address. **Example**: "Acme Support Team" ### From Email Customize the display "From" address shown in emails. This changes only the display address that recipients see - the actual SMTP/MAIL\_URL configuration remains unchanged for delivery purposes. **Example**: `notifications@yourcompany.com` {% hint style="info" %} The From Email setting only changes the display address. Your SMTP configuration (MAIL\_URL) determines the actual sending server and authentication. {% endhint %} ### Custom Logo Upload a custom logo to appear in email communications instead of the default Buzzy logo. **Requirements**: * Format: PNG or JPG * Width: 150px wide (recommended) * Storage: Uploaded logos are stored in your app's S3 bucket Click **Upload Logo** to select and upload your logo file. ### Before CTA (Markdown) Add optional content that appears before the main call-to-action button in emails (such as login links). This field supports Markdown formatting, allowing you to include: * Custom welcome messages * Important notices or disclaimers * Links to additional resources * Formatted text with bold, italic, or lists **Example**: ```markdown Welcome to our platform! If you have any questions, please contact [support@yourcompany.com](mailto:support@yourcompany.com). ``` ## Troubleshooting ### Logo not displaying in emails * Verify the image is in PNG or JPG format * Check that the image uploaded successfully to S3 * Ensure your S3 bucket permissions allow public read access for email assets ### Changes not reflected in emails * Email customization changes take effect immediately for new emails * Previously queued or cached emails may still show old settings * Clear any email preview caches if testing ## Related Documentation * [Email Deliverability Guide](/working-with-buzzy/buzzy-deployment-and-app-stores/email-deliverability-guide) - Configure SMTP and improve email delivery * [Setting up your custom Buzzy app](/working-with-buzzy/buzzy-deployment-and-app-stores/setting-up-your-custom-buzzy-app) - General deployment configuration * [Buzzy Settings](/advanced-deployment-settings/installation/buzzy-settings) - Server-level configuration options # Connecting your own server This page focuses on pointing tools and traffic at your own Deployment server (e.g., Figma plugin connection, DNS/SSL concepts). You can now create and manage Deployments yourself—see “Create and manage Deployments”. After creation, complete configuration steps (domain/DNS, mail SMTP, Maps) using “Setting up your custom Buzzy app”. ## Connecting the Buzzy Figma plugin to your own server If you have your own Buzzy Deployment, you’ll want to connect your Buzzy Figma plugin to your server so your Figma file publishes to it, not the default `app.buzzy.buzz` server. Table of contents 1. [Disconnect your Buzzy Figma plugin from the default server](#disconnect-your-buzzy-figma-plugin-from-the-default-server) 2. [Connect the plugin to your own server](#connect-the-plugin-to-your-own-server) 3. [Errors or timeout? Reset the connection](#errors-or-timeout-reset-the-connection) *** ### Disconnect your Buzzy Figma plugin from the default server Before you start, make sure you have configured your server, and any DNS changes have propagated. For DNS guidance, see “Setting up your custom Buzzy app”. Once that’s ready, disconnect your Buzzy Figma plugin from the default server. Open Figma and launch the Buzzy plugin (on any Figma file). Go to the ‘Settings’ tab in the plugin (the cog icon), and click ‘Disconnect from Buzzy’. This will also log you out of the Buzzy CMS if you have it open in a browser window. ![](/files/1OOnoRh1LHZi2QCa9Dux) ### Connect the plugin to your own server The plugin will log you out of Buzzy, and display its connection screen. Click the ‘Server URL’ link at the bottom left. ![](/files/2gMZ3ymJmGU26sXVF5uk) Enter your server URL (without the trailing slash `/`) and click ‘Apply’. ![](/files/EJAeGyn4taNVAdpAPctF) {% hint style="danger" %} **Important: Do \_not**\_\*\* include a trailing slash `/` in your server url !\*\* The input may try to add it by default - make sure you delete it if it’s there. {% endhint %} The plugin will attempt to contact your Buzzy server—this may take some time. It will then refresh and display the connection screen again. Click ‘Connect to Buzzy’ and proceed as normal. ### Errors or timeout? Reset the connection If you made a mistake entering your server url and get the timeout screen, or want to reset it to the default (`https://app.buzzy.buzz`), simply hit the ‘Reset’ button. ![](/files/IIU7uTBdPGK6Eer4z0Py) **Note:** Your plugin connection settings apply across the board within Figma—if you connect the plugin to your server, it will remain connected to that server even if you switch Figma files. To switch, disconnect the plugin and connect it to the relevant server for your next file/app. *** # Apple & Google App Stores Note: to create native (iOS and Android) accounts you will need a minimum of a [Buzzy Medium Deployment](https://www.buzzy.buzz/pricing#deployment) plan or better. A Deployment is a prerequisite for app store publishing. Currently, initial app store setup is handled by the Buzzy team; an automated flow is planned. Please contact to get started. To publish apps on both the Apple App Store and Google Play Store, you'll need to follow specific steps for each platform. {% hint style="success" %} Use to generate your Android, iOS and web icons. Let it worry about dimensions, specs and formats. {% endhint %} *** ## Apple App Store ### Assets For Apple documentation on required assets and publishing to the app store, see You'll need the following: * App name (max 30 char) * Icon (see ) * Subtitle (max 30 char) * Previews (optional video) (see ) * Screenshots (max 10) (see ) * Description text * Promotional text (max 170 char) * Keywords * Categories see ### Publishing Steps 1. **Create an Apple Developer Account**: * Create an Apple ID if you don't have one. * Enrol in the Apple Developer Program as an individual or organization. * Provide necessary details like name, address, and, for organizations, a D-U-N-S Number. * Please follow instructions [here](https://developer.apple.com/programs/enroll/) 2. **App Listing and Metadata**: * Prepare an engaging app title, description, keywords, and screenshots (see above). * Set pricing and availability regions in App Store Connect. * See instructions for creating your app listing [here](https://developer.apple.com/help/app-store-connect/create-an-app-record/add-a-new-app/) 3. **Connecting Buzzy to your Apple App**: * Once you have your Apple Account and App set up, reach out to to provide access so Buzzy can publish your app to Apple TestFlight. This allows you to verify your app is working and ready for submission to Apple for approval. 4. **Publish the App**: * Once approved, your app will be available on the App Store. *** ## Google Play Store ### Assets For a simple reference article, check out You'll need the following: * App name * Description (The first 255 characters are immediately visible to users before they need to hit the More button) * Video preview (YouTube, optional — use the full YouTube URL; up to \~2 minutes) * Square icon (JPEG image, 512 × 512 pixels) * Screenshots (JPEG images, 1242 × 2208 pixels, recommended 3–6 screenshots) * Banner (JPEG, 1024 × 500 pixels) ### Publishing Steps 1. **Create a Google Play Developer Account**: * Visit the Google Play Developer Console and [create an account](https://play.google.com/console/signup) 2. **Prepare Your App**: * Ensure the app is stable and follows Google's Material Design guidelines. * Review content for compliance with Google Play policies. 3. **App Listing on Google Play Store**: * Log in to your Google Play Developer account. * Click on "Create App" and fill in the app's details, including title, description, and graphics. * Set pricing and distribution settings. 4. **Connecting Buzzy to your Google App**: * Build your app in release mode. * Once you have your Google Play Console account and App listing set up, reach out to to provide access so Buzzy can publish your app to the Internal Test Track. This allows you to verify your app is working and ready for submission to Google for approval. 5. **Publish Your App**: * Submit your app for review in the Google Play Console. * Once approved, your app will be available on the Google Play Store. By following these steps for each platform, you can successfully publish your apps on both the Apple App Store and Google Play Store. Ensure you adhere to each platform's guidelines to streamline approval and publication. # iOS & Android App Deployment Complete overview and guide on automated mobile app publishing for iOS and Android using Buzzy. Buzzy now supports automated mobile app publishing. Buzzy can build your app and publish it to your app store/ Google Play account. Mobile app publishing requires that you first have a valid deployment and active subscription. If you don't have an active deployment please see [Create and manage Deployments](/working-with-buzzy/buzzy-deployment-and-app-stores/create-and-manage-deployments). Users may choose to deploy apps to Android and/or iOS. {% hint style="info" %} **Include accessibility in mobile release readiness.** Web-browser results do not establish accessibility for a signed mobile build. Test the production app with VoiceOver on iOS and TalkBack on Android, including navigation, forms, errors, dialogs, orientation, larger text and any device-specific integrations. See [Accessibility at Buzzy](/accessibility#mobile-applications). {% endhint %} ### Managing Mobile Deployment in the Buzzy Editor Mobile app deployment controls can be found under the **Publishing** tab in the editor, then scroll down to the **Deployment** section, under active deployments, click on **View** on your deployment for the app and scroll down to the **Mobile App Deployment** section. Each mobile deployment, Android or iOS has a readiness attribute. When all the required information is provided to Buzzy, then an app is ready to be built and deployed. See the [#ios-app-deployment](#ios-app-deployment "mention")and/or [#android-app-deployment](#android-app-deployment "mention")sections on exactly how to obtain this deployment information. #### What does Buzzy need in order to deploy your app? Buzzy requires API access to user's iOS and/or Google Play developer accounts using an API key/certificate. As such, users agree to give the Buzzy system access to create releases and publish app bundles to your accounts. Buzzy also requires the app bundle signing certificates, app bundle signing is strictly required for both iOS and Android in order to get a user's app into the app/play stores. ## Shared Properties A set of shared properties are required for either iOS and Android. * App Display Name * Buzzy Settings Override * This is a generated property, Buzzy will generate the correct settings in order to link the mobile app to your Buzzy app. Simply click the **Generate** button in the deployment window. * Client assets * Splash screen background color ### Client assets This is a zip file that contains the app logo and splash screen assets for iOS and Android. We've provided the standard Buzzy app assets as a guide to what is required. If only publishing to either Android or iOS users only need to provide assets for the platforms they are publishing to. {% file src="/files/l3gYCx3KsyBlOTqLlrAk" %} Users must ensure the asset file structures adheres to the example above. Some useful web tools for creating/generating mobile app assets: * * ## iOS App Deployment ### Requirements Before beginning the deployment process, please ensure that you are enrolled as an Apple developer, this is where you will manage your app store listing and app marketing information. In order for Buzzy to deploy your app to your Apple account, we require the following information:
This documentation will guide you through the collection of this information. ### Register a Bundle ID Before being able to create a new app in App Store Connect, you must first register a bundle ID. The bundle ID is a unique identifier for your application. This is usually your domain name backwards plus the name of the app at the end. For example, the app MovieTest hosted under buzzy.buzz becomes **buzz.buzzy.movietest**. To register a new bundle ID, go to: {% embed url="" %}
Click on the **+** next to identifiers to create a new bundle ID. Then keep **App IDs** selected then click **Next**. Select **App** for the type then **next**.
Add a description, and your Bundle ID. Note the **App ID Prefix**, save this Team ID as it is one of the pieces of information Buzzy requires for deployment. Once done scroll down to the **Capabilities** section. You must click to enable the following capabilities: * Associated Domains * Game Center * iCloud (with the default setting) * Push notifications * Siri Once done, click on **Continue** then confirm the correct details have been entered before clicking **Register.** Done, you now have the **Bundle ID**, and the **Apple Team ID**. ### Create App Listing As the bundle ID is now created, you can now create an app listing. Simply go to: {% embed url="" %} Click on the **+** next to apps to create a new app. Fill in the form, under the **Bundle ID** dropdown you should see the bundle ID you created in the previous step.\ ![](/files/Fkz4NdWUdBnIzMNJ0a1y) Once created, it will take you to your apps listing page. Here is where you will need to add any marketing information for the app. This will show on your app's app store page that users will interact with when downloading/finding your app. If you are not ready to publish your app, and are looking to only test for the time being, this information isn't critical. However, it is required in order to have your application reviewed by Apple prior to release to the app store.
Now go to **App Information** under the **General** section.
Scroll down to the **General Information** section, and copy the **Apple ID** number. This is your app's unique identifier generated by Apple. Enter this as the **App Store ID** in the Buzzy app deployment manager. At this point you should have the following information entered in the (iOS Section) Buzzy deployment manager: * Bundle ID * App Store ID * Apple Team ID ### Creating a Certificate for App Store Connect API Access In order for Buzzy to automatically build and deploy your application to your App Store account, we require a way to authenticate with Apple. This is done using a certificate for API access. The following section will walk through generating that certificate on the App Store Connect website and how to provide that to Buzzy. To get started simply head to: {% embed url="" %} If this is your first time using the App Store Connect API, you might need to request API access, simply follow the prompts and forms for that process. Note that only the account holder can request access.
When finished you should see this (minus any registered/active keys):
First thing to take note of before creating a team key is to copy the **Issuer ID** and provide it to the Buzzy deployment manager under **Connect Issuer ID**. This is another piece of information we need. Now click on the **+** next to the **Active** section. Simply fill the form, give it a name (e.g. "Buzzy API Access"), and you must select **App Manager** as the role. This ensures that Buzzy has the ability to upload build to your App Store Connect account.
Your new key will now show up on the list. See the example below:
First copy the **Key ID** in this example it is "Q955LK62PJ" and enter this in the Buzzy deployment manager under **Connect Key Identifier**. Next, you will see the download link on the far right of the entry, please note that once downloaded, Apple will not let you download a key again. So ensure you save this key to a save location. Click on **Download**. The downloaded file has a .p8 file extension, you will need to upload this file to the Buzzy deployment manager under the **App Store Connect API Private Key (pem)** section of the form. At this point you have provided almost all the information required to deploy your app to apple, in this section we collected the following items for deployment: * Connect Issuer ID * Connect key identifier * App store connect API private key (pem) ### Generating the Signing Certificate For the **Certificate Private Key** section of the Buzzy deployment manager, all you need to do is simply click on the **Generate** button and the Buzzy server will generate a signing certificate for you. Ensure the output looks similar to this:
### Setting Up Firebase (iOS) Please refer to the [#setting-up-firebase](#setting-up-firebase "mention") section. Please ensure you complete this before continuing and it is a pre-requisite of the app build process. ### Save Deployment Configuration Please do not forget to click **Save** in the Buzzy deployment manager then ensure that you publish your configuration to our build server, see [#publishing-your-deployment-variables](#publishing-your-deployment-variables "mention"). ### Publishing Your First iOS App At this point, the iOS deployment configuration is ready for deployment to the App store. After saving and publishing your deployment configuration you will simply be able to click on the **Deploy to App Store** button. iOS build can take up for 30 minutes so you may periodically refresh the build status to see what's happening.
Once the build process is done, it may take up to an hour for Apple to process the initial build, please ensure that you check your email for any correspondence from Apple. After the build is uploaded to Apple it should show up in the **Builds** section of your app listing. You should see a button to **Add Build** to your app store submission:
### Apple's Testflight If you are not ready to submit your app for review and would like to test, utilise Apple's **Testflight**. In the **Testflight** section you can add a build to be tested by individuals or groups of testers.
You can then download the Testflight app on your iPhone device and utilise it to test your published app before submitting the app for review by Apple. ## Android App Deployment ### Requirements Similar to iOS, user's are required to set up a developer account in the Google Play developer console. ### Initial Android Deployment Settings The first set of settings can be set without leaving Buzzy. Namely, the package ID and keystore.
Please pick a unique package ID/Name. This is usually your domain name backwards plus the name of the app at the end. For example, the app MovieTest hosted under buzzy.buzz becomes **buzz.buzzy.movietest**. #### **Generating an Android Signing Keystore** This keystore is a file that is generated on the Buzzy server. However, the user must provide the **key alias**, **password** and **keystore password**. Save these parameters in a secure location (password manager) as you may want to use the same keystore to sign other apps. Once filled-in, simply click **Generate Keystore**. ### Setting up Google Play API Access User's must first enable the Google Play Android Developer API. This can be done in the Google Cloud Admin Console. {% embed url="" %} > Note: You want click "Enable API" On the same page, in the left sidebar navigation, go to "Credentials" then in the "Service Accounts" section, click on "Manage service accounts".
When on the manage service accounts page, then click on "Create service account". Give it a name, label, and description. Then you must select "Service account user" for the role.
For the final step leave it blank. Then continue. Once the service account is successfully created the user must download the certificate/key and provide it to Buzzy. Do this by clicking on the actions menu, then "Manage keys".
On the "Manage keys" page then click **Add key -> Create new key**. Make sure the key type is JSON.
On creation, the file will be downloaded to your computer. This file is what you will provide as the file under the **Google Play Services Account (JSON)** section in the Buzzy deployment setup.
### Setting up Firebase (Android) Please refer to the [#setting-up-firebase](#setting-up-firebase "mention") section. Please ensure you complete this before continuing and it is a pre-requisite of the app build process. ### Save Deployment Configuration Please do not forget to click **Save** in the Buzzy deployment manager then ensure that you publish your configuration to our build server, see [#publishing-your-deployment-variables](#publishing-your-deployment-variables "mention"). ### Publishing Your First Android App It is important to reiterate that the initial build of an Android app must be uploaded **manually**. Buzzy gives you this option by allowing you to download the app bundle after the build has completed. You can initiate this initial build by clicking **Create Initial Android Build** in the mobile app deployment controls.
After the initial build has started, you need to refresh in order for Buzzy to fetch the download link for you. Initial builds take around 10-25 minutes so get a coffee and come back. Once the build is ready after clicking refresh you will be able to click on the **Download App Bundle** button and it will download the initial app bundle to your computer. {% embed url="" %} Head back to the Google play console to now create your app listing and upload your initial app. Create your app entry if it doesn't exist yet.
After creating the app listing, then go to the **Test and release** section and under **Internal release** then create a new release.
Follow the process guided by the UI then you may upload your android app bundle file (.aab). **Note:** Google will require a plethora of app and account setup prior to final release of your application, these processes are guided and done through the Google play console interface. As these processes change frequently, we don't have step-by-step documentation for such processes. ### Set Android Fingerprint Post-publish After the initial app publish, in order for app deep linking support, we require the **Android SHA256 Fingerprint.** This is the final setting in the Android deployment configuration and it is used to identify your app so that URLs on Android phones will link into your application. This is a requirement for password-less login flows to work. **Note you must have created your initial release with the initial AAB app file before continuing.** #### Getting the SHA256 Fingerprint In the **Test and release** section of the Google Play console, go to **App integrity**.
Then scroll down to **Play app signing**, click on **Settings**. Under SHA256 Fingerprint section, use the button to copy the value.
Paste this value into the Android deployment configuration in Buzzy.
When done, don't forget to **Save** and **Deploy** the deployment variables. ## Publishing Your Deployment Variables It is **imperative** that users remember to **Publish** their deployment variables. When editing your deployment variables, don't forget to click **Save.** Then, ensure that you click on **Publish Deployment Variables** or **Update Deployment Variables** (if changing) before you initiate an app deployment.
## Setting Up Firebase Buzzy uses Firebase for some application features. As such, every user must setup their own Firebase project in order to build their application. {% embed url="" %} Start by going to the firebase console and clicking **Create a new Firebase project**. Go through the process to create your project. **Note**, Google Analytics is not necessary, you can disable this feature in the creation process to make the process easier. Once the project is created it will take you to the project home page, where you can **Add an app**.
Select the appropriate platform, **Android or iOS**.
Fill in the details that you have already done in Buzzy. Then download the config file. **Note:** When downloading the config for **Android** it will be a **JSON** file. For iOS, it is a **Plist** file. Upload the respective file to the deployment manager in Buzzy, under **Firebase google\_services.json** or **Firebase GoogleService-Info.plist**.
### iOS Authentication Keys for Firebase (Notifications) For iOS deployments, Firebase requires 2 key files to ensure push notifications can propagate to user devices. One key file is for development app builds, the other is for production builds. This setup is **required** to ensure authentication with Apple for the push notification service. 1. Go to your Firebase project in the Firebase console: 2. Under **Project Settings** -> **Cloud Messaging** -> **Apple app configuration** 3. Under **APNs Authentication Key** section, you require 2 keys from Apple, these can be generated from the Apple app store connect interface. Instructions on how to generate these keys is given below. 4. Note, these docs assume the process of using the **APNs Authentication Key** method **NOT** the "**APNs Certificates**" method 5. [#getting-your-apns-key-files](#getting-your-apns-key-files "mention") #### Getting your APNs key files 1. We can generate the associated APNs keys at 2. Click on the **+** icon to create a key. 3. Give the key a name and append "Dev" to its name, this will be your development APNs key. 4. Ensure you check **Apple Push Notifications service (APNs)** option 5. Then click on "**Configure**" for the Apple Push Notifications service (APNs) option 6. Ensure you select "Sandbox"
7. Ensure Team Scoped (All Topics) is selected. 8. Save and ensure the correct settings for this key:
9. Click **Continue** then click **Register** 10. Note the key ID and ensure you download the key before continuing
11. Go back to the Firebase console and upload this key for the **Development APNs auth key** entry. Ensure the correct key ID is entered. 12. Repeat these steps to create another APNs key but select **Production** in the configuration for the Apple Push Notifications service (APNs) option. Also ensure you give this key a different, unique name, append "Production" to the key name for simplicity.
13. Upload your production APNs key to the Firebase console under the **Production APNs auth key** entry. 14. Save all changes. 15. Your Firebase console should now be correctly set up to ensure functional push notifications from Buzzy apps are present on user devices. 16. Note users will be prompted to give notification permissions when launching your Buzzy powered app, if permission is refused, your app will not be able to push notifications to that user. # Buzzy Accreditation Buzzy Accreditation is for designers, builders, agencies, and implementation partners who want to demonstrate that they can create a working Buzzy app using the Buzzy Figma plugin and accepted Buzzy/Figma practices. ## Accreditation Task Start with the [Getting Started with Figma](/getting-started-with-buzzy/getting-started-with-figma) guide. The focus is using the Buzzy Figma plugin to create a working Buzzy app from a Figma file. Watch the relevant Figma plugin videos in that guide, then create your own version of a simple Buzzy application with: * multiple screens * responsive layouts * a working data model * create, read, update, and delete behavior * clean Figma structure and markup Use the Buzzy plugin in expert/manual mode. This task does not require Buzzy AI or AI tokens; the goal is to show that you understand how to manually structure, mark up, and publish a Buzzy app from Figma. Use this wireframe as the functional brief:
The visual design and UI are up to you. You do not need user login or complex functionality unless the brief explicitly asks for it. ## Deliverables Send the following to : 1. A link to your marked-up Figma file. 2. A link to your published web app on [app.buzzy.buzz](https://app.buzzy.buzz). 3. A short cover note with your name, contact details, and any relevant project or partner context. ## Assessment Criteria The published application should: * function correctly against the brief * render in a browser * work responsively when the viewport is resized or viewed on mobile * show working create, read, update, and delete behavior where required The Figma file should demonstrate: * clean and structured layer organization * clear screen and component structure * appropriate use of Figma auto layout * sensible frame nesting and layer naming * Buzzy markup that maps cleanly to the published app * avoidance of unnecessary Figma groups where frames/components are the better structure ## Useful Resources * [Getting Started with Figma](/getting-started-with-buzzy/getting-started-with-figma) * [Buzzy for Figma](/working-with-buzzy/buzzy-for-figma) * [Buzzy Figma community files](https://www.figma.com/@buzzy) * [The Building Blocks](/the-building-blocks/the-building-blocks) # Buzzy Project Guide Plan, build, test, release, and maintain Buzzy apps. Use this guide when you are planning a Buzzy project beyond a quick experiment. It brings together the same lifecycle covered across Getting Started, Building Blocks, Builder MCP, Figma, Tests, Security Review, and Deployment. ## Choose the Right Starting Point | Starting point | Use when | Primary guide | | ----------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | Prompt / Buzzy AI | You want a fast first version from an idea. | [Buzzy AI](/working-with-buzzy/buzzy-ai) | | Figma | Design fidelity or an existing design file is the starting point. | [Buzzy for Figma](/working-with-buzzy/buzzy-for-figma) | | Builder MCP | An AI coding agent should build, adapt, inspect, or change the app in stages. | [Buzzy Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp) | | No-code Workspace | You want to edit data, screens, people, settings, functions, tests, or security directly. | [The Building Blocks](/the-building-blocks/the-building-blocks) | ## Project Lifecycle ### 1. Define the Product Clarify: * users, roles, and organizations * core jobs to be done * critical workflows and edge cases * data the app must store * security and privacy requirements * external systems, AI services, or APIs * release target: prototype, internal app, customer-facing web app, or native mobile app Use [App Brief](/the-building-blocks/app-brief), [Flows](/the-building-blocks/flows), and [What to Use When](/getting-started-with-buzzy/what-to-use-when). ### 2. Shape the App Definition Every serious Buzzy app needs a coherent app definition: * **Brief** for product intent * **Flows** for journeys and process states * **Data model** for datatables, fields, relationships, and access * **Theme** for visual direction * **Blueprint** for high-level screens and navigation * **Screens** for concrete forms, views, fields, filters, actions, and widgets Use [The Building Blocks](/the-building-blocks/the-building-blocks) as the conceptual map. ### 3. Build and Iterate Keep the iteration loop short: 1. Make a bounded change. 2. Preview the app. 3. Check the affected data, screens, bindings, and actions. 4. Use the Debug panel when something does not behave correctly. 5. Add or update Tests for important paths. 6. Run Security Review when permissions, Private Data, APIs, MCP, or external integrations are involved. For agent-assisted changes, use [Builder MCP Change and Extension Workflow](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/builder-mcp-change-workflows). For Figma-led work, use [Buzzy for Figma](/working-with-buzzy/buzzy-for-figma). ### 4. Extend Only Where Needed Standard Buzzy screens, datatables, forms, fields, and actions should handle most app behavior. Extend when the app needs more: * [Code widgets](/the-building-blocks/code-widget-custom-code) for custom UI * [Buzzy Functions & Constants](/the-building-blocks/buzzy-functions-and-constants) for server-side logic, secrets, webhooks, AI calls, and external APIs * [REST API Reference](/developing-and-extending-buzzy/buzzy-rest-api/rest-api) for external systems * [Buzzy Custom MCP](/the-building-blocks/mcp/buzzy-custom-mcp) to expose app-specific tools to MCP clients * [API and Extension Surfaces](/developing-and-extending-buzzy/api-and-extension-surfaces) when you need to choose between extension paths ### 5. Test and Review Before release, create repeatable checks for the workflows users rely on: * sign in and onboarding * main create/read/update/delete paths * search, filter, approval, booking, payment, or support workflows * role-specific views and admin paths * functions, widgets, APIs, and MCP-backed behavior * permission-sensitive and Private Data paths Use [Tests](/the-building-blocks/release-tests), [Testing Approaches](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/testing-approaches), [Security Review](/the-building-blocks/security-review), and [In-App Debugging](/troubleshooting/in-app-debugging). ### 6. Publish and Operate Publishing depends on the target: * prototype or internal testing on app.buzzy.buzz * production web app on a Buzzy deployment * native iOS or Android app through app stores * enterprise or single-tenant deployment Use [Buzzy Deployment & App Stores](/working-with-buzzy/buzzy-deployment-and-app-stores), [Publish your app to your Deployment](/working-with-buzzy/buzzy-deployment-and-app-stores/publish-to-deployment), [Software Config Management](/working-with-buzzy/buzzy-deployment-and-app-stores/software-config-management), and [Release Management](/advanced-deployment-settings/installation/release-management). ## Practical Project Checklist * [ ] The brief states the app purpose, users, roles, and core capabilities. * [ ] Flows cover the main user journeys and decision branches. * [ ] Datatables, fields, and relationships match the workflows. * [ ] Organizations, Teams, Viewers, Team Viewers, field access, and Private Data are configured where needed. * [ ] Blueprint covers public, signed-in, admin, confirmation, and role-specific screens. * [ ] Screens are bound to real datatables and fields. * [ ] Theme is coherent across desktop and mobile. * [ ] Functions, constants, widgets, APIs, and MCP are used only where they add real value. * [ ] Tests cover the workflows that must not break. * [ ] Security Review findings have been read and addressed. * [ ] Deployment, publishing, and support responsibilities are clear. ## Related Sections * [Working with Buzzy](/working-with-buzzy/working-with-buzzy) * [The Building Blocks](/the-building-blocks/the-building-blocks) * [Building with AI Project Workflow](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow) * [Buzzy Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp) * [Buzzy for Figma](/working-with-buzzy/buzzy-for-figma) * [FAQs](/working-with-buzzy/faqs) # Buzzy App Examples AI-created Buzzy app templates and example patterns for starting from a working app definition. Use this section for app-level examples and templates. The current focus is AI-created Buzzy templates that can be duplicated, inspected, and adapted with Builder MCP. For lower-level custom UI examples, keep using the [Buzzy code widget examples](/the-building-blocks/code-widget-custom-code/examples), including ratings and aggregation, image galleries, maps, charts, file management, and search/filter widgets. For examples organized by Buzzy feature area, see [Buzzy Examples by Use Case](/the-building-blocks/examples). ## AI-Created Templates ### ShortStay ShortStay is the premium AI-created template for now. Use it when your target app has a marketplace-style workflow: browse listings or providers, view details, check availability, make a booking or request, message or coordinate, and manage admin review. ShortStay is valuable because it is not just a screen design. It is a working Buzzy app definition with real structure: roles, datatables, relationships, screens, booking patterns, admin surfaces, and sample data. Good variant targets include: * carers or disability-support providers * tutors or coaches * cleaners, trades, or home services * venue, equipment, or room booking * appointment-based local services * provider directories with enquiry flows The key pattern is adaptation, not copy/paste. With Builder MCP, an agent can inspect the ShortStay app definition, map source concepts to the new domain, rewrite the brief, adapt flows and data, update screens, and verify the result. | ShortStay pattern | Variant example | | ----------------- | --------------------------------------------------------------------------- | | Property listing | Carer, tutor, provider, venue, or service profile | | Host | Provider, carer, tutor, tradesperson, or venue owner | | Guest | Client, customer, student, family member, or requester | | Nightly booking | Hourly booking, session booking, visit request, appointment, or hire period | | Property search | Provider, service, location, availability, or capability search | | Admin review | Operations, safety, compliance, support, or quality review | Start here: * [How we turned a short-stay rental app into a care booking app](https://www.buzzy.buzz/post/short-stay-to-care-connect-buzzy-builder-mcp/) * [Tutorial: Build a carer app from a template](/the-building-blocks/mcp/buzzy-builder-mcp/tutorial-carer-app-from-a-template) * [Short Stay to Care Connect example](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/short-stay-template-adaptation) * [Buzzy Builder MCP: From a template](/the-building-blocks/mcp/buzzy-builder-mcp/from-a-template) {% hint style="success" %} More AI-created templates will be added here as they are ready. For now, treat ShortStay as the main premium template and the best example of adapting a maintained Buzzy app definition into a new product. {% endhint %} ## Template Adaptation Workflow 1. Choose the closest working template. 2. Give Builder MCP the source template editor URL or app ID. 3. Describe the new app and what must change. 4. Tell the agent not to edit the original template. 5. Review the adapted brief before continuing. 6. Review flows, data model, theme, and blueprint. 7. Generate sample data and screens. 8. Test important paths with Release Tests. 9. Run Security Review if the variant handles private, sensitive, regulated, or role-restricted data. ## Code Widget Linkage Some app variants need custom UI that standard Buzzy components do not cover. Use code widgets for maps, rich search, galleries, charts, booking panels, file managers, and advanced dashboards. * [Code Widget Examples](/the-building-blocks/code-widget-custom-code/examples) * [Builder MCP Change and Extension Workflow](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/builder-mcp-change-workflows) * [Async API + React HTML Components](/the-building-blocks/code-widget-custom-code/new-async-api-+-react-html-components) ## Figma Templates and Design References Figma templates are still useful as design references, especially for teams working primarily in Figma. They are not the main app-template path on this page. Find official Buzzy Figma templates at [figma.com/@buzzy](https://www.figma.com/@buzzy). ### Project Management App with Many-to-Many Relationships This Figma template demonstrates a project management application with task management, team collaboration, project tracking, and many-to-many relationship concepts. [View Project Management Template](https://www.figma.com/community/file/1280412712042107305/project-management-app-with-many-to-many-relationships) {% hint style="info" %} Use Figma templates as design or layout references. For production-minded app creation and variants, prefer working Buzzy templates plus Builder MCP adaptation. {% endhint %} # Buzzy Templates AI-created Buzzy templates you can duplicate, inspect, and adapt into new applications. Buzzy templates are working app definitions. They can include a brief, flows, data model, theme, blueprint, screens, sample data, functions, code widgets, and settings. The best template workflow is not to copy the visible UI and rename things by hand. Use [Buzzy Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp) to inspect the source app, create a new app, and adapt the template's structure into the new domain. ## Premium Template: ShortStay ShortStay is the premium template for now. It is a strong source app for marketplace, booking, provider-directory, and appointment-style products. ShortStay gives you a working pattern for: * public discovery and search * listing/profile detail pages * availability and booking/request flows * client and provider roles * admin review and support surfaces * realistic sample data * app structure that Builder MCP can inspect and adapt Use it as the starting point when your app is structurally similar, even if the domain is different. ## Creating Variants with Builder MCP ShortStay can become many different apps because the app definition is semantic. A property listing can become a carer profile, a host can become a provider, and a nightly booking can become an hourly care visit or service appointment. Example variant: * Source: ShortStay rental marketplace * Target: CareConnect care booking marketplace * Key changes: carer profiles, client care data, hourly bookings, stronger privacy posture, service-area display, and role-specific workflows Read the public case study and tutorial: * [How we turned a short-stay rental app into a care booking app](https://www.buzzy.buzz/post/short-stay-to-care-connect-buzzy-builder-mcp/) * [Tutorial: Build a carer app from a template](/the-building-blocks/mcp/buzzy-builder-mcp/tutorial-carer-app-from-a-template) * [Short Stay to Care Connect example](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/short-stay-template-adaptation) ## Adaptation Checklist When creating a new variant: 1. Start with the closest working template. 2. Use Builder MCP to inspect the template before changing anything. 3. Map old concepts to new concepts. 4. Rewrite the brief first. 5. Adapt flows, data model, theme, blueprint, and screens in order. 6. Replace source-domain wording, images, sample data, code widget assumptions, and function assumptions. 7. Generate new sample data. 8. Run Release Tests for search, detail, request/booking, admin, and permission paths. 9. Run Security Review when the new domain involves private or sensitive data. ## Code Widgets in Templates Some templates use code widgets for richer interactions such as maps, galleries, summaries, filters, booking panels, and custom dashboards. When adapting a template, review widget code for source-domain wording, field IDs, action payloads, and stale assumptions. * [Code Widget Examples](/the-building-blocks/code-widget-custom-code/examples) * [Async API + React HTML Components](/the-building-blocks/code-widget-custom-code/new-async-api-+-react-html-components) * [Builder MCP Change and Extension Workflow](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/building-examples/builder-mcp-change-workflows) {% hint style="info" %} More AI-created templates will be added here soon. For now, use ShortStay as the main premium template and best template-adaptation reference. {% endhint %} # FAQs ## What is Buzzy? Buzzy is a low-code/no-code app platform for creating web and mobile applications from a structured app definition. You can start with a prompt, a Figma design, Builder MCP, or direct no-code Workspace editing. A Buzzy app definition can include brief, flows, data model, blueprint, theme, screens, functions, widgets, people, settings, tests, security configuration, APIs, and MCP exposure. ## How is Buzzy different from AI tools that generate code? Many AI app tools generate a new codebase for each app. That can be fast at first, but it leaves you responsible for understanding, hosting, upgrading, securing, and maintaining the generated code. Buzzy uses AI to help create or edit a structured app definition. The Buzzy runtime renders that definition into working web and mobile apps. This is the difference highlighted across the Buzzy blog: the long-term value is not just generating something quickly; it is keeping the app editable, testable, governable, and maintainable after launch. Related reading: * [Using AI to Generate Code Is NOT the Same as No-Code](https://www.buzzy.buzz/post/using-ai-to-generate-code-is-not-the-same-as-no-code-here-s-why-that-matters) * [AI can write the app. Now you own it.](https://www.buzzy.buzz/post/ai-can-write-the-app-now-you-own-it) * [Why Your Next AI App Should Be "Semantic," Not Just Generated](https://www.buzzy.buzz/post/why-your-next-ai-app-should-be-semantic-not-just-generated) ## What are the main ways to create an app with Buzzy? There are four common starting points: | Starting point | Use when | | --------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | [Buzzy AI](/working-with-buzzy/buzzy-ai) | You want a first version from a prompt. | | [Buzzy for Figma](/working-with-buzzy/buzzy-for-figma) | You have a design file or design-led workflow. | | [Buzzy Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp) | You want an AI coding agent to build, adapt, inspect, or change the app in stages. | | No-code Workspace editing | You want to edit the app directly in Buzzy. | All four paths work with the same app model. You can start with one and continue with another. ## Can I start with Buzzy AI and keep editing later? Yes. A prompt-generated app is a starting point. After generation, continue in the Workspace: * refine the brief and flows * adjust datatables, fields, relationships, and permissions * update blueprint and screens * edit the theme * add functions, constants, widgets, APIs, or MCP * configure People, Teams, Organizations, and Settings * add Tests and run Security Review See [Buzzy AI](/working-with-buzzy/buzzy-ai) and [The Building Blocks](/the-building-blocks/the-building-blocks). ## Can I start with Figma? Yes. Use [Buzzy for Figma](/working-with-buzzy/buzzy-for-figma) when the design file is the starting point. The Buzzy Figma plugin can turn marked-up Figma screens into a working Buzzy app with real data, forms, navigation, and responsive layouts. You can also start with Buzzy AI, then refine the app in Figma. ## What is Builder MCP? [Buzzy Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp) lets an AI coding agent such as Codex or Claude Code work with Buzzy as a structured app builder. The agent can inspect and update app artifacts such as brief, flows, data model, theme, blueprint, screens, functions, widgets, and settings. Builder MCP is useful for staged app creation, adapting templates, adding code widgets, creating Buzzy Functions, fixing screens, validating changes, and preparing reviewable pull requests. ## What is Buzzy Custom MCP? [Buzzy Custom MCP](/the-building-blocks/mcp/buzzy-custom-mcp) exposes an existing Buzzy app to MCP clients such as ChatGPT or Claude. It is app-specific: the assistant can use governed tools generated from that app's datatables, functions, widgets, and permissions. Use Builder MCP to build or edit an app. Use Custom MCP after an app exists and you want an assistant to work with that app's data and actions. ## Can I still build manually without AI? Yes. You can use the Buzzy Workspace directly to work with Data, Design, Theme, Constants, MCP, Functions, People, Settings, Publish, Tests, Security, and Versions. AI is a useful accelerator, not a requirement for every change. ## Can I use custom code? Yes, but use the smallest extension point that fits the job: * [Code widgets](/the-building-blocks/code-widget-custom-code) for custom UI inside screens. * [Buzzy Functions & Constants](/the-building-blocks/buzzy-functions-and-constants) for server-side logic, secrets, AI calls, webhooks, and external APIs. * [REST API Reference](/developing-and-extending-buzzy/buzzy-rest-api/rest-api) for external systems. * [Buzzy Custom MCP](/the-building-blocks/mcp/buzzy-custom-mcp) for assistant-facing app tools. Use [API and Extension Surfaces](/developing-and-extending-buzzy/api-and-extension-surfaces) to choose the right surface. ## Can Buzzy integrate with other systems? Yes. Buzzy supports REST API access, Buzzy Functions, constants, code widgets, datatable rules, imports from CSV or URLs, and MCP. Integrations should authenticate as the correct user or integration account and respect row access, field access, and Private Data rules. See [Buzzy REST API](/developing-and-extending-buzzy/buzzy-rest-api), [Buzzy Functions & Constants](/the-building-blocks/buzzy-functions-and-constants), and [API and Extension Surfaces](/developing-and-extending-buzzy/api-and-extension-surfaces). ## How does Buzzy handle security? Buzzy security is layered: * app privacy and authentication * app roles such as Admin, Author, and Audience * People, Teams, and Organizations * datatable row access * field view and field edit * Private Data classification, masking, reveal, encryption, and audit behavior * API and MCP governance * deployment controls for production and enterprise environments See [Security and Access Control](/the-building-blocks/datatables-fields-and-data/security-and-access-control), [Private Data](/the-building-blocks/datatables-fields-and-data/private-data), and [Security Review](/the-building-blocks/security-review). ## How should I test a Buzzy app? Use [Tests](/the-building-blocks/release-tests) for repeatable smoke and regression checks. Good candidates include login, onboarding, main CRUD paths, search and filter, approvals, bookings, payments, admin flows, permission-sensitive paths, functions, widgets, APIs, and MCP-backed behavior. Use the [In-App Debugging](/troubleshooting/in-app-debugging) when a screen binding, form, view, action, filter, or row context is not behaving correctly. ## Can Buzzy create native mobile apps? Yes. Buzzy can support web and native mobile app delivery depending on your plan and deployment setup. Native app publishing requires the appropriate Buzzy deployment and app store preparation. See [Buzzy Deployment & App Stores](/working-with-buzzy/buzzy-deployment-and-app-stores), [iOS & Android App Deployment](/working-with-buzzy/buzzy-deployment-and-app-stores/ios-and-android-app-deployment), and [Apple & Google App Stores](/working-with-buzzy/buzzy-deployment-and-app-stores/apple-and-google-app-stores). ## Does Buzzy support offline mobile use? Buzzy's mobile architecture can support offline-first use cases where app design and app data are available on-device and changes sync back when connectivity returns. Offline behavior, conflict handling, and offline maps depend on app requirements and deployment configuration. For complex offline workflows, plan and test the data model, sync behavior, conflict scenarios, file/image handling, and user permissions early. ## Do I need a deployment plan? For design, prototyping, and early testing, you may be able to work on app.buzzy.buzz. For production apps, custom domains, customer-facing deployments, native mobile apps, single-tenant infrastructure, or enterprise requirements, you need an appropriate deployment plan. See [Buzzy Deployment & App Stores](/working-with-buzzy/buzzy-deployment-and-app-stores) and [Publish your app to your Deployment](/working-with-buzzy/buzzy-deployment-and-app-stores/publish-to-deployment). ## Can I self-host Buzzy? Enterprise deployment options can support customer-controlled infrastructure such as private cloud or on-premise environments. See [Introduction to deployment](/advanced-deployment-settings/installation/deployment/introduction-to-deployment) and contact Buzzy to discuss requirements. ## Can I access the database directly? Buzzy uses MongoDB underneath Buzzy deployments. For most integrations, use Buzzy's REST API, functions, exports, or MCP surfaces rather than writing directly to the database. This helps preserve Buzzy's data integrity, permissions, and runtime behavior. ## Do I get the Buzzy runtime source code? No. The maintained Buzzy runtime is part of the platform. Your app definition, Figma design assets, functions, constants, widgets, data model, and configuration are the app-specific assets you control. This is what allows Buzzy to keep improving the runtime without forcing every customer to maintain a forked application codebase. ## How do I choose between Buzzy AI, Figma, Builder MCP, and no-code editing? Start with [What to Use When](/getting-started-with-buzzy/what-to-use-when). In short: * choose Buzzy AI for fast first drafts * choose Figma for design-led creation or visual iteration * choose Builder MCP for staged AI-agent builds and deeper changes * choose no-code Workspace editing for direct app maintenance ## How can I confirm that a subscription or charge is from Buzzy? Check the receipt or invoice before contacting Buzzy Support. A Buzzy subscription or charge should be identified as `BUZZY.BUZZ`. Services branded or billed as `buzzy.now`, `buzzy.ai`, or another similar name are not affiliated with Buzzy. Buzzy Support cannot access or cancel subscriptions purchased from those services. Contact the company named on the receipt or invoice instead. If the receipt or invoice identifies the charge as `BUZZY.BUZZ`, you can manage the subscription through the [Buzzy Workspace](https://app.buzzy.buzz/) or the [Buzzy Subscription Portal](https://billing.stripe.com/p/login/aEU29EaLI96J42AdQQ). If you still need help, contact [Buzzy Support](mailto:support@buzzy.buzz) from the email address used for the purchase and include the receipt or invoice details. Never send your full card number. ## How do I cancel a Buzzy subscription? First, confirm that the receipt or invoice identifies the subscription as `BUZZY.BUZZ`. Then cancel it from your profile in the [Buzzy Workspace](https://app.buzzy.buzz/) or through the [Buzzy Subscription Portal](https://billing.stripe.com/p/login/aEU29EaLI96J42AdQQ). For detailed steps and the refund policy, see [Cancellations](https://www.buzzy.buzz/cancellations) and [Troubleshooting Buzzy AI](/working-with-buzzy/buzzy-ai/troubleshooting-buzzy-ai#cancel-a-subscription). ## Where can I get help? Use: * [Help & Support](https://www.buzzy.buzz/support) * [Discord community](https://discord.gg/qt7svhCMbj) * [Buzzy Documentation](/) * [Buzzy Accreditation](/working-with-buzzy/buzzy-accreditation) for partner and implementation skill validation * [Buzzy blog](https://www.buzzy.buzz/blog/) for current thinking, product examples, and AI app delivery guidance # Overview Buzzy apps are made from a small set of durable artifacts: brief, flows, data model, theme, blueprint, screens, functions, widgets, tests, and security settings. Once you understand how those pieces connect, the editor, Builder MCP, Buzzy AI, code widgets, APIs, and Custom MCP all become easier to reason about. Use this section when you want the mental model for how a Buzzy app works, not just a list of features. ## Workspace Map The Buzzy Workspace left navigation is organized around the app lifecycle: understand the app, build the definition, configure extension points and access, then release and support it. | Workspace area | What it is for | Building block | | -------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | Dashboard | App-level entry point and workspace overview. | Operational home for the app. | | Brief | Product intent, audience, roles, capabilities, and external-function requirements. | [App Brief](/the-building-blocks/app-brief) | | Flows | User journeys, process branches, lifecycle states, and logic paths. | [Flows](/the-building-blocks/flows) | | Blueprint | High-level screen map, navigation model, screen families, and major app surfaces. | [Blueprint, Design & Screens](/the-building-blocks/screens-and-blueprint) | | Design | Screen-level layout and binding work: views, forms, fields, actions, widgets, and responsive UI. | [Blueprint, Design & Screens](/the-building-blocks/screens-and-blueprint) | | Data | Datatables, fields, relationships, sample data, row access, field access, and Private Data. | [Datatables, Fields & Data](/the-building-blocks/datatables-fields-and-data) | | Theme | App-wide visual identity, tokens, typography, colors, radius, shadows, and design guidance. | [Themes](/the-building-blocks/themes) | | Constants | Reusable configuration values and secrets used by functions and integrations. | [Buzzy Functions & Constants](/the-building-blocks/buzzy-functions-and-constants) | | MCP | Builder MCP for app creation/editing, and Custom MCP for exposing an existing app as governed tools. | [Model Context Protocol](/the-building-blocks/mcp) | | Functions | Server-side logic for APIs, AI calls, webhooks, sensitive processing, and custom workflows. | [Buzzy Functions & Constants](/the-building-blocks/buzzy-functions-and-constants) | | People | App users, roles, teams, organizations, and access groups. | [Security and Access Control](/the-building-blocks/datatables-fields-and-data/security-and-access-control) | | Settings | App privacy, app settings, authentication posture, screen settings, and deployment-facing configuration. | [Security and Access Control](/the-building-blocks/datatables-fields-and-data/security-and-access-control) | | Publish | Make the app available through its intended deployment or sharing path. | [Publish your app to your Deployment](/working-with-buzzy/buzzy-deployment-and-app-stores/publish-to-deployment) | | Tests | Repeatable smoke and regression checks for important workflows. | [Tests](/the-building-blocks/release-tests) | | Security | Security Review for permissions, Private Data, API/MCP exposure, and sensitive-data risk. | [Security Review](/the-building-blocks/security-review) | | Versions | Version and change history context for release and rollback decisions. | [Release Management](/advanced-deployment-settings/installation/release-management) | | Help & Support | Support resources when the app or builder workflow needs help. | [FAQs](/working-with-buzzy/faqs) | This section focuses on the conceptual building blocks behind those nav items. Some operational pages live elsewhere in the docs, especially publishing, deployment, and support. ## How a Buzzy App Hangs Together At runtime, a Buzzy app is driven by structured data and screens. The **data model** defines the datatables, fields, relationships, permissions, and Private Data rules. **Screens** render that model into a usable app: they show lists and detail pages, collect data through forms, filter records, navigate between screens, run actions, and call functions or widgets when standard components are not enough. ```mermaid flowchart TD A["App Brief
what the app is for"] --> B["Flows
journeys, states, branches"] A --> C["Data Model
datatables, fields, relationships"] B --> D["Blueprint
screen map and navigation"] C --> D A --> E["Theme
visual identity and tokens"] D --> F["Screens
forms, views, filters, actions, widgets"] C --> F E --> F F --> G["Runtime App
users create, read, update, approve, search, and report"] H["Functions, APIs, MCP"] --> C F --> H I["Tests, Debug, Security Review"] --> F I --> C ``` Think of it this way: | Layer | What it answers | Main docs | | -------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | Product intent | What are we building, for whom, and why? | [App Brief](/the-building-blocks/app-brief) | | Behavior | What paths do users take, and what states can work move through? | [Flows](/the-building-blocks/flows) | | Data | What records exist, how are they related, and who can access them? | [Datatables, Fields & Data](/the-building-blocks/datatables-fields-and-data) | | Structure | Which screens exist, and how do users move through them? | [Blueprint, Design & Screens](/the-building-blocks/screens-and-blueprint) | | Look and feel | What visual system should every screen inherit? | [Themes](/the-building-blocks/themes) | | Extensions | What needs custom UI, server-side logic, external APIs, constants, widgets, or MCP? | [Developing and Extending Buzzy](/developing-and-extending-buzzy/developing-and-extending-buzzy) | | Confidence | How do we test, debug, and review risk before release? | [Tests](/the-building-blocks/release-tests), [Security Review](/the-building-blocks/security-review), [In-App Debugging](/troubleshooting/in-app-debugging) | ## Data Model First Most Buzzy apps start with datatables. A **datatable** is a structured collection of rows, like Properties, Bookings, Guests, Care Plans, Tasks, Tickets, Invoices, or Products. Each datatable has **fields**. Fields can store values such as text, numbers, dates, locations, images, files, status selections, ratings, and relationships to other datatables. ```mermaid erDiagram PROPERTY ||--o{ BOOKING : "has" GUEST ||--o{ BOOKING : "makes" BOOKING ||--o{ PAYMENT : "records" PROPERTY { text name locationField address number nightlyRate images photos } BOOKING { dateRange stayDates selection status subTable payments } GUEST { text name emailAddress email telephoneNumber phone } PAYMENT { currency amount selection status } ``` Screens only work well when they are bound to the right datatables and fields. A list screen queries a datatable. A detail screen displays one row. A create screen inserts a row. An edit screen updates a row. A child table, such as Booking Payments, usually inherits context from its parent row. Start with [Buzzy Datamodel Overview](/the-building-blocks/datatables-fields-and-data/buzzy-datamodel-overview) when you are new to datatables. ## What Screens Do Screens are the functional surface of the app. A screen is not just a static page. It can contain: * **Views** that query rows from a datatable and render repeated cards, tables, lists, calendars, maps, or dashboards. * **Forms** that create, read, or edit rows. * **Fields** that render values from the active row or collect new values. * **Filters** that feed query settings into views. * **Actions** that navigate, submit, delete, update fields, run functions, or trigger agents. * **Widgets** for richer interaction, including native widgets, reusable widget patterns, and custom code widgets. ```mermaid flowchart LR S["Screen"] --> V["View Component
queries a datatable"] V --> R["Repeated Row Layout
card, table row, list item"] S --> F["Form Component
capture, read, edit"] F --> FD["Field Nodes
insert, read, edit, summary"] S --> X["Filter Component
sets filter context"] X --> V S --> A["Actions
navigate, submit, delete, run function"] S --> W["Widgets
native widgets or code widgets"] ``` The blueprint defines the screen set and navigation intent. The real screens then implement that intent with data bindings, layouts, actions, and widgets. See [Blueprint, Design & Screens](/the-building-blocks/screens-and-blueprint). ## Themes Themes are the app-wide design system. A theme includes visual identity, brand settings, light/dark mode, typography, colors, borders, shadows, radius, and design guidance. Screens and widgets should inherit that theme so the app feels like one product rather than a collection of unrelated pages. Use [Themes](/the-building-blocks/themes) when you need to understand how theme choices shape generated screens, custom widgets, and later refinements. ## Organizations, Teams, and Security Buzzy security is layered. The app can be public, unlisted, or private. Signed-in users can have app roles such as Admin, Author, or Audience. Datatables then add row-level rules, field-level rules, Viewers fields, Team Viewers fields, and Private Data controls. Organizations and Teams fit into that model as access groups. | Concept | How it is used | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Organization | Often represents a tenant, customer, business unit, school, clinic, agency, or partner group. Useful for multi-tenant apps. | | Team | A named group of users, often inside or alongside an organization, such as Legal Reviewers, Compliance Team, Care Coordinators, Account Managers, or Technicians. | | Viewers field | Grants row access to specific users. | | Team Viewers field | Grants row access to members of selected teams or organizations. | | Field view/edit | Controls which visible-row fields each user or group can see or change. | | Private Data | Masks, hides, encrypts, gates attachments, and audits sensitive field access. | The key rule: row access is the first server-side gate. Field access and Private Data apply after the user is allowed to see the row. UI visibility rules are useful for experience, but they are not the security boundary. For the full model, see [Security and Access Control](/the-building-blocks/datatables-fields-and-data/security-and-access-control), [Private Data](/the-building-blocks/datatables-fields-and-data/private-data), and [Security Review](/the-building-blocks/security-review). ## Toolkits, Cookbooks, and Widgets in AI Builds Builder MCP and Buzzy AI do not have to invent every app from scratch. ```mermaid flowchart TD P["User prompt or template goal"] --> C["Cookbooks
domain, workflow, data, security guidance"] P --> T["Toolkits
approved screen, section, grid, component, fragment layouts"] P --> W["Widgets
native and custom interaction patterns"] C --> B["Brief, flows, data model, blueprint, theme"] T --> S["Screens and responsive layout"] W --> S B --> S ``` * **Cookbooks** provide reusable product knowledge: app archetypes, workflows, data-model conventions, security expectations, integrations, and screen guidance. * **Toolkits** provide reusable UI structure: screen shells, sections, grids, components, fragments, navigation, forms, dashboards, lists, and responsive layout patterns. * **Widgets** provide richer interaction patterns that can be reused or embedded into screens. Standard/native widgets cover common app interactions; code widgets support custom HTML/React behavior when needed. The widget editor is available at [app.buzzy.buzz/editor/widgets](https://app.buzzy.buzz/editor/widgets). In an AI-assisted build, cookbooks guide what should be built, toolkits guide how screens should be structured, and widgets extend what a screen can do. See [Toolkits, Cookbooks & Widgets](/the-building-blocks/toolkits-and-cookbooks), [Code widget](/the-building-blocks/code-widget-custom-code), and [Buzzy Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp). ## Testing, Debugging, and Review Once an app works, capture the important workflows as repeatable tests. Tests help you think through flows and logic, then keep checking the app after changes to data, screens, functions, widgets, permissions, or integrations. Use: * [Tests](/the-building-blocks/release-tests) for repeatable smoke and regression checks. * [In-App Debugging](/troubleshooting/in-app-debugging) when a screen, binding, action, form, view, or filter does not behave as expected. * [Security Review](/the-building-blocks/security-review) before exposing sensitive data, adding external APIs, enabling Custom MCP, or publishing to a wider audience. ## Where to Go Next * New to data: start with [Buzzy Datamodel Overview](/the-building-blocks/datatables-fields-and-data/buzzy-datamodel-overview). * Building an app with AI: start with [Buzzy Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp). * Designing the app flow: read [App Brief](/the-building-blocks/app-brief), then [Flows](/the-building-blocks/flows). * Building screens: read [Blueprint, Design & Screens](/the-building-blocks/screens-and-blueprint). * Extending the app: read [API and Extension Surfaces](/developing-and-extending-buzzy/api-and-extension-surfaces). * Debugging a broken screen: read [In-App Debugging](/troubleshooting/in-app-debugging). # App Brief The app brief is the first durable definition of what the app is meant to do. It is a concise, editable source of truth that captures the app name, summary, functions, user roles, data requirements, authentication and access expectations, and any reusable guidance that should carry into later build stages. In Builder MCP and Buzzy AI workflows, the brief comes before flows, data model, theme, blueprint, sample data, and screens. Downstream stages should use the accepted brief as the product intent, not reinterpret the original prompt from scratch. ## What the Brief Controls | Brief area | Why it matters | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | Name and summary | Sets the product frame and keeps generated artifacts aligned to the same app concept. | | Functions | Describes what users should be able to do and who each capability is for. | | External functions | Captures server-side behavior, webhooks, external APIs, AI calls, and other Buzzy Function requirements before implementation begins. | | User roles | Defines the people or groups the app needs to support, such as customer, staff, reviewer, admin, or public visitor. | | Data requirements | Tells the data-model stage what records, relationships, and fields need to exist. | | Authentication requirements | Records whether the app is public, signed-in, role-based, invite-only, or requires onboarding/profile capture. | | Cookbook context | Stores reusable domain, workflow, and design guidance selected during brief construction so later stages can reuse the same assumptions. | ## Where it Fits in the Build Flow For a new app, the staged flow is: 1. Create or generate the brief. 2. Review and accept the brief. 3. Generate flows from the accepted brief. 4. Generate the data model from the accepted brief and flows. 5. Generate theme and blueprint from the accepted product direction. 6. Ensure screens, wire navigation, generate sample data, and build screens. If the brief is wrong, downstream artifacts will usually be wrong in more expensive ways. Fix the brief first when the product goal, users, data, security posture, or integration requirements change. ## Good Brief Hygiene * Keep it high-level enough to guide the whole app, but specific enough to prevent vague downstream generation. * Capture user roles and access expectations early. * Put server-side or external integration requirements in external functions rather than hiding them in screen notes. * Include important domain constraints, approval steps, lifecycle states, and edge cases. * Review generated cookbooks or reusable guidance when present, because those assumptions can shape later stages. ## Related Pages * [Buzzy Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp) * [Flows](/the-building-blocks/flows) * [Datatables, Fields & Data](/the-building-blocks/datatables-fields-and-data) * [Buzzy Functions & Constants](/the-building-blocks/buzzy-functions-and-constants) * [Toolkits, Cookbooks & Widgets](/the-building-blocks/toolkits-and-cookbooks) # Flows Flows are now a first-class part of your Buzzy app definition. A flow describes how users and systems move through your app's processes to complete goals, including key states, decision points, and transitions. Why this matters: * Flows define functionality and behavior, not just screen content. * Flows provide stronger context for Buzzy AI when generating blueprint and screens. * Flows help identify missing datamodel requirements earlier (for example status or lifecycle fields). Use Flows together with: * Brief: functional and business requirements. * Datamodel: entities, fields, and relationships. * Blueprint: overall app/sitemap structure. * Theme: visual design system context. Related guides: * [Functional Design: Flows](https://docs.buzzy.buzz/the-building-blocks/pages/nXKIBokPljM9E7i9shdv#id-1.-flows) * [Buzzy AI](/working-with-buzzy/buzzy-ai) * [Datatables, Fields & Data](/the-building-blocks/datatables-fields-and-data) # Blueprint, Design & Screens The blueprint is the high-level screen plan for a Buzzy app. Design is where those planned screens become real screen-level layouts, bindings, actions, and widgets. Screens are the runtime surfaces users interact with. Use this page to understand how screens pull data from datatables, render forms and views, pass row context, and connect the app together. ## Blueprint vs Design vs Screens | Artifact | Purpose | Why it matters | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | | Blueprint | Defines the intended screens, navigation, major screen families, and screen roles before detailed layout work starts. | It is the last cheap place to check whether the app has the right high-level surfaces. | | Design | Screen-level editing and generation surface for layouts, components, data bindings, actions, widgets, and responsive behavior. | It turns the blueprint into usable screens that pull the right data and support the right workflows. | | Screen resources | Persisted screens with real IDs, layouts, bindings, actions, and settings. | Runtime navigation, screen settings, and tests need real screen IDs. | | Screen settings | App-level wiring such as home screen, public screens, sign-in screens, and other navigation entry points. | The runtime needs to know where users start and which screens are public. | In Builder MCP workflows, the usual order is: 1. Review the accepted brief, flows, data model, and theme. 2. Generate or adapt the blueprint. 3. Ensure screens from the blueprint so the planned screen names become real screen resources. 4. Update app screen settings using the real screen IDs. 5. Build or refine detailed screen layouts. 6. Verify bindings, actions, tests, and preview behavior. ## High-Level Blueprint The blueprint should answer the structural questions before detailed screen editing begins: * What are the main public, authenticated, admin, and role-specific screens? * Which screens are list, detail, create, edit, dashboard, onboarding, confirmation, modal, or settings surfaces? * Which screens need persistent navigation such as header, footer, side panel, or left navigation? * Which screens pass row context to other screens? * Which destructive or submit workflows need confirmation screens? * Which screens should be public, and which require sign-in? ```mermaid flowchart TD H["Home / Dashboard"] --> L["Bookings List"] L --> D["Booking Detail"] D --> E["Edit Booking"] D --> C["Cancel Booking Confirmation"] H --> P["Properties"] P --> PD["Property Detail"] H --> A["Admin Settings"] ``` The blueprint does not need every text label or card layout. It needs enough structure that the app has the right screens, navigation, role coverage, and workflow endpoints. ## Screen-Level Design The Design surface is where each screen becomes concrete. Screen-level design decides: * which toolkit layout or shell a screen uses * which datatable each view, form, filter, or widget reads from * which fields appear in summary, read, edit, insert, or filter mode * how repeated rows render as cards, table rows, lists, dashboards, maps, calendars, or custom panels * which actions submit, navigate, delete, update fields, run functions, or run agents * how widgets are embedded and configured * how the screen behaves across desktop, tablet, and mobile contexts Blueprint is about screen architecture. Design is about making each screen work. ## What a Screen Contains A Buzzy screen is a tree of layout nodes, components, fields, text, media, icons, actions, visibility rules, and optional widgets. ```mermaid flowchart TD A["Screen"] --> B["Layout Structure
sections, grids, containers, shells"] A --> C["Components"] C --> C1["View
query rows"] C --> C2["Form
capture/read/edit"] C --> C3["Filter
provide filter context"] A --> D["Fields
summary/read/edit/insert/filter"] A --> E["Actions
navigate, submit, delete, update field, run function"] A --> F["Widgets
native widgets or code widgets"] A --> G["Visibility Rules
show/hide based on context"] ``` ## Views A view component reads rows from a datatable and renders them through a repeated layout. Views are used for lists, tables, cards, dashboards, search results, calendars, maps, and many reporting surfaces. A view usually needs: * a selected datatable * filters or a filter context when the results should be narrowed * sorting and paging settings where relevant * a results layout with one repeated row/card/table item * a no-results layout for empty states ```mermaid flowchart LR T["Datatable"] --> Q["View Query
filters, sort, paging"] Q --> R["Rows"] R --> L["Repeated Layout"] L --> U["Rendered list, table, cards, map, or dashboard"] ``` Use a normal view for independent row queries. For parent-scoped child rows, use the real sub-table field pattern where the data model declares a parent-child relationship. ## Forms and Fields A form component provides row context for fields. It can be used in: * **capture** mode to create a row * **read** mode to display a row * **edit** mode to update a row Field nodes render actual fields from the data model. The same field can appear differently depending on mode: | Field mode | Typical use | | ---------- | ------------------------------------------------- | | Insert | Collect a value before creating a row. | | Read | Show a value in a form/detail context. | | Edit | Let an allowed user update a value. | | Summary | Show compact display in cards, lists, or headers. | | Filter | Capture filter input for a filter component. | ## Row Context Many screens need to know which row they are working with. ```mermaid flowchart TD L["List Screen
view over Booking rows"] -->|user opens one booking| D["Booking Detail Screen
receives current booking row"] D -->|sub-table context| P["Payments
child rows where embeddingRowID = booking row ID"] D -->|edit action| E["Edit Booking Screen
same booking row context"] ``` Common context sources include: * a view repeated row * a screen opened from a selected row * a form that is editing or reading a row * a parent row for sub-table children * a filter context consumed by a view When fields or sub-tables appear outside the context they need, the Debug panel can surface errors such as missing row context, invalid table reference, invalid field reference, or sub-table context mismatch. ## Actions Actions make a screen interactive. Common actions include: * navigate to another screen * pass the current row, parent row, or no row * submit a capture form * delete a row * update a field * filter or clear a filter * run a Buzzy Function * run an agent * authenticate, register, reset password, or log out Navigation actions should target real persisted screen IDs, not guessed screen names. This is why blueprint screens are ensured before detailed navigation and tests are finalized. ## Widgets Use widgets when a screen needs richer interaction than standard forms, fields, views, and filters provide. Examples include: * map or calendar experiences * galleries and file managers * dashboard panels and charts * booking or availability panels * custom controls backed by the Async API * reusable native widget patterns Code widgets run inside a browser/webview sandbox and can use the [Async API + React HTML Components](/the-building-blocks/code-widget-custom-code/new-async-api-+-react-html-components) to read and update app data through the current user context. Keep secrets and privileged provider calls in [Buzzy Functions & Constants](/the-building-blocks/buzzy-functions-and-constants), not in widget code. ## Debugging Screens Use the [In-App Debugging](/troubleshooting/in-app-debugging) when a screen does not behave as expected. Common problems include: * a view or form has no datatable selected * a field points to a missing or wrong field ID * a field is outside the view/form/row context it needs * a sub-table is not inside its parent row context * a filter context is not consumed by the intended view * an action points to a missing screen * submit or filter actions are outside the component that owns them Fix errors first, then review warnings, then use informational debug output to understand runtime context. ## Related Pages * [Buzzy Datamodel Overview](/the-building-blocks/datatables-fields-and-data/buzzy-datamodel-overview) * [Themes](/the-building-blocks/themes) * [Toolkits, Cookbooks & Widgets](/the-building-blocks/toolkits-and-cookbooks) * [Code widget](/the-building-blocks/code-widget-custom-code) * [In-App Debugging](/troubleshooting/in-app-debugging) # Datatables, Fields & Data Datatables are the data backbone of a Buzzy app. They store records, define fields, model relationships, control row and field access, and give screens something concrete to display or edit. A new user can think of the data model this way: * **Datatables** are the main record types in the app, such as Property, Booking, Guest, Care Plan, Task, Ticket, Product, Invoice, or Review. * **Rows** are individual records in a datatable. * **Fields** define what each row stores, such as text, numbers, dates, locations, images, files, selections, links, sub-tables, viewers, or Private Data. * **Relationships** connect records through sub-tables and linked-table fields. * **Access settings** decide who can view rows, add rows, delete rows, see fields, edit fields, or reveal Private Data. * **Screens** use datatables to render views, forms, filters, details, dashboards, maps, calendars, widgets, and actions. **New to Buzzy's datamodel?** Start with our [Buzzy Datamodel Overview](/the-building-blocks/datatables-fields-and-data/buzzy-datamodel-overview) for a comprehensive guide to understanding relationships, fields, and how to work with data programmatically. Please note - Datatables were previously called "Microapps" - some code snippets may still refer to a microapp (e.g. the API end-point `microappdata`). If in doubt, email support. ### Table of contents Start with the overview pages, then use the field-type sections as references when you need a specific behavior. * [Buzzy Datamodel Overview](/the-building-blocks/datatables-fields-and-data/buzzy-datamodel-overview) - **Start here for a comprehensive guide** * [Introduction to Fields](/the-building-blocks/datatables-fields-and-data/introduction-to-fields) * [Basic Fields](/the-building-blocks/datatables-fields-and-data/basic-fields) * [Advanced Fields](/the-building-blocks/datatables-fields-and-data/advanced-fields) * [Display Fields](/the-building-blocks/datatables-fields-and-data/display-fields) * [Metadata Fields](/the-building-blocks/datatables-fields-and-data/metadata-fields) * [Filter Controls](/the-building-blocks/datatables-fields-and-data/filter-controls) * [External Fields](/the-building-blocks/datatables-fields-and-data/external-fields) * [Sort Fields](/the-building-blocks/datatables-fields-and-data/sort-fields) * [Formula language](/the-building-blocks/datatables-fields-and-data/formulas) * [Datatable to Datatable Relationship](/the-building-blocks/datatables-fields-and-data/datatable-to-datatable-relationships) * [Security and Access Control](/the-building-blocks/datatables-fields-and-data/security-and-access-control) * [Display Formula](/the-building-blocks/datatables-fields-and-data/display-formula) * [Hiding a field based on role using a display formula](/the-building-blocks/datatables-fields-and-data/hiding-a-field-based-on-role-using-a-display-formula) * [In-App Debugging](/troubleshooting/in-app-debugging) * [Examples by Use Case](/the-building-blocks/examples) *** # Buzzy Datamodel Overview A comprehensive guide to understanding Buzzy's datamodel, including datatables, fields, relationships, and how to work with data programmatically. ## What is the Buzzy Datamodel? The Buzzy datamodel is the structured data layer behind your app. It defines the datatables, fields, relationships, row access, field access, and Private Data controls that screens, functions, APIs, MCP tools, and widgets use at runtime. A **datatable** is a record type. For example: * a Short Stays app might have Property, Guest, Booking, Payment, Review, and Maintenance Request datatables * a care coordination app might have Client, Care Plan, Visit, Service, Carer, Task, and Incident datatables * a compliance workflow app might have Request, Finding, Evidence, Review, Approver, and Audit Event datatables Each datatable contains rows. Each row contains fields. Screens then use those datatables to render views, forms, details, filters, dashboards, and widgets. ```mermaid flowchart LR D["Datatable
Booking"] --> R["Rows
one booking per row"] R --> F["Fields
guest, dates, status, amount"] F --> S["Screens
list, detail, create, edit"] S --> A["Actions
submit, approve, cancel, notify"] ``` Buzzy can also model complex data relationships, including **1:M (one-to-many)** and **N:M (many-to-many)** relationships. You do not need to manually create database foreign keys; Buzzy manages relationship context through datatable configuration, sub-table fields, linked-table fields, and row metadata. ### Core Concepts **Datatable**: A structured record type made up of fields. Each row in the datatable is one record. **Fields**: The values and controls on each row. Field types include text, number, date, location, image, file, selection, toggle, rating, formula, viewers, team viewers, sub-table, linked table, and more. **Rows**: Individual records in a datatable. A Property datatable contains property rows. A Booking datatable contains booking rows. **Relationships**: Connections between datatables. Use sub-table fields for parent-owned child rows and linked-table fields for references to records in another datatable. **Screens**: Runtime surfaces that read and update datatables through views, forms, fields, filters, widgets, and actions. **Organizations and Teams**: Access groups that can be used with Viewers and Team Viewers patterns to separate tenants, departments, review groups, support queues, or other real-world groups. **Metadata**: Every row automatically includes system-generated metadata: * `_id`: Unique identifier, automatically generated for each row * `embeddingRowID`: Foreign key from a "child" row to a "parent" row in another datatable * `author`: Name of the user who created the row (automatically populated) * `userID`: User ID of the user who created the row (automatically populated) * `viewers`: Field that stores a list of users who may view secured data * `teamViewers`: Field that stores a list of user teams who may view secured data ## How Screens Use Datatables Datatables are not just storage. They are what screens bind to. | Screen pattern | Datamodel dependency | | -------------------- | ----------------------------------------------------------------------------------- | | List screen | A view component queries a datatable and renders repeated rows. | | Detail screen | The screen receives or loads one row and displays fields in read or summary mode. | | Create screen | A form captures insert-mode fields and creates a new row. | | Edit screen | A form displays edit-mode fields for an existing row. | | Dashboard | Views aggregate, filter, or summarize rows from one or more datatables. | | Child table | A sub-table field shows child rows scoped to the current parent row. | | Search/filter screen | Filter fields feed filter context into a view over a datatable. | | Widget-backed screen | A widget or code widget reads or updates app data through the current user context. | ## Understanding Relationships ### 1:M (One-to-Many) Relationships A single parent record can have multiple child records. For example, one Invoice can have many Invoice Lines. ``` Invoice (Parent Datatable) ├── _id: "inv_001" ├── Invoice Number: "INV-2024-001" ├── Customer: "Acme Corp" └── Invoice Lines (Sub-table field) ├── Line 1 │ ├── _id: "line_001" │ ├── embeddingRowID: "inv_001" ← Links to parent Invoice │ ├── Description: "Web Development" │ └── Amount: 1500 └── Line 2 ├── _id: "line_002" ├── embeddingRowID: "inv_001" ← Links to parent Invoice ├── Description: "Design Services" └── Amount: 800 ``` **How to set up**: In the Invoice datatable, add a [Sub-table field](/the-building-blocks/datatables-fields-and-data/advanced-fields/sub-tables) pointing to the Invoice Lines datatable. Buzzy automatically manages the `embeddingRowID` relationships. ### N:M (Many-to-Many) Relationships Multiple records from one datatable can relate to multiple records in another datatable. For example, Invoice Lines can reference Products, where each Product can appear in many invoice lines. ``` Invoice Lines ←→ Products (Many-to-Many via Linked Table Field) Invoice Line 1 ├── _id: "line_001" ├── embeddingRowID: "inv_001" ├── Quantity: 2 └── Product (Linked Table Field): "prod_123" ← References Product datatable Invoice Line 2 ├── _id: "line_002" ├── embeddingRowID: "inv_001" ├── Quantity: 1 └── Product (Linked Table Field): "prod_456" ← References Product datatable Product "prod_123" ├── _id: "prod_123" ├── Name: "Premium Widget" ├── Price: 99.99 └── Category: "Electronics" Product "prod_456" ├── _id: "prod_456" ├── Name: "Standard Widget" ├── Price: 49.99 └── Category: "Electronics" ``` **How to set up**: In the Invoice Lines datatable, add a [Linked Table Field](/the-building-blocks/datatables-fields-and-data/advanced-fields/linked-table-field) to the Products datatable. ### Multi-Level Relationships You can create complex hierarchies by combining 1:M and N:M relationships: ``` Organization (Level 1) ├── _id: "org_001" ├── Name: "Tech Solutions Inc" └── Invoices (Sub-table) ├── Invoice 1 │ ├── _id: "inv_001" │ ├── embeddingRowID: "org_001" │ └── Invoice Lines (Sub-table) │ ├── Line 1 → Product A (Linked Table Field) │ └── Line 2 → Product B (Linked Table Field) └── Invoice 2 ├── _id: "inv_002" ├── embeddingRowID: "org_001" └── Invoice Lines (Sub-table) └── Line 1 → Product C (Linked Table Field) ``` ## Practical Examples ### Example 1: Chat Application (Simple 1:M) Based on our [AI-Powered Chat App](https://github.com/Buzzy-Buzz/buzzy-docs-gitbook/blob/main/working-with-buzzy/buzzy-app-examples/buzzy-ai-chat-app.md) example: ``` Chat (Parent) ├── _id: "chat_001" ├── Title: "Project Discussion" └── Messages (Sub-table) ├── Message 1 │ ├── _id: "msg_001" │ ├── embeddingRowID: "chat_001" │ ├── Content: "Let's discuss the project timeline" │ └── Author: "john@example.com" └── Message 2 ├── _id: "msg_002" ├── embeddingRowID: "chat_001" ├── Content: "Sounds good, when can we start?" └── Author: "jane@example.com" ``` ### Example 2: Project Management (Complex Relationships) ``` Projects ├── _id: "proj_001" ├── Name: "Website Redesign" └── Tasks (Sub-table) ├── Task 1 │ ├── _id: "task_001" │ ├── embeddingRowID: "proj_001" │ ├── Title: "Design Homepage" │ ├── Assignee (Linked Table Field): "user_123" │ └── Status: "In Progress" └── Task 2 ├── _id: "task_002" ├── embeddingRowID: "proj_001" ├── Title: "Develop Contact Form" ├── Assignee (Linked Table Field): "user_456" └── Status: "Not Started" Users (Referenced by Tasks) ├── User 1 │ ├── _id: "user_123" │ ├── Name: "Alice Designer" │ └── Role: "Designer" └── User 2 ├── _id: "user_456" ├── Name: "Bob Developer" └── Role: "Developer" ``` ## Displaying Related Data When you display data in Buzzy, you can automatically show related information: 1. **Child data**: Include a sub-table field on a screen to show all related child records 2. **Linked data**: Add fields from linked datatables to display related information 3. **Parent data**: Reference parent, grandparent, or great-grandparent fields for breadcrumb navigation For example, when displaying an Invoice Line, you can show: * The Invoice Number (from parent Invoice) * The Organization Name (from grandparent Organization) * The Product Name and Price (from linked Product datatable) ## Working with Data Programmatically Buzzy provides comprehensive APIs for working with your datamodel programmatically. For detailed examples and implementation guides, see: * [REST API Reference](/developing-and-extending-buzzy/buzzy-rest-api/rest-api) - Full CRUD operations for external integrations * [Async API Documentation](/the-building-blocks/code-widget-custom-code/new-async-api-+-react-html-components) - Client-side data operations within Code Widgets ## Security and Access Control Buzzy's datamodel includes [security and access-control features](/the-building-blocks/datatables-fields-and-data/security-and-access-control): * **Viewers Field**: Control who can see specific records * **Team Viewers Field**: Combine team-based and user-based access * **Organizations Pattern**: Multi-tenant SaaS security model * **Personal Data Pattern**: User-specific data access * **Field view and Field edit**: Control which visible-row fields each user or group can see or change * **Private Data**: Mask, hide, encrypt, gate attachments, and audit sensitive field access Row access is the first server-side gate. Field access and Private Data apply after row access is granted. ## Performance Considerations When designing your datamodel: 1. **Limit nesting levels**: While you can create multiple levels of relationships, test for performance with your expected data volumes 2. **Use filtering**: Apply filters to sub-tables and views to limit data retrieval 3. **Consider indexing**: For large datasets, consider how your queries will perform 4. **Upgrade infrastructure**: For high-performance needs, consider upgrading your Buzzy deployment ## Best Practices 1. **Plan your relationships**: Sketch out your datamodel before implementation 2. **Use consistent naming**: Follow clear naming conventions for datatables and fields 3. **Test with real data**: Verify performance with realistic data volumes 4. **Document your model**: Keep track of relationships for team members 5. **Start simple**: Begin with basic relationships and add complexity as needed ## Related Documentation * [Introduction to Fields](/the-building-blocks/datatables-fields-and-data/introduction-to-fields) * [Sub-tables](/the-building-blocks/datatables-fields-and-data/advanced-fields/sub-tables) * [Linked Table Fields](/the-building-blocks/datatables-fields-and-data/advanced-fields/linked-table-field) * [Datatable to Datatable Relationships](/the-building-blocks/datatables-fields-and-data/datatable-to-datatable-relationships) * [Security and Access Control](/the-building-blocks/datatables-fields-and-data/security-and-access-control) * [REST API Reference](/developing-and-extending-buzzy/buzzy-rest-api/rest-api) * [Async API Documentation](/the-building-blocks/code-widget-custom-code/new-async-api-+-react-html-components) * [App Examples](/working-with-buzzy/buzzy-app-examples) *** *This documentation provides a comprehensive overview of Buzzy's datamodel capabilities. For specific implementation details, refer to the linked documentation sections above.* # Introduction to Fields The Buzzy Framework provides a standard pattern to build and deploy websites and apps. The framework acts as a structure that keeps code simple and consistent. Essential to this framework are Datatable and their field types. All fields have a Name and optional Help Text that is displayed beneath the field. Specific parameters will vary depending on the field type - for instance default values or formatting options. ## Field Naming Best Practices When naming fields in Buzzy, follow these guidelines for optimal performance and compatibility: * **Avoid reserved words**: Certain field names are reserved for system use (see below) * **Avoid dots (.) in field names**: Using dots can cause issues with JSONata formulas and data access * **Use camelCase**: This naming convention (e.g., `firstName`, `orderTotal`) makes fields easier to reference * **For JSONata formulas**: When referencing fields with special characters or spaces, use backticks (\`) to enclose the field name, not single quotes (') which are used for strings ### Reserved Field Names The following field names are reserved for system metadata and should not be used when defining your own fields: * **\_id**: The current row's unique ID * **\_currentUrl**: Gets the current URL from the browser (only works in forms in "insert/capture" mode) * **\_contextRow**: Provides access to context row fields * **userID**: The user ID of the creator * **\_currentUserID**: The user ID of the currently logged in user * **viewers**: Array of additional user IDs who can view the row * **isLocked**: Indicates if the row has been locked * **submitted**: Epoch date time value of when the server created the record * **deviceID**: The device ID for debugging purposes * **appVersion**: App version when the row was created * **hasConflict**: Array of conflicts * **clientCounter**: For debugging client-server record synchronization * **clientSubmitted**: Epoch time when client submitted the record ## Field Configuration **Field modes** include 'Read' (readonly value), 'Summary' (formatted value), 'Insert' (create), and 'Edit'. 'Value' was added as an extra option that doesn't use the any Buzzy rendering or formatting, it just pulls out the raw value. There's also differences across the different field types, for instance with a date field you can add params to format the date string when it's in Value or Read mode, but not Summary mode (since that comes already formatted). 'Filter' and 'Image' are special field types that apply only to those components. **Field permissions** control who can view and edit a field after the user is already allowed to view the row. Field edit should be the same as Field view or more restrictive. For example, if Field view is restricted to Admins, Authors, and Creators, Field edit should not be set to Anyone. **Private Data** marks fields that contain personal, sensitive, regulated, or confidential information. Basic Private Data is masked or redacted by the server. Sensitive Private Data is hidden by default, can be revealed only by permitted users, and records audit entries. See [Private Data](/the-building-blocks/datatables-fields-and-data/private-data) for configuration steps. **Field visibility** in the Buzzy Workspace summary table can be enabled or disabled. **Field validation** can be customized using JSONata. For more information see [Formula language](/the-building-blocks/datatables-fields-and-data/formulas) A Display Formula provides a mechanism to dynamically alter the visibility of a field or screen element. See [Display Formula](/the-building-blocks/datatables-fields-and-data/display-formula) for examples and debugging guidance. *** # Basic Fields The Buzzy Integrated Development Environment provides a set of foundational field types known as Basic Fields. *** ### Table of contents * [Text](/the-building-blocks/datatables-fields-and-data/basic-fields/text) * [Number](/the-building-blocks/datatables-fields-and-data/basic-fields/number) * [Date](/the-building-blocks/datatables-fields-and-data/basic-fields/date) * [Location](/the-building-blocks/datatables-fields-and-data/basic-fields/location) * [Toggle](/the-building-blocks/datatables-fields-and-data/basic-fields/toggle) * [Checkboxes](/the-building-blocks/datatables-fields-and-data/basic-fields/checkboxes) * [Checklist](/the-building-blocks/datatables-fields-and-data/basic-fields/checklist) * [Selectlist](/the-building-blocks/datatables-fields-and-data/basic-fields/selectlist) * [Rating](/the-building-blocks/datatables-fields-and-data/basic-fields/rating) * [Attachments](/the-building-blocks/datatables-fields-and-data/basic-fields/attachments) * [Images](/the-building-blocks/datatables-fields-and-data/basic-fields/images) * [Signature](/the-building-blocks/datatables-fields-and-data/basic-fields/signature) * [Audio Recording](/the-building-blocks/datatables-fields-and-data/basic-fields/audio-recording) * [Embedded Link](/the-building-blocks/datatables-fields-and-data/basic-fields/embedded-link) *** # Text Text fields allow the input of plain text - it can be multiline (it will resize itself as user types). Links within the text are automatically parsed on submit. They are clickable only in readonly mode by users without edit rights. ### Settings If Mandatory is selected, then a field value must be specified at run time to successfully submit the row. The Text field type can be set to be one of the following with validation rules: * Plain Text * URL * Email * Phone Number A default value for the text field can be specified by either a text value or a JSONata formula. A maximum character count can be set for the field. The initial screen area in lines can be set using the number of rows option. *** # Number This is a single-line numeric input. Commas are not accepted, only decimal digits. ### Settings If Mandatory is selected, then a field value must be specified at run time to successfully submit the row. A default value for the number field can be specified by either a numeric value or a JSONata formula. *** --- [Next Page](/llms-full.txt/1)