Contribution

A Contribution is an audit and progress-tracking record for a user-initiated blueprint contribution run — typically triggered when a workspace user submits or publishes a new provider blueprint (e.g. building a connector for “amazon” or “qonto”). It captures the run lifecycle (status, started/ended timestamps, progress payload), the provider being built (provider_slug), the originating page (source_url), and the structured input data (addresses, country, flow_json). Each contribution is workspace-scoped via a nullable FK to Workspace that is stamped at creation time to prevent cross-tenant drift. The entity is written exclusively by the blueprint contribution pipeline (POST /v1/contribution) and updated by dedicated PATCH handlers for appending steps and transitioning status; no fields are user-editable via the records-table PATCH surface.

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

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/contributions`	🟡 Planned
Retrieve	`GET /v1/contributions/{id}`	🟡 Planned
Create	`POST /v1/contributions`	🟡 Planned
Update	`PATCH /v1/contributions/{id}`	🟡 Planned
Delete	`DELETE /v1/contributions/{id}`	🟡 Planned

Data model

Attributes

Field	Type	Required	Constraints	Allowed values	Description
contribution_id	string (UUID) 🔒 system	✅ Yes	unique; generated by gen_random_uuid() on INSERT	—	Public-facing UUID identifier for the contribution. Never editable after creation.
name	string	✅ Yes	NOT NULL (no explicit length limit in entity)	—	Human-readable label for the contribution run, typically set by the client at creation time.
addresses	json (array of objects)	✅ Yes	NOT NULL; stored as JSONB array	—	Array of address objects captured during the contribution run. Schema is open-ended (Record<string, unknown>[]).
country	string[] (array)	✅ Yes	NOT NULL; stored as Postgres text[]	—	ISO-3166-1 alpha-2 country codes relevant to this contribution. Populated by the extension at run start.
status	string (enum ContributionStatus)	✅ Yes	NOT NULL; default ‘initial’; stored as plain string (not native Postgres enum)	initial \| processing \| cancel \| done	Lifecycle status of the contribution run. Transitions are driven by PATCH /:id/status — not by the records-table PATCH surface.
flow_json	json (object)	✅ Yes	NOT NULL; stored as JSONB	—	Structured blueprint-flow payload recorded during the contribution. Contains the sequence of steps (navigate, interact, extract) that the extension executed.
ai_historic	json (object)	⚪ No	nullable	—	AI processing history for the contribution — model used, phases completed, token usage, and intermediate LLM outputs. Populated by the blueprint analyzer pipeline.
provider_slug	string	⚪ No	nullable; max length 255	—	Provider identifier (e.g. ‘amazon’, ‘qonto’) for the new blueprint being built by this contribution. Set by the extension at run start.
source_url	string	⚪ No	nullable; max length 2048	—	The page the user was on in the Well app when they initiated the contribution run. Useful for support and replay context.
started_at	datetime	⚪ No	nullable; timestamptz	—	Timestamp when the extension began executing the contribution run. Set by PATCH /:id/status or the pipeline on first step.
ended_at	datetime	⚪ No	nullable; timestamptz	—	Timestamp when the contribution run completed (status = done or cancel). Set by the pipeline or PATCH /:id/status.
progress	json (ContributionProgress object)	⚪ No	nullable; stored as JSONB	—	Live progress snapshot for the in-flight run. Fields: total (int), current (int), inserted (int), status (string), message (string), error (string). All sub-fields are optional.
created_at	datetime 🔒 system	✅ Yes	NOT NULL; set once on INSERT via onCreate hook	—	Row creation timestamp. Stamped automatically by the MikroORM lifecycle hook; never supplied by the client.
updated_at	datetime 🔒 system	✅ Yes	NOT NULL; updated on every write via onUpdate hook	—	Last-modified timestamp. Refreshed automatically by the MikroORM lifecycle hook on every flush.
deleted_at	datetime 🔒 system	⚪ No	nullable; soft-delete sentinel	—	Soft-delete timestamp. NULL means the record is active. When set, the row is excluded from all workspace-scoped Hasura queries via the user-role RLS filter.

Relationships

Name	Type	Required	Description
workspace	to-one (ManyToOne)	No	The Workspace this contribution was initiated from. Nullable FK (`workspace_pk`) stamped at creation to prevent cross-tenant drift. Orphan rows whose workspace no longer resolves are excluded from scoped queries automatically by Hasura RLS. Target: `core_api.workspaces`.

System-computed

contribution_id: generated by gen_random_uuid() on INSERT — never supplied by the client
created_at: set once on INSERT by MikroORM onCreate hook (new Date())
updated_at: refreshed on every flush by MikroORM onUpdate hook (new Date())
deleted_at: soft-delete sentinel — NULL on active rows; set by a soft-delete operation, never by the client directly
status default: ‘initial’ set by the entity class initializer and the DB column default — no application code needs to supply it on creation
workspace_pk: stamped at creation by ContributionService/route handler from req.workspace (JWT-resolved) so in-flight runs are always correctly tenant-scoped; nullable on pre-migration legacy rows

Example

{
  "data": {
    "type": "contribution",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "attributes": {
      "name": "Amazon blueprint contribution — 2026-05-01",
      "addresses": [
        { "street": "410 Terry Ave N", "city": "Seattle", "country": "US" }
      ],
      "country": ["US"],
      "status": "done",
      "flow_json": {
        "steps": [
          { "type": "navigate", "url": "https://www.amazon.com/gp/b2b/manage" }
        ]
      },
      "ai_historic": {
        "model": "gemini-3-flash-preview",
        "phases": ["navigation", "exploration", "generation"],
        "token_usage": 12400
      },
      "provider_slug": "amazon",
      "source_url": "https://app.wellapp.ai/workspaces/ws_abc/settings/connectors",
      "started_at": "2026-05-01T09:12:00.000Z",
      "ended_at": "2026-05-01T09:14:35.000Z",
      "progress": {
        "total": 8,
        "current": 8,
        "inserted": 8,
        "status": "complete",
        "message": "Blueprint published successfully"
      },
      "created_at": "2026-05-01T09:11:55.000Z",
      "updated_at": "2026-05-01T09:14:35.000Z",
      "deleted_at": null
    },
    "relationships": {
      "workspace": {
        "data": { "type": "workspace", "id": "9f3a2b1c-0000-4abc-8def-000000000001" }
      }
    }
  }
}

_{Source: /Users/maximechampoux/platform/apps/api/src/database/entities/Contribution.ts · domain: intelligence · tier: Activity}

Main objects

Supporting objects

Platform objects

Activity objects

Infrastructure objects

API operations

Data model

Attributes

Relationships

System-computed

Example

​API operations

​Data model

​Attributes

​Relationships

​System-computed

​Example

API operations

Data model

Attributes

Relationships

System-computed

Example