If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/GoogleCloudPlatform/microservices-demo shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 5 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 59% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live GoogleCloudPlatform/microservices-demo repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/GoogleCloudPlatform/microservices-demo.

What it runs against: a local clone of GoogleCloudPlatform/microservices-demo — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in GoogleCloudPlatform/microservices-demo | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of GoogleCloudPlatform/microservices-demo. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/GoogleCloudPlatform/microservices-demo.git
#   cd microservices-demo
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of GoogleCloudPlatform/microservices-demo and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "GoogleCloudPlatform/microservices-demo(\\.git)?\\b" \\
  && ok "origin remote is GoogleCloudPlatform/microservices-demo" \\
  || miss "origin remote is not GoogleCloudPlatform/microservices-demo (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "kubernetes-manifests/kustomization.yaml" \\
  && ok "kubernetes-manifests/kustomization.yaml" \\
  || miss "missing critical file: kubernetes-manifests/kustomization.yaml"
test -f "helm-chart/Chart.yaml" \\
  && ok "helm-chart/Chart.yaml" \\
  || miss "missing critical file: helm-chart/Chart.yaml"
test -f "helm-chart/values.yaml" \\
  && ok "helm-chart/values.yaml" \\
  || miss "missing critical file: helm-chart/values.yaml"
test -f ".github/workflows/ci-main.yaml" \\
  && ok ".github/workflows/ci-main.yaml" \\
  || miss "missing critical file: .github/workflows/ci-main.yaml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/GoogleCloudPlatform/microservices-demo"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Online Boutique is a production-grade microservices reference architecture implementing a full e-commerce platform (product browsing, shopping cart, payment processing) using 11 gRPC-connected services written in Go, Python, Node.js, C#, and Java. It demonstrates how to build cloud-native applications on Google Cloud Platform (GKE, Service Mesh, Spanner, Memorystore, AlloyDB) while remaining Kubernetes-agnostic—the core demo is deployment-platform-independent. Flat service-oriented: /src/ contains 11 independent microservice directories (frontend/, cartservice/, productcatalogservice/, paymentservice/, etc.), each with own Dockerfile and language-specific build config. Protocol buffer definitions in /protos/ shared across all services. Deployment configs (Kubernetes manifests, Terraform, Helm charts) in root and .github/release-cluster/. CI pipeline definitions in .github/workflows/.

Enterprise architects and Kubernetes engineers evaluating cloud modernization strategies; GCP sales engineers demonstrating cloud-first patterns; DevOps engineers learning Istio service mesh configuration; polyglot developers building distributed systems with gRPC; teams migrating monoliths to microservices and needing a concrete reference implementation.

Actively maintained with strong Google backing (part of official GCP demos) and visible CI/CD pipelines in .github/workflows/ (ci-main.yaml, ci-pr.yaml, helm-chart-ci.yaml). The breadth of deployment options (Terraform in .github/terraform/, Kustomize, Helm, DeployStack) and multi-language support indicate production-ready quality. Regular dependency updates via Renovate (renovate.json5) and structured testing confirm active development.

High dependency complexity across 5+ languages (Java gRPC 1.80.0, Jackson 2.21.2, protobuf 4.34.1, plus Go, Python, Node.js, C# ecosystems) means security updates require coordination across teams. Single-source-of-truth risk: Google Cloud services (Spanner, Memorystore, AlloyDB) tightly integrated into demos may limit portability if running outside GCP. Proto file changes in ./protos require regeneration across all 11 services.

Active development on cloud-backend integrations (AlloyDB, Spanner references in README); CI automation for Helm charts, Kustomize builds, Terraform validation; dependency updates via Renovate; documentation in docs/ including adding-new-microservice.md and development-guide.md suggesting ongoing contributor onboarding.

git clone https://github.com/GoogleCloudPlatform/microservices-demo.git
cd microservices-demo
# Install dependencies (language-specific; see src/* for per-service setup)
# To deploy: kubectl apply -f kubernetes-manifests/ (requires GKE or Kubernetes cluster)
# Or use Terraform: cd .github/terraform && terraform apply

Daily commands: Service-specific: each /src/SERVICE/ has build instructions. Example for Go services: go build -o service-name ./cmd/main.go. For Docker: docker build -t service-name . in service directory. Full cluster deployment: kubectl apply -f kubernetes-manifests/ (requires active Kubernetes cluster and GCP credentials for cloud services). Local development: see docs/development-guide.md.

• README.md — Entry point describing the entire Online Boutique microservices architecture, deployment options, and GCP integration patterns.
• kubernetes-manifests/kustomization.yaml — Root Kustomize configuration defining all 10 microservices deployments and their orchestration on Kubernetes.
• helm-chart/Chart.yaml — Helm chart metadata for packaging and deploying the entire application stack in production environments.
• helm-chart/values.yaml — Central configuration file for all microservice images, replicas, resources, and GCP service integrations.
• .github/workflows/ci-main.yaml — CI/CD pipeline that validates builds, tests, and releases container images for all services.
• docs/development-guide.md — Essential guide explaining how to build, run, and develop microservices locally and on GKE.
• docs/adding-new-microservice.md — Step-by-step instructions for extending the codebase with new gRPC microservices following established patterns.

Add a New Microservice

1. Review the template pattern in docs/adding-new-microservice.md (docs/adding-new-microservice.md)
2. Create Kubernetes deployment manifest following conventions in existing services (kubernetes-manifests/adservice.yaml)
3. Add Helm template configuration for the new service (helm-chart/templates/adservice.yaml)
4. Add kustomize base manifest alongside other services (kustomize/base/adservice.yaml)
5. Include service in root kustomization to enable deployment (kubernetes-manifests/kustomization.yaml)
6. Update Helm chart values with image, ports, and resource configs (helm-chart/values.yaml)

Configure Service Mesh (Istio) Routing

1. Define ingress gateway for external traffic entry (istio-manifests/frontend-gateway.yaml)
2. Create VirtualService to route traffic to backend services (istio-manifests/frontend.yaml)
3. Add egress policies for external API calls (e.g., to Google Cloud APIs) (istio-manifests/allow-egress-googleapis.yaml)

Add GCP Service Integration (Spanner, Memorystore, AlloyDB)

1. Update Helm values.yaml to inject credentials and connection strings (helm-chart/values.yaml)
2. Add environment variables and secret mounts in service deployment templates (helm-chart/templates/cartservice.yaml)
3. Reference integration in service-specific Kubernetes manifest (kubernetes-manifests/cartservice.yaml)

Update CI/CD Pipeline

1. Define build and test steps for new services (.github/workflows/ci-main.yaml)
2. Configure cloud build steps for container image creation (cloudbuild.yaml)
3. Execute release script to create versioned artifacts (docs/releasing/make-release.sh)

• gRPC — Inter-service communication with strong typing, low latency, HTTP/2 multiplexing, and polyglot support across 10 microservices
• Kubernetes + Istio — Production-grade container orchestration with declarative deployment, auto-scaling, traffic management, and observability
• Helm Charts — Templated Kubernetes manifests enabling multi-environment configuration (dev/staging/prod) with parameterized values
• Memorystore (Redis) — In-memory cache for cart service session state, reducing latency and database load
• Google Cloud Services (Spanner, AlloyDB, Cloud Operations) — Demonstrate modern GCP integrations for databases, tracing, logging, and metrics in a cloud-native context

• gRPC for internal communication vs REST APIs

  • Why: gRPC provides better performance and type safety for service-to-service calls, reducing serialization overhead
  • Consequence: Developers must learn Protocol Buffers and gRPC tooling; REST-only clients require gRPC gateway for external access

• Monolithic frontend vs separate frontend service

  • Why: Single frontend service simplifies deployment and reduces inter-service latency for UI rendering
  • Consequence: Frontend becomes a potential bottleneck; scaling requires containerization separate from backend services

• Istio service mesh for traffic control

  • Why: Enables traffic splitting, canary deployments, and observability without modifying application code
  • Consequence: Adds operational complexity; Istio sidecars increase resource consumption and debugging difficulty

• Declarative infrastructure (Helm + Kustomize)

  • Why: Gitops-friendly approach enabling version control, reproducible deployments, and multi-environment support
  • Consequence: Steep learning curve for teams unfamiliar with templating; debugging requires understanding layering order

• Not a production-grade e-commerce platform—omits critical features like fraud detection, PCI compliance, and advanced inventory management
• Does not implement authentication/authorization layer (demo assumes trusted internal network)
• Not optimized for extreme scale—uses single-region deployment without global load balancing strategies
• Does not include persistent data migration tools or schema versioning utilities for production database evolution

Environment dependencies: running full demo requires GCP project with enabled APIs (GKE, Spanner, Memorystore, Service Mesh) and active gcloud credentials. Proto regeneration: modifying /protos/ requires running language-specific proto compilers; Java uses Gradle (see src/adservice/build.gradle protobuf block), but Go/Python/C# tools must be run manually or via CI. Service startup order: frontend depends on product-catalog and cart services being reachable; Kubernetes deployment handles this, but local testing requires manual startup. Redis hard dependency: cartservice fails without Redis; kubernetes-manifests/redis.yaml provides it in cluster. Multi-language toolchain: dev environment needs Go, Python, Node.js, C#/dotnet, and Java installed for full local testing.

• gRPC and Protocol Buffers — Every inter-service communication in Online Boutique uses gRPC over HTTP/2 with .proto contracts; understanding proto message evolution and gRPC streaming is essential to extend or modify the demo
• Service Mesh (Istio) — While optional, the README and docs/ reference Istio for observability, traffic splitting, and mTLS in production; knowing how sidecar proxies intercept gRPC calls helps troubleshoot network issues
• Microservices communication patterns — Online Boutique demonstrates synchronous gRPC-based communication (frontend calls product catalog, cart service) and asynchronous patterns (caching in Redis); critical for understanding failure modes and latency optimization
• Kubernetes Deployments, Services, and ConfigMaps — The kubernetes-manifests/ directory structures all 11 services as separate Deployments with internal Services; native Kubernetes knowledge is required to debug pod crashes, update replicas, or change environment variables
• Infrastructure-as-Code (Terraform) — The .github/terraform/ setup provisions GKE clusters and cloud services automatically; understanding HCL and cloud resource dependencies helps customize the demo for different GCP projects or regions
• Multi-language build and dependency management — Services use Go modules, Python pip/requirements.txt, Node.js npm, C# NuGet, and Java Gradle; the CI in .github/workflows/ must coordinate builds across ecosystems, making polyglot dependency version conflicts a real challenge
• Cloud-native observability (Cloud Operations, tracing, metrics) — The README mentions Cloud Operations (GCP's managed logging, tracing, and monitoring); the demo integrates with OpenTelemetry SDKs in some services to emit traces and metrics critical for diagnosing microservice issues at scale

• GoogleCloudPlatform/cloud-run-microservices-demo — Similar Google-owned e-commerce demo but target Cloud Run (serverless) instead of Kubernetes; shares proto definitions and service concepts
• grpc/grpc-go — Core gRPC Go implementation used by frontend and product catalog services; understanding gRPC internals helps optimize service communication
• istio/istio — Service mesh referenced in README for traffic management and observability; optional but recommended layer for production deployments of Online Boutique
• kubernetes/kubernetes — Foundation orchestrator for all deployments; kubernetes-manifests/ contains YAML targeting Kubernetes API directly
• GoogleCloudPlatform/kubernetes-engine-samples — Companion repo with GKE-specific patterns (workload identity, managed certificates, ingress); shares deployment philosophy with this demo

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add CI workflow for Helm Chart linting and template validation

The repo has .github/workflows/helm-chart-ci.yaml listed but no corresponding Helm linting workflow. While helm-chart/ directory exists with templates for multiple services (adservice, cartservice, checkoutservice, currencyservice, etc.), there's no automated validation that Helm templates render correctly or follow best practices. This prevents catching template syntax errors, missing required values, or chart.yaml issues before deployment.

• [ ] Create .github/workflows/helm-lint-ci.yaml that runs helm lint helm-chart/ on PRs
• [ ] Add helm template validation to ensure all service templates (adservice.yaml, cartservice.yaml, etc.) render without errors
• [ ] Integrate Helm chart testing with chart-testing tool to validate Chart.yaml metadata and chart dependencies
• [ ] Reference the existing .github/workflows/helm-chart-ci.yaml to avoid duplication and coordinate CI stages

Add integration test workflow for DeployStack configuration

The repo includes .deploystack/deploystack.yaml, pre-init scripts at .deploystack/scripts/preinit.sh, and test configuration at .deploystack/test.yaml, but there's no GitHub Action that validates the DeployStack deployment end-to-end. This means breaking changes to deployment scripts or configuration could go undetected. A workflow should verify that the preinit script executes without errors and that the deployment manifests are valid.

• [ ] Create .github/workflows/deploystack-validation-ci.yaml that executes .deploystack/scripts/preinit.sh in a controlled environment
• [ ] Add validation step to verify .deploystack/deploystack.yaml structure against DeployStack schema
• [ ] Run kubectl apply --dry-run=client -f on generated manifests from .deploystack/test.yaml to catch invalid Kubernetes configurations
• [ ] Document the workflow in .github/workflows/README.md explaining how contributors should test DeployStack changes locally

Add Protocol Buffer code generation validation to CI

The build.gradle for adservice (and likely other services) defines protobuf compilation with gRPC plugin at version 1.80.0, but there's no CI workflow that validates .proto files compile correctly across all services before merging. This risks shipping proto definitions that fail compilation in dependent services or have breaking changes to the API contract.

• [ ] Create .github/workflows/protobuf-validation-ci.yaml that discovers all .proto files across microservice directories
• [ ] Add steps to compile .proto files for each service using the configured protoc version (4.34.1) and grpc-java plugin (1.80.0)
• [ ] Validate that generated Java source files don't introduce compilation errors with Java 21 (as specified in build.gradle sourceCompatibility)
• [ ] Add a step to check for proto breaking changes using buf tool if .proto files reference a buf.yaml configuration, and document this in docs/adding-new-microservice.md

• Add integration tests for the cartservice-to-Redis connection: The src/cartservice/ C# service has no visible unit tests in the repo structure; writing tests covering Redis cache hits/misses and error cases would improve reliability and serve as documentation for the Redis integration pattern used by other services.
• Document the Protocol Buffer compilation workflow: While docs/adding-new-microservice.md exists, there's no step-by-step guide showing how to regenerate stubs after modifying .proto files in each language (Go: protoc flags, Python: grpcio-tools, C#: grpc tools, Java: Gradle). Adding this to docs/development-guide.md would unblock contributors.
• Add example e2e test in .github/workflows/: The CI runs linting and builds but no visible end-to-end test deploying all services and validating a user flow (e.g., add item to cart → checkout). Creating a test job using kind or minikube would catch integration regressions early and serve as a deployment validation example.

• High · Outdated gRPC Version — build.gradle (grpcVersion = "1.80.0"). The codebase uses gRPC version 1.80.0, which may contain known security vulnerabilities. gRPC has had multiple security updates since this version was released. Regular updates are critical for protobuf handling and network security. Fix: Update to the latest stable gRPC version. Review gRPC security advisories at https://github.com/grpc/grpc/security/advisories and upgrade to at least version 1.62.0 or later.
• High · Protobuf Version Mismatch Risk — build.gradle (protocVersion = "4.34.1"). The protoc version (4.34.1) and protobuf-java version should be aligned. Version mismatches can lead to incompatibility issues and potential security bypasses in message parsing. Fix: Verify that protobuf-java version matches the protoc compiler version. Consider using a BOM (Bill of Materials) to ensure consistent versioning across protobuf dependencies.
• Medium · Netty TCNative BoringSSL Pinned Version — build.gradle (netty-tcnative-boringssl-static:2.0.75.Final). The netty-tcnative-boringssl-static is pinned to version 2.0.75.Final. This version may have known vulnerabilities or missing security patches for TLS/SSL operations in gRPC. Fix: Update to the latest stable version of netty-tcnative-boringssl-static. Check CVE databases for known vulnerabilities in version 2.0.75 and upgrade accordingly.
• Medium · Incomplete Build Configuration — build.gradle (end of file). The build.gradle file appears truncated ('// Inform IDEs like Inte'). Missing configuration sections could hide security-related build settings or dependency declarations. Fix: Complete the build.gradle configuration and ensure all security-related plugins and tasks are defined, including dependency verification and signing configurations.
• Medium · No Dependency Verification Mechanism — build.gradle. The build.gradle does not appear to include dependency verification, checksums, or signature validation for downloaded artifacts. This could allow man-in-the-middle attacks or compromised dependencies. Fix: Implement Gradle dependency verification using gradle-dependency-lock or similar mechanisms. Add checksum validation and consider using verified-metadata.xml for Maven Central dependencies.
• Medium · Log4j Core Included as Direct Dependency — build.gradle (org.apache.logging.log4j:log4j-core:2.25.4). Log4j-core 2.25.4 is included as a direct dependency. While this version appears relatively recent, logging libraries are common attack vectors. Ensure proper configuration to prevent log injection attacks. Fix: Review log4j configuration to disable script engines and JNDI lookups. Validate that user-controlled input is not logged without sanitization to prevent log injection.
• Low · Jackson Databind Known Attack Surface — build.gradle (jackson-databind:2.21.2). Jackson-databind 2.21.2 is used for serialization. While recent, jackson-databind has a history of deserialization vulnerabilities. Configuration matters significantly. Fix: Ensure Jackson is configured with default typing disabled unless absolutely necessary. Use ObjectMapper.enableDefaultTyping() only with caution. Keep updated to the latest minor version for security patches.
• Low · Annotation API Version — build.gradle (javax.annotation:javax.annotation-api:1.3.2). javax.annotation:javax.annotation-api:1.3.2 is relatively old. The jakarta.annotation packages have largely replaced javax.annotation in modern Java applications. Fix: Consider migrating to jakarta.annotation:jakarta.annotation-api for Java 11+ compatibility and better long-term support. If Java 8 compatibility is required, document this decision.
• Low · Missing Security Headers Configuration — undefined. Based on the file structure, Kubernetes and Ingress configurations are present, but frontend-ingress.yaml and related configs may lack Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.