# TrialBalance

## Description

TrialBalance is a point-in-time snapshot report that summarizes the balances of all GL accounts for a specific accounting period within a company. For each account, the report presents the opening balance, total period debits, total period credits, and the resulting closing balance via TrialBalanceLine records. The trial balance serves as the fundamental verification mechanism in double-entry bookkeeping: total debits across all accounts must equal total credits. The report supports two variants: pre-close (reflecting standard and adjusting entries) and post-close (reflecting closing entries that zero out temporary accounts). The trial balance is the foundational input for financial statement generation.

## Domain Model Definitions

### Model type

Standard

### Command Definitions

- [generateTrialBalance](../commands/GenerateTrialBalance.md) - Generate a trial balance snapshot for a company, period, and variant

### Query Definitions

- [GetTrialBalance](../queries/GetTrialBalance.md) - Retrieve a trial balance snapshot by id with all line items
- [ListTrialBalances](../queries/ListTrialBalances.md) - List trial balance snapshots for a company with optional filters (period, variant)

### Models

- TrialBalance
- TrialBalanceLine

### Invariants

- Trial balance can only be generated for a company with an ACTIVE Chart of Accounts
- Trial balance can only be generated for a valid accounting period that exists in the system
- Trial balance must include all GL accounts from the active CoA, even those with zero balances
- Opening balance for each account equals the closing balance from the immediately preceding period
- Opening balance for the first period of a new CoA defaults to zero for all accounts
- Period debits per account equal the sum of all debit amounts from posted journal lines for that account in the period
- Period credits per account equal the sum of all credit amounts from posted journal lines for that account in the period
- Closing balance per account equals opening balance plus period debits minus period credits
- Total debits across all accounts must equal total credits across all accounts (fundamental equilibrium check)
- Pre-close trial balance excludes closing entries
- Post-close trial balance includes all closing entries and shows zero balances for all temporary accounts
- Trial balance is scoped to a single company; accounts from other companies are never included
- Only posted journal entries are included; draft or voided entries are excluded
- Trial balance snapshot includes a generation timestamp
- Trial balance snapshot records the variant type (PRE_CLOSE or POST_CLOSE)
- Generating a trial balance when total debits do not equal total credits produces an imbalance error with the discrepancy amount
- Trial balance respects the account group hierarchy from coa-management, providing subtotals at each group level
- Trial balance accounts are ordered by account code in ascending order within each account group
- Generating a trial balance for a period with no posted journal entries produces a valid report with zero debits, zero credits, and opening balances carried forward
- Regenerating a trial balance for the same period and variant produces an updated snapshot reflecting any new postings since the last generation
- Trial balance generation emits an audit event via the audit module recording the acting user, company, period, variant, and timestamp

### Relationships

- **References Company**: Each trial balance is scoped to a Company via companyId (organization module)
- **References AccountingPeriod**: Each trial balance references an AccountingPeriod via accountingPeriodId
- **References ChartOfAccounts**: Each trial balance references a ChartOfAccounts via chartOfAccountsId (coa-management module)
- **Has Many TrialBalanceLine**: A trial balance contains line items for each account
