CompanyFinancial - Well Starter Kit

CompanyFinancial is a one-to-one “financial profile” extension of the Company entity that stores default ledger-account preferences (accounts receivable and payable) plus classifier provenance metadata indicating how and with what confidence those defaults were assigned. It is written exclusively by the internal classification pipeline — never directly by users — making it a read-only supporting record from the API consumer perspective. Each company may have at most one CompanyFinancial row (enforced by a UNIQUE constraint on company_pk). The source / confidence pair is governed by a database-level invariant: confidence is stored only when source = 'classifier_auto'; any transition away from the auto-classifier must clear confidence in the same write.

Naming	Value
Object	CompanyFinancial
Resource type (JSON:API `type`)	`company_financial`
Collection / records root	— _{(not a records root)}
REST base	`/v1/company-financials`
Entity class	`CompanyFinancial`

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

Data model

Attributes

Field	Type	Required	Constraints	Allowed values	Description
company_financial_id	string (UUID)	✅ Yes	UNIQUE; DEFAULT gen_random_uuid()	—	Public UUID identifier for this record. Generated via gen_random_uuid() on insert. Used as the JSON:API resource `id`.
source	🔒 system — enum (CompanyFinancialSourceEnum) \| null	⚪ No	Nullable; native PostgreSQL enum ‘core_api.company_financial_source_enum’; CHECK company_financials_source_confidence_invariant	classifier_auto \| classifier_suggested_human_confirmed \| human_override \| imported_chart_rule \| migration	Provenance of the default ledger-account assignment. Set by the classification pipeline; never written directly by users. When ‘classifier_auto’, the `confidence` field must also be non-null (enforced by DB CHECK). Transitions away from ‘classifier_auto’ must clear `confidence` in the same write.
confidence	🔒 system — decimal(4,3) stored as string \| null	⚪ No	Nullable; DECIMAL(4,3); CHECK confidence IS NULL OR (confidence >= 0 AND confidence <= 1); CHECK company_financials_source_confidence_invariant (confidence non-null ↔ source=‘classifier_auto’)	0.000 – 1.000	Classifier confidence score in the range [0, 1] with three decimal places. Non-null only when source=‘classifier_auto’; any other source value requires this to be null (DB CHECK invariant). Stored as DECIMAL(4,3) and returned as a string by MikroORM.
created_at	🔒 system — Date	✅ Yes	NOT NULL; set once on create	—	Timestamp of record creation. Set automatically on insert via MikroORM onCreate hook; never updated.
updated_at	🔒 system — Date \| null	⚪ No	Nullable on initial read before first update; set on create and update	—	Timestamp of the last update. Set on create and on every subsequent update via MikroORM onUpdate hook.
deleted_at	🔒 system — Date \| null	⚪ No	Nullable	—	Soft-delete timestamp. Null means the record is active. All live queries must filter deleted_at IS NULL.

Relationships

Name	Type	Required	Description
company	to-one (OneToOne → Company)	✅ Yes	The company this financial profile belongs to. Enforced unique at the DB level (company_pk UNIQUE), guaranteeing at most one CompanyFinancial per Company.
account_receivable_default	to-one (ManyToOne → LedgerAccount)	⚪ No	Default ledger account applied to accounts-receivable postings for this company. Nullable; set by the chart-of-accounts classification pipeline.
account_payable_default	to-one (ManyToOne → LedgerAccount)	⚪ No	Default ledger account applied to accounts-payable postings for this company. Nullable; set by the chart-of-accounts classification pipeline.

System-computed

company_financial_id — generated via gen_random_uuid() on insert; unique public identifier
created_at — set to new Date() on insert via MikroORM onCreate hook
updated_at — set to new Date() on insert and on every update via MikroORM onUpdate hook
deleted_at — set by the pipeline soft-delete path; null for active records
source + confidence — both fields are written exclusively by the chart-of-accounts classification pipeline (classifier_auto), human review confirmation flow (classifier_suggested_human_confirmed, human_override), rule import (imported_chart_rule), or data migration (migration); never set via a user-facing PATCH
DB CHECK company_financials_confidence_range — database enforces confidence ∈ [0,1] when non-null
DB CHECK company_financials_source_confidence_invariant — database enforces that confidence is non-null iff source=‘classifier_auto’; any pipeline transition clearing the auto-classifier must write confidence=null in the same statement

Example

{
  "data": {
    "type": "company_financial",
    "id": "b3e7c1a2-84fd-4f1e-9c20-3a77d5e82b01",
    "attributes": {
      "company_financial_id": "b3e7c1a2-84fd-4f1e-9c20-3a77d5e82b01",
      "source": "classifier_auto",
      "confidence": "0.921",
      "created_at": "2026-03-15T10:42:00.000Z",
      "updated_at": "2026-05-20T14:08:33.000Z",
      "deleted_at": null
    },
    "relationships": {
      "company": {
        "data": { "type": "company", "id": "e1c4a7b0-1234-4abc-b000-99aabb001122" }
      },
      "account_receivable_default": {
        "data": { "type": "ledger_account", "id": "d9f3a100-aaaa-4bbb-cccc-000011112222" }
      },
      "account_payable_default": {
        "data": { "type": "ledger_account", "id": "f2e1b200-bbbb-4ccc-dddd-111122223333" }
      }
    }
  }
}

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

Documentation Index

​API operations

​Data model

​Attributes

​Relationships

​System-computed

​Example

API operations

Data model

Attributes

Relationships

System-computed

Example