How wepay/waltz works
Waltz is a distributed, replicated write-ahead log for transactions. The main workflow is an application submitting transactions through the client API; Waltz servers coordinate replicated partitions backed by storage nodes, while clients can retrieve transaction data. Storage also exposes administrative operations, and the tools include storage recovery. The README documents the client/server/storage cluster and ZooKeeper-based test setup. Some server and client internals were not sampled, so unverified call paths are omitted; the graph emphasizes relationships visible in excerpts or documented in the README.
Main entry points: StorageManager.java Storage manager · RecoveryManagerImpl.java Replica recovery · WaltzStorage.java Storage service · StorageClient.java Storage client
Components 21
Client API
- Waltz client
waltz-client/src/main/java/com/wepay/waltz/client/WaltzClient.java - Transaction access
waltz-client/src/main/java/com/wepay/waltz/client/Transaction.java - RPC client
waltz-client/src/main/java/com/wepay/waltz/client/internal/RpcClient.java
Server Replication
- Waltz servers
waltz-server/src/main/java/com/wepay/waltz/server/WaltzServer.java - Request handling
waltz-server/src/main/java/com/wepay/waltz/server/internal/WaltzServerHandler.java - Replica recovery
waltz-server/src/main/java/com/wepay/waltz/store/internal/RecoveryManagerImpl.java - Replica connection
waltz-server/src/main/java/com/wepay/waltz/store/internal/ReplicaConnection.java - Replica session
waltz-server/src/main/java/com/wepay/waltz/store/internal/ReplicaSession.java
Storage Engine
- Storage service
waltz-storage/src/main/java/com/wepay/waltz/storage/WaltzStorage.java - Storage manager
waltz-storage/src/main/java/com/wepay/waltz/storage/server/internal/StorageManager.java - Storage partition
waltz-storage/src/main/java/com/wepay/waltz/storage/server/internal/Partition.java - Storage client
waltz-storage/src/main/java/com/wepay/waltz/storage/client/StorageClient.java - Storage admin
waltz-storage/src/main/java/com/wepay/waltz/storage/client/StorageAdminClient.java - Segment storage
waltz-storage/src/main/java/com/wepay/waltz/storage/server/internal/Segment.java
Shared Protocol
- Transaction records
waltz-common/src/main/java/com/wepay/waltz/common/message/Record.java - Request IDs
waltz-common/src/main/java/com/wepay/waltz/common/message/ReqId.java - Storage protocol
waltz-storage/src/main/java/com/wepay/waltz/storage/common/message/StorageMessageCodecV0.java
Operations
- Storage CLI
waltz-tools/src/main/java/com/wepay/waltz/tools/storage/StorageCli.java - Offline recovery
waltz-tools/src/main/java/com/wepay/waltz/tools/storage/StorageRecoveryRunnable.java
Other components
- Application
- ZooKeeper
Connections 15
- Application → Waltz client: submits transactions
- Waltz client → Waltz servers: sends transactions
- Transaction access → RPC client: fetches data
waltz-client/src/main/java/com/wepay/waltz/client/Transaction.java - Replica recovery → Replica connection: uses
waltz-server/src/main/java/com/wepay/waltz/store/internal/RecoveryManagerImpl.java - Replica recovery → Replica session: uses
waltz-server/src/main/java/com/wepay/waltz/store/internal/RecoveryManagerImpl.java - Storage service → Storage manager: configures
waltz-storage/src/main/java/com/wepay/waltz/storage/WaltzStorage.java - Storage manager → Storage partition: opens
waltz-storage/src/main/java/com/wepay/waltz/storage/server/internal/StorageManager.java - Storage manager → Segment storage: manages partitions
- Storage client → Transaction records: transfers records
waltz-storage/src/main/java/com/wepay/waltz/storage/client/StorageClient.java - Storage client → Storage protocol: encodes messages
waltz-storage/src/main/java/com/wepay/waltz/storage/client/StorageClient.java - Storage CLI → Storage admin: assigns partitions
waltz-tools/src/main/java/com/wepay/waltz/tools/storage/StorageCli.java - Offline recovery → Storage admin: reads source records
waltz-tools/src/main/java/com/wepay/waltz/tools/storage/StorageRecoveryRunnable.java - Offline recovery → Replica connection: writes destination
waltz-tools/src/main/java/com/wepay/waltz/tools/storage/StorageRecoveryRunnable.java - Storage CLI → ZooKeeper: reads cluster metadata
waltz-tools/src/main/java/com/wepay/waltz/tools/storage/StorageCli.java - Storage service → ZooKeeper: uses cluster metadata