Architecture

Infrarails uses a ledger-centered architecture to organize financial records, transactions, and account balances.

The design separates core accounting operations from application-specific workflows and external provider integrations.

Architectural principles

The infrastructure is organized around several core principles.

Ledger isolation

Financial records are associated with a specific ledger.

Each ledger acts as a logical accounting boundary containing its own accounts and transactions.

Double-entry accounting

Financial movements are represented through debit and credit entries.

This allows the accounting effects of a transaction to be recorded in a structured and balanced manner.

Transaction lifecycle management

Financial operations progress through defined transaction states.

This separates operations awaiting completion from transactions whose accounting effects have been finalized.

Integer-based monetary values

Financial amounts are represented in integer minor units, with the currency exponent determining their display representation.

This avoids the precision issues associated with floating-point arithmetic.

Idempotent operations

Ledger-scoped idempotency supports duplicate prevention for eligible financial operations.

Provider independence

Internal financial records are maintained separately from external provider operations.

This enables integrations to coordinate external events with internal accounting workflows.

Core resource relationships

Ledger
│
├── Accounts
│   ├── Account A
│   ├── Account B
│   └── Account C
│
└── Transactions
    │
    ├── Transaction 1
    │   ├── Entry: Debit Account A
    │   └── Entry: Credit Account B
    │
    └── Transaction 2
        ├── Entry: Debit Account B
        └── Entry: Credit Account C

Ledgers

A ledger provides the top-level accounting context.

Accounts and transactions are associated with a ledger identifier, which is used to organize and scope financial operations.

Accounts

Accounts represent financial balances within a ledger.

An account includes information such as:

• Unique account identifier.
• Ledger association.
• Currency.
• Currency exponent.
• Available balance.
• Pending balance.
• Account status.
• Optional metadata.

Transactions

Transactions represent financial operations recorded within a ledger.

Supported ledger transaction types include:

Transactions are associated with lifecycle states and accounting entries.

Entries

Entries represent the individual debit and credit effects associated with a transaction.

For a conventional transfer, one account is debited and another is credited.

For issuance and retirement operations, the accounting model normalizes the operation into corresponding entries.

Transaction lifecycle

The core transaction lifecycle uses the following states:

The supported transitions are:

PENDING
  ├── INFLIGHT
  │     ├── COMPLETED
  │     ├── REJECTED
  │     └── VOID
  │
  ├── COMPLETED
  ├── REJECTED
  └── VOID

Completed transactions represent finalized financial activity.

Monetary representation

Infrarails uses integer minor units.

For an account with a currency exponent of 2:

The account's currency exponent must be respected when interpreting stored balances and transaction amounts.

Provider integration layer

External financial infrastructure providers may participate in payment or account workflows.

Provider-specific operations are handled separately from core ledger accounting.

A conceptual integration flow is:

Application
    |
    v
Financial Workflow
    |
    +----------------------+
    |                      |
    v                      v
Infrarails Ledger     External Provider
    |                      |
    v                      v
Accounting Records    Provider Operations
    |                      |
    +----------+-----------+
               |
               v
       Reconciliation

This separation supports tracking the internal accounting state independently from the external provider's processing state.

Reliability and consistency

Financial operations should preserve accounting consistency, prevent duplicate posting, and maintain sufficient transaction history for investigation and reconciliation.

Applications should also account for asynchronous provider processing and uncertain external operation outcomes.

Next steps

Continue with the Core Concepts documentation:

• Ledgers
• Accounts
• Balances
• Transactions
• Entries
• Transaction Lifecycle

These sections explain the financial data model in greater technical detail.