Architecture Decision Records (ADR) and technical RFCs: what they are and why version-control them

# ADR-003: Use Kafka for Inter-Service Events

## Status
Accepted (2024-01-15)

## Context
The account-ledger and fraud-detection services at National Bank of India
need to communicate asynchronously. The ledger publishes account events
(deposits, withdrawals, transfers) and the fraud service consumes them.
We need reliable, ordered, high-throughput event delivery.

## Decision
We will use Apache Kafka as the event backbone.

## Alternatives Considered
- **RabbitMQ** -- simpler setup but lacks log-based replay and
  partition-level ordering at high throughput.
- **AWS SQS + SNS** -- managed but no ordering guarantees within
  a partition and no replay from offset.
- **Direct REST calls** -- synchronous coupling, no buffering,
  a fraud-service outage would block ledger writes.

## Consequences
- **Easier:** Replay from any offset for debugging and reprocessing.
  Partition-key ordering by account_id. High throughput.
- **Harder:** Operational overhead of managing a Kafka cluster
  (or cost of a managed service). Team must learn consumer
  group semantics and offset management.

# RFC: Migrate Settlement from Overnight Batch to Near-Real-Time

## Author
Pankaj (Architect)

## Motivation
The current overnight batch settlement means customers do not see
transfer results until the next business day. Competitors offer
near-real-time settlement. Customer complaints have increased 40%.

## Proposed Design
Replace the nightly batch job with a Kafka-driven event pipeline.
Each transfer event triggers immediate settlement processing.
Use Kafka transactions to ensure exactly-once semantics.

## Alternatives
1. Optimize the batch to run every hour (lower risk, still not real-time)
2. Use AWS Step Functions for orchestrated settlement (vendor lock-in)

## Risks
- Higher operational complexity with streaming infrastructure.
- Requires idempotent settlement logic to handle replays.

## Migration Path
Phase 1: Dual-write to batch and stream. Phase 2: Switch reads.
Phase 3: Decommission batch.

## Open Questions
- What is the acceptable latency SLA for near-real-time?
- Do we need to support replay of settlement events for auditing?

# ADRs live in the repo, versioned like code
ls docs/adr/

001-use-postgresql-for-ledger.md
002-use-bigdecimal-for-money.md
003-use-kafka-for-events.md
004-settlement-near-real-time.md

# Who decided and when?
git log --oneline docs/adr/003-use-kafka-for-events.md

abc1234 Pankaj   2024-01-15  Accept ADR-003: Use Kafka for events
def5678 Rajesh   2024-01-12  RFC: propose Kafka for inter-service events

package com.bank.ledger.event;

import java.math.BigDecimal;

/**
 * This event class exists because of ADR-003.
 * We chose Kafka over SQS for ordered, replayable events.
 * See docs/adr/003-use-kafka-for-events.md for the full reasoning.
 */
public record AccountEvent(
    String accountId,
    String eventType,
    BigDecimal amount,
    String correlationId
) {}

# ADR-005: Switch from Kafka to AWS MSK Serverless

## Status
Accepted (2024-06-01)
Supersedes: ADR-003

## Context
Managing a self-hosted Kafka cluster proved operationally expensive.
AWS MSK Serverless removes cluster management while preserving
Kafka's API and ordering guarantees.

## Decision
Migrate to AWS MSK Serverless.

## Consequences
- **Easier:** No cluster management, automatic scaling.
- **Harder:** Vendor lock-in to AWS, slightly higher per-message cost.

# Auditor asks: "Why is customer data encrypted at rest?"
git log docs/adr/002-encrypt-customer-data.md

abc1234 2023-09-10 Pankaj   Accept ADR-002: Encrypt all customer data at rest
  Reviewed-by: Rajesh, Priya (Security)
  Approved in PR #128

# WRONG -- no ADR written
"We use Kafka because... I think Pankaj said so in a meeting?"

# CORRECT -- ADR in Git
"We use Kafka because of ADR-003: ordered, replayable events.
 See docs/adr/003-use-kafka-for-events.md"