Concepts & Glossary

The rest of the dashboards docs reuse a small set of words: a query, a widget, a pin, a scope, a snapshot, a publish mode. This page defines each one in plain terms and shows how they fit together, so the other pages read cleanly. You do not need any of this to build a dashboard (the editor does it for you), but it helps when a feature behaves in a way that only makes sense once you know the model underneath.

The three layers: query, widget, dashboard#

The single most useful idea is that there are three separate things, stacked. Most of the time the editor collapses them into one screen, but they are distinct, and a few behaviors only make sense once you can tell them apart.

Read it bottom to top: a dashboard holds widgets, and each widget reads from a query. Or read it as a sentence: a dashboard shows widgets, a widget draws a query, a query pulls your data.

Query#

A query is a reusable, named pull of data: one source (a feed, a live bank, a small static table you type in, or two feeds combined) plus an optional pipeline that filters, summarizes, sorts, and limits the rows. It produces rows; it has no opinion about charts. Because a query is a first-class object in your workspace, two widgets pointing at the same query share a single read and (usually) a single round of summarizing.

You often will not create a query directly. When you point a widget at a feed in the inspector, BankSync authors a query for you behind the scenes. The Binding data guide is, in effect, the guide to authoring a query without ever using the word.

Widget#

A widget is the renderable unit: a query, plus a chart kind, plus styling. It is what you place, resize, and look at. A widget comes in one of two shapes:

• A view widget renders data: a chart, a KPI tile, a gauge, or a table. It carries a query (or an inline one-off data definition) and the field bindings that map columns onto the chart.
• A control widget emits state or an action instead of reading data: a filter control (like a date-range picker), a button, or a text input. It has no query of its own.

A view widget can also overlay a few named datasets alongside its main one, so a single chart can show, say, actual spend from one feed and a budget line from another at the same time. That is an advanced case; most widgets read exactly one query.

Dashboard#

A dashboard is the page: a grid layout, the widgets placed on it, the dashboard-wide filters in the header, an optional theme, and a few settings like a default time zone. The grid is twelve columns wide; each widget sits in a cell you can drag and resize. Mobile layouts are stacked into a single column automatically, so you only ever arrange the desktop layout.

Pin vs. duplicate#

When you add a widget you already built to another dashboard, you are choosing between two very different actions. The words matter.

Pinning places a reference to one widget. Internally each placement is a small "join" record that says "this widget, at this size, in this cell, on this dashboard," optionally with a per-placement title or filter override. The widget itself is stored once. So if you pin your "Monthly spend" chart onto three dashboards and later change its colors, all three update, because they are the same widget. BankSync tracks how many times a widget is used (its reference count) so it can warn you before you delete one that is pinned in several places.

Duplicating makes a brand-new widget that happens to start out identical. From the moment you duplicate, the two are unrelated: editing one never touches the other. Reach for duplicate when you want a variant ("same chart, but for the other account") that you intend to diverge.

Scope: workspace vs. family#

Every query reads at one of two scopes. Most reads are workspace-scoped; family scope is a capability for people who run several client workspaces.

• Workspace (the default): the query reads data from this workspace only, and only workspace members can see it.
• Family: the query rolls up across the child workspaces under a parent. For a client portal setup, that means one chart can total figures across every client workspace at once, instead of one chart per client.

If you only have a single workspace, scope never matters and you can ignore it: everything is workspace-scoped. Family scope is the lever that makes a multi-client roll-up possible, and it is the reason a number on a parent-workspace dashboard can be larger than what any single child workspace would show.

Snapshots and freshness#

A snapshot is BankSync's internal, cached copy of the rows behind a source. You never see or manage snapshots directly; they exist so that two widgets reading the same data do not fetch it twice, and so a dashboard loads fast. The important part for you is how a snapshot stays honest:

• Every snapshot is stamped with a version. For a feed, the version tracks your last sync; for a live bank source, it is a short time window.
• A new version means the data may have changed, so the old snapshot is thrown out. A stale snapshot is never served. When your feed syncs, the next dashboard load reads the fresh copy.

This is why a dashboard does not need a refresh button: it re-reads its sources when it loads, and the snapshot version guarantees you are looking at current data, as current as your most recent sync.

The one exception to "always current" is a frozen published link, covered next.

Publish mode: frozen vs. live#

When you publish a dashboard or a widget to share it, you pick one of two modes. This is the central trade-off of sharing, and it decides whether your shared link tracks new data.

See Publishing and sharing for how to publish, regenerate a link, and embed.

Where things are created and where they live#

A quick map of provenance, because a widget on your canvas did not necessarily come from you.

• Origin records who or what made a widget or dashboard: you, a built-in template, an AI agent (if you drive BankSync through one), or custom code. It is a label, not a permission.
• A template is a prebuilt dashboard you can instantiate against your own feeds. A dashboard made from a template remembers where it came from, which is what powers the "update available" prompt when the template is improved. See Dashboard templates.
• Size presets (small, medium, large, full-width) give a widget a sensible default footprint on the grid whether you place it in the app or through an agent, so the same widget lands the same size either way.

A worked example, end to end#

Suppose you want monthly spend on two dashboards, one of which also needs a client-specific heading.

1. You point a widget at your Transactions feed and set it to sum Amount by month. Behind the scenes this is a query (the data) wrapped in a widget (drawn as a bar chart).
2. You pin that widget onto your "Cashflow" dashboard. The placement records its cell and size.
3. You pin the same widget onto your "Board pack" dashboard, and give that placement a per-pin title override ("Spend, last 12 months"). Same widget, local heading.
4. Later you recolor the chart once. Both dashboards update, because both are pins of one widget.
5. For a client you instead duplicate the widget and switch its source to that client's feed. The copy is independent and will not change when you edit the original.
6. You publish the "Board pack" dashboard in frozen mode for a month-end snapshot. The shared link stays fixed until you re-publish, even as new transactions arrive.

That sequence touches every term on this page: query, widget, pin, override, duplicate, and frozen publish mode.

Glossary at a glance#

Related guides#

• Dashboards & widgets overview: the big picture and the editor.
• Binding data: authoring a query without using the word.
• KPI, table & gauge widgets: the non-chart view widgets.
• Dashboard templates: start from a prebuilt dashboard.
• Publishing and sharing: frozen vs. live, links, and embeds.
• Filters & cross-filtering: control widgets and dashboard-wide filters.