RFC 002: Financial & Ledger Suite Specification

1. Core Domain Schema Design

The Financial Management Suite enforces strict auditability using declarative SQLAlchemy models mapped to PostgreSQL. The Chart of Accounts is structured as a self-referential tree:

class Account(BaseDocType):
    """Declarative Chart of Accounts (COA) entity."""

    account_name: str = Field(max_length=150, unique=True)
    account_code: str = Field(max_length=20, unique=True)
    root_type: str = Field(description="Asset, Liability, Equity, Income, Expense")
    is_group: bool = Field(default=False, description="Group accounts hold children but cannot post entries")
    parent_account: str | None = Field(default=None, description="Self-referential key to parent Account")
    company: str = Field(max_length=100)
    currency: str = Field(default="INR", max_length=10)

    class Meta:
        table_name = "account"
        indexes = ["account_code", "parent_account", "root_type"]

---

2. General Ledger Immutable Postings

Every transaction affecting balances must post as a pair of debits and credits in the General Ledger Entry (GLE) table:

class GLEntry(BaseDocType):
    """Immutable double-entry transaction record."""

    posting_date: date
    voucher_type: str = Field(description="e.g. Journal Voucher, Payment Entry")
    voucher_no: str = Field(max_length=100)
    account: str = Field(description="Foreign key to posting Child Account")
    debit: Decimal = Field(default=Decimal("0.00"))
    credit: Decimal = Field(default=Decimal("0.00"))
    cost_center: str | None = None
    company: str
    narration: str

    class Meta:
        table_name = "gl_entry"
        indexes = ["posting_date", "account", "voucher_no"]

2.1 Double-Entry Balance Validator

At the database repository level, before committing a batch of GLEntry records, the system executes an atomic transaction assertion: $$\sum \text{Debit} - \sum \text{Credit} \equiv 0.00$$ If this balance sum does not equal zero, the database transaction is aborted, and a LedgerValidationError is raised.

---

3. Subsystem Architecture Specifications

3.1 Budget Allocation & Controls

Budgets are locked by fiscal years and cost centers:

class Budget(BaseDocType):
    fiscal_year: str
    cost_center: str
    account: str
    allocated_amount: Decimal
    action_if_exceeded: str = Field(default="Block")  # "Warn", "Block"

• Evaluation Hook: On submitting a Purchase Invoice, the BudgetController runs a cumulative sum query: $$\sum \text{GLEntry.debit for CostCenter} + \text{CurrentInvoiceAmount} > \text{Budget.allocated_amount}$$
• If exceeded and action_if_exceeded is set to “Block”, the submission fails and issues a BudgetExceededError.

3.2 Earnest Money Deposits (EMD)

Tracks vendor performance deposits:

• EMDs are ledger-marked as temporary liabilities.
• The EMD controller tracks transition states: Received ➔ Released | Forfeited (which routes funds to corporate Revenue accounts).

---

4. REST API Endpoint Mapping

Decomposed Finance microservices expose standard REST gateways for transaction management:

Endpoint	Method	Payload DTO	Description
/api/v1/finance/accounts	GET, POST	AccountCreateDTO	List or create chart of accounts nodes.
/api/v1/finance/journal-voucher	POST	JVBatchSubmitDTO	Submit double-entry ledger vouchers.
/api/v1/finance/payment-entry	POST	PaymentSubmitDTO	Record payment settlement against vendor invoices.
/api/v1/finance/reports/trial-balance	GET	company, date	Generate Trial Balance statement.