Rinha de Backend - 2025: Java Solution

This is the backend application developed for the Rinha de Backend - 2025 challenge. The solution is built in Java and Spring Boot, and it is designed for high concurrency and resilience under strict resource constraints.

---

Technologies Used

• Language: Java 21
• Framework: Spring Boot 3.5.3
• Web Server: Tomcat (embedded in Spring Boot)
• Database: PostgreSQL 16
• HTTP Client: Spring WebClient (Project Reactor)
• Load Balancer: Nginx
• Containerization: Docker and Docker Compose
• Other: Lombok (for boilerplate reduction), Maven

---

Solution Architecture

The solution is a multi-container application orchestrated by Docker Compose. The architecture is designed to handle high-volume requests and manage external service dependencies reliably.

• api1 and api2: Two instances of a Spring Boot application, running on a standard JVM. They are responsible for processing business logic, handling communication with external services, and interacting with the database.
• db: A single PostgreSQL instance that serves as a shared, persistent data store for both API instances.
• nginx: This service acts as a load balancer and reverse proxy. It distributes all incoming client requests on port 9999 to either the api1 or api2 instance, ensuring even load distribution and high availability.
• External Payment Processors: The payment-processor-default and payment-processor-fallback services are external dependencies that are started separately but are connected to the same Docker network as the API instances.

---

Payment Routing Strategy

The application implements a dynamic and resilient strategy to choose which external Payment Processor to use for each transaction.

1. Health Checks: A scheduled task runs periodically (e.g., every 30 seconds for local development) to check the health status of both the Default and Fallback processors via their /payments/service-health endpoints. The results are cached in memory.
2. Dynamic Selection: When a POST /payments request is received, the application's logic prioritizes processors based on the cached health data:
   • If both processors are healthy, the one with the lowest minResponseTime is chosen to optimize for performance.
   • If only one processor is healthy, that one is chosen.
   • If both are unhealthy, the application defaults to attempting the Default processor and relies on its resilience mechanisms to handle the failure gracefully.
3. Resilience: The WebClient calls to external processors are configured with a 2-second timeout and 1 retry attempt. This prevents the application from hanging on slow or transiently failing external services, ensuring a responsive and stable API.

---

How to Run the Solution Locally

To get the complete solution running on your local machine, follow these steps.

1. Prerequisites: Ensure you have Docker Desktop and Git installed.

2. Clone the Rinha Repository: First, clone the official Rinha challenge repository:

   git clone https://github.com/zanfranceschi/rinha-de-backend-2025.git

3. Start External Payment Processors:

   • Navigate into the payment processors directory of the cloned repository:

     cd rinha-de-backend-2025/payment-processor

   • Start the services (for Mac M-series, use the arm64 file):

     docker compose -f docker-compose-arm64.yml up -d

   • You can verify they're running by checking docker ps or by visiting http://localhost:8001/payments/service-health in your browser.

4. Build Your Backend Application's Docker Image:

   • Navigate to the root of your Java project (rinha-backend):

     cd /path/to/your/rinha-backend 

   • Build the Docker image:

     docker build -t rinha-backend-app .

5. Navigate to Your Submission Directory:

   • Go to your solution's folder within the Rinha repository.

     cd rinha-de-backend-2025/participantes/your-name-java 

6. Start Your Backend Solution:

   docker compose up -d

   • All services should start. Verify by running docker ps.

7. Test the Application (via cURL):

   • Purge Payments: curl -X POST http://localhost:9999/purge-payments -H 'Content-Type: application/json'
   • Process Payment: curl -X POST http://localhost:9999/payments -H 'Content-Type: application/json' -d '{"correlationId": "a-unique-uuid", "amount": 123.45}'
   • Payment Summary: curl http://localhost:9999/payments-summary