> ## Content Index
> Fetch the complete content index at: https://blog.protokol.io/llms.txt
> Use this file to discover other available public pages before exploring further.

# Components: the building block of every Protokol project
- URL: https://blog.protokol.io/components/
- Published: 2026-11-17T17:33:15.000Z
- Updated: 2026-11-17T17:33:15.000Z
- Description: What a Protokol component is, how its fields, functions, workflows and access rules fit together, and where components are used across the platform.
- Author: Strahinja Djuric
- Tags: Engineering

If you build anything on Protokol, you build it out of components. Orders, customers, products, tickets, invoices, work orders: each one is a component. This post explains what a component is, how it works, and where it shows up across the platform.

## What a component is

A component is **a data model and the logic that belongs to it, in one place**. It is at the same time:

- **a data store**: it holds your records;
- **a schema**: it defines what a record looks like and validates every write;
- **a programmable resource**: it carries its own functions, event workflows, access rules and UI.

Instead of a database table in one place, an API layer in another, validation in a third and background jobs in a fourth, a component keeps all of it together. Everything about "orders" lives in the `orders` component.

Like everything in a project, a component exists in two environments, **Dev** and **Live**. You build and test changes in Dev before they reach your production data.

## How it works

A component is described by its **settings**. Here are the parts that matter most.

### Fields

Fields define the shape of a record. Each field has a key, a type and an input module, which the dashboard uses to render forms automatically. That could be a text input, a rich-text editor, a select, a date picker, an image carousel, an inline table of sub-records, a relation to another component, or raw JSON. Constraints such as required fields, selectable values, date ranges and relations are checked on every write.

A component can also have **multiple schemas**, for example `default`, `premium` and `draft`, each with its own fields, addressed as `shop::order.premium`.

### Types with IDL

For fields that hold structured data, and for function inputs and outputs, you can add an **IDL** (Interface Definition Language). It gives you:

- **write-time validation**: a value that doesn't match the declared shape is rejected;
- **editor type safety**: the dashboard's code editor autocompletes your fields and function inputs and flags type errors before you save;
- **typed SDK results**: `ptkl component generate-types` turns the IDL into TypeScript types for your own codebase.

### Functions

Components carry their own **functions**: JavaScript that runs in a secure sandbox with full `async`/`await` support. Use them for calculations, data transformations, calls to external APIs, or orchestrating work across several components.

```json
{
  "functions": [
    {
      "name": "calculate_total",
      "expr": "const items = $input.items || []; return { total: items.reduce((s, i) => s + i.price * i.quantity, 0) }"
    }
  ]
}

```

You call a function over the API, from the SDK, or from another function:

```js
import { Component } from "@ptkl/sdk"

const orders = new Component("orders")
const { total } = await orders.function("calculate_total", { items })

```

Functions on the same component can call each other directly by name. Who may call them is a permission: `functions` for all of a component's functions, or `function::calculate_total` for one.

### Events and workflows

Every component emits **events** when its records are created, updated or deleted. **Component workflows** react to them. You build them in the visual workflow editor: validate an order before it's saved, notify a warehouse after it's created, recalculate a total after an update. They can also respond to custom events that you trigger yourself.

### Access rules

Who can read, create, update or delete records is controlled by **roles and permissions**. For finer control, **policies** restrict individual fields. For example, only the HR role may read or update `salary`. **Protected fields** can't be changed by normal updates at all unless the request explicitly forces it, which keeps fields like a status set by your own logic safe from accidental overwrites.

A component's code runs as the component's **run identity**: the role or API user you chose for it, never with more access than that identity holds.

### Configuration and secrets

`config` holds the component's settings, such as thresholds, feature flags or endpoint URLs, and functions read it at run time. API keys and passwords go into **component secrets**: encrypted, write-only, and available only to that component's functions.

### Extensions

**Extensions** add fields, functions, workflows and UI to a component without touching its core settings. A `shipping_tracker` extension can add a tracking number field, a `shipping_tracker.get_tracking_status` function and a workflow that runs when an order changes. Extension fields and functions are namespaced, so they never collide with yours, and an extension can be switched off without losing its data. This is how marketplace apps add features to components you already have.

## Working with the data

Components give you more than create, read, update and delete:

- **Find** with filters, sorting and cursor pagination for lists and UIs.
- **Streaming** for processing every record (exports, migrations, background jobs) without loading everything into memory.
- **Aggregation pipelines** for reports, grouping and summaries.
- **Update operators** such as `$inc`, `$push`, `$pull`, `$addToSet` and `$min`/`$max` for precise, atomic changes, so two clients incrementing a counter at the same time don't overwrite each other.
- **Caching**: a read can accept a cached result up to a given age with `cacheTTL`, for data that doesn't need to be fresh to the second.

```js
const orders = new Component("orders")

// the first page of paid orders over 100
const page = await orders.find(
  { currentPage: 1, perPage: 25 },
  { $adv: { status: "paid", amount: { $gte: 100 } } }
)

// set the status and update counters in one atomic write
await orders.update(uuid, {
  status: "confirmed",
  $inc: { order_count: 1 },
  $push: { status_history: "confirmed" }
})

```

## Where components are used

Because components hold both the data and its rules, every other part of Protokol builds on them:

- **The dashboard.** Lists, create and edit forms, filters and saved presets are generated from a component's fields, so a new component is usable the moment you save it. Components can add their own screens and entry points for custom UI.
- **The API and SDK.** Every component is immediately available over the API and through `@ptkl/sdk`, with the same permissions and validation as in the dashboard.
- **Workflows.** Component workflows react to record changes. Project workflows, triggered by integrations such as a received payment, read and write component records as part of their logic.
- **Functions.** Platform functions, standalone HTTP endpoints, and other components' functions use components as their data layer.
- **Forge apps.** Apps create the components they need when they're installed, and their screens read and write component data. Through extensions, they add features to components that already exist.
- **Templates.** Project templates bundle components so that a whole setup can be installed into another project from the template catalog. Component secrets travel only as declarations: generated ones are created fresh, and values are never copied.
- **Your own codebase.** Generated TypeScript types make component data type-safe in the apps you build outside the platform.

## An example: orders

Put together, an `orders` component in an online shop might look like this:

- **fields**: customer (a relation to `customers`), line items (a table), status, total;
- **an IDL** describing a line item, so a malformed item is rejected and the editor autocompletes `items[0].price`;
- **a function** `calculate_total`, called by the storefront at checkout;
- **a workflow** on create that reserves stock and emails a confirmation;
- **a policy** that lets only the finance role change `total` by hand;
- **a protected field** `status`, which an ordinary update can't overwrite by accident;
- **a secret** for the payment provider's API key, available only to this component's functions;
- **an extension** from a shipping app that adds tracking.

All of it lives in one component. You can open it, read it and reason about it in one place.

## Learn more

The documentation covers every part in depth: [Component functions](https://docs.protokol.io/components/functions/?ref=blog.protokol.io), [IDL](https://docs.protokol.io/components/idl/?ref=blog.protokol.io), [Policies](https://docs.protokol.io/components/policies/?ref=blog.protokol.io), [Extensions](https://docs.protokol.io/components/extensions/?ref=blog.protokol.io), [Find](https://docs.protokol.io/components/find/?ref=blog.protokol.io) and [Update operators](https://docs.protokol.io/components/update-operators/?ref=blog.protokol.io).