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

# CompanyFinancial

> CompanyFinancial is a one-to-one 'financial profile' extension of the Company entity that stores default ledger-account preferences (accounts receivable and pay

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       | — <sub>(not a records root)</sub> |
| REST base                       | `/v1/company-financials`          |
| Entity class                    | `CompanyFinancial`                |

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

```json theme={null}
{
  "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" }
      }
    }
  }
}
```

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