​

Reconciliation System

​

Overview

The reconciliation system in CONA automatically identifies and processes matching general ledger entries to balance accounts. It groups entries by reconciliation identifiers (GIDs) and processes them when credits equal debits, ensuring accurate financial record-keeping.

​

Key Concepts

​

Reconciliation Groups

• Definition: Collections of general ledger entries that share the same reconciliation identifier (GID)
• Eligibility: Groups are reconcilable when:
  • Total balance equals zero (credits = debits)
  • Contains multiple entries (minimum 2)
  • Entries are on accounts marked to_be_reconciled = true

​

Reconciliation Identifiers (GIDs)

• Credit GID: credit_should_reconcile_gid - identifies credit entries for reconciliation
• Debit GID: debit_should_reconcile_gid - identifies debit entries for reconciliation
• Purpose: Groups related transactions (e.g., invoice + payment) for automatic reconciliation

​

Account Configuration

• Chart of Accounts: to_be_reconciled field determines which accounts participate in reconciliation
• Typical Accounts: receivables, payables, clearing accounts

​

System Architecture

​

Database Schema

-- Main reconciliation tracking
reconciliation_groups:
  - id: string (reconciliation identifier)
  - status: PENDING | IN_PROGRESS | COMPLETED | CANCELLED | ERROR
  - reconciled_at: timestamp
  - reconciled_by_id: user reference
  - org_id: organization reference

-- General ledger entries with reconciliation links
general_ledger:
  - credit_should_reconcile_gid: string (grouping identifier)
  - debit_should_reconcile_gid: string (grouping identifier)
  - credit_reconciliation_group_id: reference to reconciliation_groups
  - debit_reconciliation_group_id: reference to reconciliation_groups

-- Account configuration
chart_of_accounts:
  - to_be_reconciled: boolean (enables reconciliation for account)

​

Core Components

1. @cona/core Package

   • get-reconciliation-groups.ts - Finds reconcilable groups
   • process-reconciliation-group.ts - Processes and reconciles groups

2. Temporal Workflows Package

   • sync-reconciliation-global.ts - Orchestrates organization-wide reconciliation
   • sync-organization-reconciliation.ts - Processes single organization
   • Activities that wrap core functions

3. Web Application

   • Manual reconciliation actions
   • Search and filtering capabilities
   • Reconciliation management UI

​

Reconciliation Process Flow

​

1. Group Discovery

// Core logic: get-reconciliation-groups.ts
1. Find accounts marked for reconciliation (to_be_reconciled = true)
2. Query unreconciled GL entries on these accounts
3. Group entries by reconciliation GID
4. Filter groups where total = 0 and entries > 1
5. Return paginated reconcilable groups

​

2. Group Processing

// Core logic: process-reconciliation-group.ts
1. Validate group eligibility (balance = 0, multiple entries)
2. Create reconciliation_groups record
3. Update GL entries with reconciliation_group_id
4. Extract and connect related documents
5. Return reconciliation result

​

3. Automated Workflow

// Temporal workflow hierarchy
Global Workflow:
├── Get organizations with auto-reconciliation enabled
├── Start organization workflows concurrently (batch of 5)
└── Monitor completion

Organization Workflow:
├── Fetch reconciliation groups (batch of 50)
├── Process each group sequentially
├── Log results and continue pagination
└── Report completion statistics

​

Manual vs Automated Reconciliation

​

Automated Reconciliation

• Trigger: Temporal scheduled workflow
• Scope: All organizations with auto-reconciliation enabled
• Processing: Batch processing with concurrency limits
• Monitoring: Comprehensive logging and error handling

​

Manual Reconciliation

• Trigger: User action from web interface
• Scope: Single organization or account
• Processing: On-demand reconciliation
• Interface: Search, filter, and process specific entries

​

Key Features

​

Account-Specific Reconciliation

• Only accounts marked to_be_reconciled = true participate
• Separate tracking for credit and debit sides
• Flexible account configuration per organization

​

Document Connection

• Automatically connects related documents during reconciliation
• Links invoices, payments, and other related transactions
• Maintains audit trail of connected documents

​

Batch Processing

• Handles large volumes with pagination
• Configurable batch sizes for performance tuning
• Concurrent processing across organizations

​

Error Handling

• Graceful failure handling in workflows
• Detailed logging for debugging
• Rollback capabilities for failed reconciliations

​

API Interfaces

​

Core Functions

// Get reconciliation groups
interface GetReconciliationGroupsParams {
  organizationId: string;
  batchSize?: number;
  offset?: number;
}

// Process reconciliation group
interface ProcessReconciliationGroupParams {
  group: ReconGroup;
  organizationId: string;
  reconciliationId?: string;
}

// Reconciliation group structure
interface ReconGroup {
  entries: {
    id: string;
    amount: number;
    isCredit: boolean;
    general_ledger: {
      organization: { id: string };
    };
  }[];
  total: number; // Must be 0 for reconciliation
}

​

Web Actions

// Search GL entries for reconciliation
searchGeneralLedgerForReconciliation({
  searchParams: { [key: string]: string | string[] | undefined };
  accountNumber: string;
})

// Start manual reconciliation workflow
startReconciliationWorkflow(): Promise<{ workflowId: string }>

// Update reconciliation entries
setReconciliationEntriesAsReconciled({
  entries: ReconciliationEntry[];
  reconciliationId: string;
})