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 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
{
"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
}
}
}
apps/api/src/database/entities/Category.ts · domain: financial-graph · tier: Supporting
