Skip to main content

Core Domain Model: Entities, Workspaces & Statuses

Three concepts carry the entire platform: the entity, the workspace, and the status. Get these right and everything else — execution, cost, plugins — hangs off them cleanly.

Entity and entity object​

An entity is a registered plugin type — one row in the core entity table, recording the plugin's name, slug, and entity-object table name. The core has no opinion about what an entity is; a plugin gives it meaning (a Video, a Lead, a Thing). The entity object is the plugin-owned business record itself, in a plugin-owned table. The core never reads or writes that table — it only knows the entity exists.

Workspace — the core operational unit​

The workspace is where the platform does its bookkeeping. It's deliberately minimal: id, a workspace_status_id, and timestamps — no plugin columns. A workspace represents one operational branch of an entity, and an entity can have many at once (parallel working versions). The link between a workspace and a specific entity object is owned by the plugin, through its {entity_slug}_workspace join table — the core workspace carries none of it.

A defining invariant: core workspaces are never deleted. There's no is_deleted or is_archived on the core workspace table. This is what guarantees execution history and financial data are always preserved; deletion and archival are plugin concerns, handled on the join table.

Status — the state machine​

Every workspace has a status, and status is the engine of progression. Statuses are scoped to an entity type (workspace_status.entity_id), and each plugin registers its own. The core doesn't interpret their meaning — it enforces only the structure of the state machine:

  • a workflow is scoped to an entity type and declares one or more eligible input statuses and exactly one resulting status, all of which must belong to that same entity type;
  • a workflow can be launched only from a workspace currently in one of its eligible statuses;
  • on success, the core transitions the workspace to the workflow's resulting status.

That's the whole mechanism: work advances one workflow at a time, gated by status, with the core enforcing consistency (a workflow's statuses and the workspace's entity type must agree) but never assigning semantics. The concrete tables and columns are in the Core ER Diagram; this article is the model behind them.