# Items and roles

> Every line of a Layerz model has a role that says what it is, an input, a formula, a stock, a total or a dashboard widget. The roles and the hierarchy.

An item is any element of a model: a section, a line, a dashboard, a chart. Each item has a stable id (its `uid`), a unique name and a **role**. The role is what a spreadsheet never records: it says whether a number is typed, computed, carried forward or only shown.

## The roles

| Role | What it is |
|---|---|
| `assumption` | An input: a value per period, or one constant held every period. |
| `formula` | A computed line: an expression over other lines (lags, functions), or, with no expression, the sum of its children (a total). |
| `callup` | A typed mirror of one line whose value flows into its parent: a flow into a balance, a figure surfaced in another section. |
| `balance` | A stock rolled forward: closing = opening + the flows attached to it, period after period. |
| `section` | Structural grouping: a statement, a block of it, a department. Holds lines, carries no value of its own. |
| `chart` | A chart of one or more lines, on a dashboard. |
| `dashboard` | A tab of charts, KPIs and mini-tables over the model. |
| `kpi` | One figure with its comparison (a period, a scenario), on a dashboard. |
| `mini_table` | A short table of lines across periods, scenarios or list elements, on a dashboard. |

The first five roles build the model; the last four present it. Only `assumption`, `formula` and `balance` produce a value a formula can read. A `callup` is read through its source, and a `section` carries no value of its own.

## Hierarchy

- At the root of a model live only **sections** and **dashboards**. Each root section is a tab in the app and a sheet in Excel; each dashboard too.
- A section holds lines and nested sections (sub-sections). A dashboard holds charts, KPIs and mini-tables only.
- Tabs are ordered dashboards first, then sections, then lists, each group in its own order.

## Totals: the sum of the parts

A total is a `formula` with no expression and with children: its value is the sum of its children, period by period ("Total revenue" over its revenue lines). A formula is either a total or an expression, never both. A nested section, by contrast, only groups lines and shows no total.

## Callups

A callup mirrors one line where it is needed again, and its value flows into its parent: a flow attached to a balance, an operating figure surfaced in the cash-flow statement. It shows the name of its source unless it gets its own ("Grant" on the P&L for "Grant received"). Inside a formula, reference the source line directly: a callup is never arithmetic.

## Names

Every item has one name, unique in the model regardless of case. It is both the label people read and the identifier formulas use. Names with spaces go between back-ticks in a formula: `` `Annual revenue` * 12 ``.

## Style, format and notes

Presentation lives on the item but never changes its value: `item_style` (normal, subtotal, total, kpi), a number `format` (see [Number formats](/docs/reference/number-formats)), a note (`comment`), a folded state. An agent's partial update never resets what a person styled in the app.
