@tailor-platform/erp-kit 0.6.0 → 0.8.0

package/src/modules/finance-ledger/docs/features/subledger-integration.md

@@ -0,0 +1,141 @@
+# Subledger Integration
+
+## Overview
+
+Subledger Integration provides the standardized event-driven framework through which upstream operational modules — purchase (accounts payable), sales (accounts receivable), inventory (valuation), and manufacturing (cost settlement) — post journal entries into the general ledger. Each upstream module emits a domain event containing the financial impact of a business transaction (e.g., a validated purchase bill, an issued sales invoice, an inventory valuation change, or a manufacturing cost settlement). The finance-ledger module subscribes to these events, validates the handoff payload against its own constraints (accounting period status, account validity, debit/credit balance), creates the corresponding journal entry with appropriate journal type classification, and acknowledges successful posting back to the originating module. This event-driven architecture decouples operational transaction processing from accounting, allowing each module to evolve independently while maintaining GL completeness.
+
+The handoff contract for each subledger type defines the required payload fields, the expected account references (sourced from coa-management), the journal type assignment, and the acknowledgment pattern. Purchase and sales handoffs reference specific GL accounts for payable/receivable recognition and revenue/expense classification. Inventory handoffs carry valuation change amounts with asset and contra-account references. Manufacturing handoffs include WIP, absorption, and variance account references along with cost settlement data. All handoff contracts enforce idempotency — duplicate event delivery results in acknowledgment without re-posting — and require the originating module to have validated the target accounting period status before emitting the event. The finance-ledger module performs its own period status check as a secondary gate, rejecting events that target periods not in OPEN or FUTURE_ENTERABLE status.
+
+## Business Purpose
+
+Organizations need a disciplined, auditable mechanism for subledger-to-GL integration to ensure financial completeness and operational consistency:
+
+- **GL completeness**: Every financial transaction originating in an operational module must ultimately be reflected in the general ledger. Without standardized integration contracts, transactions can be lost between modules, leading to incomplete financial statements and failed audits
+- **Separation of concerns**: Operational modules own business logic (purchase matching, invoice issuance, inventory valuation, cost settlement) while the finance-ledger owns accounting logic (double-entry enforcement, period control, account validation). The handoff contract is the boundary — upstream modules produce financial events, the GL consumes them
+- **Event-driven decoupling**: By using domain events rather than direct API calls, subledger modules do not need runtime knowledge of GL internals. This follows the pattern used by Oracle Subledger Accounting (SLA) and SAP's document-posting architecture, where operational documents trigger accounting events that the GL processes independently
+- **Idempotent processing**: Network failures, retries, and at-least-once delivery guarantees mean the GL may receive the same event multiple times. Idempotency keyed on source document reference ensures exactly-once posting semantics without requiring distributed transactions
+- **Period validation at the boundary**: Upstream modules query accounting period status before emitting handoff events (first gate), and the finance-ledger re-validates period status upon receipt (second gate). This defense-in-depth approach prevents posting to closed or permanently closed periods even if the upstream module's status cache is stale
+- **Acknowledgment contracts**: Each subledger type receives a typed acknowledgment upon successful posting (e.g., `PurchaseBillPostingAcknowledgment`, `ManufacturingCostSettlementAcknowledgment`). This enables upstream modules to track GL posting status, detect failures, and implement compensating actions
+- **Journal type classification**: Handoff contracts assign the correct journal type (Sales, Purchase, Miscellaneous) to each generated journal entry, ensuring proper categorization in trial balances and financial statements
+- **Audit traceability**: Every subledger-originated journal entry carries a source document reference (e.g., purchase bill ID, sales invoice number, inventory event ID, manufacturing settlement ID) linking the GL entry back to the originating business transaction for audit trail continuity
+
+## Process Flow
+
+The generic subledger-to-GL posting flow applies to all upstream module types:
+
+```mermaid
+flowchart TD
+    A[Upstream module completes business transaction] --> B[Upstream module queries AccountingPeriod status]
+    B --> C{Period OPEN or FUTURE_ENTERABLE?}
+    C -- No --> D[Upstream module rejects or defers posting]
+    C -- Yes --> E[Upstream module emits subledger handoff event]
+    E --> F[finance-ledger receives handoff event]
+    F --> G{Idempotency check: already posted?}
+    G -- Yes --> H[Return existing acknowledgment]
+    G -- No --> I[Validate accounting period status]
+    I --> J{Period still OPEN or FUTURE_ENTERABLE?}
+    J -- No --> K[Reject event with period status error]
+    J -- Yes --> L[Validate GL account references via coa-management]
+    L --> M{All accounts valid and active?}
+    M -- No --> N[Reject event with account validation error]
+    M -- Yes --> O[Create journal entry with balanced debit/credit lines]
+    O --> P[Post journal entry]
+    P --> Q[Emit typed acknowledgment to upstream module]
+    Q --> R[Upstream module records GL posting confirmation]
+```
+
+Each subledger type maps to specific account structures and journal types:
+
+```mermaid
+flowchart LR
+    subgraph Purchase
+        P1[PurchaseBill validated] --> P2[Debit: Expense/Asset account]
+        P2 --> P3[Credit: Accounts Payable]
+        P3 --> P4[Journal Type: Purchase]
+    end
+
+    subgraph Sales
+        S1[SalesInvoice issued] --> S2[Debit: Accounts Receivable]
+        S2 --> S3[Credit: Revenue account]
+        S3 --> S4[Journal Type: Sales]
+    end
+
+    subgraph Inventory
+        I1[Valuation event emitted] --> I2[Debit/Credit: Inventory Asset]
+        I2 --> I3[Credit/Debit: COGS or Adjustment]
+        I3 --> I4[Journal Type: Miscellaneous]
+    end
+
+    subgraph Manufacturing
+        M1[Cost settlement emitted] --> M2[Debit: Finished Goods / Variance]
+        M2 --> M3[Credit: WIP account]
+        M3 --> M4[Journal Type: Miscellaneous]
+    end
+```
+
+## Scenario Patterns
+
+- **Purchase Bill Payable Recognition**: A purchase module validates and matches a vendor invoice (PurchaseBill) against a purchase order and goods receipt. Upon successful three-way match, it emits a handoff event containing the bill amount, expense or asset account reference, and the accounts payable GL account. The finance-ledger creates a journal entry debiting the expense/asset account and crediting accounts payable, then returns a `PurchaseBillPostingAcknowledgment` with the generated journal entry ID
+
+- **Sales Invoice Receivable Recognition**: The sales module issues a SalesInvoice to a customer. It emits a handoff event with the invoice total, accounts receivable GL account, and revenue account reference. The finance-ledger creates a journal entry debiting accounts receivable and crediting revenue, classified as a Sales journal type. The acknowledgment enables the sales module to mark the invoice as GL-posted
+
+- **Sales Credit Note Reversal**: A SalesCreditNote is issued for a returned product. The sales module emits a handoff event that mirrors the original invoice posting with reversed debits and credits — debit revenue, credit accounts receivable. The finance-ledger validates the net effect and posts the reversing entry, preserving the audit link to both the original invoice and the credit note
+
+- **Inventory Goods Receipt Valuation**: When inventory receives goods against a purchase order, the inventory module emits a valuation event with the received quantity, unit cost, inventory asset account, and goods receipt clearing account. The finance-ledger creates a journal entry debiting the inventory asset account and crediting the clearing account, capturing the cost basis of incoming stock
+
+- **Inventory Adjustment and Scrap**: A cycle count reveals a shortfall, and the inventory module emits an adjustment event. The finance-ledger debits an inventory loss/adjustment expense account and credits the inventory asset account. For scrap events, a similar pattern posts to a scrap expense account, ensuring that inventory shrinkage is properly reflected in the GL
+
+- **Manufacturing Cost Settlement**: At period end, the manufacturing module calculates actual production costs against standard costs and emits a cost settlement event containing WIP account references, finished goods account, and variance accounts (material price variance, labor efficiency variance, overhead variance). The finance-ledger debits finished goods and variance accounts, credits WIP, and returns a `ManufacturingCostSettlementAcknowledgment` so the manufacturing module can mark the production order as financially settled
+
+- **Duplicate Event Delivery (Idempotency)**: A network retry causes the purchase module to emit the same PurchaseBill handoff event twice. On the second receipt, the finance-ledger detects the duplicate via the source document reference, skips journal entry creation, and returns the original acknowledgment. No duplicate posting occurs
+
+- **Stale Period Status Rejection**: The sales module caches a period as OPEN but the period was closed by the controller between the cache read and the event emission. The finance-ledger's secondary period validation catches the mismatch and rejects the event with a period status error, prompting the sales module to defer the posting to the next open period
+
+- **Multi-Currency Subledger Posting**: A purchase bill denominated in EUR is handed off to the finance-ledger for a company whose base currency is USD. The handoff event includes the foreign currency amount, the transaction currency code, and the exchange rate. The finance-ledger creates journal lines in both the transaction currency and the base currency, applying the exchange rate conversion per the primitives module's rate lookup
+
+- **Cross-Subledger Period-End Verification**: During period-end close, the finance-ledger generates a subledger transfer completeness report checking that all expected handoff events from purchase, sales, inventory, and manufacturing for the closing period have been received and acknowledged. Outstanding items are flagged for the controller to investigate before closing the period
+
+## Test Cases
+
+- Purchase handoff event with valid PurchaseBill creates a journal entry with debit to expense/asset account and credit to accounts payable
+- Purchase handoff journal entry is classified as Purchase journal type
+- Purchase handoff acknowledgment includes the generated journal entry ID and posting timestamp
+- Sales handoff event with valid SalesInvoice creates a journal entry with debit to accounts receivable and credit to revenue account
+- Sales handoff journal entry is classified as Sales journal type
+- Sales credit note handoff creates a reversing journal entry with debit to revenue and credit to accounts receivable
+- Sales handoff acknowledgment includes the generated journal entry ID and posting timestamp
+- Inventory goods receipt handoff creates a journal entry with debit to inventory asset and credit to clearing account
+- Inventory adjustment handoff creates a journal entry with debit to adjustment expense and credit to inventory asset
+- Inventory scrap handoff creates a journal entry with debit to scrap expense and credit to inventory asset
+- Inventory handoff journal entries are classified as Miscellaneous journal type
+- Manufacturing cost settlement handoff creates journal entries debiting finished goods and variance accounts, crediting WIP
+- Manufacturing handoff returns a ManufacturingCostSettlementAcknowledgment with journal entry ID and settlement reference
+- Manufacturing variance entries separately record material price variance, labor efficiency variance, and overhead variance when applicable
+- All subledger-originated journal entries maintain balanced debits and credits (double-entry enforcement)
+- All subledger-originated journal entries carry a source document reference linking to the originating business transaction
+- Duplicate handoff events with the same source document reference are idempotent — no duplicate journal entries are created
+- Duplicate handoff events return the original acknowledgment without re-posting
+- Handoff events targeting an accounting period in OPEN status are accepted
+- Handoff events targeting an accounting period in FUTURE_ENTERABLE status are accepted (advance postings)
+- Handoff events targeting an accounting period in NEVER_OPENED status are rejected with a period status error
+- Handoff events targeting an accounting period in CLOSED status are rejected with a period status error
+- Handoff events targeting an accounting period in PERMANENTLY_CLOSED status are rejected with a period status error
+- Handoff events referencing an invalid or non-existent GL account are rejected with an account validation error
+- Handoff events referencing a GL account in DRAFT status (not yet active) are rejected with an account status error
+- Handoff events referencing a deactivated GL account with a successor mapping are redirected to the successor account
+- Multi-currency handoff events create journal lines in both transaction currency and base currency with correct exchange rate conversion
+- Handoff events with zero or negative amounts are rejected with a validation error
+- Each subledger handoff event processing emits an audit event via the audit module recording the source module, document reference, and journal entry created
+- Failed handoff processing emits an audit event recording the rejection reason and source document reference
+- Subledger transfer completeness check for a period reports all acknowledged and outstanding handoff events grouped by source module
+- Period-end close workflow blocks closing if outstanding unacknowledged subledger events exist for the target period
+- Handoff events are scoped to a company; events from one company cannot post to another company's GL accounts or periods
+
+## Reference Links
+
+- [Oracle Subledger Accounting (SLA) Overview](https://docs.oracle.com/en/cloud/saas/financials/24d/oafcf/subledger-accounting.html)
+- [SAP FI Integration with Subledgers (AP, AR, MM)](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/ee3509643e954b3da2e0ebfa846c02e1/4cbe15773ecd2a44e10000000a42189b.html)
+- [Oracle Fusion Create Subledger Journal Entries](https://docs.oracle.com/en/cloud/saas/financials/24d/oafcf/subledger-journal-entries.html)
+- [SAP Document Posting Architecture (FI-GL Integration)](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/ee3509643e954b3da2e0ebfa846c02e1/5dc0ef593e3d2944e10000000a42189b.html)
+- [Odoo Accounting Integration with Invoicing and Inventory](https://www.odoo.com/documentation/19.0/applications/finance/accounting/get_started/cheat_sheet.html)
+- [NetSuite Subledger to GL Posting](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N671498.html)

package/src/modules/finance-ledger/docs/features/trial-balance.md

@@ -0,0 +1,99 @@
+# Trial Balance
+
+## Overview
+
+The Trial Balance 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. The trial balance serves as the fundamental verification mechanism in double-entry bookkeeping: total debits across all accounts must equal total credits. Any imbalance indicates a posting error that must be resolved before financial statements can be generated. The report is scoped to a single company (via `companyId` from the organization module) and a single accounting period, and it derives its account structure from the active Chart of Accounts managed by coa-management.
+
+The trial balance supports two variants: **pre-close** and **post-close**. A pre-close trial balance is generated during or before the period-end close process, reflecting all standard and adjusting journal entries posted up to that point. A post-close trial balance is generated after all closing entries have been applied, verifying that temporary accounts (revenue, expense) have been zeroed out and their balances transferred to retained earnings. Both variants aggregate data from posted journal lines in the general ledger, grouping results by the account group hierarchy defined in coa-management. The trial balance is the foundational input for financial statement generation (income statement, balance sheet) and is a required artifact in every period-end close workflow.
+
+## Business Purpose
+
+Organizations rely on the trial balance as a core financial control and reporting mechanism:
+
+- **Debit-credit equilibrium verification**: The trial balance confirms that total debits equal total credits across all accounts, validating the integrity of double-entry bookkeeping for the period. Any discrepancy signals a posting error that must be investigated before proceeding with financial close
+- **Period-end close prerequisite**: Generating a balanced trial balance is a mandatory step in the period-end close workflow. Auditors and controllers use it to confirm that all journal entries for the period have been posted correctly before producing financial statements
+- **Pre-close visibility**: The pre-close trial balance gives accountants a working view of account balances before adjusting and closing entries are applied, enabling them to identify missing accruals, misclassifications, or unposted transactions
+- **Post-close validation**: The post-close trial balance verifies that all temporary accounts (revenue, expense, gains, losses) have been closed to retained earnings, ensuring only permanent accounts (assets, liabilities, equity) carry forward balances into the next period
+- **Account group aggregation**: Balances are organized according to the account group hierarchy from coa-management, providing subtotals at each level (e.g., Current Assets, Fixed Assets, Total Assets) that align with the company's reporting structure
+- **Financial statement foundation**: The trial balance provides the verified, balanced dataset from which the income statement, balance sheet, and other financial statements are generated. Without a balanced trial balance, downstream statement generation is blocked
+- **Multi-period comparison**: By generating trial balances for consecutive periods, organizations can perform trend analysis and variance detection, identifying unusual fluctuations in account balances that may require investigation
+- **Audit trail support**: Each generated trial balance is a timestamped snapshot, providing auditors with evidence of account balances at a specific point in time and supporting regulatory compliance requirements
+
+## Process Flow
+
+The following diagram shows the end-to-end workflow for generating a trial balance:
+
+```mermaid
+flowchart TD
+    A[Select company and accounting period] --> B[Determine trial balance variant]
+    B --> C{Pre-close or post-close?}
+    C -- Pre-close --> D[Retrieve all posted journal lines for the period]
+    C -- Post-close --> E[Retrieve all posted journal lines including closing entries]
+    D --> F[Fetch GL accounts from active CoA via coa-management]
+    E --> F
+    F --> G[Calculate opening balance per account from prior period closing balances]
+    G --> H[Aggregate period debits and credits per account from journal lines]
+    H --> I[Compute closing balance per account: opening + debits - credits]
+    I --> J{Total debits == total credits?}
+    J -- Yes --> K[Group balances by account group hierarchy]
+    K --> L[Generate trial balance snapshot with timestamp]
+    L --> M[Trial balance available for financial statement generation]
+    J -- No --> N[Report imbalance error with discrepancy amount]
+    N --> O[Investigate and correct journal entries]
+    O --> D
+```
+
+The following state diagram shows the lifecycle of a trial balance snapshot:
+
+```mermaid
+stateDiagram-v2
+    [*] --> Generating: generateTrialBalance
+    Generating --> Balanced: debit-credit totals match
+    Generating --> Imbalanced: debit-credit totals do not match
+    Balanced --> [*]: snapshot stored
+    Imbalanced --> [*]: error reported
+```
+
+## Scenario Patterns
+
+- **Standard Month-End Pre-Close**: An accountant generates a pre-close trial balance at the end of January to review all account balances before adjusting entries. The report reveals that total debits equal total credits, confirming posting integrity. The accountant identifies a missing accrual by reviewing individual account balances and posts an adjusting entry before regenerating the trial balance
+- **Post-Close Verification After Period End**: After all closing entries have been posted for Q4, the controller generates a post-close trial balance. Revenue and expense accounts show zero balances, confirming that income summary entries correctly transferred net income to retained earnings. Only balance sheet accounts carry forward into the new fiscal year
+- **Imbalance Detection and Resolution**: A trial balance generated mid-period reveals a 500 USD discrepancy between total debits and total credits. The accounting team traces the imbalance to a one-sided journal entry that was incorrectly posted. After correcting the entry, a regenerated trial balance confirms equilibrium
+- **Multi-Entity Consolidated Review**: A parent company generates trial balances for each of its three subsidiaries for the same period. Each trial balance is scoped to its respective company and CoA. The finance team uses the individual trial balances as inputs for intercompany elimination and consolidated financial statement preparation
+- **Year-End Audit Preparation**: External auditors request pre-close and post-close trial balances for all twelve months of the fiscal year. The accounting team generates each snapshot, providing auditors with a complete trail of account balances throughout the year, organized by the company's account group hierarchy
+- **New Account Verification**: After adding a new GL account for a recently launched product line, the accountant generates a trial balance to confirm that postings to the new account are correctly reflected and that overall debit-credit equilibrium is maintained
+- **Account Group Subtotal Analysis**: A CFO reviews the trial balance grouped by account hierarchy to analyze subtotals at the department level (e.g., Sales Expenses, R&D Expenses). The grouping follows the account group hierarchy defined in coa-management, enabling drill-down from summary to detail
+
+## Test Cases
+
+- 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)
+- Generating a trial balance when total debits do not equal total credits produces an imbalance error with the discrepancy amount
+- Pre-close trial balance excludes closing entries (entries that zero out temporary accounts)
+- Post-close trial balance includes all closing entries and shows zero balances for all temporary accounts (revenue, expense)
+- Post-close trial balance shows non-zero balances only for permanent accounts (assets, liabilities, equity)
+- Trial balance is scoped to a single company; accounts from other companies are never included
+- Trial balance respects the account group hierarchy from coa-management, providing subtotals at each group level
+- Only posted journal entries are included; draft or voided journal entries are excluded from aggregation
+- Trial balance snapshot includes a generation timestamp recording when the report was produced
+- Trial balance snapshot records the variant type (pre-close or post-close)
+- 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
+- Trial balance correctly handles accounts with only debit postings (no credits) and vice versa
+- Trial balance generation emits an audit event recording the acting user, company, period, variant, and timestamp
+- Regenerating a trial balance for the same period and variant produces an updated snapshot reflecting any new postings since the last generation
+- Trial balance accounts are ordered by account code in ascending order within each account group
+
+## Reference Links
+
+- [SAP Trial Balance Report](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/ee3509643e954b3da2e0ebfa846c02e1/4006d63d7e167014e10000000a42189c.html)
+- [Oracle Fusion Trial Balance](https://docs.oracle.com/en/cloud/saas/financials/24d/oafcf/trial-balance.html)
+- [NetSuite Trial Balance Report](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N1584498.html)
+- [Odoo Trial Balance and Financial Reports](https://www.odoo.com/documentation/19.0/applications/finance/accounting/reporting.html)
+- [QuickBooks Trial Balance Overview](https://quickbooks.intuit.com/learn-support/en-us/help-article/report-management/trial-balance-report/L0t0FuAGH_US_en_US)

package/src/modules/finance-ledger/docs/features/year-end-close.md

@@ -0,0 +1,84 @@
+# Year End Close
+
+## Overview
+
+Year-end close is the fiscal year-end extension of the standard period-end close process. It runs exclusively on the final period of a fiscal year, after that period's standard close checklist has been completed. The process generates an automatic closing journal entry that zeroes out all temporary accounts (revenue and expense) and transfers the net income or net loss to the retained earnings account defined in the active Chart of Accounts. This closing entry follows the explicit closing entry model used by Oracle, SAP, and NetSuite, where closing entries are posted as distinct, auditable journal entries rather than computed in real-time.
+
+After the closing entry is posted, the year-end close generates opening balance entries for the first period of the new fiscal year. These opening balances carry forward all permanent account balances (assets, liabilities, equity — including the updated retained earnings) so that the new fiscal year starts with a complete balance sheet. The year-end close is a prerequisite for the new fiscal year's accounting periods to begin accepting operational postings, ensuring continuity between fiscal years. The entire process is auditable, with each step recorded via the audit module.
+
+## Business Purpose
+
+- **Retained earnings accuracy**: Closing temporary accounts to retained earnings ensures the balance sheet correctly reflects cumulative equity at fiscal year-end, which is required by GAAP, IFRS, and virtually all accounting standards
+- **Clean start for new fiscal year**: Opening balance entries provide a complete starting point for the new fiscal year without requiring the system to recompute balances from historical transactions across all prior years
+- **Explicit and auditable closing entries**: Posting closing entries as distinct journal entries (rather than virtual real-time computation) creates a clear, immutable audit trail that external auditors can verify independently
+- **Temporary vs. permanent account distinction**: The year-end process enforces the fundamental accounting distinction between temporary accounts (revenue, expense — reset to zero each year) and permanent accounts (assets, liabilities, equity — carried forward indefinitely)
+- **Fiscal year continuity**: Opening balance generation ensures that the accounting equation (Assets = Liabilities + Equity) holds at the start of the new fiscal year, preventing orphaned or imbalanced periods
+- **Compliance with reporting standards**: IAS 1 and US GAAP require that financial statements present a complete picture of financial position, including retained earnings that reflect all prior-year results. The year-end close produces the entries that make this possible
+- **Sequential dependency enforcement**: By requiring year-end close to run only on the final period of a fiscal year and only after its standard close is complete, the system prevents premature closing that could miss late-arriving transactions
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Final period standard close completed] --> B{Is this the final period of the fiscal year?}
+    B -- No --> C[Standard permanent close - no year-end steps needed]
+    B -- Yes --> D[Initiate year-end close]
+    D --> E[Identify all temporary accounts: REVENUE and EXPENSE types]
+    E --> F[Calculate net income/loss: total revenue minus total expenses]
+    F --> G[Look up retained earnings account from CoA configuration]
+    G --> H{Retained earnings account configured?}
+    H -- No --> I[Reject: retained earnings account required]
+    H -- Yes --> J[Generate closing journal entry]
+    J --> K[Debit all revenue accounts to zero]
+    K --> L[Credit all expense accounts to zero]
+    L --> M[Post net difference to retained earnings account]
+    M --> N[Verify closing entry is balanced]
+    N --> O[Generate opening balance entries for new fiscal year]
+    O --> P[Post opening balances to first period of new fiscal year]
+    P --> Q[Year-end close complete - permanently close final period]
+```
+
+## Scenario Patterns
+
+- **Standard Year-End Close**: After closing December (the 12th and final period), the system generates a closing entry that debits all revenue accounts and credits all expense accounts, posting the net income to retained earnings. Opening balance entries are generated for January of the new fiscal year carrying forward all asset, liability, and equity balances
+- **Year-End Close with Net Loss**: The company reports a net loss for the fiscal year. The closing entry credits all revenue accounts and debits all expense accounts, with the net loss debited to retained earnings, reducing cumulative equity. Opening balances reflect the reduced retained earnings
+- **Non-Calendar Fiscal Year Close**: A company with an April-to-March fiscal year runs year-end close on the March period. The process is identical to a calendar year-end but triggers on the March period as the final period of the fiscal year
+- **13-Period Fiscal Year Close**: A company using a 13-period fiscal calendar runs year-end close on period 13. The closing entry covers all 13 periods of revenue and expense activity
+- **Multi-Entity Year-End Close**: A parent company coordinates year-end close across three subsidiaries. Each subsidiary runs its own year-end close independently, generating entity-specific closing entries and opening balances. The parent company's consolidation process consumes the resulting opening balances
+- **Missing Retained Earnings Account**: The accounting team attempts year-end close but the active Chart of Accounts does not have an account with RETAINED_EARNINGS operational classification. The process is rejected with a clear error, requiring CoA configuration before year-end close can proceed
+- **Year-End Close with Prior Adjustments**: An auditor posts a final adjustment during the soft-lock phase of the final period. The year-end close incorporates this adjustment into the closing entry calculation, ensuring the retained earnings transfer reflects all final adjustments
+
+## Test Cases
+
+- Year-end close can only be initiated for the final period of a fiscal year
+- Initiating year-end close for a non-final period is rejected with an invalid period error
+- Year-end close requires the final period's standard close checklist to be completed through the soft-lock or permanent close stage
+- Year-end close generates a closing journal entry that debits all REVENUE-type accounts to zero
+- Year-end close generates a closing journal entry that credits all EXPENSE-type accounts to zero
+- The net difference (net income or net loss) is posted to the retained earnings account
+- Year-end close fails if no account with RETAINED_EARNINGS operational classification exists in the active CoA
+- The closing journal entry is balanced (total debits equal total credits)
+- The closing journal entry is flagged with a distinct journal type (e.g., CLOSING) for identification
+- The closing journal entry is posted to the final period of the fiscal year
+- Only accounts with posted journal lines during the fiscal year are included in the closing entry (zero-balance temporary accounts are excluded)
+- Opening balance entries are generated for all permanent accounts (ASSET, LIABILITY, EQUITY types)
+- Opening balance entries are posted to the first period of the new fiscal year
+- Opening balance entries carry the correct closing balance from each permanent account, including the updated retained earnings
+- Opening balance entries are flagged with a distinct journal type (e.g., OPENING) for identification
+- The sum of all opening balance debits equals the sum of all opening balance credits (accounting equation maintained)
+- Year-end close cannot be run twice for the same fiscal year; duplicate attempts are rejected
+- Year-end close emits audit events recording each step: closing entry generation, retained earnings posting, opening balance generation
+- The closing entry references the fiscal year and the retained earnings account in its metadata for traceability
+- Opening balances for the new fiscal year are only generated if the new fiscal year's periods exist
+- Year-end close fails gracefully if the new fiscal year has not been defined, with a clear error message
+- After year-end close, the final period of the old fiscal year is permanently closed
+- After year-end close, the first period of the new fiscal year contains opening balance entries and is ready for operational postings
+- Year-end close is scoped to a single company; each company runs year-end close independently
+
+## Reference Links
+
+- [Oracle Fusion Year-End Close Process](https://docs.oracle.com/en/cloud/saas/financials/24d/oafcf/general-ledger-close.html)
+- [SAP S/4HANA Year-End Closing](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/ee3509643e954b3da2e0ebfa846c02e1/4588dcd34eab6e37e10000000a42189b.html)
+- [NetSuite Year-End Tasks](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_1531269686.html)
+- [Odoo Fiscal Year Closing](https://www.odoo.com/documentation/19.0/applications/finance/accounting/get_started/cheat_sheet.html)
+- [IFRS IAS 1 Presentation of Financial Statements](https://www.ifrs.org/issued-standards/list-of-standards/ias-1-presentation-of-financial-statements/)

package/src/modules/finance-ledger/docs/models/AccountingPeriod.md

@@ -0,0 +1,71 @@
+# AccountingPeriod
+
+## Description
+
+AccountingPeriod represents a discrete time segment (typically a month, quarter, or custom interval) within a fiscal year, scoped to a single company via companyId. Each period carries a start date, end date, period name, period type (OPERATING or ADJUSTMENT), and a five-state status that governs whether journal entries can be posted. The five-state lifecycle (NEVER_OPENED, FUTURE_ENTERABLE, OPEN, CLOSED, PERMANENTLY_CLOSED) mirrors the industry-standard model used by Oracle Financials and provides granular control over when and how transactions flow into each period. Accounting periods are the temporal backbone of the general ledger — every journal entry must reference a valid period, and the period's current status determines whether that posting is accepted or rejected.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> NeverOpened: createAccountingPeriod
+    NeverOpened --> FutureEnterable: openForAdvanceEntry
+    NeverOpened --> Open: openPeriod
+    FutureEnterable --> Open: openPeriod
+    Open --> Closed: closePeriod
+    Closed --> Open: reopenPeriod
+    Closed --> PermanentlyClosed: permanentlyClosePeriod
+    PermanentlyClosed --> [*]
+```
+
+### Command Definitions
+
+- [createAccountingPeriod](../commands/CreateAccountingPeriod.md) - Create a new accounting period in NEVER_OPENED status within a fiscal year
+- [openForAdvanceEntry](../commands/OpenForAdvanceEntry.md) - Transition a NEVER_OPENED period to FUTURE_ENTERABLE to allow advance postings
+- [openPeriod](../commands/OpenPeriod.md) - Transition a NEVER_OPENED or FUTURE_ENTERABLE period to OPEN
+- [closePeriod](../commands/ClosePeriod.md) - Transition an OPEN period to CLOSED
+- [reopenPeriod](../commands/ReopenPeriod.md) - Transition a CLOSED period back to OPEN for adjustments
+- [permanentlyClosePeriod](../commands/PermanentlyClosePeriod.md) - Transition a CLOSED period to PERMANENTLY_CLOSED (irreversible)
+- [deleteAccountingPeriod](../commands/DeleteAccountingPeriod.md) - Delete an accounting period with no associated journal entries
+
+### Query Definitions
+
+- [GetAccountingPeriod](../queries/GetAccountingPeriod.md) - Retrieve an accounting period by id
+- [ListAccountingPeriods](../queries/ListAccountingPeriods.md) - List accounting periods for a fiscal year or company with optional status filter
+- [GetPeriodByDate](../queries/GetPeriodByDate.md) - Find the accounting period for a given date and company
+
+### Models
+
+- AccountingPeriod
+
+### Invariants
+
+- Accounting periods can only be created in NEVER_OPENED status
+- Period name is required and must be non-empty
+- Period must have a valid start date and end date, with start date strictly before end date
+- Period must reference a valid companyId from the organization module
+- Period must belong to a fiscal year that is scoped to the same company
+- Periods within the same fiscal year must not have overlapping date ranges
+- Periods within the same fiscal year must cover the full fiscal year date range without gaps
+- Two periods in the same fiscal year cannot have identical start and end dates unless one is an adjustment period
+- Period type must be OPERATING or ADJUSTMENT
+- Adjustment periods share the same end date as the final regular period but are typed as ADJUSTMENT
+- A PERMANENTLY_CLOSED period cannot transition to any other status (irreversible)
+- An OPEN period cannot transition directly to PERMANENTLY_CLOSED (must go through CLOSED first)
+- A NEVER_OPENED period cannot transition directly to CLOSED
+- A period cannot be deleted if it has any associated journal entries regardless of status
+- Journal entries can only be posted to periods in OPEN or FUTURE_ENTERABLE status
+- All period status transitions emit audit events via the audit module recording the acting user, timestamp, and previous and new status values
+
+### Relationships
+
+- **References Company**: Each accounting period is scoped to a Company via companyId (organization module)
+- **References FiscalYear**: Each accounting period belongs to a FiscalYear via fiscalYearId
+- **Has Many JournalEntry**: An accounting period may have journal entries posted to it
+- **Has One PeriodClose**: An accounting period may have at most one active PeriodClose record

package/src/modules/finance-ledger/docs/models/FinancialStatement.md

@@ -0,0 +1,76 @@
+# FinancialStatement
+
+## Description
+
+FinancialStatement represents a generated financial report — Balance Sheet (statement of financial position), Profit & Loss (income statement), or Cash Flow Statement. Each statement is scoped to a single company, denominated in the company's base currency, and structured according to the account group hierarchy defined in coa-management. A statement is created in DRAFT status from trial balance data and can be regenerated (replaced) until finalized. Once FINALIZED, the statement is immutable. The statement contains FinancialStatementLineItem records organized by account group sections with subtotals and totals.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: generateFinancialStatement
+    Draft --> Draft: regenerateFinancialStatement
+    Draft --> Finalized: finalizeFinancialStatement
+    Finalized --> [*]
+```
+
+### Command Definitions
+
+- [generateFinancialStatement](../commands/GenerateFinancialStatement.md) - Generate a financial statement from trial balance data in DRAFT status
+- [regenerateFinancialStatement](../commands/RegenerateFinancialStatement.md) - Regenerate a DRAFT statement with updated trial balance data
+- [finalizeFinancialStatement](../commands/FinalizeFinancialStatement.md) - Finalize a DRAFT statement, making it immutable
+
+### Query Definitions
+
+- [GetFinancialStatement](../queries/GetFinancialStatement.md) - Retrieve a financial statement by id with all line items
+- [ListFinancialStatements](../queries/ListFinancialStatements.md) - List financial statements for a company with optional filters
+
+### Models
+
+- FinancialStatement
+- FinancialStatementLineItem
+
+### Invariants
+
+- FinancialStatement requires a valid companyId referencing an ACTIVE company
+- FinancialStatement requires a valid chartOfAccountsId referencing an ACTIVE CoA
+- Statement type must be one of: BALANCE_SHEET, PROFIT_AND_LOSS, CASH_FLOW
+- Balance Sheet generation requires a single reporting date (as-of date)
+- Profit & Loss generation requires a date range (start date and end date)
+- Cash Flow Statement generation requires a date range and a method (DIRECT or INDIRECT)
+- The reporting date or date range must fall within a closed or active accounting period
+- A Balance Sheet includes only accounts of type ASSET, LIABILITY, and EQUITY
+- A Profit & Loss includes only accounts of type REVENUE and EXPENSE
+- A Cash Flow Statement derives from ledger data covering all account types relevant to cash movements
+- On a correctly generated Balance Sheet, total assets equal total liabilities plus total equity
+- Statement line items are structured according to the account group hierarchy from coa-management
+- Comparative period data, when requested, is aligned to the same account group sections as the current period
+- If comparative period trial balance data is unavailable, generation fails with a descriptive error
+- FinancialStatement is created in DRAFT status
+- A DRAFT statement can be regenerated with updated trial balance data
+- A FINALIZED statement is immutable — its line items, parameters, and output cannot be modified
+- Finalizing an already FINALIZED statement fails
+- All monetary amounts are denominated in the company's base currency
+- Accounts not assigned to any account group are reported in an "Unclassified" section and flagged as warnings
+- Statement output includes subtotals at each level of the account group hierarchy
+- Generating a statement for a period with no posted journal entries fails with a validation error
+- Statement generation for a company with no trial balance data for the requested period returns a validation error
+- Cash Flow Statement (indirect method) starts with net income and adjusts for non-cash items and working capital changes
+- Cash Flow Statement reconciles to the net change between opening and closing cash balances
+- Each statement records a reference to the trial balance snapshot it was generated from
+- Statement generation emits an audit event via the audit module recording the acting user, timestamp, statement type, and parameters
+- Finalizing a statement emits an audit event recording the status transition from DRAFT to FINALIZED
+
+### Relationships
+
+- **References Company**: Each statement is scoped to a Company via companyId (organization module)
+- **References ChartOfAccounts**: Each statement references a ChartOfAccounts via chartOfAccountsId (coa-management module)
+- **References TrialBalance**: Each statement references the TrialBalance it was generated from via trialBalanceId
+- **References TrialBalance (comparative)**: Optionally references a prior period TrialBalance via comparativePeriodTrialBalanceId
+- **Has Many FinancialStatementLineItem**: A statement contains line items organized by sections

package/src/modules/finance-ledger/docs/models/FinancialStatementLineItem.md

@@ -0,0 +1,41 @@
+# FinancialStatementLineItem
+
+## Description
+
+FinancialStatementLineItem represents a single row in a generated FinancialStatement. Each line item carries a label, current period amount, optional comparative period amount, line type (DETAIL for individual accounts, SUBTOTAL for group aggregations, TOTAL for section totals), section type indicating where it appears in the statement, sort order for display, and optional references to the account or account group it represents. Line items are created during financial statement generation and are immutable once the parent statement is finalized.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [generateFinancialStatement](../commands/GenerateFinancialStatement.md) - Line items are created as part of financial statement generation
+
+### Query Definitions
+
+- [GetFinancialStatement](../queries/GetFinancialStatement.md) - Line items are returned as part of the parent financial statement
+
+### Models
+
+- FinancialStatementLineItem
+
+### Invariants
+
+- Each line item must belong to a valid FinancialStatement
+- Line type must be one of DETAIL, SUBTOTAL, or TOTAL
+- Section type is required and indicates the report section (e.g., Current Assets, Non-Current Liabilities, Revenue, Operating Expenses) where the line item appears
+- Label is required and must be non-empty
+- Amount is required and denominated in the company's base currency
+- Comparative amount is present only when comparative period data was requested
+- Sort order determines display positioning within the statement
+- Accounts not assigned to any account group are reported in an "Unclassified" section
+- Line items are immutable once the parent FinancialStatement is FINALIZED
+
+### Relationships
+
+- **References FinancialStatement**: Each line item belongs to a FinancialStatement via financialStatementId
+- **References AccountGroup**: Optionally references an AccountGroup via accountGroupId (coa-management module)
+- **References Account**: Optionally references an Account via accountId for DETAIL line items (coa-management module)

package/src/modules/finance-ledger/docs/models/FiscalYear.md

@@ -0,0 +1,41 @@
+# FiscalYear
+
+## Description
+
+FiscalYear represents a logical grouping of accounting periods scoped to a single company. Each fiscal year carries a name, start date, and end date, and may follow a calendar year (January–December) or a non-calendar cycle (e.g., April–March, 4-4-5 week structures). A fiscal year contains one or more AccountingPeriod records that collectively span its full date range. The fiscal year is the outermost temporal boundary for period management, trial balance generation, and year-end close processes.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createFiscalYear](../commands/CreateFiscalYear.md) - Create a new fiscal year for a company with name, start/end dates
+- [updateFiscalYear](../commands/UpdateFiscalYear.md) - Update mutable fields of an existing fiscal year (name only; dates immutable after periods exist)
+- [deleteFiscalYear](../commands/DeleteFiscalYear.md) - Delete a fiscal year with no associated accounting periods
+
+### Query Definitions
+
+- [GetFiscalYear](../queries/GetFiscalYear.md) - Retrieve a fiscal year by id
+- [ListFiscalYears](../queries/ListFiscalYears.md) - List fiscal years for a company with optional filters
+
+### Models
+
+- FiscalYear
+
+### Invariants
+
+- Fiscal year must reference a valid companyId from the organization module
+- Fiscal year name is required and must be non-empty
+- Fiscal year must have a valid start date and end date, with start date strictly before end date
+- Fiscal years within the same company must not have overlapping date ranges
+- Fiscal year start and end dates are immutable after accounting periods have been created
+- A fiscal year cannot be deleted if it has any associated accounting periods
+- Year-end close can only be run once per fiscal year; duplicate attempts are rejected
+
+### Relationships
+
+- **References Company**: Each fiscal year belongs to a Company via companyId (organization module)
+- **Has Many AccountingPeriod**: A fiscal year contains one or more accounting periods