Getting started
Architecture
How a Konstrukt solution is structured — plans as building blocks, the calculation engine, change history, the interfaces and the hosting model — at a technical, implementation-neutral level.
This page describes the platform's architecture at the level needed to design solutions and integrations. It deliberately avoids implementation details that may change between releases.
Tenant and interfaces#
Each tenant is served on its own host, https://{tenant}.konstrukt.app. The following interfaces all work against the same model and data, and all enforce the same access control:
- Browserend-user & admin UI
- Tenant API
- Plansmodel + data
- IntegrationsREST, files, storage
- Tenant API
- AI agentsMCP at /api/mcp
- Tenant API
- BI toolsSQL views
- Plans
- Web interface. The end-user app interface and the admin interface.
- REST API. Imports, Kex execution and management endpoints, authenticated with OAuth client credentials. See APIs.
- MCP server. Embedded in the tenant API at
/api/mcp. Tools are filtered by the caller's privileges. See AI agents and MCP. - External SQL views. A read-only SQL surface for BI and data-warehouse tools. See APIs.
- Integration platform. Import configurations reachable through files, storage and REST. See Data integration.
Plans as building blocks#
A plan is a complete, self-contained model, but it can read data from other plans with from plan <id>. Solutions are therefore usually split into plans with distinct responsibilities:
- Master data planshared dimensions, registers, actuals
- Planning planinput, drivers, calculations
- Reporting planconsolidation, KPIs, snapshots
| Role | Typical content |
|---|---|
| Master data | Shared dimensions (accounts, organisation, calendar), registers, imported actuals |
| Planning | Input apps, driver value types, planning calculations |
| Reporting | Aggregation, consolidation, KPIs, comparisons against references |
| Process plans | Separate processes such as close checklists or invoicing, each isolated from the others |
This hub-and-spoke structure keeps each plan small and focused. Master data is maintained once. Access and life cycle (copy, archive) can be managed per plan. Calculations in a reading plan re-run when the data they read in another plan changes.
Cross-plan reads
from plan <id> reads another plan's data using that plan's dimensions. The reading plan must have the dimensions the data uses. See the agent guide for related pitfalls.
The calculation engine#
Kex scripts are compiled to set-based database queries. They are not evaluated cell by cell:
- Each value type is stored as its own table, keyed by its dimensions.
- A Kex query is translated into SQL over those tables. Joins are resolved from shared dimensions and bound properties.
- Results are streamed to their destination: a value type, an API response or an app.
- Writes are applied as set operations — insert, update, upsert or replace — scoped to the rows the writing calculation owns.
The binding constraint on performance is usually recalculation propagation, not the size of a single query. A change to one input value type triggers every calculation that reads it, then every calculation that reads their output, and so on down the dependency graph. The depth and fan-out of that graph, and the grain of the value types it passes through, determine how long a change takes to settle. Solution design should therefore:
- aggregate to the grain needed as early as possible;
- avoid calculations that read broadly but change little;
- keep high-frequency input value types from feeding large parts of the graph unnecessarily.
The dependency graph and run order are visible in the admin interface and through the MCP server.
Rule of thumb
Size is best measured in rows per value type and in the number of rows touched per change. Large value types are fine; what matters is how many rows a typical change forces the engine to recalculate.
History and versioning#
Value-type data is stored with system-versioned history: every change keeps the previous version with its validity period. This gives:
from history <datetime>in Kex — the data as it was at any moment;- point-in-time references, which are simply named timestamps;
- the audit columns on every row: last edited, edited by, and writing calculation;
- temporal queries (
for system_time as of) in the external SQL views.
History is change-based. Writing a value identical to the stored value creates no new history row. Deleting data removes it from the current state but not from history. See References and history.
Calculation scheduling#
Calculations run asynchronously after the change that triggered them. The platform queues affected calculations in dependency order. The admin interface and the MCP tools get_running_calculations and get_all_running_calculations show calculations that are running or waiting in the queue. Cycles are detected when a calculation is activated. See Calculations.
App runtime#
An app's configuration is stored as XML. Name and description are held outside the configuration. At runtime the interface does the following:
- It evaluates a dataset's value types, expressions, initial values and access filters on the server.
- It sends the resulting rows to the browser.
- Component-level filters, grouping and pivoting are applied in the browser.
Edits are written back to value types through dataset writeback rules and then trigger calculations like any other change. See Apps.
Hosting and operations#
The service is hosted in Sweden, and all platform processing takes place there. Each tenant has its own database. Backend services are shared and stateless apart from caching. Data is encrypted in transit and at rest. New versions are rolled out in release tracks (alpha, beta, feature, stable).
See Hosting and operations for sub-processors, backup, availability and releases.