Developers · Architecture
Kinetic architecture: how it is built and where it runs
Kinetic is a set of services on Kubernetes. Core stores forms and submissions, Task runs workflows, and Integrator and the Kinetic Agent connect to your existing systems. Portals are front ends you build and host. It runs in Kinetic's cloud, on your own cluster, or air-gapped.
Platform Guide 6.1 Core, Task, Integrator and the Agent are described in Platform Architecture under Customer-Managed Installations.
Object model
What lives where
Everything you build belongs to a space, except portals, which you host yourself.
| Object | Layer | What it is | Lives in |
|---|---|---|---|
| Space | All | A tenant. Nothing in one space is visible from another. | Core |
| Kapp | Experience | The forms behind one experience, such as a service portal, with its own permissions and WebAPIs. | Core |
| Forms and submissions | Experience | Form definitions and the data submitted through them. A submission event starts a workflow. | Core |
| Portals | Experience | Front-end bundles, usually React, that you host (Amazon S3, your own servers) and that call Kinetic over REST. | Your hosting |
| Workflows and routines | Workflow | Trees run on an event. Routines are reusable workflows with declared inputs and outputs. | Task |
| Handlers | Workflow | Ruby functions that workflow nodes call. | Task (plugins) |
| Connections and Operations | Integration | Integrations with REST APIs and SQL databases (PostgreSQL, SQL Server), configured in the console. | Integrator |
| Bridges and filestores | Integration | Java adapters for live lookups and file streaming from external systems. | Kinetic Agent |
Definitions: Key Terms (opens in a new tab) and Integrations Overview (opens in a new tab).
What happens when a form is submitted
A submission is the unit of work. It does not matter who creates it: a resident on a portal, an HR system posting a new hire, or an AI client working through MCP all produce the same submission, and the workflow attached to the form runs the same defined steps.
- 01
Submit
A person submits a form. A system or agent does the same with POST /kapps/{kappSlug}/forms/{formSlug}/submissions, directly or through MCP.
- 02
Store
Core validates the values against the form definition and stores the submission under its security policies.
- 03
Trigger
The Submission Submitted event starts the workflow tree attached to the form.
- 04
Act
Nodes call handlers, routines and Operations, which read from and write to your systems of record.
- 05
Record
The workflow updates the submission and sends notifications. Each run is kept in execution history.
Related docs: Event-Driven Workflows (opens in a new tab) and Workflow Execution and Debugging (opens in a new tab).
Deployment
Where it runs
Cloud-hosted by Kinetic Data, or customer-managed on Kubernetes. Each option supports multiple spaces, custom integrations and the full API.
-
Cloud-hosted
Kinetic Data runs the platform. A Kinetic Agent in your network reaches systems behind the firewall.
-
Your Kubernetes cluster
Deploy into a cluster you already run. Bring your own ingress controller or use the provided nginx ingress.
-
Provided installer
The Kinetic installer builds a preconfigured Kubernetes cluster on servers you provide.
Customer Managed Installation Requirements (opens in a new tab)
-
Air-gapped
Either customer-managed option with no internet access. Images come from a private registry; upgrades are offline.
Container registry usage in air-gapped installs (opens in a new tab)
Customer-managed dependencies
- PostgreSQL
- Required. One database per space for workflow and integration data.
- Cassandra
- Required. Core application data.
- Elasticsearch
- Optional. Without it, logging features are off.
- Networking
- An FQDN, a wildcard TLS certificate or SANs, and a load balancer with sticky sessions.
Source: Customer Managed Installation Requirements (opens in a new tab).
Sign-in and permissions
Core authenticates users or redirects them to your identity provider. Security policies then decide what each user, team or integration account can see and do.
- Single sign-on
- SAML and OIDC, which covers Entra ID and Okta, plus LDAP. The docs have separate guides for hosted and customer-managed environments.
- CAC and PIV
- Smart-card sign-in through X.509 certificates or a reverse proxy. See Common Access Card Authentication (opens in a new tab).
- OAuth clients
- Confidential or public clients for custom front ends, with trusted resource and frame domains.
- Internal accounts
- Username and password stored in the platform. Used for admin and integration users.
- Authorization
- Security policies on spaces, Kapps, forms, submissions and workflows. See Access Rules and Permissions (opens in a new tab).
Where your own code goes
Custom code lives outside the platform services and can be reused across Kapps and spaces. All of these are available today.
| Extension point | Layer | What it is |
|---|---|---|
| Portals (opens in a new tab) | Experience | Your own front end on the Core REST API, signed in through an OAuth client. |
| Form JavaScript (opens in a new tab) | Experience | Custom JavaScript inside a form, for validation and widgets. |
| Handlers (opens in a new tab) | Workflow | Ruby with declared inputs and outputs. Test locally, then import into a space. |
| WebAPIs (opens in a new tab) | Workflow | Inbound endpoints that run a workflow and return its result. |
| Webhooks (opens in a new tab) | Workflow | Platform events posted to a workflow or an external URL. |
| Connections and Operations (opens in a new tab) | Integration | A REST or SQL system defined once, called from anywhere in the space. |
| Bridge adapters (opens in a new tab) | Integration | Java, deployed to the Kinetic Agent, for systems without a usable REST API. |
| MCP server | Build | The Core and Integrator APIs as tools for AI clients, within the signed-in user's permissions. |
Agents start and track work today through the MCP server, the Core REST API and WebAPIs. Native agent work exchange, where workflow steps are assigned to agents as they are to people, is In development . See AI agents in Kinetic workflows.
Architecture questions
Answered by Kinetic Data. Last updated .
-
Does Kinetic copy data out of my systems of record?
Kinetic stores submissions made through its forms and the workflow history for them. Other data is read and written through integrations when a form or workflow needs it, so the system of record keeps the record.
-
How are tenants isolated?
Each space is a tenant, and nothing in it is visible from another space. In customer-managed installs each space also gets its own PostgreSQL database.
-
How is access controlled inside a space?
Attribute-based security policies combine user and team attributes, resource attributes such as submission status, and environment conditions. The same policies apply to the console, portals, the REST API and the MCP server.
-
Which parts run inside my network when Kinetic is cloud-hosted?
Only the Kinetic Agent, usually installed in a DMZ. By default it does not accept remote plugin uploads, so your team reviews and installs the adapters it runs.
Review your architecture with our engineers
Bring your systems, identity provider and hosting constraints. In a free two-hour working session we map where Kinetic would run, how it connects, and what the first build looks like.