CompanyRelation

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	— _{(not a records root)}
REST base	`/v1/company-relations`
Entity class	`CompanyRelation`

Internal object. Not currently exposed on the public REST API. The operations below describe the intended contract.

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

{
  "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" }
      }
    }
  }
}

_{Source: apps/api/src/database/entities/CompanyRelation.ts · domain: financial-graph · tier: Supporting}

CompanyPhone Company web links

Main objects

Supporting objects

Platform objects

Activity objects

Infrastructure objects

API operations

Data model

Attributes

Relationships

System-computed

Example

​API operations

​Data model

​Attributes

​Relationships

​System-computed

​Example

API operations

Data model

Attributes

Relationships

System-computed

Example