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

# CompanyRelation

> CompanyRelation models a directed link between two Company entities, capturing structural or commercial relationships (parent/subsidiary hierarchy, supplier cha

CompanyRelation models a directed link between two Company entities, capturing structural or commercial relationships (parent/subsidiary hierarchy, supplier chains, client networks). Each tuple records a source company, a target company, and the typed nature of the link. The entity is workspace-adjacent — it is scoped through its Company endpoints rather than carrying a direct workspace FK. Soft-delete support is present via `deleted_at`; there is no `updated_at` column on this entity.

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

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

## Data model

### Attributes

| Field       | Type                                             | Required | Constraints                                                 | Allowed values               | Description                                                                                                                                                                        |
| ----------- | ------------------------------------------------ | -------- | ----------------------------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| link\_type  | enum (link\_type\_enum — native PostgreSQL enum) | ✅ Yes    | NOT NULL; native enum — invalid values rejected at DB level | parent \| supplier \| client | Classifies the directed relationship from source\_company to target\_company. Stored as a native PostgreSQL enum `core_api.link_type_enum`.                                        |
| created\_at | 🔒 system — Date (timestamptz)                   | ✅ Yes    | NOT NULL; immutable after insert                            | —                            | Timestamp set once at row creation via MikroORM `onCreate` hook. No `updated_at` exists on this entity.                                                                            |
| deleted\_at | Date \| null (timestamptz)                       | ⚪ No     | NULLABLE                                                    | —                            | Soft-delete sentinel. NULL means the relation is active; a non-null timestamp marks it as logically deleted. All queries must filter `deleted_at IS NULL` per platform convention. |

### Relationships

| Name            | Type               | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                    |
| --------------- | ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| source\_company | to-one (ManyToOne) | ✅ Yes    | The originating Company in the directed relationship (e.g. the subsidiary, the buyer, or the child entity). FK column: `source_company_pk` → `core_api.companies.pk`. A partial index on `source_company_pk` was added in Migration20260504120000 for hot-path query performance. Note: original migration used a typo column `souce_company_pk`; corrected to `source_company_pk` in Migration20251126135042. |
| target\_company | to-one (ManyToOne) | ✅ Yes    | The destination Company in the directed relationship (e.g. the parent, the supplier, or the client). FK column: `target_company_pk` → `core_api.companies.pk`. A partial index on `target_company_pk` was added in Migration20260504120000.                                                                                                                                                                    |

### System-computed

* created\_at — set to `new Date()` via MikroORM `onCreate` hook; never written by the caller
* deleted\_at — set by soft-delete logic; never passed in on creation
* pk — auto-increment serial primary key, internal only; never exposed in the public API
* source\_company\_pk / target\_company\_pk — FK integers resolved from the ManyToOne relations; the public API surfaces these as relationship objects, not raw integers

## Example

```json theme={null}
{
  "data": {
    "type": "company_relation",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "attributes": {
      "link_type": "supplier",
      "created_at": "2025-09-12T08:30:00.000Z",
      "deleted_at": null
    },
    "relationships": {
      "source_company": {
        "data": { "type": "company", "id": "11111111-aaaa-bbbb-cccc-dddddddddddd" }
      },
      "target_company": {
        "data": { "type": "company", "id": "22222222-aaaa-bbbb-cccc-eeeeeeeeeeee" }
      }
    }
  }
}
```

<sub>Source: `apps/api/src/database/entities/CompanyRelation.ts` · domain: financial-graph · tier: Supporting</sub>