Architecture

A runtime that separates product code from platform concerns.

Democr.ai is organized around a core runtime, renderer clients, installable extensions, and configurable infrastructure. The same application can run local-first or coordinate work across a cluster.

Core shape

One core, multiple clients, explicit extension points.

The core coordinates application behavior. Clients render. Extensions add product, model, and ingestion capabilities through public contracts.

Renderer clients Consume A2UI payloads and apply effects without owning business logic.

Core runtime Dispatch, identity, SDK context, tasks, streams, policy, audit.

Extensions Modules, engines, extractors, agents, tools, skills, commands.

Infrastructure Databases, media, vector, graph, Redis, observability, model providers.

SDK boundary Sandbox RBAC Quotas Correlation ids

01

Runtime core

Owns routing, module loading, auth context, storage providers, task orchestration, media access, and observable execution flows.

02

SDK boundary

Exposes the public surface used by modules, engines, and extractors. Extension code should not import private core internals.

03

Renderer clients

Web, desktop, and mobile-oriented clients render A2UI payloads and apply effects. They do not own business logic.

Engine orchestration

The same runtime supports a local orchestrator or a node-aware cluster.

Single-node deployments can invoke the engine orchestrator directly. Cluster deployments can put engine jobs in a shared queue, publish node state, and stream responses through Redis-backed channels.

Single node

Runtimemodel or objective request

gRPClocal orchestrator

Engine workerwarm model handle

Cluster

Queueshared invocation row

Placementcapability, warm model, resources

Nodeclaim, run, stream response

01

Node state

Runtime nodes publish heartbeat, CPU/RAM/VRAM availability, and warm engine instances.

02

Placement scoring

Jobs prefer nodes that can satisfy the requested model or capability, with affinity for warm local instances.

03

Response streams

Cluster mode can use Redis-backed response streams so callers receive output even when work lands on another node.

Request flow

A client action stays small because the runtime carries context.

User, organization, module, thread, media, model, and stream context move through the runtime instead of being rebuilt in feature code.

Request cycle: client event, dispatcher with permission and context resolution, module action through the SDK, providers, and streamed A2UI effects

Client eventA UI action sends a payload through IPC or WebSocket.

DispatcherThe core resolves route, module, permissions, and request context.

ActionThe module runs product logic through SDK methods only.

ProviderConfigured services handle storage, media, AI, knowledge, or tasks.

StreamActions can publish incremental UI effects before the final response.

RendererClients apply A2UI updates without owning domain behavior.

Deployment axis

Local-first does not mean local-only.

The same runtime shape can start with local providers and move services outward when deployment needs shared infrastructure.

Main runtime

Routing, auth context, module actions, SDK domains, media access, and UI effects.

IPCHTTPWebSocket

Engine workers

Model loading and inference stay out of UI-critical paths and can be warmed up separately.

LLMSTTTTSVision

Knowledge workers

Extraction, ingestion, embeddings, graph enrichment, and query service work asynchronously.

QueueVectorGraph

01

Local providers

SQLite, local media, sqlite-vec, and local graph/vector providers support development and desktop use.

02

External services

Configuration can move storage, queues, graph, vector, media, and observability providers out of process.

03

Worker model

Engines and background services can run outside the UI process so model loading and ingestion do not block rendering.

Runtime ownership

Each layer owns the part it can keep coherent.

This is the main design constraint: avoid pushing platform concerns into feature modules or renderer clients.

Layer	Owns	Does not own
Modules	Product behavior, routes, actions, YAML UI, models, tools, agents, skills, locales.	Storage providers, client renderers, engine internals, global runtime policy.
Core	Dispatch, identity context, permissions, module loading, provider resolution, tasks, streams.	Feature-specific product behavior or provider-specific model logic.
Providers	Database, media, vector, graph, observability, model execution, extraction implementation.	Module UI decisions or cross-feature orchestration policy.
Clients	A2UI rendering, local interaction handling, effect application, visual feedback.	Business rules, persistence rules, permission checks, model/provider selection.

01

Modules own product behavior

A module defines routes, models, actions, YAML UI, tools, agents, skills, assets, and locales for one feature area.

02

Core owns coordination

The core resolves providers, applies context, dispatches actions, manages tasks, and exposes observability.

03

Providers own capability implementation

Engines and extractors implement specific runtime methods while keeping application code provider-independent.

Use these pages to move from the concept to adjacent parts of the runtime.