Skip to main content

​
Overview

The AccountingFacade is the primary interface for all accounting operations in the system. It provides methods for creating accounts, executing transactions, querying balances, and managing financial data using double-entry bookkeeping principles. Package: com.softwarearchetypes.accounting

​
Constructor

AccountingFacade(
    Clock clock,
    AccountRepository accountRepository,
    AccountViewQueries accountViewQueries,
    TransactionRepository transactionRepository,
    TransactionBuilderFactory transactionBuilderFactory,
    EventPublisher eventPublisher
)
Package-private constructor. Use AccountingConfiguration to obtain an instance.

​
Account Management

​
createAccount

Creates a single account. 
public Result<String, AccountId> createAccount(CreateAccount request)
​
request
CreateAccount
required
Account creation request containing:
  • accountId: Unique identifier for the account
  • name: Human-readable account name
  • type: Account type (ASSET, LIABILITY, EXPENSE, REVENUE, OFF_BALANCE)
​
Result
Result<String, AccountId>
  • Success: Returns the created AccountId
  • Failure: Returns error message if account already exists
Example: 
CreateAccount request = CreateAccount.generateAssetAccount(
    AccountId.generate(),
    "Cash Account"
);
Result<String, AccountId> result = facade.createAccount(request);

​
createAccounts

Creates multiple accounts in a single operation. 
public Result<String, Set<AccountId>> createAccounts(Set<CreateAccount> requests)
​
requests
Set<CreateAccount>
required
Set of account creation requests
​
Result
Result<String, Set<AccountId>>
  • Success: Returns set of created account IDs
  • Failure: Returns error if any account already exists

​
createAccountsWithInitialBalances

Creates accounts and initializes them with opening balances. 
public Result<String, Set<AccountId>> createAccountsWithInitialBalances(
    Set<CreateAccount> requests,
    AccountAmounts accountAmounts
)
​
requests
Set<CreateAccount>
required
Account creation requests
​
accountAmounts
AccountAmounts
required
Initial balances for the accounts (positive for credits, negative for debits)
​
Result
Result<String, Set<AccountId>>
  • Success: Returns set of created account IDs
  • Failure: Returns error message if creation or initialization fails

​
Balance Queries

​
balance

Retrieves the current balance of an account. 
public Optional<Money> balance(AccountId accountId)
​
accountId
AccountId
required
The account identifier
​
Optional
Optional<Money>
The current account balance, or empty if account doesn’t exist

​
balanceAsOf

Retrieves the account balance as of a specific point in time. 
public Optional<Money> balanceAsOf(AccountId accountId, Instant when)
​
accountId
AccountId
required
The account identifier
​
when
Instant
required
The point in time for balance calculation
​
Optional
Optional<Money>
The account balance at the specified time, or empty if account doesn’t exist
Example: 
Instant lastMonth = Instant.now().minus(30, ChronoUnit.DAYS);
Optional<Money> historicalBalance = facade.balanceAsOf(accountId, lastMonth);

​
balances

Retrieves current balances for multiple accounts. 
public Balances balances(Set<AccountId> accounts)
​
accounts
Set<AccountId>
required
Set of account identifiers
​
Balances
Balances
Map of account IDs to their current balances

​
balancesAsOf

Retrieves balances for multiple accounts at a specific point in time. 
public Balances balancesAsOf(Set<AccountId> accounts, Instant when)
​
accounts
Set<AccountId>
required
Set of account identifiers
​
when
Instant
required
The point in time for balance calculation
​
Balances
Balances
Map of account IDs to their balances at the specified time

​
Transaction Operations

​
transaction

Creates a new transaction builder for constructing complex transactions. 
public TransactionBuilder transaction()
​
TransactionBuilder
TransactionBuilder
A builder for constructing and executing transactions
Example: 
Transaction tx = facade.transaction()
    .occurredAt(Instant.now())
    .appliesAt(Instant.now())
    .withTypeOf("payment")
    .executing()
    .debitFrom(sourceAccount, Money.of(100, "PLN"))
    .creditTo(targetAccount, Money.of(100, "PLN"))
    .build();

​
execute

Executes one or more transactions. 
public Result<String, TransactionId> execute(Transaction transaction)
public Result<String, Set<TransactionId>> execute(Transaction... transactions)
​
transaction
Transaction
required
The transaction to execute
​
Result
Result<String, TransactionId>
  • Success: Returns the transaction ID
  • Failure: Returns error message if execution fails
Note: All account updates use optimistic locking to prevent concurrent modification issues.

​
transfer

Performs a simple transfer between two accounts. 
public Result<String, TransactionId> transfer(
    AccountId from,
    AccountId to,
    Money amount,
    Instant occurredAt,
    Instant appliesAt
)

public Result<String, TransactionId> transfer(
    AccountId from,
    AccountId to,
    Money amount,
    Instant occurredAt,
    Instant appliesAt,
    MetaData metaData
)
​
from
AccountId
required
Source account to debit
​
to
AccountId
required
Target account to credit
​
amount
Money
required
Amount to transfer
​
occurredAt
Instant
required
When the transfer occurred in real time
​
appliesAt
Instant
required
When the transfer applies for accounting purposes
​
metaData
MetaData
Optional metadata to attach to the transaction
​
Result
Result<String, TransactionId>
  • Success: Returns the transaction ID
  • Failure: Returns error message if transfer fails
Example: 
Result<String, TransactionId> result = facade.transfer(
    fromAccount,
    toAccount,
    Money.of(500, "PLN"),
    Instant.now(),
    Instant.now()
);

​
handle (ExecuteTransactionCommand)

Executes a transaction from a command object. 
public Result<String, TransactionId> handle(ExecuteTransactionCommand command)
​
command
ExecuteTransactionCommand
required
Command containing:
  • transactionType: Type of transaction
  • occurredAt: When transaction occurred
  • appliesAt: When transaction applies
  • entries: List of credit/debit entries
  • metadata: Optional transaction metadata
​
Result
Result<String, TransactionId>
  • Success: Returns the transaction ID
  • Failure: Returns error message if execution fails

​
handle (ReverseTransactionCommand)

Reverses a previously executed transaction. 
public Result<String, TransactionId> handle(ReverseTransactionCommand command)
​
command
ReverseTransactionCommand
required
Command containing:
  • refTransactionId: ID of transaction to reverse
  • occurredAt: When reversal occurred
  • appliesAt: When reversal applies
​
Result
Result<String, TransactionId>
  • Success: Returns the reversal transaction ID
  • Failure: Returns error message if reversal fails

​
Query Operations

​
findAccount

Retrieves detailed account information including entries. 
public Optional<AccountView> findAccount(AccountId accountId)
​
accountId
AccountId
required
The account identifier
​
Optional
Optional<AccountView>
Complete account view with balance and entry history, or empty if not found

​
findAccounts

Retrieves multiple accounts by their IDs. 
public List<AccountView> findAccounts(Set<AccountId> accountIds)
​
accountIds
Set<AccountId>
required
Set of account identifiers
​
List
List<AccountView>
List of account views for existing accounts

​
findAll

Retrieves all accounts in the system. 
public List<AccountView> findAll()
​
List
List<AccountView>
List of all account views

​
findTransactionBy

Retrieves complete transaction details including all entries. 
public Optional<TransactionView> findTransactionBy(TransactionId transactionId)
​
transactionId
TransactionId
required
The transaction identifier
​
Optional
Optional<TransactionView>
Complete transaction view with all entries and accounts, or empty if not found

​
findTransactionIdsFor

Finds all transaction IDs associated with an account. 
public List<TransactionId> findTransactionIdsFor(AccountId accountId)
​
accountId
AccountId
required
The account identifier
​
List
List<TransactionId>
List of transaction IDs that affected the account

​
Projection Accounts

​
createProjectingAccount

Creates a virtual account that projects (aggregates) entries from other accounts based on filters. 
public Result<String, AccountId> createProjectingAccount(
    AccountId projecting,
    AccountEntryFilter accountEntryFilter,
    String description
)
​
projecting
AccountId
required
ID for the projection account
​
accountEntryFilter
AccountEntryFilter
required
Filter defining which entries to include
​
description
String
required
Human-readable description of the projection
​
Result
Result<String, AccountId>
  • Success: Returns the projection account ID
  • Failure: Returns error message if creation fails
Use Case: Create aggregated views like “All Revenue from Product X” or “Total Expenses by Department Y”.
  • Account - Core account entity
  • Transaction - Transaction entity
  • Entry - Individual accounting entries
  • Result<F, S> - Result monad for error handling
  • Money - Monetary value with currency
  • Instant - Point in time

Build docs developers (and LLMs) love

Get started for freeTalk to us