Architecture

Demiton is split across two processes and several infrastructure services. Understanding this split is essential for deploying, operating, and extending the platform.

Two-process model

Control plane — a FastAPI application that handles HTTP. All routers live here. It accepts workflow triggers, manages connectors and business objects, and serves the studio interface. No workflow logic runs inside the control plane.

Execution runtime — an ARQ worker that processes workflow runs from a Redis queue. The worker executes steps sequentially, updates run state, and interacts with external systems through adapters. Workers are stateless between runs and scale horizontally.

This split ensures that long-running workflow execution never blocks HTTP response cycles.

Infrastructure services

Service	Role
PostgreSQL	Workflow state, connectors, business objects, audit log
Redis	Job queue (ARQ), streaming gate, concurrency controls
Azure AI Search	Vector store for document retrieval
Azure Blob Storage	File uploads, workflow artifacts
Azure Entra ID	Authentication (OIDC), identity, group membership

Workflow execution lifecycle

Trigger (HTTP / schedule)
  ↓
Pre-flight commit — WorkflowRun + TaskRun rows written to DB
  ↓
Enqueue — job pushed to Redis
  ↓
Worker — dispatches tasks in order
  ├── AtomicOp (single task)
  ├── WorkflowRef (nested workflow)
  └── ChunkedDispatch (fan-out — one ChunkRun per generator record)
  ↓
State transitions: PENDING → RUNNING → SUCCEEDED / FAILED

The pre-flight commit is a non-negotiable invariant: if the run record doesn’t exist in the database, the workflow cannot execute. This ensures every run is observable from the moment it’s triggered.

Adapter resolution

Adapters live under app/adapters/ organized by category: erp, operational, finance, datasource, comms, identity, cognitive, intelligence, platform.

Resolution chain (in priority order):

System type — exact match on the connector’s system type
Inferred system type — resolved from connector metadata
Connection type — generic protocol fallback (SFTP, SQL, SMTP)
Deterministic failure — if all resolution fails, an error is thrown

Never instantiate adapters directly. Always use adapter_factory.get_adapter().

AI architecture

User message
  ↓
MCP service — assembles context, manages conversation history
  ↓
Context providers — fetch relevant project/worker/workflow data
  ↓
Vector search — retrieves semantically relevant documents
  ↓
LLM service — invokes the model (Azure AI Foundry or Claude Enterprise)
  ↓
Response streamed to studio

The model cannot call adapters or mutate state. If the model identifies an action that should be executed, it returns a structured suggestion; the user triggers the workflow manually.

Frontend structure

The main app (packages/ui/apps/app) is React 19 + Vite + TanStack Query + Zustand. All API calls go through packages/ui/packages/shared-services/, which wraps the generated OpenAPI client.

Route structure maps to platform layers: /studio (AI), /workflows, /connectors, /business-objects, /projects, /workers, and /hq for org settings.