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
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:
Review the accepted brief, flows, data model, and theme.
Generate or adapt the blueprint.
Ensure screens from the blueprint so the planned screen names become real screen resources.
Update app screen settings using the real screen IDs.
Build or refine detailed screen layouts.
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?
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.
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
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:
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.
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 to read and update app data through the current user context. Keep secrets and privileged provider calls in Buzzy Functions & Constants, not in widget code.
Debugging Screens
Use the 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
Last updated