Documentation Hub

Python 3.14 implementation for the Rinha de Backend 2024/Q1 challenge. This site documents how the fictional bank API keeps the HTTP layer thin, pushes balance consistency into PostgreSQL stored procedures, and keeps k6 evidence tied to committed report pages and release-workflow artifacts.

Fast Paths

Wiki Pages

Implementation Signals

• The HTTP layer validates shape, client IDs, and request payloads before handing work to PostgreSQL.
• InsertTransacao() performs balance updates and limit checks atomically with row-level locking.
• GetSaldoClienteById() returns statement-ready JSON so the API can avoid heavy response shaping.
• NGINX uses least_conn to distribute load between two identical API instances.
• Release automation publishes GHCR images, runs container checks, executes k6, uploads the latest stress-test artifact, and deploys this documentation to GitHub Pages.

External Links

• GitHub repository
• Stress test reports
• Original challenge specification

GitHub · Jonathan Peris

Architecture

Tech Stack

Runtime Topology

client / k6
   │
   ▼
NGINX (:9999, least_conn, 0.2 CPU, 20MB)
├── webapi1-python (:8080, 0.4 CPU, 100MB) — Gunicorn 4w × 2t
├── webapi2-python (:8080, 0.4 CPU, 100MB) — Gunicorn 4w × 2t
└── PostgreSQL 16.7 (0.5 CPU, 330MB)
    ├── InsertTransacao() — atomic balance update + limit validation
    └── GetSaldoClienteById() — statement projection with JSONB

Request Flow

1. NGINX receives traffic on :9999 and routes to the API instance with the fewest active connections.
2. Flask validates the route, client ID, JSON payload shape, transaction type, and description length.
3. psycopg2 checks out a connection from a SimpleConnectionPool(1, 10) inside the API process.
4. PostgreSQL stored procedures perform the balance mutation or statement projection.
5. The API commits successful transactions, rolls back failures, returns the compact response, and releases the connection.

Services and Resource Envelope

Database Responsibilities

Business logic is implemented in PostgreSQL stored procedures (InsertTransacao, GetSaldoClienteById). The database owns the race-sensitive parts of the challenge:

• Atomic debit/credit application.
• Credit-limit rejection for invalid debit outcomes.
• Recent-transaction selection for statement responses.
• JSON-shaped statement data returned to the API.

The physical schema is also tuned for the benchmark workload:

For benchmark speed, the database is tuned with durability trade-offs:

• synchronous_commit=0 — do not wait for WAL flush.
• fsync=0 — skip fsync on writes.
• full_page_writes=0 — skip full-page writes.

These settings are useful for the contest-style load test and are not production-safe for real banking data.

Gunicorn Configuration

--workers=4 --threads=2 --worker-class=sync --bind=0.0.0.0:8080 --timeout=30

Each API container therefore exposes multiple synchronous workers while keeping the Python layer intentionally small: validation, stored-procedure calls, response mapping, and connection cleanup.

Challenge

Rinha de Backend 2024/Q1

The Rinha de Backend is a Brazilian backend programming challenge. The 2024/Q1 edition simulates a fictional bank called “Rinha Financeira” that manages up to 5 named clients, each seeded at startup with a credit limit and initial balance.

The interesting part is not the endpoint count; it is the combination of high write contention, strict response semantics, and a shared container budget small enough to punish waste.

Endpoint Contract

Transaction payload

{
  "valor": 1000,
  "tipo": "c",
  "descricao": "deposito"
}

Runtime validation in src/WebApi/app.py keeps the contract narrow:

• valor must be a positive integer value.
• tipo must be c for credit or d for debit.
• descricao must be a non-empty string with at most 10 characters.
• Client IDs are fixed to 1 through 5.

The runtime client table is intentionally static and mirrors the seed data in docker-entrypoint-initdb.d/rinha.dump.sql:

Consistency Requirement

Debit requests must never push a client past their configured credit limit. This implementation keeps that invariant in the database by calling InsertTransacao() for the balance update and limit check in one atomic operation.

Constraints

The challenge imposes strict resource limits across all containers combined:

The observability sidecars and k6 runner are useful during local experiments, but the challenge budget centers on the application stack under test.

Source

Full specification: github.com/zanfranceschi/rinha-de-backend-2024-q1

Getting Started

Prerequisites

• Docker with Docker Compose
• A local clone of this repository

Clone and Run

git clone https://github.com/jonathanperis/rinha2-back-end-python.git
cd rinha2-back-end-python
docker compose up nginx -d --build

The nginx service depends on the two API containers, and each API waits for PostgreSQL health before starting.

Access

The API is available at http://localhost:9999.

Smoke Check

curl http://localhost:9999/healthz

Expected response:

Healthy

Example Requests

Create Transaction

curl -X POST http://localhost:9999/clientes/1/transacoes \
  -H "Content-Type: application/json" \
  -d '{"valor": 1000, "tipo": "c", "descricao": "deposito"}'

The response includes the client’s credit limit and updated balance:

{
  "limite": 100000,
  "saldo": 1000
}

Get Statement

curl http://localhost:9999/clientes/1/extrato

The statement response contains the current balance envelope and the recent transaction list:

{
  "saldo": {
    "total": 1000,
    "limite": 100000,
    "data_extrato": "2026-04-01T07:36:51"
  },
  "ultimas_transacoes": [
    { "valor": 1000, "tipo": "c", "descricao": "deposito" }
  ]
}

Run Stress Tests

docker compose up k6 --build --force-recreate

The compose file supports a local observability loop with InfluxDB, Prometheus, Grafana, postgres-exporter, and the k6 web dashboard. The k6 service defaults to MODE=dev for local dashboard/export behavior; the production compose file uses MODE=prod and writes ./prod/conf/stress-test/reports/stress-test-report.html, which main-release.yml uploads as the stress-test-report workflow artifact.

Dev vs Production Compose

Local Observability Ports and Credentials

Set the InfluxDB values before starting k6/observability services, for example:

export INFLUXDB_PASSWORD=local-rinha-password
export INFLUXDB_TOKEN=local-rinha-token

Troubleshooting Checklist

Stop the Stack

docker compose down

Add -v when you intentionally want to remove the PostgreSQL volume and start from a fresh seed state.

Performance

Resource Constraints

The challenge allows a total of 1.5 CPU and 550MB RAM across the application containers. This repository spends that budget on two API instances, PostgreSQL, and NGINX:

Optimization Shape

The implementation optimizes for the contest workload by keeping each layer focused:

• Thin Python path: Flask validates input and delegates consistency-sensitive work to SQL.
• Database-owned invariants: InsertTransacao() handles balance updates and limit rejection atomically.
• Compact statement reads: GetSaldoClienteById() returns statement data already shaped for the API response, ordered by Id DESC and limited to the latest 10 rows.
• Two API replicas: NGINX uses least_conn so a busy worker pool does not become the only ingress path.
• Durability trade-offs: PostgreSQL write-safety settings are relaxed for benchmark throughput, not for production banking data.
• UNLOGGED hot tables: Clientes and Transacoes are unlogged, and Transacoes uses fillfactor = 90, trading crash durability for faster contest writes.
• Targeted statement index: IX_Transacoes_ClienteId_Id_Desc backs the per-client latest-transaction lookup pattern.

Reading the Reports

Published reports are the source of truth for run-level performance evidence:

• Stress test report index lists committed historical HTML reports from docs/public/reports/.
• New non-doc mainline releases also upload a fresh stress-test-report artifact from the production k6 run; promote artifacts into docs/public/reports/ only when you want them to become part of the published historical archive.
• Compare published reports and workflow artifacts by commit context and workflow timing, not just by a single latency number.

When evaluating a run, inspect:

Benchmark Interpretation

This is a deliberately constrained system, so performance conclusions should stay tied to the workload:

1. Local Docker and GitHub-hosted runners can be noisy.
2. PostgreSQL tuning favors contest throughput over durability.
3. The Python layer is intentionally not a business-logic engine; moving limit checks out of SQL would change the contention model.
4. A good report is both fast and correct: successful status codes and stable statement semantics matter as much as latency.

Useful Next Reads

• Architecture for the runtime and stored-procedure boundaries.
• CI/CD Pipeline for how reports are produced, uploaded, and published.
• Reports for archived k6 HTML output.

CI/CD Pipeline

Workflows

This repository uses four GitHub Actions workflows:

Pull Request Gate

PRs validate the container path before merge:

1. Check out the full repository.
2. Build and start the development Compose stack with docker compose -f ./docker-compose.yml up nginx --wait.
3. Probe http://localhost:9999/healthz once after Compose reports the service ready.
4. Run CodeQL for Python security-and-quality analysis.

This catches container build failures, dependency regressions, and startup problems before they reach main.

Main Release

main-release.yml is the image-and-artifact workflow. On a non-doc push to main, it:

1. Builds and pushes the amd64 image as ghcr.io/jonathanperis/rinha2-back-end-python:latest.
2. Builds and pushes the arm64 image as ghcr.io/jonathanperis/rinha2-back-end-python:latest-arm64.
3. Merges both digests into the multi-architecture latest manifest.
4. Starts the production compose stack and retries /healthz up to 20 times.
5. Runs k6 with prod/docker-compose.yml (MODE=prod).
6. Uploads ./prod/conf/stress-test/reports/stress-test-report.html as the stress-test-report Actions artifact.

The workflow intentionally ignores docs/** pushes, so documentation-only merges deploy Pages without rebuilding images or running k6.

Report Publication Model

There are two report lanes:

A release artifact does not automatically rewrite the committed Pages archive. Promote a new artifact into docs/public/reports/ only when it should become part of the public historical record.

Pages Deployment

deploy.yml publishes the static documentation site to GitHub Pages from the docs/ package. The published site includes:

• The homepage proof narrative.
• The docs hub and wiki pages.
• The stress-test report index.
• Committed historical k6 HTML reports.

After a docs PR merges to main, the deployment run should complete before the live URL is treated as updated.

Release Evidence Loop

PR branch
  ├─ build-check.yml validates container startup
  └─ codeql.yml scans the change
       │
       ▼
main merge
  ├─ main-release.yml builds images + runs k6 + uploads report artifact
  │   └─ skipped for docs/**-only pushes
  └─ deploy.yml publishes docs and committed report archive to Pages

Where to Look

• GitHub Actions for workflow status.
• Stress test reports for committed historical k6 output.
• GHCR package for published images.