Structuring entities for High Transaction Volumes
Partitioning by Organizations, Ledgers, and Accounts
If your bank processes millions of transactions each day, distribute the workload across many accounts, ledgers, or organizations. For example, segment customers by last-name initial, or assign a separate ledger to each region. Each Midaz ledger is an independent book.Lock-oriented Operations
Midaz applies the balance changes of each transaction in a single Redis Lua script. The script checks every balance against live state before it writes, so a refused transaction changes no balance. The@external account skips the balance-floor and overdraft checks. It can go negative without limit, so transactions against it never fail on available funds. Each transaction still commits atomically. All operations apply, or none do.
Horizontal scaling of services
The Midaz ledger runs as one service that holds onboarding, transactions, CRM, and Fees. You scale it by adding instances. Start small and add instances as demand grows. For high loads, deploy several instances of the ledger service behind a load balancer. Use Kubernetes (K8s) pod scaling.CQRS and read replicas
Midaz uses CQRS (Command Query Responsibility Segregation) to separate write and read operations. You optimize each path on its own. Route heavy reporting and query loads to read replicas. This keeps transaction commits fast.Batching and N:N transactions
Where possible, batch related operations into a single transaction. This reduces overhead. Use N:N transactions for bulk work such as mass payouts. For example, one batch of 100 debits and 100 credits is often faster than 100 separate transactions. This works when the operations belong to the same logical set. Midaz processes these N:N transactions in one atomic commit.Monitoring and iterative scaling
Monitor the key metrics: transaction latency, throughput, resource use (CPU and memory), and database performance. Use the Midaz observability tools (OpenTelemetry and Grafana), or send the metrics to your own monitoring stack. Scale out or up before you reach a performance threshold. Midaz is modular and source-available, so you deploy the parts you need.Handling multi-currency and multi-entity Operations
Multi-currency strategies
Midaz supports multiple currencies with a separate account for each currency. Each transaction moves one asset. To scale well:- Configure every currency asset you need.
- Handle currency-specific logic (such as rounding and conversion rates) in your integration layer.
- For frequent currency conversion, such as forex trading, run the conversion in a separate service. Midaz records the debits and credits, but an external FX-rate service supplies the rates.
- You rarely need a separate ledger per currency, unless policy requires it. Instead, use account types and the transaction-routing API to group accounts by currency for clear reporting.
- If one currency covers most transactions, keep all currencies in the same ledger. If multi-currency operations grow too complex, split them into a separate ledger per currency group.
Multiple Entities: Consolidation and separation
For a bank that operates across countries or legal entities:- Use the organization hierarchy to segment entities. Give each entity its own base currency, local assets, and ledgers.
- Model inter-entity transactions as external movements. One organization credits its external account, and the other debits its own.
- You can run several organizations on one Midaz instance. Allocate enough resources: the same ledger instances process the requests of every organization, so total volume matters.
- You can deploy a separate Midaz instance per isolated entity, but you lose unified visibility. One cluster with internal organization separation is usually more practical.
Performance optimization best practices
Indexing and queries
Use the Midaz APIs to read data, not direct database queries. These APIs carry predefined indexes for the core identifiers: accounts, portfolios, and transactions.Indexing custom metadata fields
Create the indexes you need explicitly through the Metadata Index API. By default, Midaz does not index custom metadata fields. Clients fill these fields as flat key-value pairs. Frequent queries or filters on non-indexed fields can trigger full collection scans. These scans slow down as the data volume grows. Create an index when you regularly use a custom metadata field in search filters. With an index, MongoDB finds the documents fast and cuts query response time. Recommendations:- Index only the metadata fields you query often.
- Do not index rarely-accessed fields, because each extra index adds write overhead.