Structuring entities for High Transaction Volumes
Partitioning by Organizations, Ledgers, and Accounts
Does your bank process 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. Midaz processes the transactions in a ledger together. This split stops a single ledger from becoming a bottleneck. Midaz scales out: different ledgers can run on separate instances or database partitions.Lock-oriented Operations
Midaz applies each balance change atomically, with a single writer per balance. This prevents race conditions on the same account. Each balance carries a version. The version guards the overdraft calculation against a stale read of the 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
Midaz uses a microservices architecture. You scale each component on its own — for example, transaction processing and queries. Start small. As demand grows, scale the services that need it. For high loads, deploy several instances of the transaction 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. Reads do not slow down writes, and writes do not slow down reads.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 multi-currency transactions with a separate asset account for each currency. 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 microservices process all requests together, 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
Metadata collections already index the system-defined keys. This keeps internal operations fast. By default, Midaz does not index custom metadata fields. Clients fill these fields freely as 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 or sort order. With an index, MongoDB finds the documents fast and cuts query response time. Recommendations:- Index only the metadata fields you query or sort on often.
- Do not index rarely-accessed fields, because each extra index adds write overhead.