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

# Category

> Category is a workspace-global catalog entity representing a named classification tag that can be applied to companies or transactions

Category is a workspace-global catalog entity representing a named classification tag that can be applied to companies or transactions. It is not workspace-scoped itself — it acts as a shared taxonomy that any workspace can reference through the CompanyCategory pivot. A category carries a `category_type` discriminator (`company` or `transaction`) that controls which entity type it may label, and a `name` string that is the human-visible label.

| Naming                          | Value            |
| ------------------------------- | ---------------- |
| Object                          | Category         |
| Resource type (JSON:API `type`) | `category`       |
| Collection / records root       | `categories`     |
| REST base                       | `/v1/categories` |
| Entity class                    | `Category`       |

## API operations

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

## Data model

### Attributes

| Field          | Type                                          | Required | Constraints                                                               | Allowed values         | Description                                                                                                                                                                                     |
| -------------- | --------------------------------------------- | -------- | ------------------------------------------------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| category\_id   | string, UUID, 🔒 system                       | ✅ Yes    | unique; generated by gen\_random\_uuid() at insert                        | —                      | Public immutable identifier for the category, used in all API surfaces and relationships.                                                                                                       |
| name           | string                                        | ✅ Yes    | varchar(255), NOT NULL                                                    | —                      | Human-readable label for the category (e.g. 'SaaS', 'Payroll', 'Transport'). Must be unique within a given category\_type in practice (enforced at the application layer, not at the DB level). |
| category\_type | string (enum)                                 | ✅ Yes    | NOT NULL; native PG enum `core_api.category_type_enum`; default 'company' | company \| transaction | Discriminator controlling which entity type this category tag applies to. `company` categories are attached to companies via CompanyCategory; `transaction` categories label bank transactions. |
| created\_at    | string (ISO 8601 datetime), 🔒 system         | ✅ Yes    | NOT NULL; set by MikroORM onCreate lifecycle hook                         | —                      | Timestamp of when the category record was first created.                                                                                                                                        |
| updated\_at    | string (ISO 8601 datetime), 🔒 system         | ⚪ No     | nullable; set by MikroORM onCreate and onUpdate lifecycle hooks           | —                      | Timestamp of the most recent update to this category record.                                                                                                                                    |
| deleted\_at    | string (ISO 8601 datetime) \| null, 🔒 system | ⚪ No     | nullable; null means active                                               | —                      | Soft-delete sentinel. When non-null, the category is considered deleted and must be excluded from all active queries via `deleted_at IS NULL` predicate.                                        |

### System-computed

* `category_id` is generated at insert by the Postgres expression `gen_random_uuid()` (defaultRaw). It is unique and immutable.
* `created_at` is set by the MikroORM `onCreate` lifecycle hook to `new Date()` at insertion time.
* `updated_at` is set by both `onCreate` and `onUpdate` lifecycle hooks; tracks last modification.
* `deleted_at` is null on active records and set to the deletion timestamp on soft-delete. All queries must filter `deleted_at IS NULL`.
* `category_type` defaults to `CategoryTypeEnum.COMPANY` ('company') at the entity level. The DB column carries `NOT NULL DEFAULT 'company'` via the `category_type_enum` native PG type added in `Migration20260528120000`.
* The partial composite index `idx_categories_category_type_active ON core_api.categories (category_type, name) WHERE deleted_at IS NULL` is maintained for fast lookup by type within the active catalog.
* Category is a global (non-workspace-scoped) catalog entity — it has no `workspace_pk` column. Workspace-level association is achieved exclusively through the `CompanyCategory` pivot, which joins a workspace-scoped Company to a global Category.
* Transaction-type catalog entries were seeded by `Migration20260528120000` with a fixed list of standard transaction category names (e.g. 'Payroll', 'Rent', 'Tax', etc.).

## Example

```json theme={null}
{
  "data": {
    "type": "category",
    "id": "d4f8a3c1-09b2-4e77-bc3a-f21e6098d5ea",
    "attributes": {
      "category_id": "d4f8a3c1-09b2-4e77-bc3a-f21e6098d5ea",
      "name": "SaaS",
      "category_type": "company",
      "created_at": "2025-09-14T10:23:45.000Z",
      "updated_at": "2025-09-14T10:23:45.000Z",
      "deleted_at": null
    }
  }
}
```

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