Collect

A Collect represents a single data-collection run initiated by an authenticated user, typically driven by the browser extension (popup, side panel, or blueprint automation). Each run is bound to one People (the subject being enriched), one Workspace (stamped at creation from req.workspace and never re-derived), and optionally one Task (the automation trigger). The status lifecycle progresses from todo through in_progress to finalized or error. Workspace binding is nullable on legacy rows to handle orphaned people records; all workspace-scoped queries silently exclude those rows via Hasura RLS.

Naming	Value
Object	Collect
Resource type (JSON:API `type`)	`collect`
Collection / records root	— _{(not a records root)}
REST base	`/v1/collects`
Entity class	`Collect`

Internal object. Not currently exposed on the public REST API. The operations below describe the intended contract.

API operations

Operation	Method & path	Status
List	`GET /v1/collects`	🟡 Planned
Retrieve	`GET /v1/collects/{id}`	🟡 Planned
Create	`POST /v1/collects`	🟡 Planned
Update	`PATCH /v1/collects/{id}`	🟡 Planned
Delete	`DELETE /v1/collects/{id}`	🟡 Planned

Data model

Attributes

Field	Type	Required	Constraints	Allowed values	Description
collect_id	string (UUID)	✅ Yes	unique	—	Public stable identifier for the collect run. Generated server-side via gen_random_uuid(); never user-supplied.
provider	string	⚪ No	varchar(255), nullable	—	Slug identifying the data-collection provider or browser extension surface that initiated the run (e.g. 'linkedin', 'popup'). Null for manual or legacy rows.
status	enum (collect_status_enum)	✅ Yes	native enum collect_status_enum, default 'todo'	todo \| in_progress \| finalized \| error	Lifecycle state of the collection run. Defaults to 'todo' at creation; transitions to 'in_progress', then 'finalized' (success) or 'error' (terminal failure). Terminal statuses trigger a workspace_connector_sync_logs entry.
started_at	🔒 system — timestamptz	⚪ No	nullable, timestamptz	—	Timestamp when the run began active processing. Set by the client via PATCH; null until the extension begins extraction.
ended_at	🔒 system — timestamptz	⚪ No	nullable, timestamptz	—	Timestamp when the run reached a terminal state (finalized or error). Set by the client via PATCH alongside status update.
created_at	🔒 system — timestamptz	✅ Yes	not null, set once on insert	—	Row creation timestamp. Set via onCreate hook; never user-editable.
updated_at	🔒 system — timestamptz	⚪ No	nullable, set on insert and every update	—	Last modification timestamp. Automatically set on every update via onUpdate hook.
deleted_at	🔒 system — timestamptz	⚪ No	nullable	—	Soft-delete timestamp. When set, the row is excluded from all workspace-scoped queries and Hasura RLS filters. Set via DELETE endpoint (CollectService.deleteCollect).

Relationships

Name	Type	Required	Description
people	to-one (ManyToOne)	✅ Yes	The People record being enriched during this collection run. Resolved at creation from the authenticated user's associated person. FK: collects.people_pk → peoples.pk. Indexed via idx_collects_people (partial, deleted_at IS NULL).
workspace	to-one (ManyToOne)	⚪ No (nullable; required on all new rows by service-layer enforcement)	The Workspace this collect run belongs to. Stamped once at creation from req.workspace and never re-derived from subsequent JWT calls, ensuring cross-workspace switches cannot reroute writes mid-flight. Nullable to absorb legacy orphan rows; all workspace-scoped queries (Hasura RLS, service layer) exclude null rows automatically. FK: collects.workspace_pk → workspaces.pk (cascade update+delete). Indexed via idx_collects_workspace_status.
task	to-one (ManyToOne)	⚪ No	Optional link to the Task that triggered this collection run (blueprint automation). Null for manual/popup/side-panel collections and legacy rows. FK: collects.task_pk → tasks.pk. On Task deletion the FK is set to null (deleteRule: 'set null').

System-computed

collect_id — generated server-side via gen_random_uuid() defaultRaw; never accepted from client input
created_at — set once on insert via MikroORM onCreate hook (new Date())
updated_at — refreshed on every update via onUpdate hook (new Date())
deleted_at — soft-delete; set to current timestamp by CollectService.deleteCollect; null on active rows
workspace (workspace_pk) — stamped at creation time from req.workspace by CollectService.createCollect and never subsequently overwritten, even on PATCH calls; this immutability is the tenant-safety guarantee for in-flight runs
status default — CollectStatusEnum.TODO at row creation unless overridden by the POST body
idx_collects_status — partial index on status WHERE deleted_at IS NULL
idx_collects_people — partial index on people_pk WHERE deleted_at IS NULL
idx_collects_workspace_status — composite index on (workspace_pk, status) for active-run queries

Example

{
  "data": {
    "type": "collect",
    "id": "a3f7c2e1-84b0-4d9e-9c12-1e8f7a3b5d22",
    "attributes": {
      "collect_id": "a3f7c2e1-84b0-4d9e-9c12-1e8f7a3b5d22",
      "provider": "linkedin",
      "status": "in_progress",
      "started_at": "2026-06-02T09:15:00.000Z",
      "ended_at": null,
      "created_at": "2026-06-02T09:14:58.123Z",
      "updated_at": "2026-06-02T09:15:01.450Z",
      "deleted_at": null
    },
    "relationships": {
      "people": {
        "data": { "type": "people", "id": "d8b1a4f2-11cc-4e77-b933-abc123456789" }
      },
      "workspace": {
        "data": { "type": "workspace", "id": "7e91cd02-0a3b-4f55-8811-fedcba987654" }
      },
      "task": {
        "data": null
      }
    }
  }
}

_{Source: /Users/maximechampoux/platform/apps/api/src/database/entities/Collect.ts · domain: ingestion · tier: Infrastructure}