@tailor-platform/erp-kit 0.5.1 → 0.7.0

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

@@ -0,0 +1,80 @@
+# JournalEntry
+
+## Description
+
+JournalEntry is the core transactional entity of the finance-ledger module, implementing double-entry bookkeeping for all financial postings. A journal entry consists of a header record carrying the entry date, journal type, reference number, status, posting period, description, and optional source document reference, along with one or more JournalLine records. Every journal entry must satisfy the fundamental accounting constraint: total debits must equal total credits in the functional currency before it can be posted. Journal entries follow a lifecycle of DRAFT to POSTED, with posted entries eligible for reversal via a mirror entry that produces a REVERSED status on the original. The feature supports nine journal types (Sales, Purchase, Cash, Bank, Miscellaneous, Opening, Closing, Inventory, Manufacturing) to categorize entries by their business origin.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createJournalEntry
+    Draft --> Draft: updateJournalEntry / addJournalLine / updateJournalLine / removeJournalLine
+    Draft --> Posted: postJournalEntry
+    Posted --> Reversed: reverseJournalEntry
+    Draft --> [*]: deleteJournalEntry
+```
+
+### Command Definitions
+
+- [createJournalEntry](../commands/CreateJournalEntry.md) - Create a new journal entry in DRAFT status
+- [updateJournalEntry](../commands/UpdateJournalEntry.md) - Update mutable fields of a DRAFT journal entry
+- [deleteJournalEntry](../commands/DeleteJournalEntry.md) - Delete a DRAFT journal entry and all associated lines
+- [addJournalLine](../commands/AddJournalLine.md) - Add a journal line to a DRAFT journal entry
+- [updateJournalLine](../commands/UpdateJournalLine.md) - Update a journal line on a DRAFT journal entry
+- [removeJournalLine](../commands/RemoveJournalLine.md) - Remove a journal line from a DRAFT journal entry
+- [postJournalEntry](../commands/PostJournalEntry.md) - Post a balanced DRAFT journal entry to the general ledger
+- [reverseJournalEntry](../commands/ReverseJournalEntry.md) - Reverse a posted journal entry via a mirror entry
+- [processPurchaseHandoff](../commands/ProcessPurchaseHandoff.md) - Process a purchase subledger handoff event into a journal entry
+- [processSalesHandoff](../commands/ProcessSalesHandoff.md) - Process a sales subledger handoff event into a journal entry
+- [processInventoryHandoff](../commands/ProcessInventoryHandoff.md) - Process an inventory subledger handoff event into a journal entry
+- [processManufacturingHandoff](../commands/ProcessManufacturingHandoff.md) - Process a manufacturing subledger handoff event into a journal entry
+
+### Query Definitions
+
+- [GetJournalEntry](../queries/GetJournalEntry.md) - Retrieve a journal entry by id with all lines
+- [ListJournalEntries](../queries/ListJournalEntries.md) - List journal entries with filters (period, type, status, date range)
+
+### Models
+
+- JournalEntry
+- JournalLine
+
+### Invariants
+
+- Journal entries can only be created in DRAFT status
+- Journal entry requires a valid journal type (SALES, PURCHASE, CASH, BANK, MISCELLANEOUS, OPENING, CLOSING, INVENTORY, MANUFACTURING)
+- Journal entry requires a valid entry date
+- Journal entry requires a reference number that is unique within the company scope
+- Journal entry must reference a valid companyId; the company must be in ACTIVE status
+- Journal entry must reference a valid accounting period; the period must be in OPEN or FUTURE_ENTERABLE status for posting
+- Journal entry description is optional and can be updated while in DRAFT status
+- Source document reference is optional and can be set on creation or update in DRAFT status
+- A journal entry must have at least two journal lines before it can be posted
+- Total debits must equal total credits in the functional currency for posting to succeed
+- Posted journal entries cannot be modified (no field updates, no line additions or removals)
+- Posted journal entries cannot be deleted; only reversal is permitted
+- DRAFT journal entries can be deleted; deletion removes all associated journal lines
+- Reversing a posted entry creates a new journal entry with all debit/credit amounts inverted
+- The reversal entry references the original entry and is automatically posted
+- The original entry status transitions from POSTED to REVERSED upon successful reversal
+- Reversing an entry that is already REVERSED fails
+- The reversal entry must target a period that is in OPEN or FUTURE_ENTERABLE status
+- Journal type and entry date cannot be changed after the entry is posted
+- Adjusting entries created during period-end close must have a valid adjustingEntryType (ACCRUAL, DEFERRAL, or RECLASSIFICATION)
+- Posting a journal entry to a CLOSED, PERMANENTLY_CLOSED, or NEVER_OPENED period is rejected
+- Balance validation for multi-currency entries is performed on the functional currency amounts, not the foreign currency amounts
+- All journal entry lifecycle operations emit audit events via the audit module recording the acting user, timestamp, and field-level details
+
+### Relationships
+
+- **References Company**: Each journal entry is scoped to a Company via companyId (organization module)
+- **References AccountingPeriod**: Each journal entry references an AccountingPeriod via accountingPeriodId
+- **Has Many JournalLine**: A journal entry contains one or more journal lines
+- **References JournalEntry (reversal)**: A reversal entry references the original via reversalOfId

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

@@ -0,0 +1,47 @@
+# JournalLine
+
+## Description
+
+JournalLine represents a single debit or credit entry within a JournalEntry. Each line references a GL account from the coa-management module, specifies either a debit or credit amount (mutually exclusive), includes an optional line-level description, and optionally includes foreign currency details (currency code, exchange rate) with computed functional currency amounts. Journal lines are the atomic units of double-entry bookkeeping — they are always created, modified, and deleted in the context of their parent journal entry's lifecycle. Lines on a POSTED or REVERSED journal entry are immutable.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [addJournalLine](../commands/AddJournalLine.md) - Add a journal line to a DRAFT journal entry
+- [updateJournalLine](../commands/UpdateJournalLine.md) - Update a journal line on a DRAFT journal entry
+- [removeJournalLine](../commands/RemoveJournalLine.md) - Remove a journal line from a DRAFT journal entry
+
+### Query Definitions
+
+- [GetJournalEntry](../queries/GetJournalEntry.md) - Journal lines are returned as part of the parent journal entry
+
+### Models
+
+- JournalLine
+
+### Invariants
+
+- Each journal line must reference a valid GL account from an ACTIVE Chart of Accounts
+- Each journal line must specify either a debit amount or a credit amount (not both, and not zero for both)
+- Debit and credit amounts must be positive values
+- Multi-currency journal lines must specify a currency code and exchange rate
+- The functional currency amount is computed as the foreign amount multiplied by the exchange rate
+- Journal lines without an explicit currency default to the company's functional (base) currency with an exchange rate of 1.0
+- Journal lines referencing an inactive or draft GL account are rejected at posting time
+- Journal lines referencing a deprecated GL account with a successor mapping are redirected to the successor account at posting time
+- If the successor account is itself inactive or deprecated without a further successor, the posting is rejected
+- Journal lines can only be added to, updated on, or removed from a DRAFT journal entry
+- Balance validation for multi-currency entries is performed on the functional currency amounts, not the foreign currency amounts
+- Line-level description is optional and can be updated while the parent journal entry is in DRAFT status
+- RECEIVABLE and PAYABLE classified accounts block direct manual journal postings (control account constraint)
+
+### Relationships
+
+- **References JournalEntry**: Each journal line belongs to a JournalEntry via journalEntryId
+- **References Account**: Each journal line references a GL Account via accountId (coa-management module)
+- **References Currency**: Each journal line optionally references a Currency via currencyCode for multi-currency postings (primitives module)

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

@@ -0,0 +1,83 @@
+# PeriodClose
+
+## Description
+
+PeriodClose is a checklist-driven workflow entity that tracks the process of transitioning an accounting period from open to permanently closed. Each close operation is scoped to a single AccountingPeriod and follows a deterministic sequence of steps: initiation, subledger transfer verification, adjusting entry posting, trial balance verification, preliminary statement generation, review and approval, soft lock, and final permanent close. The entity records the initiating user, completion percentage, and current status. For the final period of a fiscal year, the close process extends to include year-end close steps (closing temporary accounts to retained earnings and generating opening balances for the new fiscal year).
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> NotStarted: initiatePeriodClose
+    NotStarted --> InProgress: beginClose
+    InProgress --> SubledgersVerified: verifySubledgerTransfers
+    SubledgersVerified --> AdjustmentsPosted: postAdjustingEntries
+    AdjustmentsPosted --> TrialBalanceVerified: verifyTrialBalance
+    TrialBalanceVerified --> UnderReview: generatePreliminaryStatements
+    UnderReview --> SoftLocked: approveAndLockPeriod
+    SoftLocked --> InProgress: revertSoftLock
+    SoftLocked --> PermanentlyClosed: finalCloseAndLockPeriod
+    PermanentlyClosed --> [*]
+```
+
+### Command Definitions
+
+- [initiatePeriodClose](../commands/InitiatePeriodClose.md) - Initiate the period close process for an accounting period
+- [beginClose](../commands/BeginClose.md) - Begin the close checklist, transitioning from NOT_STARTED to IN_PROGRESS
+- [verifySubledgerTransfers](../commands/VerifySubledgerTransfers.md) - Verify all subledger modules have transferred transactions to GL
+- [postAdjustingEntries](../commands/PostAdjustingEntries.md) - Confirm adjusting entries (accruals, deferrals, reclassifications) are posted
+- [verifyTrialBalance](../commands/VerifyTrialBalance.md) - Verify the period's trial balance is balanced
+- [generatePreliminaryStatements](../commands/GeneratePreliminaryStatements.md) - Generate preliminary financial statements for review
+- [approveAndLockPeriod](../commands/ApproveAndLockPeriod.md) - Approve and soft-lock the period
+- [revertSoftLock](../commands/RevertSoftLock.md) - Revert a soft-locked period back to IN_PROGRESS
+- [finalCloseAndLockPeriod](../commands/FinalCloseAndLockPeriod.md) - Permanently close the period (irreversible)
+- [executeYearEndClose](../commands/ExecuteYearEndClose.md) - Execute year-end close: close temporary accounts to retained earnings and generate opening balances
+
+### Query Definitions
+
+- [GetPeriodClose](../queries/GetPeriodClose.md) - Retrieve the period close record for an accounting period
+- [ListPeriodCloses](../queries/ListPeriodCloses.md) - List period close records for a fiscal year or company with optional status filter
+- [GetSubledgerTransferStatus](../queries/GetSubledgerTransferStatus.md) - Retrieve subledger transfer completeness status for an accounting period
+
+### Models
+
+- PeriodClose
+
+### Invariants
+
+- PeriodClose can only be initiated for an AccountingPeriod that is in OPEN status
+- PeriodClose cannot be initiated for a period that already has an active close in progress
+- PeriodClose lifecycle follows NOT_STARTED → IN_PROGRESS → SUBLEDGERS_VERIFIED → ADJUSTMENTS_POSTED → TRIAL_BALANCE_VERIFIED → UNDER_REVIEW → SOFT_LOCKED → PERMANENTLY_CLOSED
+- PeriodClose cannot skip steps; each transition requires the previous step to be completed
+- Subledger verification fails if any registered subledger module has pending unposted transactions for the period
+- Trial balance verification fails if the period's trial balance has a non-zero difference between total debits and credits
+- Approval step requires a user with the appropriate authorization role (controller or finance manager)
+- Soft-locking prevents the accounting team from posting new journal entries to the period
+- Soft-locked period still allows postings from users with the advisor/auditor role
+- Permanently closing a period makes it fully immutable; no further journal entries can be posted regardless of role
+- Reverting a soft-locked period to IN_PROGRESS is permitted only before permanent close
+- Reverting a permanently closed period is not permitted
+- Each period has at most one active PeriodClose record
+- Concurrent close attempts for the same period are rejected with a conflict error
+- Year-end close can only be initiated for the final period of a fiscal year
+- Year-end close requires the standard close checklist to be completed through the soft-lock stage
+- Year-end close generates a closing journal entry zeroing temporary accounts to retained earnings
+- Year-end close generates opening balance entries for the first period of the new fiscal year
+- Year-end close fails if no retained earnings account exists in the active CoA
+- Year-end close cannot be run twice for the same fiscal year
+- PeriodClose tracks a completionPercentage that increments as each checklist step is completed
+- PeriodClose records the userId of the operator who initiated the close and the userId who completed each checklist step
+- Each state transition emits an audit event recording the acting user, timestamp, previous status, and new status
+
+### Relationships
+
+- **References AccountingPeriod**: Each PeriodClose is linked to an AccountingPeriod via accountingPeriodId
+- **References FiscalYear**: The associated AccountingPeriod's fiscal year determines year-end close eligibility (via AccountingPeriod.fiscalYearId)
+- **References User**: Records the initiating user via initiatedByUserId (user-management module)
+- **References Account (retained earnings)**: Year-end close references the retained earnings account from the active CoA for closing temporary accounts

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

@@ -0,0 +1,56 @@
+# 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

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

@@ -0,0 +1,37 @@
+# TrialBalanceLine
+
+## Description
+
+TrialBalanceLine represents a single account's balance within a TrialBalance snapshot. Each line records the account reference, optional account group for hierarchical aggregation, opening balance, period debits, period credits, and computed closing balance. Lines are always created as part of trial balance generation and are immutable once the snapshot is produced.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [generateTrialBalance](../commands/GenerateTrialBalance.md) - Trial balance lines are created as part of trial balance generation
+
+### Query Definitions
+
+- [GetTrialBalance](../queries/GetTrialBalance.md) - Trial balance lines are returned as part of the parent trial balance
+
+### Models
+
+- TrialBalanceLine
+
+### Invariants
+
+- Each trial balance line must reference a valid GL account from the active CoA
+- Opening balance equals the closing balance from the immediately preceding period for the same account
+- Closing balance equals opening balance plus period debits minus period credits
+- Lines are ordered by account code in ascending order within each account group
+- Lines are immutable once generated as part of a trial balance snapshot
+
+### Relationships
+
+- **References TrialBalance**: Each line belongs to a TrialBalance via trialBalanceId
+- **References Account**: Each line references a GL Account via accountId (coa-management module)
+- **References AccountGroup**: Each line optionally references an AccountGroup via accountGroupId (coa-management module)

package/src/modules/finance-ledger/docs/queries/GetAccountingPeriod.md

@@ -0,0 +1,35 @@
+# GetAccountingPeriod
+
+## Overview
+
+GetAccountingPeriod retrieves a single accounting period record by id. The period record includes the period name, companyId, fiscalYearId, start date, end date, period type, and current status. This serves as the core period lookup for posting validation, period lifecycle management, and close workflows.
+
+## Business Rules
+
+- Accepts a single lookup parameter: `{ id }`
+- Returns the full accounting period record including all fields (id, companyId, fiscalYearId, periodName, startDate, endDate, periodType, status, timestamps)
+- Returns null if no matching accounting period is found
+- Lookup is an exact match on id
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with id] --> B[SELECT from AccountingPeriod where id = input.id]
+    B --> C{Period found?}
+    C -->|Yes| D[Return accounting period record]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ACCOUNTING_PERIOD_NOT_FOUND**: No accounting period matches the given id — caller receives null
+
+## Test Cases
+
+- returns accounting period when found by id
+- returns null when not found

package/src/modules/finance-ledger/docs/queries/GetFinancialStatement.md

@@ -0,0 +1,38 @@
+# GetFinancialStatement
+
+## Overview
+
+GetFinancialStatement retrieves a single financial statement record by id, including all line items. The financial statement record contains the generation parameters (companyId, statement type, reporting date or date range, method for cash flow, status) and the full list of line items organized by account group sections. This query supports statement review, finalization workflows, and audit evidence retrieval.
+
+## Business Rules
+
+- Accepts a single lookup parameter: `{ id }`
+- Returns the full financial statement record including all line items
+- Line items are structured according to the account group hierarchy from coa-management, with section headings and subtotals
+- Statement types include BALANCE_SHEET, PROFIT_AND_LOSS, and CASH_FLOW
+- Returns null if no matching financial statement is found
+- Lookup is an exact match on id
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with id] --> B[SELECT from FinancialStatement where id = input.id]
+    B --> C{Financial statement found?}
+    C -->|Yes| D[Load all associated line items]
+    D --> E[Return financial statement with line items]
+    C -->|No| F[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **FINANCIAL_STATEMENT_NOT_FOUND**: No financial statement matches the given id — caller receives null
+
+## Test Cases
+
+- returns financial statement with line items when found by id
+- returns null with empty line items when not found

package/src/modules/finance-ledger/docs/queries/GetFiscalYear.md

@@ -0,0 +1,35 @@
+# GetFiscalYear
+
+## Overview
+
+GetFiscalYear retrieves a single fiscal year record by id. The fiscal year contains the year name, companyId, start date, end date, and status. This serves as the core fiscal year lookup for period management, year-end close workflows, and calendar structure validation.
+
+## Business Rules
+
+- Accepts a single lookup parameter: `{ id }`
+- Returns the full fiscal year record including all fields (id, companyId, yearName, startDate, endDate, status, timestamps)
+- Returns null if no matching fiscal year is found
+- Lookup is an exact match on id
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with id] --> B[SELECT from FiscalYear where id = input.id]
+    B --> C{Fiscal year found?}
+    C -->|Yes| D[Return fiscal year record]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **FISCAL_YEAR_NOT_FOUND**: No fiscal year matches the given id — caller receives null
+
+## Test Cases
+
+- returns fiscal year when found by id
+- returns null when not found

package/src/modules/finance-ledger/docs/queries/GetJournalEntry.md

@@ -0,0 +1,37 @@
+# GetJournalEntry
+
+## Overview
+
+GetJournalEntry retrieves a single journal entry record by id, including all associated journal lines. The journal entry record contains the header fields (entry date, journal type, reference number, status, accounting period, description, source document reference) and the full list of journal lines (GL account, debit/credit amounts, currency, exchange rate, functional currency amount, line description). This is the primary query for viewing journal entry details, audit review, and reversal workflows.
+
+## Business Rules
+
+- Accepts a single lookup parameter: `{ id }`
+- Returns the full journal entry record including all header fields and all associated journal lines
+- Journal lines include account references, debit and credit amounts, currency details, and line descriptions
+- Returns null if no matching journal entry is found
+- Lookup is an exact match on id
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with id] --> B[SELECT from JournalEntry where id = input.id]
+    B --> C{Journal entry found?}
+    C -->|Yes| D[Load all associated JournalLine records]
+    D --> E[Return journal entry with lines]
+    C -->|No| F[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **JOURNAL_ENTRY_NOT_FOUND**: No journal entry matches the given id — caller receives null
+
+## Test Cases
+
+- returns journal entry with journal lines when found by id
+- returns null with empty journal lines when not found

package/src/modules/finance-ledger/docs/queries/GetPeriodByDate.md

@@ -0,0 +1,38 @@
+# GetPeriodByDate
+
+## Overview
+
+GetPeriodByDate finds the accounting period that contains a given date for a specific company. It looks up the operating period where the date falls between startDate and endDate (inclusive). This query is the primary mechanism used by upstream modules (purchase, sales, inventory, manufacturing) to determine which accounting period a transaction date maps to and whether posting is permitted.
+
+## Business Rules
+
+- Requires `companyId` and `date` as input parameters
+- Searches for an accounting period where `startDate <= date <= endDate` and `periodType = OPERATING`
+- Only OPERATING periods are returned; ADJUSTMENT periods are excluded from date-based lookup
+- Returns the full accounting period record including status, enabling callers to check posting eligibility
+- Returns null if no operating period covers the given date (e.g., date falls outside all defined fiscal year boundaries)
+- If multiple periods could theoretically match (should not occur with properly configured non-overlapping periods), the query returns the first match
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with companyId and date] --> B[SELECT from AccountingPeriod where companyId = input.companyId AND startDate <= input.date AND endDate >= input.date AND periodType = OPERATING]
+    B --> C{Period found?}
+    C -->|Yes| D[Return accounting period record]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PERIOD_NOT_FOUND**: No operating period covers the given date for the specified company — caller receives null
+
+## Test Cases
+
+- returns period when date falls within range
+- returns null when no period covers the date
+- only returns OPERATING periods (not ADJUSTMENT)

package/src/modules/finance-ledger/docs/queries/GetPeriodClose.md

@@ -0,0 +1,36 @@
+# GetPeriodClose
+
+## Overview
+
+GetPeriodClose retrieves the PeriodClose record for a given accounting period. The PeriodClose record tracks the close workflow status, checklist completion percentage, the user who initiated each step, and timestamps for each state transition. This query supports period-end close workflow management, status monitoring, and audit review of the close process.
+
+## Business Rules
+
+- Accepts a single lookup parameter: `{ accountingPeriodId }`
+- Returns the full PeriodClose record including close status, completionPercentage, initiator userId, step timestamps, and audit metadata
+- Each accounting period has at most one PeriodClose record
+- Returns null if no close record exists for the given accounting period (i.e., close has not been initiated)
+- Lookup is an exact match on accountingPeriodId
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with accountingPeriodId] --> B[SELECT from PeriodClose where accountingPeriodId = input.accountingPeriodId]
+    B --> C{PeriodClose record found?}
+    C -->|Yes| D[Return PeriodClose record]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PERIOD_CLOSE_NOT_FOUND**: No PeriodClose record exists for the given accounting period — caller receives null
+
+## Test Cases
+
+- returns period close when found by accounting period id
+- returns null when not found

package/src/modules/finance-ledger/docs/queries/GetSubledgerTransferStatus.md

@@ -0,0 +1,45 @@
+# GetSubledgerTransferStatus
+
+## Overview
+
+GetSubledgerTransferStatus returns the transfer completeness status for all subledger modules for a given accounting period. For each registered subledger module (purchase, sales, inventory, manufacturing), the query reports the total expected handoff events, the number of acknowledged (successfully posted) events, and the number of outstanding (pending) events. This query is a critical input to the period-end close workflow, where subledger transfer verification must pass before the close can proceed.
+
+## Business Rules
+
+- Accepts a single lookup parameter: `{ accountingPeriodId }`
+- Returns a status record per subledger module: purchase, sales, inventory, manufacturing
+- Each module status includes:
+  - `totalExpected` — total number of handoff events expected for the period
+  - `acknowledged` — number of events successfully posted and acknowledged
+  - `outstanding` — number of events not yet posted or acknowledged (`totalExpected - acknowledged`)
+- The query aggregates data from subledger handoff event records and their acknowledgment status
+- Returns the status for all registered subledger modules, even if a module has zero expected events
+- Used by the period-end close workflow to determine whether subledger verification can pass
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with accountingPeriodId] --> B[Query handoff events for the accounting period]
+    B --> C[Group events by source subledger module]
+    C --> D[For each module: count total expected events]
+    D --> E[For each module: count acknowledged events]
+    E --> F[For each module: compute outstanding = total - acknowledged]
+    F --> G[Return status per subledger module]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ACCOUNTING_PERIOD_NOT_FOUND**: The specified accounting period does not exist — caller receives an error
+
+## Test Cases
+
+- returns error when accounting period does not exist
+- returns status for all 4 modules
+- returns zero counts when no entries exist
+- correctly counts posted vs draft entries
+- returns correct outstanding counts

package/src/modules/finance-ledger/docs/queries/GetTrialBalance.md

@@ -0,0 +1,38 @@
+# GetTrialBalance
+
+## Overview
+
+GetTrialBalance retrieves a single trial balance snapshot by id, including all line items. The trial balance record contains the generation parameters (companyId, accounting period, variant type, generation timestamp) and the full list of line items showing each GL account's opening balance, period debits, period credits, and closing balance. This query supports period-end review, financial statement preparation, and audit evidence retrieval.
+
+## Business Rules
+
+- Accepts a single lookup parameter: `{ id }`
+- Returns the full trial balance record including all line items
+- Line items include account reference, opening balance, period debits, period credits, and closing balance
+- Line items are organized by account group hierarchy and sorted by account code ascending within each group
+- Returns null if no matching trial balance is found
+- Lookup is an exact match on id
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with id] --> B[SELECT from TrialBalance where id = input.id]
+    B --> C{Trial balance found?}
+    C -->|Yes| D[Load all associated line items]
+    D --> E[Return trial balance with line items]
+    C -->|No| F[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **TRIAL_BALANCE_NOT_FOUND**: No trial balance matches the given id — caller receives null
+
+## Test Cases
+
+- returns trial balance with lines when found by id
+- returns null with empty lines when not found