# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Build & Run Commands

```bash
# Build
./gradlew build

# Run the application
./gradlew bootRun

# Run tests
./gradlew test

# Run a single test class
./gradlew test --tests "com.test.payment.PaymentApplicationTests"

# Clean build
./gradlew clean build
```

Requires JDK 21 to run Gradle (Gradle 8.14 cannot run on JDK 25; set `JAVA_HOME` accordingly).
The app starts on port 8091 (`server.port`). Swagger UI is at `http://localhost:8091/swagger-ui.html`.
Redis is optional at runtime (`docker run -d --name mpesa-redis -p 6379:6379 redis:7-alpine`) — the app degrades gracefully without it.

## Architecture Overview

Spring Boot 4 / Java 21 reactive (WebFlux) multi-provider mobile-money service (M-Pesa STK Push, Airtel Money, MTN MoMo), using **JPA/Hibernate over PostgreSQL** for persistence, Redis (Lettuce) for token caching, and Resilience4j for fault tolerance.

**Blocking persistence under a reactive web layer.** HTTP, WebClient and Resilience4j stay reactive; JPA blocks. The bridge is a facade/store split — `PaymentLifecycleService` and `PaymentLimitService` keep their `Mono`/`Flux` API and hand each unit of work to `PaymentLifecycleStore` / `PaymentLimitStore` via `Mono.fromCallable(...).subscribeOn(Schedulers.boundedElastic())`. The stores are separate beans on purpose: `@Transactional` goes through a Spring AOP proxy that self-invocation would bypass (same trap as the Resilience4j annotations). **Never call a repository from the event loop, and never hold a transaction across a provider HTTP call** — `checkStatus` deliberately enters the store, exits, queries the provider, then re-enters.

**Layering (same shape for every provider):**
`<Provider>Controller` → `<Provider>Service` (implements `PaymentProviderService`; parses provider payloads) → `PaymentLifecycleService` (ALL persistence: initiation/response/callback/transaction, dedup, status transitions) and `<Provider>Client` (resilience-wrapped HTTP) → provider API.

**Endpoints** (identical pattern per provider under `/api/mpesa`, `/api/airtel`, `/api/mtn`):
- `POST /pay` — validated request; persists an initiation, calls the provider, persists the linked response, returns the outcome with a `providerReference`.
- `POST /callback` — provider result callback (MTN also accepts PUT); stored 1:1 with the initiation, deduplicated, updates status. Always acks.
- `GET /status/{providerReference}` — DB state; if still PENDING, performs a live provider status query and updates the DB. Degrades to last-known state when the provider rate-limits.
- `GET /api/payments/transactions?provider=` — consolidated transactions across providers.
- `GET /api/payments/limits?provider=` / `PUT /api/payments/limits` — read and upsert the configurable payment ceilings (body: `provider`, `period`, `scope`, `maxAmount`, `currency`, `active`).

**Provider identity is market-qualified.** `Operator` (MPESA/AIRTEL/MTN) is the integration — one client, one token, one set of Resilience4j instances. `PaymentProviderType` is `Operator` × `Country`: MPESA_KE, AIRTEL_KE, AIRTEL_UG, MTN_UG, … That enum name is what lands in every `provider` column and every provider-scoped lookup (limits, reconciliation dispatch, callback matching). Which market each operator runs in comes from `<operator>.country` in yml, resolved once by `ProviderMarkets`; an unsupported pairing fails at startup rather than mid-payment. `provider` columns are typed `@Enumerated(EnumType.STRING)`, never raw Strings — likewise `ProviderToken.provider`, which is an `Operator` because credentials are per operator, not per market.

**Provider specifics:**
- M-Pesa: `providerReference` = CheckoutRequestID, `secondaryReference` = MerchantRequestID; STK query "still processing" (errorCode 500.001.1001) maps to `ProviderProcessingException` → stays PENDING. Sandbox creds in yml are live.
- Airtel: reference is a generated `ATL<uuid>` transaction id; status codes TIP (pending) / TS (success) / TF (failed); receipt = `airtel_money_id`. Credentials are placeholders (`airtel.*`).
- MTN MoMo: reference is the generated `X-Reference-Id` UUID (externalId is set to the same value for callback correlation); request-to-pay returns 202 with no body; status SUCCESSFUL/FAILED/PENDING; receipt = `financialTransactionId`. Sandbox needs `mtn.subscription-key`, `mtn.api-user`, `mtn.api-key`; sandbox currency is EUR. Placeholders in yml.

**Key design points:**

- The web layer and all provider I/O are non-blocking (`Mono`/`Flux`). Never block the event loop and never call `.block()`; database work reaches JPA only through the store beans on `Schedulers.boundedElastic()`.
- All outbound provider calls live in `client/*Client` classes so the Resilience4j annotations (`@CircuitBreaker`, `@RateLimiter`, `@Retry`) go through Spring AOP — they are silently skipped on self-invocation. Each provider has its own instances (`mpesa*`, `airtel*`, `mtn*`) configured **only** in `application.yml` (YAML anchors share the retry/circuit-breaker settings).
- Shared exception model in `exceptions/`: `ProviderBusyException` (429/busy → reactive backoff retry, 503), `ProviderTransientException` (Resilience4j retry, 502), `ProviderPermanentException` (never retried, CB-ignored, 400), `ProviderProcessingException` (still processing → stays PENDING). HTTP-to-exception mapping is shared in `client/ProviderHttpErrors` (401 evicts the token so the retry refetches).
- `TokenCacheService` is the tiered token cache for all providers: Redis (`<provider>:access_token`) → `PROVIDER_TOKENS` table → live OAuth fetch (persisted to both tiers). Redis being down never fails a request (800ms timeouts, falls through). `<Provider>TokenService` classes only supply the fetch call.
- Boot 4 defaults to Jackson 3 (`tools.jackson.databind.ObjectMapper`) — inject that type, not `com.fasterxml`. The `com.fasterxml.jackson.annotation.*` annotations still work.
- Resilience4j 2.4.0 with `resilience4j-spring-boot4`; annotations require `aspectjweaver` (Boot 4 removed `spring-boot-starter-aop`). Boot 4 also split `WebClient` auto-config into `spring-boot-starter-webclient`.
- Package convention: `models` holds only database entities (`@Entity`) and the enums they persist (`Operator`, `Country`, `PaymentProviderType`, `LimitPeriod`, `LimitScope`); `models/audit` holds the provider-call audit entities; everything crossing an API boundary lives in `dto`.

**Persistence (PostgreSQL via JPA/Hibernate):**
- Connection settings live under `spring.datasource.*` (`jdbc:postgresql://localhost:5432/payments`, user `myapp`), driver `org.postgresql:postgresql`. `spring.jpa.open-in-view` is off — WebFlux has no OSIV filter, so lazy access outside a transaction should fail loudly.
- The database must exist and be reachable before startup, so `./gradlew build` (which runs the `contextLoads` test) needs a live Postgres, or use `-x test`. On PostgreSQL 15+ the app's role also needs `GRANT USAGE, CREATE ON SCHEMA public`, or startup dies with SQLSTATE 42501.
- Hibernate owns the DDL (`spring.jpa.hibernate.ddl-auto: update`). There is no schema.sql and no hand-rolled initializer; `configurations/DataSeeder` seeds only the reference data Hibernate cannot derive — the `STATUSES` rows and the default provider ceilings — each guarded by an existence check so runtime edits survive a restart.
- `STATUSES` — the payment lifecycle states as rows, not an enum: Paid, Success, Pending, Failed. `PaymentInitiation` and `Transaction` reference it `@ManyToOne` (`status_id`). There is deliberately **no enum mirroring these values**: `StatusCatalog` is the single place that names the four the code branches on, and every caller asks it for a row (`statuses.pending()`, `.paid()`, `.success()`, `.failed()`) so the value served is whatever the table currently holds. `StatusCatalog.defaults()` is also what `DataSeeder` seeds from, so the names live in exactly one file. Rows are memoised, so a transition costs no query — call `invalidate()` after inserting. **Paid vs Success**: a successful callback carrying a receipt number resolves to Paid, one without to Success.
- `PAYMENT_INITIATIONS` — one row per payment attempt, any provider.
- `<operator>_PAYMENT_RESPONSES` — the provider's answer, one table per operator (`mpesa_payment_responses`, `airtel_…`, `mtn_…`), `initiation_id UNIQUE` (1:1) and `provider_reference UNIQUE` (lookup key for callbacks/status).
- `<operator>_PAYMENT_CALLBACKS` — the result callback that resolved the payment, one table per operator, `initiation_id UNIQUE`, duplicates ignored, raw payload stored as JSON. (The duplicate-inclusive record is the separate `<operator>_callback_responses` audit table.)
- These six entities are standalone — no shared supertype, matching the audit tables. `PaymentLifecycleStore` therefore dispatches on `Operator` and hands the rest of the lifecycle a provider-neutral `PaymentLifecycleService.StoredResponse` view record (not an entity, no table). **Keep the provider equality check when resolving a reference**: one operator's table holds every one of its markets, so a MPESA_TZ reference must not resolve against a MPESA_KE payment.
- `TRANSACTIONS` — the spine that ties a payment together. Created by `saveInitiation` **at request time**, not at resolution, so a payment is never missing from this table; `recordTransaction` then updates it as the payment progresses (`resolvedBy`: CALLBACK, QUERY, REJECTION, ERROR, RECONCILIATION — left null while still open). References its `PaymentInitiation` `@ManyToOne` (`initiation_id`, UNIQUE — one transaction per attempt), its `Status`, and the provider's response and callback.
- A transaction points at **the request** and **the callback**, not the response: the response already hangs off the request (`MpesaResponse.request`), so the request is the single anchor for everything the operator sent back. Because those tables are per operator with no shared supertype, each link is three nullable FKs — `mpesa_request_id` / `airtel_request_id` / `mtn_request_id`, and the same for callbacks — of which exactly one per trio is set. `attachRequest`/`attachCallback` in the store pick the right one; `hasRequest()` / `hasCallback()` hide the null-checking.
- `attachRequest` links the **earliest** audit request for the initiation (later rows are status queries) and is **best effort**: audit rows are written asynchronously, so if one has not landed yet the link is picked up on the next update.
**Naming convention — PascalCase entity fields (`CreatedByPartner` style).** Every `@Entity` field is PascalCase. Lombok still generates ordinary `getX()`/`setX()` and builders take the PascalCase name (`.Provider(...)`). Three consequences, all of which have already bitten:
- **Spring Data derived queries break silently.** The persistent property is `Initiation`, not `initiation`, so `findByInitiationId` fails at runtime with `IllegalStateException: Binding property is null`. **Every repository therefore uses explicit `@Query` JPQL with PascalCase paths** (`WHERE t.Initiation.Id = :id`). Never add a derived query method. `findFirstBy…` has no JPQL equivalent either — those became `ORDER BY … ` queries returning a `List` whose head the caller takes.
- **Associations are `@ManyToOne(targetEntity = X.class, fetch = FetchType.LAZY)` with `@JoinColumn(name = "<FieldName>")`** — the column is named after the field, so `transactions` has `initiation`, `status`, `mpesa_request`, `mpesa_callback` rather than `*_id`. No `foreignKey = @ForeignKey(name = ...)`; constraint names are left to Hibernate. Because everything is LAZY and `open-in-view` is off, **any query whose result is serialised by the web layer must `LEFT JOIN FETCH` its associations** — see `TransactionRepository.GRAPH`, which the listing queries share.
- **Entity-returning endpoints now emit PascalCase JSON keys** (`{"Id":1,"Provider":"MPESA_KE"}`) — `/api/payments/transactions` and `/api/payments/limits`. The DTO-returning endpoints (`/pay`, `/status`, `/callback`) are unaffected and stay camelCase, because DTOs are not part of this convention.
- `<operator>_requests.initiation_id` is a **String**, not the numeric id, so it can carry a NanoID; it is a loose reference with no FK.
- `PROVIDER_TOKENS` — OAuth tokens per **operator** (not per market) with expiry.
- `PROVIDER_LIMITS` — configurable payment ceilings, `UNIQUE (provider, period, scope)`. Periods come from the `LimitPeriod` enum (PER_TRANSACTION, DAILY, MONTHLY — adding a constant is all a new period needs); `scope` from the `LimitScope` enum (PER_PAYER buckets by paying MSISDN, MERCHANT sums every payer on the provider; defaults to PER_PAYER and is ignored by PER_TRANSACTION). Defaults are seeded by `DataSeeder` only when the triple is absent (and only for the markets `<operator>.country` actually configures), so runtime edits survive a restart. `PaymentLimitService.enforce` runs in every `<Provider>Service.initiatePayment` **before** the initiation is persisted (breaches leave no DB row) and raises `PaymentLimitExceededException` → 422 `LIMIT_EXCEEDED`. Cumulative periods sum non-Failed initiations inside the window (per MSISDN for PER_PAYER, provider-wide for MERCHANT), so PENDING pushes count against the cap. An unrecognised `scope` on a row falls back to PER_PAYER (the tighter interpretation).
- **Provider-call audit trail** (`models/audit`, `repository/audit`, `ProviderCallAudit`): every outbound call and inbound callback is recorded per operator in its own independent tables — `mpesa_requests` / `mpesa_responses` / `mpesa_callback_responses`, and the `airtel_*` and `mtn_*` equivalents. Responses and callbacks reference their request `@ManyToOne`. The nine entities are **fully standalone** — no shared supertype, no `@MappedSuperclass`, no discriminator, no join. `ProviderCallAudit` therefore dispatches on `Operator` with an explicit branch per provider rather than polymorphically, which is verbose on purpose: a new operator will not compile until all three of its tables are wired up. Writes run on the `auditExecutor` pool (bounded queue, drop-on-overflow, daemon threads) so a payment is never delayed or failed by its audit trail; ordering within a call is kept by chaining onto the request's `CompletableFuture` rather than blocking on it. Credentials matching `ProviderCallAudit.SECRETS` (Password, passkey, api-key, secret, authorization, access_token) are masked before anything is stored.
- `@Table` names must be lowercase — Postgres folds unquoted DDL identifiers to lowercase and Spring Data quotes an explicit entity name verbatim. Column names carry no `@Column` annotation, so they are derived and adapt to the dialect's casing on their own; keep it that way.
- `PaymentReconciliationJob` runs two passes per tick (interval `payments.reconciliation.fixed-delay`, default 60s), **stale first** so hopeless payments stop being re-queried:
  1. anything still Pending past `payments.reconciliation.stale-age` (default 3h) → `Unresolved` via `markStaleUnresolved`, `resolvedBy = EXPIRY`;
  2. anything still Pending past `payments.reconciliation.pending-age` (default **3m**) → live provider status query, dispatched to the right `PaymentProviderService`.
- **Status transitions are guarded, not blind.** `StatusCatalog.PRECEDENCE` orders the states least- to most-informed (Pending → Unresolved → Failed → Success → Paid) and `canTransition` only allows moves *up* it. So a callback and a status query racing each other cannot make the status flap: re-asserting the current state is a silent no-op (DEBUG), a worse verdict is refused with a WARN, and a receipt-bearing callback can still rescue a payment the query gave up on (Unresolved → Paid). **A refused transition never discards the row** — the callback is still stored, only the status is held back.
- `PaymentInitiation` carries a `@Version` optimistic lock. When a callback and a query genuinely commit at the same instant the loser's transaction rolls back; `PaymentLifecycleService.blockingWithRetry` replays it once, so the callback row still lands and the guard then declines the redundant status change. Use it for any new path that resolves a payment.

**Configuration (`application.yml`):**
- Config is read via `Environment.getProperty` by project convention (no `@ConfigurationProperties`).
- `mpesa.*` (live sandbox keys), `airtel.*` and `mtn.*` (placeholders — fill in real credentials), `payments.*` (token buffer, reconciliation).
- Callback URLs (`mpesa.callback-url`, `mtn.callback-url`) must be publicly reachable for real callbacks.
- `spring.data.redis.*` — short 1s timeouts so a dead Redis degrades fast.

**Sandbox gotchas (observed live):**
- Safaricom's STK query endpoint is aggressively rate-limited (~few calls/minute) — expect `ProviderBusyException` from status checks/reconciliation during testing; the status endpoint then serves last-known DB state.
- M-Pesa test phone 254708374149 typically ends as ResultCode 1037 ("DS timeout user cannot be reached") since no real handset confirms the push.
- Airtel/MTN flows were verified against a local mock of their APIs (`scratchpad/provider_mock.py` pattern) — point `airtel.base-url`/`mtn.base-url` at a stub to test without credentials.