Skip to main content
This diagram shows how the main building blocks of Midaz connect to support financial operations at scale. Figure 1 gives an overview of how the system works.
Midaz core building blocks and how its interconnected domains fit together to support financial operations at scale

Figure 1. Midaz and its interconnected domains and modular structure.

​
Core components

​
Midaz

Midaz is at the center. It coordinates everything, from data persistence to business logic.

​
Data Layer

All data flows into the persistent data layer. This layer gives the system durability, consistency, and performance.

​
Domains and relationships

​
Organizations

Each organization is a distinct environment in Midaz. It can hold one or many ledgers, based on how you structure your data.

​
Ledgers

A ledger holds all financial activity. It tracks balances, stores assets, and powers transactions. Every ledger belongs to an organization. From here, the system branches into:
  • Assets: define the kind of value you track.
  • Portfolios: group related accounts under a shared purpose.

​
Assets

Assets define the units of value, like BRL, USD, points, or tokens. Each account uses one specific asset.

​
Portfolios

Portfolios group accounts by business logic. You can create as many portfolios as you need to organize your financial structure. Each portfolio contains one or more accounts.

​
Accounts & Segments

An account belongs to a portfolio and represents an individual balance. Segments group accounts, so you can isolate data by customer, product, region, or any other dimension. Segments help you track and report with precision. Account Types classify accounts by nature and purpose. They enable transaction routing and operational validation across account categories.

​
Balance

A Balance represents the net amount an Account holds of a given Asset in a specific Ledger.
  • An account can carry multiple balances. Each has a balanceKey (e.g. default, collateral, operational) to partition funds without splitting the account.
  • An external account has only one balance (default).
  • If you omit balanceKey in a transaction, Midaz uses the default balance.
  • Midaz derives balances automatically from ledger operations. You can list, fetch, or (in admin or test scenarios) adjust them manually.
  • The Valkey cache key includes balanceKey in its format: balance:{transactions}:<orgId>:<ledgerId>:<alias>#<balanceKey>.

​
Transactions

A transaction moves value between accounts. Each transaction contains operations (debits and credits). This keeps your logic consistent, traceable, and aligned with your business model and accounting policies.

​
Accounting Routes entities

The Accounting Routes entities extend Midaz. They create a structured system that guarantees correct annotations and correct financial-flow directions. It has two parts:
  • Operation Routes: define atomic transaction behaviors. Each route sets how Midaz annotates and directs one financial movement, based on your business rules and accounting standards.
  • Accounting Routes: orchestrate multiple Operation Routes into balanced financial events. They enforce double-entry validation and keep transaction integrity across all accounts. (The API calls this transactionRoute.)
This pair forms a self-governing system. Midaz automatically validates each transaction for correct annotation and flow direction.

​
In short

Midaz gives you a modular structure:
  • Organizations manage ledgers.
  • Ledgers hold assets, portfolios, and accounting structures.
  • Portfolios contain accounts, grouped by segment.
  • Transactions move value and trigger accounting treatments.
  • Your data stays synced, traceable, and ready for financial reporting.
Need help designing your Midaz setup?Our consulting service can help you tailor the structure to your organization’s needs. This applies whether you start from scratch or optimize an existing setup.Contact us to learn more.