Data Model Reference

Data Model Reference

All models live in pkg/model/. The MongoDB database is set by MONGODB_DB (default: ud).

Flow Execution Domain

flows — DBFlow

The template/definition of a workflow.

Field	Type	Description
_id	ObjectID	Primary key
companyId	ObjectID	Tenant isolation key (on every entity)
name	string	Display name
enabled	bool	Whether the flow can be triggered
category	string	User-defined grouping label
permanentId	string	Stable ID across versions
version	int	Incremented on each update
deleted	bool	Soft-delete flag
kvInherit	string	KV inheritance strategy from parent scope
kvConflict	string	KV conflict resolution strategy
execution	object	Execution configuration (timeout, queue settings)
groupId	ObjectID	Reference to DBFlowGroup

layers — DBFlowlet (referred to as Layer in code)

One step (module invocation) within a flow.

Field	Type	Description
_id	ObjectID	Primary key
flowId	ObjectID	Parent flow reference
name	string	Display name
ref	string	Unique reference name within the flow (used in expressions)
appId	string	Module type identifier (e.g., curl, chat, pdf-extract)
args	map	Module arguments (can contain expressions)
index	int	Execution order position
timeout	int	Per-step timeout in seconds
retry	object	Retry configuration (count, delay, backoff, jitter)
componentConfigIds	map	Override default component per kind (e.g., use specific AI provider)
linkIdsByType	map	OAuth/credential link assignments per service type
filters	array	Pre-execution conditions (AND/OR filter expressions)
needsApproval	bool	Pauses execution and waits for human approval
moduleVersion	int	Tracks which module version was used

plays — DBPlay

A single execution instance of a flow.

Field	Type	Description
_id	ObjectID	Primary key
flowId	ObjectID	Reference to the executed flow
state	string	One of: NEW, RUN, DONE, FAIL, SKIP, FILTERED, DEFERRED, WAIT, ON_HOLD
createdAt	datetime	When the play was created
startedAt	datetime	When execution began
completedAt	datetime	When execution finished (success)
failedAt	datetime	When execution failed
duration	int	Total execution time in milliseconds
args	map	Input arguments passed when triggering
globals	map	Global variables available throughout the play
isTest	bool	Whether this is a test execution
testSuiteId	ObjectID	Reference to test suite (if test)
testCaseId	ObjectID	Reference to test case (if test)
baselinePlayId	ObjectID	Reference to the baseline play for comparison
testFixtureId	ObjectID	Reference to recorded fixture for replay
idempotencyRoot	string	Key for deduplicating repeated triggers
kvSnapshot	map	Snapshot of KV store at start of play
channelId	ObjectID	Channel that triggered this play (if via channel)

Play Layers (embedded in DBPlay)

Module execution records stored within each play document.

Field	Type	Description
_id	ObjectID	Primary key
playId	ObjectID	Parent play reference
layerId	ObjectID	Reference to the flowlet definition
index	int	Execution order
state	string	DONE, FAIL, SKIP, FILTERED, etc.
args	map	Resolved arguments (after expression evaluation)
out	map	Module output data
startedAt	datetime	Step start time
completedAt	datetime	Step completion time
failedAt	datetime	Step failure time
moduleVersion	int	Module version at time of execution

User & Access Domain

companies — DBCompany

Tenant/organization record. Fields: _id, name, createdAt.

company_users — DBCompanyUser

Many-to-many user-company association. Fields: userId, companyId, default (bool — which company is the user’s default).

user_groups — DBUserGroup

Named group of users within a company. Fields: _id, companyId, name, userIds (array of user ObjectIDs).

access — DBAccess

Fine-grained permission assignment.

Field	Type	Description
entityId	ObjectID	The flow/group/channel being protected
companyId	ObjectID	Tenant context
assignedToUserId	ObjectID	User receiving the permission (or null)
assignedToGroupId	ObjectID	Group receiving the permission (or null)
type	string	Entity type (flow, group, channel)
permissions	array	List of permission names granted

Operations Domain

schedules — Schedule

Field	Description
flowId	Flow to trigger
enabled	Whether schedule is active
cronExpr	Standard cron expression (5 or 6 fields)
lastRun	Timestamp of last successful trigger

retention_policies — DBRetentionPolicy

Field	Description
type	general, flow, or group
target	flows.all, flows.filtered, or audit
flowId / groupId	Scoped to specific flow/group (if type is not general)
retentionMinutes	How long to keep data (in minutes)
keepEntries	Max records to retain
enabled	Whether policy is active

queue_jobs — QueueJob

Background job queue. Fields: type, relatedId, status, createdAt, updatedAt, extra.

Channel Domain

channels — DBChannel

Field	Description
kind	http, ws, or mcp
port	Allocated port (from CHANNEL_PORT_RANGE)
authMode	public or header_token
authToken	Token for header_token auth mode
routes	Array of DBChannelRoute
runtime	Current runtime state snapshot
enabled	Whether channel is active

channel_routes — DBChannelRoute

Field	Description
channelId	Parent channel
httpMethod	GET, POST, PUT, DELETE
path	URL path (e.g., /webhook/intake)
targetFlowIds	Flows triggered by this route
responderFlowId	Flow that produces the sync response
responseMode	sync or async
timeoutSeconds	Max wait time for sync responses

Storage & Configuration Domain

kvs — DBKV

Field	Description
companyId	Tenant key
scopeType	global, flow, or flow_group
scopeKey	ID of the scoped entity
key	KV key name
value	Encrypted stored value
isMultiline	Display hint for UI
updatedAt	Last modification time

links — DBLink

OAuth and API credentials. dataOAuth, dataBasic, dataBearer, dataServiceAccount fields are all encrypted.

component_configs — DBComponentConfig

Field	Description
kind	Component type: storage, ai, db, request, console
impl	Implementation name (e.g., s3, openai, postgresql)
name	Human-readable name
isDefault	Whether this is the default for its kind
settings	Implementation-specific config (JSON map)

system_config — DBSystemConfig

Single document per installation. Contains nested objects for: AI defaults, notification settings, retention overrides, execution configuration.

AI Domain

ai_chat — AiChat

AI conversation session wrapper. Fields: entityType, permanentEntityId, userId, status.

ai_chat_messages — AiChatMessage

Individual messages within an AI chat. Fields: chatId, userId, userFriendlyText, senderType.

ai_generation — AiGeneration

Records of AI-generated content (e.g., flow generation from a prompt). Fields: userId, userPrompt, type, aiResponse, error, status.

Testing Domain

flow_test_suites — DBFlowTestSuite

Groups test cases for a specific flow version. Fields: flowId, flowPermanentId, flowVersion, name.

flow_test_cases — DBFlowTestCase

Individual test case definition. Fields: suiteId, flowId, name, baselinePlayId, fixtureId, flowletInputsByRef, expectedOutByRef.

test_fixtures — DBTestFixture

Recorded component I/O for deterministic replay. Fields: flowId, baselinePlayId, events (array of call snapshots).

play_component_events — DBPlayComponentEvent

Individual component call log entry. Fields: playId, playLayerId, componentKind, operation, input, output, error, seq.