> For the complete documentation index, see [llms.txt](https://docs.buzzy.buzz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buzzy.buzz/working-with-buzzy/buzzy-project-guide.md).

# Buzzy Project Guide

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.md)                        |
| Figma             | Design fidelity or an existing design file is the starting point.                         | [Buzzy for Figma](/working-with-buzzy/buzzy-for-figma.md)          |
| 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.md) |
| 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.md) |

## 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.md), [Flows](/the-building-blocks/flows.md), and [What to Use When](/getting-started-with-buzzy/what-to-use-when.md).

### 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.md) 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.md). For Figma-led work, use [Buzzy for Figma](/working-with-buzzy/buzzy-for-figma.md).

### 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.md) for custom UI
* [Buzzy Functions & Constants](/the-building-blocks/buzzy-functions-and-constants.md) for server-side logic, secrets, webhooks, AI calls, and external APIs
* [REST API Reference](/developing-and-extending-buzzy/buzzy-rest-api/rest-api.md) for external systems
* [Buzzy Custom MCP](/the-building-blocks/mcp/buzzy-custom-mcp.md) to expose app-specific tools to MCP clients
* [API and Extension Surfaces](/developing-and-extending-buzzy/api-and-extension-surfaces.md) 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.md), [Testing Approaches](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow/testing-approaches.md), [Security Review](/the-building-blocks/security-review.md), and [In-App Debugging](/troubleshooting/in-app-debugging.md).

### 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.md), [Publish your app to your Deployment](/working-with-buzzy/buzzy-deployment-and-app-stores/publish-to-deployment.md), [Software Config Management](/working-with-buzzy/buzzy-deployment-and-app-stores/software-config-management.md), and [Release Management](/advanced-deployment-settings/installation/release-management.md).

## 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.md)
* [The Building Blocks](/the-building-blocks/the-building-blocks.md)
* [Building with AI Project Workflow](/the-ultimate-guide-for-vibe-coding-an-application-with-ai/project-workflow.md)
* [Buzzy Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp.md)
* [Buzzy for Figma](/working-with-buzzy/buzzy-for-figma.md)
* [FAQs](/working-with-buzzy/faqs.md)