₹ Payflow API¶
Enterprise Transaction & Double-Entry Payment Ledger Engine¶
A high-concurrency peer-to-peer payment backend built with Java 25 and Spring Boot 4.1.0.
Guaranteed zero double-spending • Deterministic row locking • Distributed Redisson locks • Immutable balance ledger • Transactional Outbox & Kafka streaming
🚀 Key Architectural Pillars¶
| Architectural Pillar | Core Guarantee & Engineering Mechanics |
|---|---|
| 🔒 Concurrency Safety | Row-level pessimistic write locking (SELECT ... FOR UPDATE) paired with deterministic alphabetical lock ordering by UPI ID, eliminating race conditions and deadlocks during concurrent account debits and credits. |
| 📜 Double-Entry Ledger | Atomic paired DEBIT and CREDIT records with strict base-10 BigDecimal arithmetic precision denominated in Indian Rupees (INR, symbol: ₹, scale = 4) and Banker's Rounding (HALF_EVEN), preserving an immutable financial audit trail. |
| 🔁 Durable Idempotency | Mandatory Idempotency-Key headers (validated 255-char regex boundary) backed by raw SHA-256 payload hashing to prevent tampering, coupled with Redisson distributed locking (payflow:lock:idemp:{key}) to coordinate mutations across multi-instance clusters. |
| 🛡️ Resilience & Fault Tolerance | Dynamic per-user rate limiting (10 req/s, RFC 6585 Retry-After: 1), Resilience4j circuit breaking on external banking rails, bounded timeouts, and automatic memory eviction of inactive limiter buckets. |
| ⚡ Transactional Outbox | Spring Modulith Event Publication Registry atomically persisting domain events (TransferCompletedEvent) within the database transaction, bridging to Apache Kafka without dual-write inconsistency, with automated background retention cleanup (OutboxCleanupService). |
| 🔐 Zero-Trust Security | Stateless HMAC-SHA256 JWT tokens with fail-fast production secret validation, strict principal-bound sender verification, role-based access control (ROLE_ADMIN on user enumeration), clickjacking defense (sameOrigin), and RFC 9457 ProblemDetail error responses. |
| 📊 Enterprise Observability | Native Elastic Common Schema (ECS) JSON structured logging, MDC trace correlation (requestId, traceId, spanId), Prometheus metrics, and profile-conditional Redis distributed caching with targeted cache eviction and Caffeine local fallback. |
| 🤖 Gen-AI Spend Insights | Spring AI 2.0.1 integration providing automated expenditure classification and contextual budgeting tips with structured JSON output, guarded by Resilience4j circuit breakers and deterministic keyword heuristic fallback. |
| 🚀 Virtual Threads & Concurrency | Java 25 Project Loom Virtual Threads enabled globally (spring.threads.virtual.enabled: true), with bounded HikariCP connection pool configurations and a low-memory prod-light profile designed for <= 1 GiB single-node production environments. |
| 🐳 Cloud-Native Orchestration & Quality Gates | Hardened multi-stage Docker build (eclipse-temurin:25-jre, unprivileged payflow:10001 user), full-stack Docker Compose (PostgreSQL 17, Redis 7, Kafka KRaft, Ollama, Prometheus, Grafana), Kubernetes HPA/PDB topology with zero-downtime graceful shutdown, SpotBugs static analysis, and automated JaCoCo coverage enforcement (90% Line / 73% Branch). |
🏗️ System Architecture Overview¶
📐 View Declarative D2 Diagram Source
📚 Project Documentation Hub¶
| Document | Description |
|---|---|
| 📊 Code Coverage & Quality Gates | Automated CI/CD quality gates, bundle-level line/branch thresholds, and SpotBugs audit |
| 🚀 Interactive JaCoCo Report | Live interactive code coverage drilldown (90% Line, 73% Branch) generated per-build |
| 📘 System Architecture | Deep-dive concurrency models, pessimistic locking mechanics, test pyramid |
| 🛡️ Security Architecture & Threat Model | Zero-Trust filter chain, STRIDE threat model, IAM policy matrix, financial concurrency controls |
| 🌐 REST API Specification | Complete REST endpoint contracts, schemas, RFC 9457 ProblemDetail payloads |
| 🗓️ Phased Roadmap | Full 12-phase technical expansion blueprint and milestone statuses |
| 📋 Engineering Conventions | Java 25 standards, Spotless/Checkstyle rules, testing guidelines |
| 📜 Architecture Decisions (ADRs) | Master index of modular architectural decision records (ADR-001 through ADR-030) |
| 📝 Changelog | Version-by-version implementation notes |
| 🔒 Security Policy | Open-source vulnerability reporting guidelines and project security posture |
| 🤝 Contributing Guide | Development environment setup and pull request requirements |
⚡ Quick Start¶
- Swagger UI Interactive Docs: http://localhost:8080/swagger-ui.html
- OpenAPI 3.0 JSON Specification: http://localhost:8080/v3/api-docs
- H2 Console: http://localhost:8080/h2-console (
jdbc:h2:mem:payupidb, Credentials:user/user)
# Spin up complete distributed stack (Postgres, Redis, Kafka, Ollama, Prometheus, Grafana)
docker compose up -d --build
- Payflow API: http://localhost:8080
- Prometheus: http://localhost:9090
- Grafana: http://localhost:3000 (Credentials:
admin/admin) - Ollama AI: http://localhost:11434
- Cluster Workloads: ConfigMap, Secrets, and Deployment with rolling update strategy
- Horizontal Pod Autoscaler (HPA): Min 2, max 10 replicas based on 70% CPU / 80% Memory
- High Availability: Pod Disruption Budget (PDB) with
minAvailable: 1
# Execute full verification pipeline: Spotless, Checkstyle, SpotBugs, Tests & JaCoCo gates
mvn clean verify -DskipITs
- Spotless: Code formatting verification
- Checkstyle: Enterprise static code linting
- SpotBugs: Bytecode bug pattern analysis
- JaCoCo: Quality gates requiring >= 80% line and >= 70% branch coverage (90% / 73% achieved across 191 tests)