High-Performance Balance Management Service

Java 21 · Maven · gRPC · RocksDB · Speedb

gRPC + RocksDB

This repository contains a high-performance, stateful backend service designed for balance and ledger processing in real-time, distributed systems.

The service uses gRPC for low-latency communication and RocksDB as an embedded storage engine.
It is optimized for extreme throughput, correctness, and deterministic behavior under concurrent load.

This project represents a production-inspired reference implementation of architectural and performance patterns used in large-scale backend platforms.

---

Key Features

• High-throughput gRPC-based APIs
• Stateful balance processing with atomic updates
• RocksDB-backed storage with sharding to reduce contention
• Idempotent request handling and deduplication
• Deterministic request execution
• Designed for integration with event-driven systems (e.g. Kafka, message brokers)

---

Architecture Overview

The service is designed as a standalone platform component, decoupled from domain-specific logic (e.g. games or UI).

High-level architecture:

• gRPC request/response interface
• Sharded state storage backed by RocksDB
• Deterministic processing pipeline:
  • request validation
  • state lookup
  • atomic mutation (WriteBatch)
  • persistence
  • response generation
• Optional event emission to downstream systems

This separation allows the service to be reused across multiple systems requiring high-throughput, low-latency state updates.

---

Performance Characteristics

The system was evaluated across different execution paths to distinguish network/serialization overhead from full persistent state updates.

gRPC Transport Layer (In-Memory Processing)

• ~80M requests/second throughput for the pure gRPC layer (request parsing, validation, and in-memory processing without persistence).

Persistent Execution Path (State Mutation + Storage)

• ~4M requests/second sustained throughput
• 8–9M requests/second peak throughput

Measured during full round-trip execution: (request → processing → state mutation → persistence → response)

Latency characteristics:

• Single-digit millisecond p95 latency under sustained load

Test Environment (Representative)

• CPU: multi-core server (16 cores / 32 threads)
• Storage: NVMe SSD (~500 GB)
• Storage engines: RocksDB, later migrated to Speedb

Performance numbers are based on controlled load testing and live traffic observations. Exact results may vary depending on workload, configuration, and hardware.

---

Design Considerations

Atomicity

State updates are applied atomically using RocksDB WriteBatch, ensuring correctness for money-related workflows.

Idempotency

Duplicate or retried requests are safely deduplicated, preventing double-application of balance changes.

Sharding

State is partitioned across shards to minimize lock contention and improve scalability.

Determinism

For identical inputs, request processing produces consistent results, enabling safe retries and predictable behavior.

---

Use Cases

This service can be used as a backend component for:

• Balance and ledger management
• Transaction processing
• High-throughput state mutation services
• Financial or gaming platforms requiring strict correctness guarantees

---

Quickstart

Requirements

• Java 21
• Maven 3.9+

Build (multi-module)

mvn -B -ntp clean package

Run Server

java -jar grpc-server/target/grpc-server-1.0-SNAPSHOT.jar

Run Client

java -jar grpc-client/target/grpc-client-1.0-SNAPSHOT.jar

Status

This repository serves as a reference implementation demonstrating architectural and performance techniques used in production systems.

Selected components are shared for educational and demonstration purposes.

---

Disclaimer

This project is not intended as a drop-in production solution.
It is provided to showcase system design, concurrency models, and performance-oriented engineering approaches.

---

Author

Raim Beketov
Backend / Platform Engineer
https://github.com/aimov6464