Skip to content
Demiton

Core Concepts

Understanding Demiton requires familiarity with a few core concepts. These describe how the system models business data, executes workflows, and interacts with external platforms.

Workflows

Workflows are deterministic sequences of steps that execute operational tasks across connected systems.

A workflow defines:

  • the steps required to perform an operation
  • how data moves between systems
  • validation and governance rules

Each step in a workflow executes exactly one verb — FETCH, TRANSFORM, GOVERN, PUSH, EXECUTE, or LOGIC_GATE. Workflows run asynchronously through the execution runtime, with every state transition persisted to the database.

Business Objects

Business objects represent semantic business concepts: Project, LabourEntry, Vendor, PaymentFile, ProjectFinancialState.

Instead of interacting with raw API payloads, workflows operate on business objects. A business object may bind to an external system resource, allowing it to fetch data from that system without embedding system-specific logic inside the workflow itself.

Business objects can form relationships with each other, creating a semantic graph of business entities that the AI layer can reason about.

Adapters

Adapters are the integration boundary between the Demiton platform and external systems.

All communication with external systems occurs through adapters. An adapter knows how to:

  • authenticate with the target system
  • make API calls (REST, OData, SQL, SFTP, etc.)
  • normalize responses into a standard envelope

Adapters are resolved by the adapter factory using the connector’s system type. They are never instantiated directly and must fail deterministically if resolution fails.

The platform currently includes 29 adapters across ERP, operational, finance, identity, cognitive, and intelligence categories.

Connectors

A connector is a configured connection to an external system. It stores credentials, connection parameters, and the system type. The adapter factory uses the connector to resolve and instantiate the correct adapter.

You manage connectors in the platform under Connectors → Systems.

The Sovereign Envelope

Every adapter response is wrapped in a SovereignEnvelope:

{
  "records": [...],
  "metrics": { "execution_time_ms": 120, "count": 42 },
  "trace": { "protocol": "odata", "timestamp": "..." },
  "narrative": { "technical_message": "...", "clerk_remark": "..." },
  "metadata": {},
  "schema_v": "DFS-031-A"
}

This ensures consistent behavior across all workflows regardless of the originating system.

The Execution Runtime

The execution runtime is the asynchronous engine that runs workflows. When a workflow is triggered:

  1. A WorkflowRun record is created and persisted
  2. TaskRun records are created for every step (pre-flight commit)
  3. The job is enqueued in Redis
  4. The ARQ worker picks up the job and executes steps sequentially
  5. Each step transitions through PENDING → RUNNING → SUCCEEDED / FAILED

Workflows can be triggered manually, via API, or on a cron schedule.

The AI Layer

The AI layer provides reasoning and knowledge retrieval. Users can ask natural language questions about operational data; the platform performs vector search to retrieve relevant context, then passes it to the language model.

The AI layer is advisory only. It can suggest workflows, summarize data, and answer questions — but it cannot mutate external systems. Execution always requires explicit user approval.

Next steps