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

# CompanyCategory

> CompanyCategory is a pivot relation that links a Company to a Category within the Well financial graph

CompanyCategory is a pivot relation that links a Company to a Category within the Well financial graph. It carries no business attributes beyond the join keys and a creation timestamp, enabling a many-to-many classification of companies by user-defined categories (e.g. "Supplier", "Client"). Rows are soft-deleted via `deleted_at` rather than hard-deleted, preserving the audit trail of historical classifications. The entity is written exclusively by the connector-sync and enrichment pipelines; users cannot create or mutate rows through a resource PATCH.

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

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

## Data model

### Attributes

| Field       | Type                    | Required | Constraints                                                                            | Allowed values            | Description                                                                                                                                  |
| ----------- | ----------------------- | -------- | -------------------------------------------------------------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| created\_at | 🔒 system — timestamptz | ✅ Yes    | Set once on INSERT via onCreate hook; never NULL                                       | ISO-8601 datetime         | Timestamp recording when this company–category association was created. Immutable after creation.                                            |
| deleted\_at | timestamptz \| null     | ⚪ No     | NULL means active; non-NULL means soft-deleted. No updated\_at present on this entity. | ISO-8601 datetime or null | Soft-delete timestamp. Set by the system when the company–category association is removed. All live queries must filter deleted\_at IS NULL. |

### Relationships

| Name     | Type               | Required                                 | Description                                                                                                                                                                                                       |
| -------- | ------------------ | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| company  | to-one (ManyToOne) | Yes — NOT NULL FK with ON UPDATE CASCADE | The Company this category is attached to. FK: company\_categories.company\_pk → companies.pk. A soft-deleted company\_category row no longer appears in live queries but the FK is preserved for the audit trail. |
| category | to-one (ManyToOne) | Yes — NOT NULL FK with ON UPDATE CASCADE | The Category being associated with the company. FK: company\_categories.category\_pk → categories.pk. Category rows carry a category\_type\_enum discriminator (e.g. COMPANY, TRANSACTION).                       |

### System-computed

* pk — serial auto-increment integer, internal join key only; never exposed in the public API
* created\_at — set once on INSERT via MikroORM onCreate: () => new Date(); no onUpdate hook exists on this entity
* deleted\_at — written by the system (pipeline or service layer) when the pivot row is logically removed; never user-settable via PATCH
* No UUID public identifier (company\_category\_id) exists on this entity — the row is identified exclusively by its compound context (company + category). The JSON:API id is therefore the internal pk.
* No updated\_at column — the entity has no MikroORM onUpdate hook and the migration DDL confirms the column is absent.

## Example

```json theme={null}
{
  "data": {
    "type": "company_category",
    "id": "1",
    "attributes": {
      "created_at": "2025-09-14T08:23:11.000Z",
      "deleted_at": null
    },
    "relationships": {
      "company": {
        "data": { "type": "company", "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }
      },
      "category": {
        "data": { "type": "category", "id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210" }
      }
    }
  }
}
```

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