> For the complete documentation index, see [llms.txt](https://flapjax.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://flapjax.gitbook.io/docs/your-data/stacks/browsing-stacks.md).

# Browsing Stacks

### The Stacks List

Your stacks appear in one of two layouts. Use the toggle in the top-right corner to switch between them.

**Table view** gives you a row per stack, with columns for the stack name, its type, its tags, the number of attributes, who last updated it, and an actions menu.

**Card view** lays stacks out as a grid of cards. Each card shows the stack's emoji, name, description, tags and attribute count.

Both views put the most recently updated stack first.

***

### Stack Types

Every stack belongs to one of three types. The sidebar groups them so you can focus on just the type you need.

* **Items** hold general-purpose records you create, edit and delete freely.
* **Events** hold records that capture something that happened at a point in time. They turn read-only once created.
* **Signals** hold records that fire automations on creation or update.

Click a type in the sidebar to filter the list. A count badge on each type shows how many stacks it holds. **All stacks** clears the filter.

***

### Choosing a Stack Type

Your choice of type decides **who may write to a stack's records and how**. You set it at creation, and it governs every client request against those records.

* **Items** let clients create, read, update and delete records freely.
* **Events** let clients **create** and read records. A written event record takes no update or delete from a client, and Flapjax rejects both requests.
* **Signals** let clients **read** records. Nothing writes a signal record over the API or by CSV import. **Automations alone** create and change them.

**Decision guide: event, item or signal?**

* A **frozen log of something that happened** at a point in time, such as a page view, an order placed or a ticket opened, belongs in an **event** stack. You append occurrences and never edit them.
* An **entity you look up, relate to and keep current**, such as a product, a customer account or a support ticket you re-status, belongs in an **item** stack. You correct and re-save it across its lifetime.
* A piece of **automation-derived state** that no client should author, such as a risk flag or an account status raised by a rule, belongs in a **signal** stack. An automation is the only writer, which is what makes it trustworthy.

All three are stacks, so their columns are ordinary [stack attributes](/docs/core-concepts/data-types.md#3-scopes--where-a-type-shows-up) and follow the same [relationship rules](/docs/core-concepts/relationships.md#2-reference-attributes). A stack record may hold `Related Person (One)`, `Related People (Many)` or `Related Stack` references. A **person** attribute may reference a stack and never another person.

***

### Worked example: an Items stack, "Products"

A catalogue entity you create once and keep editing. Prices change, stock toggles, descriptions get corrected. **Items** exist for exactly that.

Attributes, with the attribute name and its [data type](/docs/core-concepts/data-types.md#2-the-full-catalogue):

| Attribute  | Data type              |
| ---------- | ---------------------- |
| `name`     | Text (String)          |
| `sku`      | Text (String)          |
| `price`    | Decimal (Float)        |
| `currency` | Currency List          |
| `category` | Single Choice (Select) |
| `in_stock` | True/False (Boolean)   |

Sample rows:

| name                   | sku    | price | currency | category  | in\_stock |
| ---------------------- | ------ | ----- | -------- | --------- | --------- |
| Aluminium Water Bottle | WB-500 | 18.00 | USD      | Drinkware | true      |
| Canvas Tote Bag        | TB-011 | 12.50 | USD      | Bags      | true      |
| Enamel Mug             | MG-330 | 9.00  | USD      | Drinkware | false     |

A price change or a final sale means you **update** the existing record in place. No new row, no history entry. Deleting a discontinued product is an ordinary client request too.

***

### Worked example: an Events stack, "Page Views"

An event captures something that occurred and then **freezes**. Clients may create page-view records, usually one per view, and read them. They may not update or delete them afterwards. The stack type enforces that, rather than convention.

Attributes:

| Attribute    | Data type            |
| ------------ | -------------------- |
| `url`        | Text (String)        |
| `referrer`   | Text (String)        |
| `session_id` | Text (String)        |
| `viewed_at`  | Date & Time          |
| `visitor`    | Related Person (One) |

The `visitor` column shows a valid relationship. A **stack** attribute may take the type `Related Person (One)`, so an event points at the person who triggered it. A *person* attribute cannot take that type, since person attributes reference stacks alone. See [relationships §2](/docs/core-concepts/relationships.md#2-reference-attributes).

Sample rows:

| url              | referrer   | session\_id | viewed\_at           | visitor                          |
| ---------------- | ---------- | ----------- | -------------------- | -------------------------------- |
| /pricing         | google.com | s-8f21      | 2026-07-14T09:12:04Z | `{ "external_id": "acct-1007" }` |
| /docs/quickstart | /pricing   | s-8f21      | 2026-07-14T09:12:41Z | `{ "external_id": "acct-1007" }` |
| /signup          | /pricing   | s-3b90      | 2026-07-14T10:02:18Z | `{ "external_id": "acct-2210" }` |

To correct an event you record a new one. Old events never get rewritten.

***

### Worked example: a Signals stack, "Account Flags"

A signal is **automation-authored state**. No API client or CSV import writes an Account Flag, since clients get read-only access. Rows appear through a running automation and no other route. That guarantee lets downstream logic trust the flag.

Attributes:

| Attribute   | Data type              |
| ----------- | ---------------------- |
| `account`   | Related Person (One)   |
| `flag_type` | Single Choice (Select) |
| `severity`  | Single Choice (Select) |
| `reason`    | Text (String)          |
| `raised_at` | Date & Time            |

Sample rows, each written by an automation and never by a client:

| account                   | flag\_type      | severity | reason                  | raised\_at           |
| ------------------------- | --------------- | -------- | ----------------------- | -------------------- |
| `{ "internal_id": 1007 }` | Payment Failure | High     | 3 failed charges in 24h | 2026-07-14T09:30:00Z |
| `{ "internal_id": 2210 }` | Dormant         | Low      | No activity for 90 days | 2026-07-14T00:05:00Z |

**Filling it with a `CreateRecord` action.** Clients cannot write signals, so an automation fills an Account Flags stack through the CreateRecord action. Point the action's `stack_id` at the Account Flags stack, then map one operand per attribute under `data.<attributeKey>`, resolving each value from run context:

* `data.account` takes the person in context, which resolves to a `{ internal_id }` or `{ external_id }` reference.
* `data.flag_type` takes a fixed operand, such as `Payment Failure`.
* `data.severity` takes `High`.
* `data.reason` takes an enriched operand describing why the rule fired.
* `data.raised_at` takes the system value `now`.

The action creates the record and writes the created field map back into `actions.<id>` for later steps. That automation-only write path is the whole point of the signal type. See CreateRecord for the full field reference.

***

### Source Type

Every record carries a built-in **Source Type**, exactly as every person does. Show it as a column in the records grid, or filter on it as a field.

It records **how that record was created**. Flapjax stamps it once at creation and never changes it. It is a system field, so you never define it as a stack attribute, and it is always available as a filter with the same nine options people use:

* **API**, created through a REST API call.
* **Manual**, created here in the backoffice interface.
* **Import**, created by a CSV import.
* **Automation**, created by an automation, such as a `CreateRecord` action, the only write path for Signals stacks.
* **Label Rule**, created by a label rule.
* **RabbitMQ**, created from an AMQP ingest message.
* **Callback Event**, created from a channel provider's callback.
* **Auto-Created**, a stub created to satisfy a relationship reference.
* **Unsubscribe Page**, created from a consent write on the hosted unsubscribe page.

For the full data-model reference, see [Source Type in Data Types](/docs/core-concepts/data-types.md#6-special-types).

***

### Filtering by Tags

Tags organise stacks into groups that suit your team. Open the **Tags** dropdown in the sidebar and select one or more. Only stacks carrying **all** the selected tags appear, since tags combine with AND logic.

Click **Create new tag** at the bottom of the dropdown to make one without leaving the page. Give it a name and colour, then save.

***

### Managing Tags on a Stack

Click the **tag icon** in a stack's actions column in table view, or in its card menu, to open the tag manager. A searchable list of every tag appears with checkboxes. Tick and untick to assign and remove them. Your changes save as you close the modal.

***

### Searching

The search bar above the list finds stacks by name, plural name or description. Results update as you type.

***

### Stack Actions

Each stack carries an actions menu: the three-dot icon in table view, or the menu on each card. It offers:

* **View**, opening the stack's records page
* **Settings**, jumping to the stack's configuration in Settings
* **Update**, editing the stack's name, description and other details
* **Delete**, removing the stack permanently after a confirmation

***

### Creating a Stack

Click **New Stack** in the top-right corner to open the creation form in Settings. The [Stacks Schema guide](/docs/your-data/stacks/schema.md) covers configuring a new stack and its attributes.