Skip to content

Sub-Domain Blueprint: Finance Reconciliation

Domain: Finance (Ledger, Budget, AP, AR) Logical Sub-Domain: Compliance (Audit & Matching) Physical Packages: @sd/mod-finance/compliance Related Documents: Data Definition Context: This document defines the Bank Sync, Statement Parsing, and Transaction Matching workflows. Status: Stable (v2.5)

1. Mandate

The Reconciliation Sub-Domain ensures the Shadow Ledger (Bank Feeds) matches the General Ledger. It ingests PDF Statements, uses AI/Heuristics to extract transactions, and matches them against open Invoices or Bills. This is the primary defense against Fraud and Accounting Errors.

2. Capabilities

Capability Description Component
Statement Ingestion Uploading and validating PDF Statements. uploadStatement
Extraction Parsing text/tables from PDFs into structured data. parseStatement
Auto-Matching Linking Bank Lines to Invoices based on Amount/Desc. autoMatch
Balance Validation Verifying Opening + Tx = Closing Balance. validateBalances

3. Process Models

A. Statement Processing

Happy Path: Monthly Upload.

sequenceDiagram
    participant Treasury
    participant Service as ReconciliationService
    participant AI as DocAI
    participant DB as Firestore

    Treasury->>Service: uploadStatement(pdf)
    Service->>AI: parse(pdf)
    AI-->>Service: Transactions[]

    Service->>Service: validate(Opening + Net = Closing)

    loop Every Tx
        Service->>DB: createBankTx(status="unmatched")
    end

    Service->>Service: autoMatch()

B. Auto-Match Logic

Happy Path: Dues Payment.

sequenceDiagram
    participant Engine as EntityMatcher
    participant BankTx
    participant Invoice

    Engine->>BankTx: check("DEP $500 UNIT 101")
    Engine->>Invoice: find(amount=500, unit="101")

    alt Confidence > 90%
        Engine->>BankTx: update(status="potential", target=InvoiceID)
    end

4. State Machines

Bank Transaction Status

stateDiagram-v2
    [*] --> Unmatched
    Unmatched --> Potential: AI Match
    Potential --> Matched: User Confirmed
    Unmatched --> Ignored: User Hidden

5. Interface Definitions

ReconciliationService

  • uploadStatement(file): Promise<Statement>
  • parseStatement(id): Promise<Tx[]>
  • autoMatch(id): Promise<Stats>
  • confirmMatch(txId): Promise<void>

6. Changelog

Date Author Description Reference
2026-01-24 Antigravity Initial creation Implementation Plan