# README

<!-- This section should contain the following subsections in order: -->
<!-- 1. ## Overview (required) -->
<!-- 2. ## Key Features (required) -->
<!-- 3. ## Module Scope (required) -->
<!-- 4. ## Module Dependencies (required) -->

## Overview

The financial-accounting module owns the financial accounting foundation for ERP
transactions. It provides the general ledger, accounting periods, fiscal years,
posting controls, trial balance, period close workflow, and the subledger posting
boundary used by sales, purchase, inventory, manufacturing, and management
accounting modules.

The module is intentionally broader than a general-ledger-only module. It is the
home for GL postings and the accounting-side AP/AR foundation: open items,
payment clearing, cash receipt clearing, and bank reconciliation belong here as
financial accounting facts. Operational documents such as customer invoices,
vendor bills, sales orders, purchase orders, shipments, and goods receipts remain
owned by their upstream modules.

## Key Features

- Double-entry journal entry posting with immutable posted entries and reversal-only corrections
- Fiscal year and accounting period management with posting status controls
- Trial balance generation and verification for posted ledger activity
- Period-end close workflow with subledger transfer checks and final lock controls
- Subledger handoff contracts for sales, purchase, inventory, manufacturing, and accounting postings
- AP/AR accounting foundation for future open item, clearing, and reconciliation workflows

## Module Scope

### In Scope

- General ledger journal entries and journal lines
- Posting, reversal, adjusting entries, and opening/closing entries
- Fiscal years, accounting periods, period status transitions, and period close
- Trial balances and ledger-balance verification
- Subledger posting handoffs from operational modules
- Accounting-side AP/AR open item and clearing foundations
- Bank and cash reconciliation foundations tied to posted ledger lines

### Out of Scope

- Chart of accounts and account master governance, owned by `coa-management`
- Cost centers, profit centers, budgets, allocations, commitments, and variance analysis, owned by `accounting`
- Customer invoice lifecycle, shipment lifecycle, and sales order processing, owned by `sales`
- Vendor bill lifecycle, purchase order processing, and goods receipt matching, owned by `purchase`
- Inventory valuation source events and stock movement lifecycle, owned by `inventory`
- Manufacturing order costing source events and production lifecycle, owned by `manufacturing`
- Bank connectivity, bank feed ingestion, and payment execution rails

### Scope Decision Rationale

`financial-accounting` is the financial record of business activity, not the
operational system that creates that activity. Upstream modules own business
documents and domain-specific validation. This module receives validated
financial handoffs, enforces accounting controls, posts immutable ledger impact,
and tracks accounting settlement state.

This boundary keeps the module compatible with both SoftLedger-style API-first
financial accounting and SAP FI-style separation between financial accounting,
management accounting, chart of accounts governance, and operational logistics.

## Module Dependencies

- `coa-management` - GL account references used by journal lines and posting validation
- `organization` - Company scope for fiscal calendars, periods, and journal entries
- `primitives` - Currency and exchange rate concepts used by multi-currency postings
- `user-management` - Actor references for close workflow and approval actions
- `audit` - Immutable audit events for financial accounting lifecycle operations
