Financial Management Architecture

1. Overview

The general-ledger parts of this page predate the current design. Posting triggers, transaction types, delta handling and account mapping through a processor on the order are superseded by General Ledger (append-only postings, accounts per organisation by role, the processor on each payment) and Income Processing (payment processors, fees, the service provider as agent, statements to the organiser). The reconciliation parts stand.

The Financial Management architecture provides a framework for:

  1. Payment Reconciliation - Importing and matching transaction data from payment processors (PayFast, PayGate) against orders

  2. General Ledger Integration - Recording the financial effect of orders as GL entries with support for delta tracking

  3. Journal Management - Consolidating GL transactions for export to external accounting systems

2. Problem Statement

2.1. Business Challenges

The Event and Membership System processes registrations that generate financial transactions. Several challenges exist:

Challenge Impact

Payment verification

Orders may be marked as paid when payment actually failed, or vice versa

Fee tracking

Payment processor fees are not captured, making cost analysis incomplete

Accounting integration

Financial data must be manually transferred to external accounting software

Order modifications

Changes after initial recording create discrepancies in accounting records

Audit trail

Difficult to trace the financial history of individual orders

2.2. Requirements

The financial management system must:

  • Import transaction records from PayFast and PayGate

  • Match transactions to orders for payment verification

  • Calculate and apportion transaction fees across line items

  • Generate GL entries automatically when orders are paid

  • Track delta changes when orders are modified after journaling

  • Consolidate GL transactions into journals for export

  • Support journal reversal to correct errors

  • Maintain clear separation between operational (Order) and financial (GL) records

3. Architecture Overview

finance-architecture

4. Component Architecture

4.1. Reconciliation Subsystem

The reconciliation subsystem imports transaction data from payment processors for verification.

recon-architecture

Key Design Decisions:

  • JPA Inheritance (JOINED): Separate tables for processor-specific fields

  • 2-char Discriminator: Compact type codes ("PF", "PG") following established enum pattern

  • Direct Import: Fixed CSV schema from payment processors, no column mapping UI required

  • Order Matching: Link recon records to orders via external reference ID

4.2. General Ledger Subsystem

The GL subsystem records the financial effect of orders using double-entry accounting principles.

gl-architecture

Key Design Decisions:

  • GlTransaction Owns Order: FK on gl_transaction.order_id; Order has mappedBy inverse

  • GlRecord Owns OrderLineItem: FK on gl_record.order_line_item_id for traceability

  • GlTransactionType Enum: ORDER, JOURNAL, ADJUSTMENT, REFUND - no separate journal entity

  • Delta Tracking: is_delta flag on GlRecord indicates post-journal modifications

  • PaymentProcessor Account Mapping: GL accounts derived from Order.paymentProcessor (bankAccount, feeAccount, incomeAccount)

  • Journal Filter Parameters: Journals can be filtered by organisation, transactionDate, registrationSystem, and paymentProcessor

5. Data Flow

5.1. Order Payment Flow

payment-flow

5.2. Order Modification with Delta

delta-flow

5.3. Journal Creation Flow

journal-flow

6. Transaction Type State Machine

transaction-states

6.1. State Descriptions

Type Description Behavior

ORDER

Created from order payment

Can be modified directly; eligible for journaling

JOURNAL

Consolidated export entry

Cannot be modified directly; order changes create delta records

ADJUSTMENT

Manual correction

Stand-alone transaction for adjustments

REFUND

Refund transaction

Created when order is refunded

7. Account Structure

GL accounts follow a standard chart of accounts pattern:

1000 - Assets
  1100 - PayFast Balance
  1200 - PayGate Balance
  1300 - Bank Account

4000 - Revenue
  4100 - Event Registration Income
  4200 - Membership Fee Income
  4300 - Product Sales Income

5000 - Expenses
  5100 - Payment Processing Fees
  5200 - Refunds Issued

Each organisation maintains its own chart of accounts, enabling multi-tenant operation with independent financial tracking.

7.1. PaymentProcessor Account Mapping

GL accounts are determined by the PaymentProcessor configured on each Order:

PaymentProcessor Field Account Type Usage

bankAccount

Asset (1xxx)

Debit for net payment received (consolidated per order)

feeAccount

Expense (5xxx)

Debit for processing fees (per line item)

incomeAccount

Revenue (4xxx)

Credit for gross income (per line item)

This enables different payment processors to post to different accounts while using the same GL structure.

8. Integration Points

8.1. Payment Processor Integration

Processor Import Method Fee Calculation

PayFast

CSV file upload

Included in transaction record

PayGate

CSV file upload

R2.00 fixed + 3.5% of gross + 15% VAT on fee

8.2. Accounting Software Export

Journals are designed for export to external accounting software:

  • Each journal represents a period’s consolidated transactions

  • Account-level totals suitable for bulk import

  • Maintains audit trail back to source orders

  • Supports incremental export (delta journals)

9. Related Documentation