Cloudbank version 5

cloudbank-v5/CBV5.md

@@ -0,0 +1,70 @@
+# Installing Cloudbank v5
+
+This repo contains a almost ready deployment of cloudbank v5. There are minimal changes to make this work in your environment. **NOTE:** this example assumes that OBaaS is installed in a namespace called `obaas-dev` and that CBv5 will be installed in the same namespace called `obaas-dev`.
+
+Cluudbank v5 has only been tested on Java 21.
+
+You must set the DOCKER_HOST variable to be able to build CLoudbank v5, for example if you're using Rancher Desktop on a Mac `export DOCKER_HOST=unix:///Users/atael/.rd/docker.sock`.
+
+**NOTE** the repositories must by public. Needs to investigate why private repos aren't working (authentication error). You can use the script `create-oci-repos.sh` to create the necessary repositories. For example `source create-oci-repos.sh andytael sjc.ocir.io/maacloud/cloudbank`.
+
+## Dependencies for Cloudbank
+
+Build dependencies and install  -- `mvn clean install -pl common,buildtools`
+
+## Build cloudbank
+
+A script called `update-jkube-image.sh` is provided to update the `pom.xml` file for JKube to point to the repository that will be used (update-jkube-image.sh <new-image-prefix> (sjc.ocir.io/maacloud/cloudbank-v5 for example)). When that change is made you can execute the following command to build and push the images:
+
+```bash
+mvn clean package k8s:build k8s:push -pl account,customer,transfer,checks,creditscore,testrunner
+```
+
+## Create account and customer DB users
+
+Update the `sqljob.yaml` file to reflect your environment. Run the job and **VERIFY** that the job finished successfully before proceeding.
+
+```bash
+k create -f sqljob.yaml
+```
+
+## Create secrets for account and customer microservices
+
+A script called `acc_cust_secrets.sh` is provided that could be used create the necessary secrets. This script *MUST* be updated to reflect your environment.
+
+## Change values.yaml
+
+A script called `update_image.sh` is provided that could be used to change the repository and tag to your environment (`./update-image.sh <repository> <tag>`) in the `values.yaml` file. For example `update-image.sh sjc.ocir.io/maacloud/cloudbank-v5 0.0.1-SNAPSHOT`.
+
+Verify and change credentialSecret and walletSecret values in the `values.yaml` if needed. Names can be found be looking at the secrets in the `obaas-dev` namespace.
+
+## Install CBv5
+
+A script call `deploy-all-services.sh` is provided that can be used to deploy all the Cloudbank services (account,customer,transfer,checks,creditscore,testrunner). For example `./deploy-all-services.sh obaas-dev`.
+
+## Create APISIX routes
+
+1. Retrieve the API KEY (requires `yq`) for APISIX by running this command:
+
+```bash
+kubectl -n obaas-dev get configmap apisix -o yaml | yq '.data."config.yaml"' | yq '.deployment.admin.admin_key[] | select(.name == "admin") | .key'
+```
+
+If the command doesn't work you can get the API key by looking into the ConfigMap 
+...... 
+
+1. Create tunnel to APISIX
+
+```shell
+kubectl port-forward -n obaas-dev svc/apisix-admin 9180
+```
+
+1. Create the routes by running this command:
+
+```bash
+(cd apisix-routes; source ./create-all-routes.sh <YOUR-API-KEY>)
+```
+
+## Test the services
+
+Follow the [README](README.md) section `Test CloudBank Services`.

cloudbank-v5/CLAUDE.md

@@ -0,0 +1,131 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+CloudBank v5 is a microservices-based banking application built with Spring Boot 3.4.6 and Java 21. It demonstrates Oracle Backend for Microservices and AI (OBaaS) capabilities, including distributed transactions using Long Running Actions (LRA), observability, and service mesh integration.
+
+## Build and Development Commands
+
+### Build the entire project
+```bash
+mvn clean package
+```
+
+### Run specific tests for a module
+```bash
+mvn test -pl <module-name>
+# Example: mvn test -pl account
+```
+
+### Code quality checks
+```bash
+# Run checkstyle validation
+mvn checkstyle:check
+
+# Run dependency vulnerability scan
+mvn org.owasp:dependency-check-maven:check
+```
+
+### Docker image build and push
+```bash
+mvn k8s:build
+```
+
+## Architecture
+
+### Microservices Structure
+- **account**: Account management service with journal/transaction tracking
+- **customer**: Customer management and profile operations
+- **transfer**: Inter-account transfer service with LRA support
+- **checks**: Check deposit/clearance processing
+- **creditscore**: Credit scoring service
+- **chatbot**: AI-powered chatbot service (optional)
+- **testrunner**: Test automation and system testing utilities
+- **common**: Shared configuration and utilities
+- **buildtools**: Development tooling and quality checks
+
+### Key Architectural Patterns
+- **Event-driven Architecture**: Services communicate via REST APIs with distributed transaction support
+- **Saga Pattern**: Implemented using Oracle MicroTx LRA for distributed transactions
+- **Service Discovery**: Eureka-based service registration and discovery
+- **Circuit Breaker**: OpenFeign with resilience patterns
+- **Observability**: OpenTelemetry tracing, Micrometer metrics, Prometheus monitoring
+
+### Database Design
+- Oracle Database with UCP connection pooling
+- Liquibase for database migrations
+- JPA/Hibernate for ORM with optimistic locking
+- Each service has its own schema (account, customer, etc.)
+
+### Configuration Management
+- Spring Cloud Config for centralized configuration
+- Service-specific `application.yaml` files
+- Common configuration shared via `common.yaml`
+- Environment-specific overrides through externalized config
+
+## Technology Stack
+
+### Core Framework
+- Spring Boot 3.4.6 with Virtual Threads enabled
+- Spring Cloud 2024.0.1 for microservices infrastructure
+- Oracle MicroTx for distributed transactions
+
+### Database & Persistence
+- Oracle Database with oracle-spring-boot-starter-ucp
+- Liquibase for schema migrations
+- JPA/Hibernate with Oracle dialect
+
+### Observability & Monitoring
+- OpenTelemetry for distributed tracing
+- Micrometer with Prometheus for metrics
+- SigNoz for APM and observability dashboards
+- Spring Boot Actuator for health checks
+
+### Service Communication
+- OpenFeign for service-to-service communication
+- Eureka for service discovery
+- APISIX for API gateway and routing
+
+## Development Guidelines
+
+### LRA Transaction Patterns
+- Use `@LRA(value = LRA.Type.REQUIRES_NEW)` for new transaction boundaries
+- Implement `@Complete` and `@Compensate` methods for saga compensation
+- Pass LRA context headers between services for transaction correlation
+
+### REST API Conventions
+- All APIs follow `/api/v1/` versioning pattern
+- Use standard HTTP status codes (201 for creation, 204 for deletion)
+- Return `Location` headers for created resources
+- Implement proper error handling with meaningful HTTP status codes
+
+### Database Patterns
+- Use repository pattern with Spring Data JPA
+- Implement proper transaction boundaries at service layer
+- Follow naming conventions: `findBy*`, `existsById`, etc.
+- Use `saveAndFlush()` for immediate persistence when needed
+
+### Testing Approach
+- Unit tests with Spring Boot Test slice annotations
+- Integration tests using `@SpringBootTest`
+- Use testrunner service for end-to-end system testing
+- Mock external service dependencies with WireMock or similar
+
+## Common Issues & Solutions
+
+### LRA Transaction Timeouts
+- Check MicroTx coordinator connectivity via `${MP_LRA_COORDINATOR_URL}`
+- Verify LRA headers are properly propagated between services
+- Monitor transaction logs for compensation trigger patterns
+
+### Service Discovery Issues
+- Verify Eureka client configuration in `common.yaml`
+- Check service registration with Eureka dashboard
+- Ensure `spring.application.name` matches service discovery expectations
+
+### Database Connection Problems
+- Validate Oracle UCP configuration in service-specific `application.yaml`
+- Check connection pool sizing (`initial-pool-size`, `max-pool-size`)
+- Verify Liquibase migrations complete successfully during startup