From 3cefa97f293e31bd5fae3fc04240d767e4545ce4 Mon Sep 17 00:00:00 2001 From: Rami Mohamed Date: Sun, 30 Aug 2026 16:04:54 +0400 Subject: [PATCH 1/8] docs: update project handoff for implementation wave --- docs/project-handoff.md | 69 +++++++++++++++++++++++++++++++++-------- 1 file changed, 56 insertions(+), 13 deletions(-) diff --git a/docs/project-handoff.md b/docs/project-handoff.md index 0c95026..a5c3411 100644 --- a/docs/project-handoff.md +++ b/docs/project-handoff.md @@ -33,6 +33,7 @@ The working style is: | `customer-service` | Customer identity and profile management | | `account-service` | Account lifecycle, account lookup, admin account search | | `ledger-service` | Immutable ledger entry posting and lookup | +| `transaction-service` | Transfer orchestration and saga/process-manager foundation | | `infra-sit` | Local SIT infrastructure: shared PostgreSQL, Kafka, and AKHQ tooling | ## Environment Model @@ -40,8 +41,8 @@ The working style is: | Environment | Meaning | | --- | --- | | `sit` | Lowest integrated development and testing environment on Docker Desktop Kubernetes | -| `uat` | Future AWS-hosted pre-production environment | -| `prod` | Future AWS production environment | +| `uat` | Formal cloud-hosted pre-production environment | +| `prod` | Formal production environment | `LOCAL-DEV` is retired as a formal environment and Spring profile. Running a single service from VS Code or Eclipse remains supported for debugging, but the process uses the `sit` profile and temporary property overrides to connect to forwarded SIT dependencies. It is not a second deployment topology. @@ -155,6 +156,8 @@ Ledger reconciliation is an operational comparison across independently owned vi No service should expose naive public balance mutation APIs. +`transaction-service` is now a repository and has an open bootstrap PR, but it is not yet a completed transfer workflow. The bootstrap scope is limited to the Spring Boot service shell, Config Client, health endpoints, container/Helm delivery, and CI. Transfer APIs, persistence, Kafka transport, reservations, and saga orchestration remain follow-on work. + ## Event-Driven Direction The platform is moving toward eventual consistency for financial workflows. @@ -201,7 +204,7 @@ Ledger Service should not orchestrate sagas. Transaction Service should own saga ## Current Implementation Snapshot -Implemented or substantially started: +The following baseline is merged on the repository default branches or was already established before this update: - `config-server` bootstrap, tests, Dockerfile, Helm chart, CI, Git-backed config - `config-repo` externalized service configuration @@ -213,6 +216,27 @@ Implemented or substantially started: - `infra-sit` shared PostgreSQL, Kafka, and AKHQ deployment for local SIT - org-level and repo-level `AGENTS.md` files - Java test phase convention documentation +- ledger reconciliation architecture and the independent-view reconciliation model +- shared local SIT Kafka and AKHQ tooling +- ledger database credential injection for SIT + +The following reviewable wave is open and non-draft as of 2026-08-30. Open PRs are not merged, deployed, or complete until their PRs are accepted and the required rollout verification is recorded: + +| Repository / PR | Reviewable scope | Current state | +| --- | --- | --- | +| [`.github#137`](https://github.com/digital-bank-java/.github/pull/137) | AsyncAPI 3.0.0 ledger posting outcome contracts, event metadata, failure codes, and reversal provenance | Open; contract prerequisite for ledger outbox, account reservations, and transaction workflow work | +| [`.github#138`](https://github.com/digital-bank-java/.github/pull/138) | Structured JSON logging, correlation/trace fields, and redaction contract | Open; self-contained documentation | +| [`.github#139`](https://github.com/digital-bank-java/.github/pull/139) | `sit`/`uat`/`prod` API documentation access and safe interactive execution policy | Open; self-contained documentation | +| [`transaction-service#5`](https://github.com/digital-bank-java/transaction-service/pull/5) | Transaction Service Spring Boot, Config Client, health, container, Helm, and CI bootstrap | Open; service shell only, with no transfer workflow | +| [`infra-sit#23`](https://github.com/digital-bank-java/infra-sit/pull/23) | Shared Redis StatefulSet, persistence, service, probes, and SIT Helm validation | Open; prerequisite for a later Redis-backed gateway rate limiter | +| [`api-gateway#20`](https://github.com/digital-bank-java/api-gateway/pull/20) | Resilience4j circuit breaker, GET-only safe retries, and controlled `503` fallback | Open; can merge independently of Redis | +| [`ledger-service#14`](https://github.com/digital-bank-java/ledger-service/pull/14) | Transactional ledger outbox persistence and posting-event metadata | Open; depends on [`.github#137`](https://github.com/digital-bank-java/.github/pull/137); Kafka dispatch remains deferred | +| [`account-service#33`](https://github.com/digital-bank-java/account-service/pull/33) | Account reservation persistence boundary, commands, status, and optimistic-concurrency rules | Open; depends on [`.github#137`](https://github.com/digital-bank-java/.github/pull/137); event transport remains deferred | +| [`config-repo#30`](https://github.com/digital-bank-java/config-repo/pull/30) | Config Server defaults and `sit` profile for `transaction-service` on port `8084` | Open; required with `transaction-service#5` before a SIT rollout | + +`account-service#27` (quality-gate follow-up) is also open and reviewable, but it is outside the current event/transaction implementation wave. The implementation PRs report focused unit/integration, Helm, container, schema, or configuration verification in their PR descriptions; that evidence does not establish a merged or deployed state. + +Current verification evidence is review evidence only: transaction-service#5 reports Maven `verify`, strict SIT Helm lint/template checks, and a non-root/read-only-container smoke test; infra-sit#23 reports Redis/PostgreSQL/Kafka/AKHQ/Redis Helm lint and render checks plus a Kubernetes dry run; api-gateway#20 reports Maven `verify`, strict SIT Helm validation/rendering, and container smoke coverage; ledger-service#14 reports `./mvnw verify` with 8 unit and 15 integration tests plus Flyway V1-V5 Testcontainers coverage; account-service#33 has green Maven, Helm, and container CI checks; config-repo#30 reports YAML parsing and `git diff --check`; and `.github#137`-`.github#139` report focused contract/Markdown checks. SIT rollout, UAT deployment, and production deployment still require separate evidence. Prepared local/SIT event-delivery work that is verified on dedicated review branches but is still awaiting non-draft PR publication: @@ -230,13 +254,15 @@ Prepared local/SIT event-delivery work that is verified on dedicated review bran High-priority missing capabilities: -- Kafka application integration -- Transactional ledger outbox implementation and posting outcome publication, dependent on [`docs/contracts/ledger-events-asyncapi.yml`](contracts/ledger-events-asyncapi.yml) -- Account reservation persistence and event consumption boundary, dependent on [`docs/contracts/ledger-events-asyncapi.yml`](contracts/ledger-events-asyncapi.yml) -- Transaction Service process-manager bootstrap, dependent on [`docs/contracts/ledger-events-asyncapi.yml`](contracts/ledger-events-asyncapi.yml) -- saga/process-manager implementation in Transaction Service -- account reservation tables and APIs -- account outbox/inbox tables and publishers/consumers +- complete governed account/transfer event-contract documentation and compatibility checks +- integrated SIT rollout and end-to-end transfer verification across Transaction, Account, and Ledger services +- gateway routing and SIT configuration for the newly bootstrapped services +- service-to-service security and admin API authentication/authorization +- API Gateway rate limiting and resilience rollout +- centralized logging with OpenSearch, Fluent Bit, dashboards, and alerts +- distributed tracing and correlation IDs +- event-driven reconciliation checks and scheduled reconciliation reporting +- production documentation and the later AWS UAT/PROD delivery path - service-to-service security - API Gateway rate limiting and resilience - admin API authentication/authorization @@ -317,18 +343,35 @@ Before doing work: Useful local command: ```bash -for repo in .github config-server config-repo api-gateway customer-service account-service ledger-service infra-sit; do +for repo in .github config-server config-repo api-gateway customer-service account-service ledger-service transaction-service infra-sit; do printf "\n== %s ==\n" "$repo" git -C "$repo" status -sb done ``` -## Recommended Next Work +## Next Dependency-Aware Work + +The implementation wave is merged. The next work is review and rollout, in this +order: + +1. Merge the governance/documentation PRs [`.github#173`](https://github.com/digital-bank-java/.github/pull/173) and [`.github#176`](https://github.com/digital-bank-java/.github/pull/176). No waiting period is required, but dependent service configuration should use the accepted contract. +2. Merge the service configuration PRs [`config-repo#30`](https://github.com/digital-bank-java/config-repo/pull/30), [`config-repo#32`](https://github.com/digital-bank-java/config-repo/pull/32), [`config-repo#33`](https://github.com/digital-bank-java/config-repo/pull/33), and [`config-repo#34`](https://github.com/digital-bank-java/config-repo/pull/34). Restart Config Server or refresh its Git checkout before service rollout. +3. Merge [`infra-sit#23`](https://github.com/digital-bank-java/infra-sit/pull/23) before enabling the Redis-backed gateway limiter. OpenSearch and Fluent Bit can merge independently after review. +4. Roll out Auth, MFA, Transaction, Payment, Notification, Account, and Ledger services in SIT. Verify migrations, Kafka topics, gateway routes, health, authentication, transfer acceptance, reservation events, ledger outcomes, and notification consumption. +5. Record the SIT evidence in the supporting issues and update Sprint 3, 4, and 5 statuses. Keep UAT/PROD cloud deployment deferred to Sprint 7. -Finish and verify any remaining local SIT event-driven domain work before starting AWS delivery. Keep saga completion, reconciliation execution, and later security/resilience work in their assigned Sprint 3 or Sprint 6 items. Consult GitHub Project #1 for the current native hierarchy and status; Sprint 7 remains the later AWS/UAT/PROD boundary. +Consult GitHub Project #1 for the authoritative Sprint hierarchy and current issue status. ## Update Log +### 2026-09-01 + +- Merged the event-driven implementation wave: Ledger Service PRs #14-#16, Account Service PRs #33-#36, Transaction Service PRs #6-#12, Auth Service PRs #1-#4, MFA Service PRs #1-#6, Payment Service PRs #1-#5, Notification Service PRs #1-#5, organization event contracts PR #137, and SIT Kafka topics PR #27. +- Closed and recorded evidence for the completed Sprint 3 implementation issues #101, #102, #103, #170, #171, #182, and #183, plus the completed auth, MFA, payment, notification, and transfer implementation tasks. +- Corrected the native parent hierarchy: payment resource contract task #167 is now under payment lifecycle task #161; transfer authorization task #169 is now under transfer HTTP task #165. +- Audited GitHub Project #1 after authentication refresh: 223 tracked issues, exactly eight root Sprint epics, and no unparented non-Epic issue. Closed issue state and Project status are synchronized for the completed implementation items. +- AWS/UAT/PROD deployment remains deferred; the current focus is local SIT rollout and verification. + ### 2026-08-30 - Sprint 3 ledger event contract - Published [`docs/contracts/ledger-events-asyncapi.yml`](contracts/ledger-events-asyncapi.yml) as the governed AsyncAPI contract for `LedgerPostingCompleted.v1` and `LedgerPostingFailed.v1`. From 1358f9be8b4e335941253e9a1d2b2b375c423f4a Mon Sep 17 00:00:00 2001 From: Rami Mohamed Date: Tue, 1 Sep 2026 23:41:37 +0400 Subject: [PATCH 2/8] docs: refresh project handoff after merged implementation wave --- docs/project-handoff.md | 59 +++++++++++++++++++++++++++++------------ 1 file changed, 42 insertions(+), 17 deletions(-) diff --git a/docs/project-handoff.md b/docs/project-handoff.md index a5c3411..dfeed3a 100644 --- a/docs/project-handoff.md +++ b/docs/project-handoff.md @@ -144,18 +144,31 @@ Ledger reconciliation is an operational comparison across independently owned vi - account opening - account lookup - account listing/search -- future available-balance reservations -- future account balance projection updates driven by ledger events +- available-balance reservations and reservation lifecycle +- account balance projection updates driven by ledger events `ledger-service` owns: - immutable ledger entries - balanced debit/credit posting rules - ledger lookup -- future ledger posting outcome events +- governed ledger posting outcome events +- transactional outbox delivery with retry, lease, and quarantine semantics No service should expose naive public balance mutation APIs. +`transaction-service` owns: + +- internal transfer workflow state and lifecycle +- saga/process-manager decisions +- reservation and ledger command transport +- transfer outcome handling and transactional outboxes + +`auth-service`, `mfa-service`, `payment-service`, and `notification-service` have +their initial runtime and core HTTP/event foundations merged. Their remaining +SIT configuration, contract documentation, and hardening tasks remain tracked in +later Sprint 4 and Sprint 5 work. + `transaction-service` is now a repository and has an open bootstrap PR, but it is not yet a completed transfer workflow. The bootstrap scope is limited to the Spring Boot service shell, Config Client, health endpoints, container/Helm delivery, and CI. Transfer APIs, persistence, Kafka transport, reservations, and saga orchestration remain follow-on work. ## Event-Driven Direction @@ -182,7 +195,7 @@ Transaction Service Account Service -> validate available balance -> reserve funds - -> publish AccountReservationCreated through outbox + -> publish reservation outcome facts through outbox Transaction Service -> request Ledger Service posting @@ -219,12 +232,31 @@ The following baseline is merged on the repository default branches or was alrea - ledger reconciliation architecture and the independent-view reconciliation model - shared local SIT Kafka and AKHQ tooling - ledger database credential injection for SIT - -The following reviewable wave is open and non-draft as of 2026-08-30. Open PRs are not merged, deployed, or complete until their PRs are accepted and the required rollout verification is recorded: - -| Repository / PR | Reviewable scope | Current state | -| --- | --- | --- | -| [`.github#137`](https://github.com/digital-bank-java/.github/pull/137) | AsyncAPI 3.0.0 ledger posting outcome contracts, event metadata, failure codes, and reversal provenance | Open; contract prerequisite for ledger outbox, account reservations, and transaction workflow work | + - governed ledger event contracts and AsyncAPI documentation + - ledger transactional outbox publication, retry, lease, and quarantine behavior + - account reservation persistence, ledger-event consumption, and reservation transport + - transaction transfer lifecycle, saga/process manager, HTTP workflow API, authorization, and Kafka transport + - auth-service session/JWT foundations and configurable single-session policy + - mfa-service provider, TOTP, challenge, authenticated HTTP API, and principal binding foundations + - payment-service lifecycle, internal HTTP API, idempotency, authorization, and resource contract + - notification-service delivery lifecycle, TransferCreated consumer, and durable inbox + - SIT ledger Kafka topic provisioning + +The implementation wave above is merged on the service default branches as of +2026-09-01. Its PRs report the required Maven, Helm, and PostgreSQL/Testcontainers +verification. SIT rollout and end-to-end transfer demonstration remain separate +operational evidence and are not inferred from merged PRs. + +The remaining reviewable PRs are non-draft and are not merged or deployed until +accepted and verified: + +| Repository / PR | Reviewable scope | +| --- | --- | +| [`.github#173`](https://github.com/digital-bank-java/.github/pull/173) and [`.github#176`](https://github.com/digital-bank-java/.github/pull/176) | Transfer and account reservation event-contract governance | +| [`.github#178`](https://github.com/digital-bank-java/.github/pull/178), [`.github#179`](https://github.com/digital-bank-java/.github/pull/179), [`.github#180`](https://github.com/digital-bank-java/.github/pull/180), [`.github#181`](https://github.com/digital-bank-java/.github/pull/181) | Auth, AsyncAPI, transfer Insomnia, and layered-debugging documentation | +| [`config-repo#30`](https://github.com/digital-bank-java/config-repo/pull/30), [`config-repo#32`](https://github.com/digital-bank-java/config-repo/pull/32), [`config-repo#33`](https://github.com/digital-bank-java/config-repo/pull/33), [`config-repo#34`](https://github.com/digital-bank-java/config-repo/pull/34), [`config-repo#35`](https://github.com/digital-bank-java/config-repo/pull/35), [`config-repo#36`](https://github.com/digital-bank-java/config-repo/pull/36) | Transaction, auth/MFA, notification/payment, gateway resilience, and rate-limit SIT configuration | +| [`infra-sit#23`](https://github.com/digital-bank-java/infra-sit/pull/23), [`infra-sit#24`](https://github.com/digital-bank-java/infra-sit/pull/24), [`infra-sit#25`](https://github.com/digital-bank-java/infra-sit/pull/25) | Redis, OpenSearch, and Fluent Bit local-SIT infrastructure | +| [`account-service#27`](https://github.com/digital-bank-java/account-service/pull/27) | Account-service Maven quality gate follow-up | | [`.github#138`](https://github.com/digital-bank-java/.github/pull/138) | Structured JSON logging, correlation/trace fields, and redaction contract | Open; self-contained documentation | | [`.github#139`](https://github.com/digital-bank-java/.github/pull/139) | `sit`/`uat`/`prod` API documentation access and safe interactive execution policy | Open; self-contained documentation | | [`transaction-service#5`](https://github.com/digital-bank-java/transaction-service/pull/5) | Transaction Service Spring Boot, Config Client, health, container, Helm, and CI bootstrap | Open; service shell only, with no transfer workflow | @@ -263,13 +295,6 @@ High-priority missing capabilities: - distributed tracing and correlation IDs - event-driven reconciliation checks and scheduled reconciliation reporting - production documentation and the later AWS UAT/PROD delivery path -- service-to-service security -- API Gateway rate limiting and resilience -- admin API authentication/authorization -- centralized logging with OpenSearch direction -- distributed tracing and correlation IDs -- AWS infrastructure path for UAT and production -- ledger idempotent replay, append-only reversals, and reconciliation controls Deferred or intentionally not first: From cc5707da855bdca968f60df71952475b8f8e9979 Mon Sep 17 00:00:00 2001 From: Rami Mohamed Date: Fri, 4 Sep 2026 05:31:58 +0400 Subject: [PATCH 3/8] docs: refresh current SIT delivery handoff --- docs/project-handoff.md | 93 +++++++++++++++++++++-------------------- 1 file changed, 48 insertions(+), 45 deletions(-) diff --git a/docs/project-handoff.md b/docs/project-handoff.md index dfeed3a..88b45b2 100644 --- a/docs/project-handoff.md +++ b/docs/project-handoff.md @@ -1,6 +1,6 @@ # Digital Bank Java Project Handoff -Last updated: 2026-09-01 +Last updated: 2026-09-04 This document is the durable resume point for AI agents and contributors working on the Digital Bank Java platform. @@ -34,6 +34,10 @@ The working style is: | `account-service` | Account lifecycle, account lookup, admin account search | | `ledger-service` | Immutable ledger entry posting and lookup | | `transaction-service` | Transfer orchestration and saga/process-manager foundation | +| `auth-service` | Authentication, JWT/session foundation, and login/logout workflow | +| `mfa-service` | TOTP enrollment and authenticated MFA challenge workflow | +| `payment-service` | Authenticated internal payment instruction lifecycle | +| `notification-service` | Transfer-event notification consumption and durable inbox | | `infra-sit` | Local SIT infrastructure: shared PostgreSQL, Kafka, and AKHQ tooling | ## Environment Model @@ -165,11 +169,13 @@ No service should expose naive public balance mutation APIs. - transfer outcome handling and transactional outboxes `auth-service`, `mfa-service`, `payment-service`, and `notification-service` have -their initial runtime and core HTTP/event foundations merged. Their remaining -SIT configuration, contract documentation, and hardening tasks remain tracked in -later Sprint 4 and Sprint 5 work. +their runtime and core HTTP/event foundations merged. Their current review wave +adds the shared SIT JWT trust contract, service configuration, and local rollout +prerequisites. -`transaction-service` is now a repository and has an open bootstrap PR, but it is not yet a completed transfer workflow. The bootstrap scope is limited to the Spring Boot service shell, Config Client, health endpoints, container/Helm delivery, and CI. Transfer APIs, persistence, Kafka transport, reservations, and saga orchestration remain follow-on work. +`transaction-service` has its transfer lifecycle, reservation/ledger transport, +authorization, persistence, and saga/process-manager foundation merged. End-to-end +SIT execution remains operational evidence, not an assumption from merged code. ## Event-Driven Direction @@ -240,47 +246,34 @@ The following baseline is merged on the repository default branches or was alrea - mfa-service provider, TOTP, challenge, authenticated HTTP API, and principal binding foundations - payment-service lifecycle, internal HTTP API, idempotency, authorization, and resource contract - notification-service delivery lifecycle, TransferCreated consumer, and durable inbox - - SIT ledger Kafka topic provisioning + - SIT ledger and transfer Kafka topic provisioning The implementation wave above is merged on the service default branches as of 2026-09-01. Its PRs report the required Maven, Helm, and PostgreSQL/Testcontainers verification. SIT rollout and end-to-end transfer demonstration remain separate operational evidence and are not inferred from merged PRs. -The remaining reviewable PRs are non-draft and are not merged or deployed until -accepted and verified: +The current reviewable implementation wave is non-draft and is not merged or +deployed until accepted and verified: | Repository / PR | Reviewable scope | | --- | --- | -| [`.github#173`](https://github.com/digital-bank-java/.github/pull/173) and [`.github#176`](https://github.com/digital-bank-java/.github/pull/176) | Transfer and account reservation event-contract governance | -| [`.github#178`](https://github.com/digital-bank-java/.github/pull/178), [`.github#179`](https://github.com/digital-bank-java/.github/pull/179), [`.github#180`](https://github.com/digital-bank-java/.github/pull/180), [`.github#181`](https://github.com/digital-bank-java/.github/pull/181) | Auth, AsyncAPI, transfer Insomnia, and layered-debugging documentation | -| [`config-repo#30`](https://github.com/digital-bank-java/config-repo/pull/30), [`config-repo#32`](https://github.com/digital-bank-java/config-repo/pull/32), [`config-repo#33`](https://github.com/digital-bank-java/config-repo/pull/33), [`config-repo#34`](https://github.com/digital-bank-java/config-repo/pull/34), [`config-repo#35`](https://github.com/digital-bank-java/config-repo/pull/35), [`config-repo#36`](https://github.com/digital-bank-java/config-repo/pull/36) | Transaction, auth/MFA, notification/payment, gateway resilience, and rate-limit SIT configuration | -| [`infra-sit#23`](https://github.com/digital-bank-java/infra-sit/pull/23), [`infra-sit#24`](https://github.com/digital-bank-java/infra-sit/pull/24), [`infra-sit#25`](https://github.com/digital-bank-java/infra-sit/pull/25) | Redis, OpenSearch, and Fluent Bit local-SIT infrastructure | -| [`account-service#27`](https://github.com/digital-bank-java/account-service/pull/27) | Account-service Maven quality gate follow-up | -| [`.github#138`](https://github.com/digital-bank-java/.github/pull/138) | Structured JSON logging, correlation/trace fields, and redaction contract | Open; self-contained documentation | -| [`.github#139`](https://github.com/digital-bank-java/.github/pull/139) | `sit`/`uat`/`prod` API documentation access and safe interactive execution policy | Open; self-contained documentation | -| [`transaction-service#5`](https://github.com/digital-bank-java/transaction-service/pull/5) | Transaction Service Spring Boot, Config Client, health, container, Helm, and CI bootstrap | Open; service shell only, with no transfer workflow | -| [`infra-sit#23`](https://github.com/digital-bank-java/infra-sit/pull/23) | Shared Redis StatefulSet, persistence, service, probes, and SIT Helm validation | Open; prerequisite for a later Redis-backed gateway rate limiter | -| [`api-gateway#20`](https://github.com/digital-bank-java/api-gateway/pull/20) | Resilience4j circuit breaker, GET-only safe retries, and controlled `503` fallback | Open; can merge independently of Redis | -| [`ledger-service#14`](https://github.com/digital-bank-java/ledger-service/pull/14) | Transactional ledger outbox persistence and posting-event metadata | Open; depends on [`.github#137`](https://github.com/digital-bank-java/.github/pull/137); Kafka dispatch remains deferred | -| [`account-service#33`](https://github.com/digital-bank-java/account-service/pull/33) | Account reservation persistence boundary, commands, status, and optimistic-concurrency rules | Open; depends on [`.github#137`](https://github.com/digital-bank-java/.github/pull/137); event transport remains deferred | -| [`config-repo#30`](https://github.com/digital-bank-java/config-repo/pull/30) | Config Server defaults and `sit` profile for `transaction-service` on port `8084` | Open; required with `transaction-service#5` before a SIT rollout | - -`account-service#27` (quality-gate follow-up) is also open and reviewable, but it is outside the current event/transaction implementation wave. The implementation PRs report focused unit/integration, Helm, container, schema, or configuration verification in their PR descriptions; that evidence does not establish a merged or deployed state. - -Current verification evidence is review evidence only: transaction-service#5 reports Maven `verify`, strict SIT Helm lint/template checks, and a non-root/read-only-container smoke test; infra-sit#23 reports Redis/PostgreSQL/Kafka/AKHQ/Redis Helm lint and render checks plus a Kubernetes dry run; api-gateway#20 reports Maven `verify`, strict SIT Helm validation/rendering, and container smoke coverage; ledger-service#14 reports `./mvnw verify` with 8 unit and 15 integration tests plus Flyway V1-V5 Testcontainers coverage; account-service#33 has green Maven, Helm, and container CI checks; config-repo#30 reports YAML parsing and `git diff --check`; and `.github#137`-`.github#139` report focused contract/Markdown checks. SIT rollout, UAT deployment, and production deployment still require separate evidence. - -Prepared local/SIT event-delivery work that is verified on dedicated review branches but is still awaiting non-draft PR publication: - -- governed ledger event contracts: `.github` `feature/104-event-contracts`, latest commit `e37a717` -- ledger outbox delivery and safety: `ledger-service` `fix/176-ledger-outbox-safety`, latest commit `1dc0f81` -- account reservation transport: `account-service` `feature/177-account-reservation-transport`, latest commit `71cfe80` -- transaction reservation transport: `transaction-service` `feature/178-transfer-kafka-transport`, latest commit `8922c06` -- transaction SIT transport configuration: `config-repo` `fix/transaction-service-sit-config`, latest commit `8152613` -- ledger outbox SIT configuration: `config-repo` `feature/23-ledger-service-sit-config`, latest commit `3549b7c` -- SIT Kafka topic provisioning: `infra-sit` `feature/103-sit-kafka-topics`, latest commit `c3dcd16` -- Ledger posting command consumer: `ledger-service` `feature/103-ledger-posting-consumer`, latest commit `76c11a5` -- Transaction-to-Ledger Kafka transport: `transaction-service` `feature/103-transaction-ledger-transport`, latest commit `f2092f3` +| [`.github#201`](https://github.com/digital-bank-java/.github/pull/201) | Shared SIT Auth JWT secret runbook | +| [`config-repo#32`](https://github.com/digital-bank-java/config-repo/pull/32) | Auth/MFA SIT configuration, shared issuer, and Auth scopes | +| [`auth-service#6`](https://github.com/digital-bank-java/auth-service/pull/6) | Shared SIT JWT scope contract | +| [`mfa-service#8`](https://github.com/digital-bank-java/mfa-service/pull/8) | HMAC/JWK JWT validation for SIT and cloud modes | +| [`payment-service#7`](https://github.com/digital-bank-java/payment-service/pull/7) | HMAC/JWK JWT validation and SIT deployment contract | +| [`config-repo#33`](https://github.com/digital-bank-java/config-repo/pull/33) and [`config-repo#34`](https://github.com/digital-bank-java/config-repo/pull/34) | Notification and Payment SIT configuration | +| [`infra-sit#29`](https://github.com/digital-bank-java/infra-sit/pull/29) | Transfer-created Kafka topic and dead-letter topic provisioning | +| [`config-repo#39`](https://github.com/digital-bank-java/config-repo/pull/39) | Auth, MFA, Transaction, and Payment gateway routes and centralized OpenAPI entries | + +The application PRs report focused Maven, Helm, and container verification. The +configuration PRs report YAML parsing and diff checks. SIT rollout, end-to-end +transfer demonstration, and secret provisioning still require separate evidence. + +Other local-SIT operational PRs remain independently reviewable: `infra-sit#23` +(Redis), `infra-sit#24` (OpenSearch), `infra-sit#25` (Fluent Bit), +`config-repo#35` (gateway resilience), and `config-repo#36` (gateway rate limits). ## Known Missing Work @@ -288,7 +281,7 @@ High-priority missing capabilities: - complete governed account/transfer event-contract documentation and compatibility checks - integrated SIT rollout and end-to-end transfer verification across Transaction, Account, and Ledger services -- gateway routing and SIT configuration for the newly bootstrapped services +- rollout of the newly added gateway routes and SIT configuration for Auth, MFA, Transaction, and Payment - service-to-service security and admin API authentication/authorization - API Gateway rate limiting and resilience rollout - centralized logging with OpenSearch, Fluent Bit, dashboards, and alerts @@ -376,19 +369,29 @@ done ## Next Dependency-Aware Work -The implementation wave is merged. The next work is review and rollout, in this -order: +The current implementation wave is ready for review and rollout, in this order: -1. Merge the governance/documentation PRs [`.github#173`](https://github.com/digital-bank-java/.github/pull/173) and [`.github#176`](https://github.com/digital-bank-java/.github/pull/176). No waiting period is required, but dependent service configuration should use the accepted contract. -2. Merge the service configuration PRs [`config-repo#30`](https://github.com/digital-bank-java/config-repo/pull/30), [`config-repo#32`](https://github.com/digital-bank-java/config-repo/pull/32), [`config-repo#33`](https://github.com/digital-bank-java/config-repo/pull/33), and [`config-repo#34`](https://github.com/digital-bank-java/config-repo/pull/34). Restart Config Server or refresh its Git checkout before service rollout. -3. Merge [`infra-sit#23`](https://github.com/digital-bank-java/infra-sit/pull/23) before enabling the Redis-backed gateway limiter. OpenSearch and Fluent Bit can merge independently after review. -4. Roll out Auth, MFA, Transaction, Payment, Notification, Account, and Ledger services in SIT. Verify migrations, Kafka topics, gateway routes, health, authentication, transfer acceptance, reservation events, ledger outcomes, and notification consumption. -5. Record the SIT evidence in the supporting issues and update Sprint 3, 4, and 5 statuses. Keep UAT/PROD cloud deployment deferred to Sprint 7. +1. Merge [`.github#201`](https://github.com/digital-bank-java/.github/pull/201), the shared SIT Auth Secret runbook. +2. Merge [`config-repo#32`](https://github.com/digital-bank-java/config-repo/pull/32), then [`auth-service#6`](https://github.com/digital-bank-java/auth-service/pull/6). +3. Merge [`mfa-service#8`](https://github.com/digital-bank-java/mfa-service/pull/8) and [`payment-service#7`](https://github.com/digital-bank-java/payment-service/pull/7) in parallel. +4. Merge [`config-repo#33`](https://github.com/digital-bank-java/config-repo/pull/33), [`config-repo#34`](https://github.com/digital-bank-java/config-repo/pull/34), and [`infra-sit#29`](https://github.com/digital-bank-java/infra-sit/pull/29). The first two depend on config-repo#32; the Kafka topic PR can merge independently. +5. Merge [`config-repo#39`](https://github.com/digital-bank-java/config-repo/pull/39) after the corresponding service/configuration contracts are available. +6. Provision the local SIT Auth Secret, roll out the services, and verify health, protected workflows, Kafka delivery, centralized Swagger, and database state. +7. Record runtime evidence in the supporting issues and synchronize Sprint 3, 4, and 5 statuses. Keep UAT/PROD cloud deployment deferred to Sprint 7. Consult GitHub Project #1 for the authoritative Sprint hierarchy and current issue status. ## Update Log +### 2026-09-04 - SIT security and gateway review wave + +- Added the shared SIT Auth JWT secret delivery runbook in [`.github#201`](https://github.com/digital-bank-java/.github/pull/201). +- Aligned Auth, MFA, and Payment JWT trust behavior for local HMAC SIT validation while preserving OIDC/JWK support for future cloud environments. +- Completed the Auth/MFA/Notification/Payment SIT configuration review wave in `config-repo#32`, `#33`, and `#34`, including shared issuer/scopes and README structure corrections. +- Provisioned the transfer-created Kafka topic and dead-letter topic in [infra-sit#29](https://github.com/digital-bank-java/infra-sit/pull/29). +- Added the missing Auth, MFA, Transaction, and Payment gateway routes and centralized OpenAPI entries in [config-repo#39](https://github.com/digital-bank-java/config-repo/pull/39), tracked by [`.github#202`](https://github.com/digital-bank-java/.github/issues/202). +- No pull request was merged directly by the implementation agent. The remaining boundary is user review/merge followed by local SIT rollout evidence. + ### 2026-09-01 - Merged the event-driven implementation wave: Ledger Service PRs #14-#16, Account Service PRs #33-#36, Transaction Service PRs #6-#12, Auth Service PRs #1-#4, MFA Service PRs #1-#6, Payment Service PRs #1-#5, Notification Service PRs #1-#5, organization event contracts PR #137, and SIT Kafka topics PR #27. From 2dfc23c837dccf64dd594fffcb171adce22db2ae Mon Sep 17 00:00:00 2001 From: Rami Mohamed Date: Fri, 4 Sep 2026 05:50:32 +0400 Subject: [PATCH 4/8] docs: track gateway security review wave --- docs/project-handoff.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/project-handoff.md b/docs/project-handoff.md index 88b45b2..fd35863 100644 --- a/docs/project-handoff.md +++ b/docs/project-handoff.md @@ -266,6 +266,7 @@ deployed until accepted and verified: | [`config-repo#33`](https://github.com/digital-bank-java/config-repo/pull/33) and [`config-repo#34`](https://github.com/digital-bank-java/config-repo/pull/34) | Notification and Payment SIT configuration | | [`infra-sit#29`](https://github.com/digital-bank-java/infra-sit/pull/29) | Transfer-created Kafka topic and dead-letter topic provisioning | | [`config-repo#39`](https://github.com/digital-bank-java/config-repo/pull/39) | Auth, MFA, Transaction, and Payment gateway routes and centralized OpenAPI entries | +| [`api-gateway#23`](https://github.com/digital-bank-java/api-gateway/pull/23) | Feature-flagged JWT validation and scope authorization at the gateway | The application PRs report focused Maven, Helm, and container verification. The configuration PRs report YAML parsing and diff checks. SIT rollout, end-to-end @@ -282,6 +283,7 @@ High-priority missing capabilities: - complete governed account/transfer event-contract documentation and compatibility checks - integrated SIT rollout and end-to-end transfer verification across Transaction, Account, and Ledger services - rollout of the newly added gateway routes and SIT configuration for Auth, MFA, Transaction, and Payment +- gateway security rollout after the shared SIT secret is provisioned and the dependent configuration PRs are merged - service-to-service security and admin API authentication/authorization - API Gateway rate limiting and resilience rollout - centralized logging with OpenSearch, Fluent Bit, dashboards, and alerts @@ -390,6 +392,7 @@ Consult GitHub Project #1 for the authoritative Sprint hierarchy and current iss - Completed the Auth/MFA/Notification/Payment SIT configuration review wave in `config-repo#32`, `#33`, and `#34`, including shared issuer/scopes and README structure corrections. - Provisioned the transfer-created Kafka topic and dead-letter topic in [infra-sit#29](https://github.com/digital-bank-java/infra-sit/pull/29). - Added the missing Auth, MFA, Transaction, and Payment gateway routes and centralized OpenAPI entries in [config-repo#39](https://github.com/digital-bank-java/config-repo/pull/39), tracked by [`.github#202`](https://github.com/digital-bank-java/.github/issues/202). +- Added feature-flagged gateway JWT validation and scope authorization in [api-gateway#23](https://github.com/digital-bank-java/api-gateway/pull/23), tracked by [`.github#203`](https://github.com/digital-bank-java/.github/issues/203); updated config-repo#32 with `admin.internal` and config-repo#39 with the SIT enablement flag. - No pull request was merged directly by the implementation agent. The remaining boundary is user review/merge followed by local SIT rollout evidence. ### 2026-09-01 From 4c6233146ef76e1027a4813ee665a89a85c5d6e6 Mon Sep 17 00:00:00 2001 From: Rami Mohamed Date: Fri, 4 Sep 2026 06:56:37 +0400 Subject: [PATCH 5/8] docs: track durable auth and mfa persistence wave --- docs/project-handoff.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/project-handoff.md b/docs/project-handoff.md index fd35863..c754961 100644 --- a/docs/project-handoff.md +++ b/docs/project-handoff.md @@ -262,6 +262,8 @@ deployed until accepted and verified: | [`config-repo#32`](https://github.com/digital-bank-java/config-repo/pull/32) | Auth/MFA SIT configuration, shared issuer, and Auth scopes | | [`auth-service#6`](https://github.com/digital-bank-java/auth-service/pull/6) | Shared SIT JWT scope contract | | [`mfa-service#8`](https://github.com/digital-bank-java/mfa-service/pull/8) | HMAC/JWK JWT validation for SIT and cloud modes | +| [`auth-service#7`](https://github.com/digital-bank-java/auth-service/pull/7) | PostgreSQL-backed Auth session persistence and replica-safe revocation | +| [`mfa-service#9`](https://github.com/digital-bank-java/mfa-service/pull/9) | PostgreSQL-backed MFA enrollment/challenge persistence with encrypted TOTP secrets | | [`payment-service#7`](https://github.com/digital-bank-java/payment-service/pull/7) | HMAC/JWK JWT validation and SIT deployment contract | | [`config-repo#33`](https://github.com/digital-bank-java/config-repo/pull/33) and [`config-repo#34`](https://github.com/digital-bank-java/config-repo/pull/34) | Notification and Payment SIT configuration | | [`infra-sit#29`](https://github.com/digital-bank-java/infra-sit/pull/29) | Transfer-created Kafka topic and dead-letter topic provisioning | @@ -375,10 +377,10 @@ The current implementation wave is ready for review and rollout, in this order: 1. Merge [`.github#201`](https://github.com/digital-bank-java/.github/pull/201), the shared SIT Auth Secret runbook. 2. Merge [`config-repo#32`](https://github.com/digital-bank-java/config-repo/pull/32), then [`auth-service#6`](https://github.com/digital-bank-java/auth-service/pull/6). -3. Merge [`mfa-service#8`](https://github.com/digital-bank-java/mfa-service/pull/8) and [`payment-service#7`](https://github.com/digital-bank-java/payment-service/pull/7) in parallel. +3. Merge [`auth-service#7`](https://github.com/digital-bank-java/auth-service/pull/7) for durable sessions, then [`mfa-service#8`](https://github.com/digital-bank-java/mfa-service/pull/8), [`mfa-service#9`](https://github.com/digital-bank-java/mfa-service/pull/9), and [`payment-service#7`](https://github.com/digital-bank-java/payment-service/pull/7) in parallel. 4. Merge [`config-repo#33`](https://github.com/digital-bank-java/config-repo/pull/33), [`config-repo#34`](https://github.com/digital-bank-java/config-repo/pull/34), and [`infra-sit#29`](https://github.com/digital-bank-java/infra-sit/pull/29). The first two depend on config-repo#32; the Kafka topic PR can merge independently. 5. Merge [`config-repo#39`](https://github.com/digital-bank-java/config-repo/pull/39) after the corresponding service/configuration contracts are available. -6. Provision the local SIT Auth Secret, roll out the services, and verify health, protected workflows, Kafka delivery, centralized Swagger, and database state. +6. Provision the local SIT Auth Secret, MFA TOTP encryption Secret, and service databases; roll out the services and verify health, protected workflows, Kafka delivery, centralized Swagger, and database state. 7. Record runtime evidence in the supporting issues and synchronize Sprint 3, 4, and 5 statuses. Keep UAT/PROD cloud deployment deferred to Sprint 7. Consult GitHub Project #1 for the authoritative Sprint hierarchy and current issue status. @@ -395,6 +397,14 @@ Consult GitHub Project #1 for the authoritative Sprint hierarchy and current iss - Added feature-flagged gateway JWT validation and scope authorization in [api-gateway#23](https://github.com/digital-bank-java/api-gateway/pull/23), tracked by [`.github#203`](https://github.com/digital-bank-java/.github/issues/203); updated config-repo#32 with `admin.internal` and config-repo#39 with the SIT enablement flag. - No pull request was merged directly by the implementation agent. The remaining boundary is user review/merge followed by local SIT rollout evidence. +### 2026-09-04 - Durable Auth and MFA persistence review wave + +- Added PostgreSQL/Flyway Auth session persistence with transaction-safe same-user revocation in [auth-service#7](https://github.com/digital-bank-java/auth-service/pull/7), linked to `.github#28` and `.github#45`. +- Added PostgreSQL/Flyway MFA enrollment and challenge persistence with AES-256-GCM protected TOTP secrets in [mfa-service#9](https://github.com/digital-bank-java/mfa-service/pull/9), linked to `.github#29` and `.github#49`. +- Updated both container smoke workflows to start disposable PostgreSQL instances and pass only CI-local credentials; all Auth and MFA Maven, Helm, and container checks passed. +- SIT rollout requires the existing PostgreSQL Secret, separate `auth_service` and `mfa_service` databases, and an externally managed `mfa-service-secrets` key containing a base64-encoded 32-byte AES key. No secret material was committed. +- These PRs are open, non-draft, and awaiting user review. No pull request was merged directly by the implementation agent. + ### 2026-09-01 - Merged the event-driven implementation wave: Ledger Service PRs #14-#16, Account Service PRs #33-#36, Transaction Service PRs #6-#12, Auth Service PRs #1-#4, MFA Service PRs #1-#6, Payment Service PRs #1-#5, Notification Service PRs #1-#5, organization event contracts PR #137, and SIT Kafka topics PR #27. From 21fa575e49a63890f4b3e73d13743d8e9689b6b4 Mon Sep 17 00:00:00 2001 From: Rami Mohamed Date: Fri, 4 Sep 2026 07:04:39 +0400 Subject: [PATCH 6/8] docs: record MFA SIT rollout prerequisite --- docs/project-handoff.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/project-handoff.md b/docs/project-handoff.md index c754961..e71afe8 100644 --- a/docs/project-handoff.md +++ b/docs/project-handoff.md @@ -401,6 +401,8 @@ Consult GitHub Project #1 for the authoritative Sprint hierarchy and current iss - Added PostgreSQL/Flyway Auth session persistence with transaction-safe same-user revocation in [auth-service#7](https://github.com/digital-bank-java/auth-service/pull/7), linked to `.github#28` and `.github#45`. - Added PostgreSQL/Flyway MFA enrollment and challenge persistence with AES-256-GCM protected TOTP secrets in [mfa-service#9](https://github.com/digital-bank-java/mfa-service/pull/9), linked to `.github#29` and `.github#49`. +- Created the parented SIT rollout task [`.github#204`](https://github.com/digital-bank-java/.github/issues/204) for the `mfa_service` database and externally supplied `mfa-service-secrets` / `MFA_TOTP_ENCRYPTION_KEY` prerequisite. +- No secret material is stored in Git, Helm values, Config Server, or issue comments. UAT/PROD secret delivery remains deferred to Sprint 7. - Updated both container smoke workflows to start disposable PostgreSQL instances and pass only CI-local credentials; all Auth and MFA Maven, Helm, and container checks passed. - SIT rollout requires the existing PostgreSQL Secret, separate `auth_service` and `mfa_service` databases, and an externally managed `mfa-service-secrets` key containing a base64-encoded 32-byte AES key. No secret material was committed. - These PRs are open, non-draft, and awaiting user review. No pull request was merged directly by the implementation agent. From 1afb611cd1e36bb5426f52090a1552943f115835 Mon Sep 17 00:00:00 2001 From: Rami Mohamed Date: Fri, 4 Sep 2026 07:36:38 +0400 Subject: [PATCH 7/8] docs: record transfer risk gate wave --- docs/project-handoff.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/project-handoff.md b/docs/project-handoff.md index e71afe8..4de0e93 100644 --- a/docs/project-handoff.md +++ b/docs/project-handoff.md @@ -549,3 +549,13 @@ Consult GitHub Project #1 for the authoritative Sprint hierarchy and current iss - Payment Service is prepared in dependency order: HTTP lifecycle, PostgreSQL/idempotency/authorization, then resource-contract documentation. SIT configuration is available in `config-repo` on `feature/162-payment-service-sit-config`, but the service is not yet deployed in the SIT baseline. - Notification transfer-consumer verification reports 15 passing tests; the transfer-saga branch reports passing domain, persistence, and Spring integration suites. Their PR publication and Project updates remain blocked by expired GitHub CLI authentication. - GitHub Project status, parent, assignee, and native issue-type changes must be applied after authentication is restored; no item is to be treated as updated based only on local branch state. + +### 2026-09-04 - Transfer Risk Decision Gate + +- Started and implemented [.github#205](https://github.com/digital-bank-java/.github/issues/205) under Sprint 4 Story #55, with the project item moved to `In review`. +- Opened [transaction-service PR #16](https://github.com/digital-bank-java/transaction-service/pull/16) for review; it is intentionally not merged by the agent. +- Added a deterministic, configuration-driven transfer-risk gate with outcomes `ALLOW`, `REQUIRE_STEP_UP`, and `DECLINE` before account reservation is recorded. +- Persisted normalized transfer intent and the bound risk decision snapshot with Flyway migration 7, unique decision request/decision identifiers, expiry, and additive API response fields. +- `REQUIRE_STEP_UP` remains `PENDING` without a reservation action; `DECLINE` becomes `FAILED` without reservation or ledger actions. MFA challenge execution remains the follow-up under Story #56. +- Added focused risk-boundary tests, SIT verification documentation, runtime properties, and Helm values. Full Maven verify passed with 85 unit-phase tests and 15 integration tests; PostgreSQL Testcontainers, H2 migration validation, and Helm lint/render passed. +- No AWS/UAT/PROD work was started; this remains local SIT implementation. From 7427fe83f4a81ccb64175649905961e4ce0b605f Mon Sep 17 00:00:00 2001 From: Rami Mohamed Date: Fri, 4 Sep 2026 08:04:55 +0400 Subject: [PATCH 8/8] docs: record transfer-bound MFA challenge wave --- docs/project-handoff.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/project-handoff.md b/docs/project-handoff.md index 4de0e93..0718110 100644 --- a/docs/project-handoff.md +++ b/docs/project-handoff.md @@ -559,3 +559,12 @@ Consult GitHub Project #1 for the authoritative Sprint hierarchy and current iss - `REQUIRE_STEP_UP` remains `PENDING` without a reservation action; `DECLINE` becomes `FAILED` without reservation or ledger actions. MFA challenge execution remains the follow-up under Story #56. - Added focused risk-boundary tests, SIT verification documentation, runtime properties, and Helm values. Full Maven verify passed with 85 unit-phase tests and 15 integration tests; PostgreSQL Testcontainers, H2 migration validation, and Helm lint/render passed. - No AWS/UAT/PROD work was started; this remains local SIT implementation. + +### 2026-09-04 - Transfer-Bound MFA Challenge + +- Created and parented [.github#206](https://github.com/digital-bank-java/.github/issues/206) under Sprint 4 Story #56, assigned it to `ramioooz`, and placed it in `In review`. +- Opened [mfa-service PR #10](https://github.com/digital-bank-java/mfa-service/pull/10) as a non-draft dependent PR; durable persistence [mfa-service PR #9](https://github.com/digital-bank-java/mfa-service/pull/9) must merge first, with no delay required. +- Added transfer-bound challenge creation and verification APIs that retain the risk decision, authenticated subject, account references, normalized amount/currency, policy version, and correlation ID. +- Added PostgreSQL Flyway migration 2 and persistence rehydration for the immutable binding; mismatched transfer/decision/subject verification returns a controlled conflict. +- Verified focused controller coverage, persistence migration/rehydration, full Maven `verify` (42 unit-phase and 19 integration tests), Helm lint/render, and `git diff --check`. +- API Gateway routing and Transaction Service continuation after MFA assurance remain follow-up integration work; no AWS/UAT/PROD work was started.