> 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/the-building-blocks/the-building-blocks.md).

# 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.md)                                                                      |
| Flows          | User journeys, process branches, lifecycle states, and logic paths.                                      | [Flows](/the-building-blocks/flows.md)                                                                              |
| Blueprint      | High-level screen map, navigation model, screen families, and major app surfaces.                        | [Blueprint, Design & Screens](/the-building-blocks/screens-and-blueprint.md)                                        |
| Design         | Screen-level layout and binding work: views, forms, fields, actions, widgets, and responsive UI.         | [Blueprint, Design & Screens](/the-building-blocks/screens-and-blueprint.md)                                        |
| Data           | Datatables, fields, relationships, sample data, row access, field access, and Private Data.              | [Datatables, Fields & Data](/the-building-blocks/datatables-fields-and-data.md)                                     |
| Theme          | App-wide visual identity, tokens, typography, colors, radius, shadows, and design guidance.              | [Themes](/the-building-blocks/themes.md)                                                                            |
| Constants      | Reusable configuration values and secrets used by functions and integrations.                            | [Buzzy Functions & Constants](/the-building-blocks/buzzy-functions-and-constants.md)                                |
| 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.md)                                                               |
| Functions      | Server-side logic for APIs, AI calls, webhooks, sensitive processing, and custom workflows.              | [Buzzy Functions & Constants](/the-building-blocks/buzzy-functions-and-constants.md)                                |
| People         | App users, roles, teams, organizations, and access groups.                                               | [Security and Access Control](/the-building-blocks/datatables-fields-and-data/security-and-access-control.md)       |
| 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.md)       |
| 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.md) |
| Tests          | Repeatable smoke and regression checks for important workflows.                                          | [Tests](/the-building-blocks/release-tests.md)                                                                      |
| Security       | Security Review for permissions, Private Data, API/MCP exposure, and sensitive-data risk.                | [Security Review](/the-building-blocks/security-review.md)                                                          |
| Versions       | Version and change history context for release and rollback decisions.                                   | [Release Management](/advanced-deployment-settings/installation/release-management.md)                              |
| Help & Support | Support resources when the app or builder workflow needs help.                                           | [FAQs](/working-with-buzzy/faqs.md)                                                                                 |

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<br/>what the app is for"] --> B["Flows<br/>journeys, states, branches"]
    A --> C["Data Model<br/>datatables, fields, relationships"]
    B --> D["Blueprint<br/>screen map and navigation"]
    C --> D
    A --> E["Theme<br/>visual identity and tokens"]
    D --> F["Screens<br/>forms, views, filters, actions, widgets"]
    C --> F
    E --> F
    F --> G["Runtime App<br/>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.md)                                                                                                                       |
| Behavior       | What paths do users take, and what states can work move through?                    | [Flows](/the-building-blocks/flows.md)                                                                                                                               |
| Data           | What records exist, how are they related, and who can access them?                  | [Datatables, Fields & Data](/the-building-blocks/datatables-fields-and-data.md)                                                                                      |
| Structure      | Which screens exist, and how do users move through them?                            | [Blueprint, Design & Screens](/the-building-blocks/screens-and-blueprint.md)                                                                                         |
| Look and feel  | What visual system should every screen inherit?                                     | [Themes](/the-building-blocks/themes.md)                                                                                                                             |
| 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.md)                                                                  |
| Confidence     | How do we test, debug, and review risk before release?                              | [Tests](/the-building-blocks/release-tests.md), [Security Review](/the-building-blocks/security-review.md), [In-App Debugging](/troubleshooting/in-app-debugging.md) |

## 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.md) 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<br/>queries a datatable"]
    V --> R["Repeated Row Layout<br/>card, table row, list item"]
    S --> F["Form Component<br/>capture, read, edit"]
    F --> FD["Field Nodes<br/>insert, read, edit, summary"]
    S --> X["Filter Component<br/>sets filter context"]
    X --> V
    S --> A["Actions<br/>navigate, submit, delete, run function"]
    S --> W["Widgets<br/>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.md).

## 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.md) 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.md), [Private Data](/the-building-blocks/datatables-fields-and-data/private-data.md), and [Security Review](/the-building-blocks/security-review.md).

## 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<br/>domain, workflow, data, security guidance"]
    P --> T["Toolkits<br/>approved screen, section, grid, component, fragment layouts"]
    P --> W["Widgets<br/>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.md), [Code widget](/the-building-blocks/code-widget-custom-code.md), and [Buzzy Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp.md).

## 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.md) for repeatable smoke and regression checks.
* [In-App Debugging](/troubleshooting/in-app-debugging.md) when a screen, binding, action, form, view, or filter does not behave as expected.
* [Security Review](/the-building-blocks/security-review.md) 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.md).
* Building an app with AI: start with [Buzzy Builder MCP](/the-building-blocks/mcp/buzzy-builder-mcp.md).
* Designing the app flow: read [App Brief](/the-building-blocks/app-brief.md), then [Flows](/the-building-blocks/flows.md).
* Building screens: read [Blueprint, Design & Screens](/the-building-blocks/screens-and-blueprint.md).
* Extending the app: read [API and Extension Surfaces](/developing-and-extending-buzzy/api-and-extension-surfaces.md).
* Debugging a broken screen: read [In-App Debugging](/troubleshooting/in-app-debugging.md).