> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wellapp.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
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\\[]). |
| 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
```json theme={null}
{
"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