> ## 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.

# CompanyWorkspaceConnector

> CompanyWorkspaceConnector is a per-row provenance junction table that records the relationship between a `Company` entity and a `WorkspaceConnector` instance, d

CompanyWorkspaceConnector is a per-row provenance junction table that records the relationship between a `Company` entity and a `WorkspaceConnector` instance, discriminated by a `direction` field (`input` for data pulled from the connector, `output` for data pushed to it). It mirrors the `document_workspace_connectors` pattern and was introduced in W19 to replace a rejected single `ManyToOne` shape. Tenant scope is inherited indirectly through the referenced `Company.workspace` and `WorkspaceConnector.workspace` — there is deliberately no direct `workspace_pk` column on the junction itself. Multiple rows are permitted per (company, connector, direction) triple; deduplication logic is deferred to a future iteration.

| Naming                          | Value                              |
| ------------------------------- | ---------------------------------- |
| Object                          | CompanyWorkspaceConnector          |
| Resource type (JSON:API `type`) | `company_workspace_connector`      |
| Collection / records root       | — <sub>(not a records root)</sub>  |
| REST base                       | `/v1/company-workspace-connectors` |
| Entity class                    | `CompanyWorkspaceConnector`        |

<Note>
  **Internal object.** Not currently exposed on the public REST API. The operations below describe the intended contract.
</Note>

## API operations

| Operation | Method & path                                  | Status     |
| --------- | ---------------------------------------------- | ---------- |
| List      | `GET /v1/company-workspace-connectors`         | 🟡 Planned |
| Retrieve  | `GET /v1/company-workspace-connectors/{id}`    | 🟡 Planned |
| Create    | `POST /v1/company-workspace-connectors`        | 🟡 Planned |
| Update    | `PATCH /v1/company-workspace-connectors/{id}`  | 🟡 Planned |
| Delete    | `DELETE /v1/company-workspace-connectors/{id}` | 🟡 Planned |

## Data model

### Attributes

| Field       | Type                               | Required | Constraints                                                                                    | Allowed values      | Description                                                                                                                                                                                                     |
| ----------- | ---------------------------------- | -------- | ---------------------------------------------------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| direction   | 🔒 system — enum (direction\_enum) | ✅ Yes    | Native Postgres enum `core_api.direction_enum`; CHECK implicit via enum type; NOT NULL         | "input" \| "output" | Discriminates the data-flow direction: `input` = record was pulled from this connector (source provenance); `output` = record was pushed to this connector (distribution provenance).                           |
| created\_at | 🔒 system — datetime (timestamptz) | ✅ Yes    | DEFAULT now(); set once on INSERT via MikroORM `onCreate` hook; NOT NULL                       | —                   | Timestamp when the provenance row was first created. Stamped automatically by the MikroORM lifecycle hook; never set by caller.                                                                                 |
| updated\_at | 🔒 system — datetime (timestamptz) | ⚪ No     | Nullable; set on INSERT and refreshed on every UPDATE via MikroORM `onCreate`/`onUpdate` hooks | —                   | Timestamp of the last mutation to this row. Managed automatically; null only if the row was never updated after creation in edge cases.                                                                         |
| deleted\_at | 🔒 system — datetime (timestamptz) | ⚪ No     | Nullable; soft-delete sentinel; column-level nullable=true                                     | —                   | Soft-delete timestamp. When non-null the row is logically deleted and excluded from active queries. Set by the connector sync orchestrator on revocation or re-link deduplication; never set directly by users. |

### Relationships

| Name               | Type               | Required | Description                                                                                                                                                                                                                                                                           |
| ------------------ | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| company            | to-one (ManyToOne) | ✅ Yes    | The Company entity whose sync provenance this row records. Foreign key `company_pk` → `core_api.companies.pk` ON UPDATE CASCADE. Tenant isolation is resolved through this relationship (Company carries `workspace_pk`). Declared on this entity as `@ManyToOne(() =&gt; Company)`.  |
| workspaceConnector | to-one (ManyToOne) | ✅ Yes    | The WorkspaceConnector instance that sourced (direction=input) or received (direction=output) this company record. Foreign key `workspace_connector_pk` → `core_api.workspace_connectors.pk` ON UPDATE CASCADE. Declared on this entity as `@ManyToOne(() =&gt; WorkspaceConnector)`. |

### System-computed

* pk — serial primary key, auto-incremented by Postgres on INSERT; never exposed in API responses.
* created\_at — stamped once at INSERT time via MikroORM onCreate: () => new Date(); no caller input accepted.
* updated\_at — stamped at INSERT and refreshed on every UPDATE via MikroORM onUpdate: () => new Date().
* deleted\_at — soft-delete sentinel; set by the connector sync pipeline (not user-initiated); rows with non-null deleted\_at are filtered out of active queries.
* No workspace\_pk column by design — tenant scope is inherited through the Company and WorkspaceConnector parent relationships; Hasura RLS traverses these relationships for row-level isolation.
* No unique constraint on (company\_pk, workspace\_connector\_pk, direction) — duplicate rows are permitted by design; deduplication is deferred to a future iteration (stated explicitly in migration comments).
* No external\_id field — connector-pointer provenance only; external-object identity tracking is iteration 4+ work.
* Rows are created exclusively by the connector sync orchestrator during entity persistence; there is no user-facing resource PATCH route for this junction.

## Example

```json theme={null}
{
  "data": {
    "type": "company_workspace_connector",
    "id": "3f8c2a1d-0e45-4b7f-9c3e-1a2b3c4d5e6f",
    "attributes": {
      "direction": "input",
      "created_at": "2026-05-10T14:32:00.000Z",
      "updated_at": "2026-05-10T14:32:00.000Z",
      "deleted_at": null
    },
    "relationships": {
      "company": {
        "data": { "type": "company", "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }
      },
      "workspace_connector": {
        "data": { "type": "workspace_connector", "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901" }
      }
    }
  }
}
```

<sub>Source: `apps/api/src/database/entities/CompanyWorkspaceConnector.ts` · domain: ingestion · tier: Infrastructure</sub>