Account & Transaction API (Vert.x)

This project is a showcase of a high-performance, asynchronous sample REST API for managing financial accounts and transactions, built using the Vert.x toolkit. It serves as a demonstration of a fast, non-blocking, event-driven service suitable for financial low latency applications.

Features

• Asynchronous & Non-Blocking: Built on the Vert.x event loop to handle high concurrency with minimal resource usage.
• Account Management: Create and retrieve customer accounts.
• Transaction Processing: Post financial transactions (purchases, payments, etc.) against accounts.
• OpenAPI Documented: Includes a full openapi.yml specification.
• Comprehensive Tests: Includes unit, integration, and high-concurrency performance tests.
• SQL Database: Uses an H2 in-memory database, initialized on startup via schema.sql and data.sql.

Tech Stack

• Toolkit: Vert.x
• Language: Java 25+
• Build: Apache Maven
• Database: H2 (In-Memory)
• Testing: JUnit 5, Vert.x JUnit 5, Mockito
• API: Vert.x Web, Vert.x Web OpenAPI

Run Instructions

Prerequisites

• Java JDK 25 (or newer)
• Apache Maven 3.8.x (or newer)

Build the Project

Clone the repository and build the project using Maven. This will also run all the unit and integration tests.

# Navigate to the project root
cd pismo-account-transaction/

# Clean, compile, test, and package the application
mvn clean install

# Run the performance test
mvn test -Dtest=HttpApiPerformanceTest

Performance

Test Environment

The performance test was executed on a cheap(~150£) low powered GMKtec mini PC with the following specifications:

Component	Specification
CPU	Intel(R) N150 (4 cores, Max clock observed at ~3.04 GHz)
Memory	16 GB RAM
Operating System	OpenSuse Tumbleweed Linux 6.17.5-1-default (x86_64)
JVM	OpenJDK Java 25
Framework	Vert.x 5.0.5
Database	H2 embedded database (used during test)

Performance Test Results

The performance test targeted the I/O-intensive GET /accounts/{accountId} endpoint to stress the application's throughput under high concurrency (50,000 requests).

Metric	Value
Total Requests	50,000
Total Time	9,926,000 $\mu$s (9,926 ms)
Requests per Second (Throughput)	5,037.28 reqs/second
Average Latency	198.5 $\mu$s (0.1985 ms)

---

Analysis

The results confirm the application's high performance, demonstrating low latency and high throughput characteristic of the Vert.x reactive programming model.

1. High Throughput and Low Latency: The API sustains over 5,000 requests per second with an average latency of 198.5 $\mu$s (sub-200 $\mu$s), confirming the efficiency of asynchronous processing.
2. The JDBC Bridge Note: The application uses the H2 embedded database via the vertx-jdbc-client. Since H2 is a blocking database, the vertx-jdbc-client employs an internal JDBC bridge with a worker thread pool. This mechanism is crucial: it offloads the blocking I/O of the database to dedicated worker threads, ensuring the main Vert.x Event Loop remains non-blocking and highly responsive. This design effectively masks the blocking nature of H2.
3. Production Context: It is important to consider that H2 is running in-memory for this test. In a production scenario with a remote database (like PostgreSQL or MySQL) and network latency, the overall transaction time would increase. However, in the case of switch to MySQL or PostgreSQL it would be possible switching to a native reactive SQL client (e.g., vertx-pg-client) and eliminate the thread-pooling overhead of the JDBC bridge.