Skip to content

Architecture Decision Records (ADRs)

This directory contains the formal log of all architectural decisions made for the Payflow API payment engine, adhering to standard Architecture Decision Record (ADR) conventions used in production engineering organizations.

Each record documents the business and technical context, options evaluated, rationale for the chosen decision, and resulting trade-offs.

📑 ADR Index

ADR # Title Date Status Phase
0001 Use BigDecimal for All Monetary Values 2026-08-01 Accepted Phase 2A
0002 Constructor Injection Over Field Injection 2026-08-01 Accepted Phase 2A
0003 Rich Domain Model Over Anemic Domain Model 2026-08-01 Accepted Phase 2A
0004 URI-Based API Versioning and DTO Isolation Layer 2026-08-01 Accepted Phase 2B
0005 MapStruct for Compile-Time Type-Safe DTO Mapping 2026-08-02 Accepted Phase 2C
0006 RFC 7807 ProblemDetail & Centralized Exception Handling 2026-08-03 Accepted Phase 2D
0007 UUID Reference IDs Over Auto-Increment Primary Keys in APIs 2026-08-05 Accepted Phase 2E
0008 Spring Modulith Modular Monolith Over Distributed Microservices 2026-08-07 Accepted Phase 6B
0009 OpenTelemetry Distributed Tracing via Micrometer Bridge 2026-08-07 Accepted Phase 8A
0010 Pessimistic Locking for High-Concurrency Balance Operations 2026-08-07 Accepted Phase 3B
0011 Deterministic Lock Ordering for Deadlock Prevention 2026-08-07 Accepted Phase 3B
0012 Double-Entry Balance Ledger as Immutable Audit Trail 2026-08-09 Accepted Phase 3C
0013 Flyway Database Migrations Over DDL Auto-Generation 2026-08-10 Accepted Phase 4A
0014 Spring Environment Profiles and Testcontainers Integration Testing Strategy 2026-08-11 Accepted Phase 4B
0015 SHA-256 Request Payload Hashing & Durable Database-Backed Idempotency Engine 2026-08-15 Accepted Phase 6A
0016 Spring Modulith Event Publication Registry & Transactional Outbox Pattern 2026-08-16 Accepted Phase 6B
0017 Stateless JWT Authentication & Spring Security Architecture 2026-08-17 Accepted Phase 7A
0018 Principal-Bound Resource Access Control & Sender Verification 2026-08-18 Accepted Phase 7B
0019 Declarative HTTP Interface Client (RestClient) & Resilient External Service Integration 2026-08-26 Accepted Phase 7C
0020 Structured Logging, Prometheus Metrics & OpenTelemetry Observability Architecture 2026-08-27 Accepted Phase 8A
0021 Resilience4j Circuit Breaking, Per-User Rate Limiting & Fault-Tolerance Policies 2026-09-05 Accepted Phase 8B
0022 Redis Distributed Caching and Caffeine Local Fallback Strategy 2026-09-06 Accepted Phase 8C
0023 Redis Distributed Locking with Redisson and Fail-Safe Local Fallback 2026-09-07 Accepted Phase 8D
0024 Kafka Event Streaming via Spring Modulith Event Externalization 2026-09-10 Accepted Phase 9A
0025 Production Hardening, Targeted Cache Invalidation, and Enterprise Security Controls 2026-09-20 Accepted Phase 9B
0026 Gen-AI Spend Categorization with Spring AI and Circuit Breaker Fallback 2026-09-28 Accepted Phase 10A
0027 Java 25 Virtual Threads and Bounded HikariCP Connection Pool Optimization 2026-09-28 Accepted Phase 10B
0028 Multi-Stage Containerization and Full-Stack Docker Compose Orchestration 2026-09-29 Accepted Phase 11A
0029 Cloud-Native Kubernetes Deployment Topology and Horizontal Pod Autoscaling 2026-09-29 Accepted Phase 11B
0030 Automated CI/CD Quality Gates, JaCoCo Coverage Enforcement, and SpotBugs Static Analysis 2026-09-29 Accepted Phase 11C

🔮 Planned ADRs (Roadmap)

ADR # Title Target Phase Status
0031 Distributed Chaos Engineering and Automated Fault Injection Phase 12 Planned

🏛️ ADR Process & Guidelines

  1. Format: Every ADR follows the lightweight format comprising:
  2. Title & Metadata: Sequence number, title, date, status, and associated development phase.
  3. Context & Problem Statement: The architectural or engineering challenge being addressed.
  4. Considered Options: The technical alternatives evaluated with pros and cons.
  5. Decision Outcome & Rationale: The chosen option and the explicit reasons for selection.
  6. Consequences: Positive architectural outcomes, trade-offs, and risk mitigations.
  7. Immutability: Once an ADR is marked as Accepted, its content remains immutable. If an architectural decision changes in the future, a new ADR is authored that explicitly supersedes the earlier record.