update README.md with some gibbity after proofreading

greatestusername · greatestusername · commit e1e51fa4a7fb · 2025-10-23T15:41:02.000-04:00
diff --git a/src/shop-dc-shim/README.md b/src/shop-dc-shim/README.md
@@ -1,38 +1,127 @@
 # Shop Datacenter Shim Service
 
-The Shop Datacenter Shim Service is an N-Tier Java Spring Boot application that simulates a traditional on-premises retail system deployed in a datacenter environment. This service demonstrates hybrid cloud-on-premises integration by acting as a shim that bridges local shop purchases to cloud checkout services.
+The Shop Datacenter Shim Service is an N-Tier Java Spring Boot application that simulates a traditional on-premises retail system deployed in a datacenter environment. This service demonstrates hybrid cloud-on-premises integration by acting as a shim that bridges local shop purchases to cloud checkout services.  
 
-## Architecture
+**NOTE:** This demo is an addition to an existing Astronomy Shop Demo and expects a deployment of such in the same k8s cluster
 
-This service follows traditional enterprise N-Tier architecture:
+## Demo Use Case
 
-- **Presentation Layer**: REST controllers for shop transaction APIs
-- **Business Layer**: Service classes handling local validation and cloud integration
-- **Data Layer**: JPA repositories with PostgreSQL for local transaction storage
-- **Integration Layer**: gRPC client for calling cloud checkout services
+This service demonstrates a real-world hybrid architecture scenario:
+
+- **On-Premises Reality**: Traditional retail POS systems deployed in datacenters
+- **Cloud Integration**: Modern checkout and payment processing in the cloud
+- **Monitoring Bridge**: Shows how enterprises monitor hybrid architectures
+- **Technology Evolution**: Traditional Java/DB architecture calling modern microservices
+
+## Demo Features & Intentional Errors
 
-## Key Features
+### Intentional Jackson Serialization Errors
+The service includes **intentional Jackson serialization errors** on the transaction status endpoint (`GET /api/shop/transaction/{transactionId}`) to demonstrate real-world error scenarios:
 
-- **On-Premises Retail Simulation**: Mimics traditional datacenter-deployed point-of-sale systems
-- **Cloud Integration**: Makes gRPC calls to cloud-hosted checkout service
-- **Dual Instrumentation**: Supports both AppDynamics (traditional) and Splunk Observability (modern)
-- **Enterprise Patterns**: Follows traditional enterprise Java patterns with database persistence
-- **Async Processing**: Background processing with transaction state management
-- **Load Generation**: Dedicated load generator simulating realistic shop transactions
+**What Works As Intended:**
+- ✅ Purchase submissions (`POST /api/shop/purchase`) - returns 202 successfully
+- ✅ Background transaction processing and database persistence
+- ✅ gRPC calls to cloud checkout service 
+
+### Business Context
+- Local shop systems handle inventory, pricing, customer data
+- Cloud services provide scalable checkout, payment, and fulfillment
+- Dual monitoring shows both AppDynamics and Splunk Observability
+- Demonstrates enterprise modernization patterns
 
 ## Environment Configuration
 
 ### Deployment Environment
+**NOTE:** These new services will be in a separate environment from your Astronomy Shop Demo. Filter to both environments to see the entire service map.
 - `deployment.environment.name`: `datacenter-b01`
 - `service.namespace`: `datacenter`
 - Network: Separate datacenter network (172.20.0.0/16) with bridge to cloud services
 
 ### Service Configuration
 - **Service Port**: 8070
-- **Database**: PostgreSQL (shop-dc-shim-db)
+- **Database**: SQL Server (shop-dc-shim-db)
 - **Cloud Integration**: gRPC to checkout service
 - **Monitoring**: Dual AppDynamics + Splunk Observability
 
+## Development / Contribution
+
+### Using Demo In A Box instance (from Splunk Show Observability4Ninjas / Portfolio Demo)
+**Note:** This requires the instance to have a k3s/k3d deployment with Astronomy Shop Demo
+- Update and use `build-image-quay-dev.sh` to build a new image with your local changes
+- Reference that new image in `k8s-addition.yaml` and copy to your instance
+- `kubectl apply -f k8s-addition.yaml` will add the `shop-dc-shim-db`, `shop-dc-shim`, and `shop-dc-load-generator` pods to your cluster
+- Once `shop-dc-shim` finishes spinning up (5-7min) the load generator will start sending traffic
+- To delete `kubectl delete -f k8s-addition.yaml` will remove all shop-dc related resources
+
+### Bare Metal (thar may be dragons)
+**NOTE:** REQUIRES A DEPLOYMENT OF ASTRONOMY SHOP DEMO IN A LOCAL K3S CLUSTER
+```bash
+# Build the service
+./gradlew build
+
+# Run with local profile
+java -jar build/libs/shop-dc-shim-*.jar
+
+# Run load generator
+cd load-generator
+pip install -r requirements.txt
+python shop_load_generator.py --url http://localhost:8070
+
+# Docker build
+docker build -t shop-dc-shim:latest .
+```
+
+## Architecture
+
+This service follows traditional enterprise N-Tier architecture:
+
+- **Presentation Layer**: REST controllers for shop transaction APIs
+- **Business Layer**: Service classes handling local validation and cloud integration
+- **Data Layer**: JPA repositories with SQL Server for local transaction storage
+- **Integration Layer**: gRPC client for calling cloud checkout services
+
+## Configuration
+
+### Environment Variables
+
+**Service Configuration:**
+- `SHOP_DC_SHIM_PORT`: Service port (default: 8070)
+- `DB_CONNECTION_STRING`: SQL Server connection string (jdbc:sqlserver://...)
+- `DB_USERNAME`: Database username (default: sa)
+- `DB_PASSWORD`: Database password (default: ShopPass123!)
+- `CHECKOUT_SERVICE_ADDR`: Cloud checkout service address (default: checkout:8080)
+- `CHECKOUT_SERVICE_HOST`: Cloud checkout service host (default: checkout)
+- `CHECKOUT_SERVICE_PORT`: Cloud checkout service port (default: 8080)
+
+**AppDynamics Configuration:**
+- `APPDYNAMICS_JAVAAGENT_ENABLED`: Enable AppD agent
+- `APPDYNAMICS_CONTROLLER_HOST_NAME`: AppD controller
+- `APPDYNAMICS_AGENT_APPLICATION_NAME`: App name in AppD
+- `APPDYNAMICS_AGENT_TIER_NAME`: Tier name in AppD
+
+**Splunk Observability:**
+- `OTEL_EXPORTER_OTLP_ENDPOINT`: OTLP collector endpoint
+- `OTEL_RESOURCE_ATTRIBUTES`: Resource attributes
+- `SPLUNK_PROFILER_ENABLED`: Enable profiler
+
+### Startup Script
+The service uses `start-app-dual.sh` which matches enterprise Ansible deployment patterns:
+
+```bash
+# AppDynamics + Splunk dual instrumentation
+export AGENT_DEPLOYMENT_MODE=dual
+java -javaagent:/opt/appdynamics/javaagent.jar \
+     -Dagent.deployment.mode=dual \
+     -Dotel.instrumentation.jdbc.enabled=true \
+     -Dsplunk.profiler.enabled=true \
+     -Dsplunk.profiler.memory.enabled=true \
+     -Dsplunk.snapshot.profiler.enabled=true \
+     -Dsplunk.snapshot.selection.probability=0.2 \
+     -Dotel.exporter.otlp.endpoint=http://splunk-otel-collector-agent:4318 \
+     -Dappdynamics.sim.enabled=true \
+     -jar /app/*.jar
+```
+
 ## API Endpoints
 
 ### POST /api/shop/purchase
@@ -106,6 +195,29 @@ Check the status of a shop transaction.
 }
 ```
 
+### GET /api/shop/store/{storeLocation}/transactions
+Get recent transactions for a specific store location.
+
+**Query Parameters:**
+- `hours` (optional): Number of hours to look back (default: 24)
+
+**Response:**
+```json
+{
+  "storeLocation": "DC-NYC-01",
+  "hoursBack": 24,
+  "transactionCount": 15,
+  "transactions": [
+    {
+      "transactionId": "uuid-string",
+      "status": "COMPLETED",
+      "totalAmount": 299.99,
+      "createdAt": "2024-01-01T10:00:00"
+    }
+  ]
+}
+```
+
 ### GET /api/shop/health
 Health check endpoint with transaction statistics.
 
@@ -128,6 +240,60 @@ Health check endpoint with transaction statistics.
 }
 ```
 
+
+
+## Request Flow Through Java Components
+
+### End-to-End Transaction Processing Flow
+
+When a purchase request is submitted to the shop-dc-shim service, it flows through these Java components:
+
+1. **ShopController.processPurchase()** (`/api/shop/purchase`)
+   - Receives HTTP POST request with purchase details
+   - Creates OpenTelemetry span for tracing
+   - Validates request using `@Valid` annotation
+   - Calls `ShopTransactionService.initiateShopPurchase()`
+   - Returns HTTP 202 (Accepted) with transaction ID
+
+2. **ShopTransactionService.initiateShopPurchase()**
+   - Generates unique transaction ID and local order ID
+   - Creates `ShopTransaction` entity with INITIATED status
+   - Serializes shipping address and items to JSON
+   - Saves transaction to SQL Server database
+   - Calls `processTransactionAsync()` for background processing
+   - Returns transaction ID to controller
+
+3. **ShopTransactionService.processTransactionAsync()** (Async)
+   - Runs in background thread pool
+   - Updates transaction status to VALIDATING
+   - Calls `performLocalValidation()` for on-premises validation
+   - Updates status to SUBMITTING_CLOUD
+   - Calls `CloudCheckoutService.submitToCloudCheckout()`
+   - Processes cloud response and updates transaction status
+   - Saves final transaction state to database
+
+4. **ShopTransactionService.performLocalValidation()**
+   - Simulates on-premises validation logic:
+     - Local inventory checks
+     - Customer information validation
+     - Fraud detection
+     - Payment limits verification
+   - Adds processing delay to simulate real validation
+
+5. **CloudCheckoutService.submitToCloudCheckout()**
+   - Creates gRPC channel to checkout service
+   - Generates unique user ID for cloud transaction
+   - Calls `buildGrpcRequest()` to create protobuf request
+   - Makes blocking gRPC call to checkout service
+   - Returns `CloudCheckoutResult` with success/failure status
+
+6. **CloudCheckoutService.buildGrpcRequest()**
+   - Converts shop purchase request to protobuf format
+   - Builds `Address`, `CreditCardInfo`, and `PlaceOrderRequest` messages
+   - Returns properly formatted gRPC request
+
+The entire flow is instrumented with OpenTelemetry spans for distributed tracing, and each step updates the transaction status in the SQL Server database for monitoring and reconciliation.
+
 ## Transaction Processing Flow
 
 1. **Local Purchase Initiation**: Customer makes purchase at store terminal
@@ -138,55 +304,12 @@ Health check endpoint with transaction statistics.
 6. **Confirmation**: Local transaction updated with cloud response
 7. **Completion**: Final status stored locally for reconciliation
 
-## Transaction States
-
-- `INITIATED`: Local transaction started
-- `VALIDATING`: Performing local validation checks
-- `SUBMITTING_CLOUD`: Sending request to cloud checkout
-- `CLOUD_PROCESSING`: Cloud is processing the request
-- `COMPLETED`: Successfully completed end-to-end
-- `FAILED`: Failed at any stage
-- `RETRY_PENDING`: Queued for retry
-
-## Database Schema
-
-The service uses PostgreSQL with the following main tables:
-
-```sql
--- Main transaction table
-CREATE TABLE shop_transactions (
-    id BIGSERIAL PRIMARY KEY,
-    transaction_id VARCHAR(255) UNIQUE NOT NULL,
-    local_order_id VARCHAR(255) NOT NULL,
-    cloud_order_id VARCHAR(255),
-    customer_email VARCHAR(255) NOT NULL,
-    customer_name VARCHAR(255),
-    total_amount DECIMAL(10,2),
-    currency_code CHAR(3),
-    status VARCHAR(20) NOT NULL DEFAULT 'INITIATED',
-    store_location VARCHAR(100),
-    terminal_id VARCHAR(50),
-    -- ... additional fields for timestamps, addresses, etc.
-);
-
--- Store location lookup
-CREATE TABLE store_locations (
-    id SERIAL PRIMARY KEY,
-    store_code VARCHAR(10) UNIQUE NOT NULL,
-    store_name VARCHAR(100) NOT NULL,
-    address TEXT,
-    city VARCHAR(50),
-    state VARCHAR(50),
-    country VARCHAR(50),
-    timezone VARCHAR(50) DEFAULT 'America/New_York',
-    is_active BOOLEAN DEFAULT true
-);
-```
+
+
+
 
 ## Monitoring & Observability
 
-### Dual Instrumentation
-The service supports both traditional and modern observability:
 
 **AppDynamics (Traditional APM)**
 - Application: `shop-dc-shim-service`
@@ -243,73 +366,9 @@ python shop_load_generator.py --mode burst --concurrent 20 --total 50
 python shop_load_generator.py --mode single
 ```
 
-## Demo Use Case
-
-This service demonstrates a real-world hybrid architecture scenario:
-
-- **On-Premises Reality**: Traditional retail POS systems deployed in datacenters
-- **Cloud Integration**: Modern checkout and payment processing in the cloud
-- **Monitoring Bridge**: Shows how enterprises monitor hybrid architectures
-- **Technology Evolution**: Traditional Java/DB architecture calling modern microservices
-
-### Business Context
-- Local shop systems handle inventory, pricing, customer data
-- Cloud services provide scalable checkout, payment, and fulfillment
-- Dual monitoring shows both traditional APM and modern observability
-- Demonstrates enterprise modernization patterns
 
-## Configuration
 
-### Environment Variables
 
-**Service Configuration:**
-- `SHOP_DC_SHIM_PORT`: Service port (default: 8070)
-- `DB_CONNECTION_STRING`: PostgreSQL connection
-- `CHECKOUT_SERVICE_HOST`: Cloud checkout service host
-- `CHECKOUT_SERVICE_PORT`: Cloud checkout service port
-
-**AppDynamics Configuration:**
-- `APPDYNAMICS_JAVAAGENT_ENABLED`: Enable AppD agent
-- `APPDYNAMICS_CONTROLLER_HOST_NAME`: AppD controller
-- `APPDYNAMICS_AGENT_APPLICATION_NAME`: App name in AppD
-- `APPDYNAMICS_AGENT_TIER_NAME`: Tier name in AppD
-
-**Splunk Observability:**
-- `OTEL_EXPORTER_OTLP_ENDPOINT`: OTLP collector endpoint
-- `OTEL_RESOURCE_ATTRIBUTES`: Resource attributes
-- `SPLUNK_PROFILER_ENABLED`: Enable profiler
-
-### Startup Script
-The service uses `start-app-dual.sh` which matches enterprise Ansible deployment patterns:
-
-```bash
-# AppDynamics + Splunk dual instrumentation
-export AGENT_DEPLOYMENT_MODE=dual
-java -javaagent:appdynamics/javaagent.jar \
-     -javaagent:opentelemetry-javaagent.jar \
-     -Dagent.deployment.mode=dual \
-     -Dotel.instrumentation.jdbc.enabled=true \
-     -Dsplunk.profiler.enabled=true \
-     -jar app.jar
-```
-
-## Local Development
-
-```bash
-# Build the service
-./gradlew build
-
-# Run with local profile
-java -jar build/libs/shop-dc-shim-*.jar
-
-# Run load generator
-cd load-generator
-pip install -r requirements.txt
-python shop_load_generator.py --url http://localhost:8070
-
-# Docker build
-docker build -t shop-dc-shim:latest .
-```
 
 ## Docker Compose Setup
 
@@ -325,7 +384,23 @@ networks:
         - subnet: 172.20.0.0/16
 
 services:
+  shop-dc-shim-db:
+    image: mcr.microsoft.com/mssql/server:2022-latest
+    environment:
+      - ACCEPT_EULA=Y
+      - MSSQL_SA_PASSWORD=ShopPass123!
+    ports:
+      - "1433:1433"
+    networks:
+      - datacenter-network
+
   shop-dc-shim:
+    depends_on:
+      - shop-dc-shim-db
+    environment:
+      - DB_CONNECTION_STRING=jdbc:sqlserver://shop-dc-shim-db:1433;databaseName=master;encrypt=false;trustServerCertificate=true
+      - DB_USERNAME=sa
+      - DB_PASSWORD=ShopPass123!
     networks:
       - datacenter-network  # On-prem network
       - default             # Cloud service connectivity
diff --git a/src/shop-dc-shim/k8s-addition.yaml b/src/shop-dc-shim/k8s-addition.yaml
@@ -1,3 +1,5 @@
+### Expects a deployment of Astronomy Shop Demo in the same cluster
+### Uses checkout service from that demo
 ---
 apiVersion: v1
 kind: Service

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+### Expects a deployment of Astronomy Shop Demo in the same cluster`
	`2`	`+### Uses checkout service from that demo`
`1`	`3`	`---`
`2`	`4`	`apiVersion: v1`
`3`	`5`	`kind: Service`