Virtual accounts

Virtual accounts represent accounting accounts and account-like projections. They are hierarchical and maintained through a closure table.

Assets
  Cash
    USD
      Nostro USD

Liabilities
  Client Deposits
    USD
      Acme Holdings
        Operating
        Payroll
        Escrow

Income
  Fees
    Wire Fees

Expenses
  Interest Expense

Suspense
  USD Suspense

Important principle

Virtual accounts are not balances. Balances are derived from postings.

Schema: `virtual_accounts`

field	type	notes
`id`	bigint	PK
`parent_id`	bigint	self-reference; nil for roots
`code`	string	unique, stable, human-readable (colon-separated)
`name`	string	required
`account_type`	string	`asset`, `liability`, `equity`, `income`, `expense`, `client`, `settlement`, `suspense`, `fee`, `tax`, `clearing`
`currency`	string	required for posting accounts; nil allowed for aggregation accounts
`status`	string	`active`, `inactive`, `frozen`, `closed`
`posting_allowed`	boolean	only leaf accounts may allow postings
`normal_balance`	string	`debit` or `credit`
`external_id`	string
`metadata`	map
`inserted_at` / `updated_at`	utc_datetime

Schema: `virtual_account_closure`

field	type
`ancestor_id`	bigint
`descendant_id`	bigint
`depth`	integer

Self-rows (depth 0) are always present; the closure is rewritten on insert and on move_account/2. Cycles are prevented.

Rules enforced

account code is unique
only leaf accounts (no children) may allow postings
posting accounts require a currency
aggregation accounts may have a nil currency
a child cannot be created under a posting account
cycles are forbidden on move

Functions

Logistiki.VirtualAccounts.create_account(attrs)
Logistiki.VirtualAccounts.update_account(account, attrs)
Logistiki.VirtualAccounts.get_account!(id)
Logistiki.VirtualAccounts.get_account_by_code!(code)
Logistiki.VirtualAccounts.list_accounts(opts \\ [])
Logistiki.VirtualAccounts.list_children(account)
Logistiki.VirtualAccounts.list_descendants(account)
Logistiki.VirtualAccounts.list_ancestors(account)
Logistiki.VirtualAccounts.move_account(account, new_parent)
Logistiki.VirtualAccounts.leaf?(account)
Logistiki.VirtualAccounts.posting_account?(account)

Account types → financial-statement sections

Logistiki.Projections.ProjectionEngine maps account types to balance-sheet and income-statement sections:

Assets: asset, settlement
Liabilities: liability, client, suspense, clearing, tax
Equity: equity
Income: income, fee
Expenses: expense

← Previous Page Testing strategy

Next Page → Vision