Components: the building block of every Protokol project
What a Protokol component is, how its fields, functions, workflows and access rules fit together, and where components are used across the platform.
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-typesturns 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.
{
"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:
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,$addToSetand$min/$maxfor 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.
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
totalby 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, IDL, Policies, Extensions, Find and Update operators.