# sujithchandran1/boutique_app architecture

> Architecture diagram of the GitHub repository sujithchandran1/boutique_app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sujithchandran1/boutique_app
- Repository: https://github.com/sujithchandran1/boutique_app

## Overview

1. **What this repo is**
   - This is a containerized e-commerce microservices system, deployed primarily onto **AWS EKS** with **Terraform** and Kubernetes.
   - The repository is split into three main planes: **infrastructure provisioning**, **application services**, and **deployment/operational packaging**.

2. **Runtime architecture**
   - The live application is a cluster of independently deployed services behind Kubernetes Services.
   - A user typically enters through the **frontend** service, which renders server-side pages and coordinates calls to the backend microservices.
   - A **loadgenerator** service exists to simulate traffic and exercise the system end-to-end.

3. **Core application boundary: frontend**
   - `src/frontend` is the UI edge service and the main orchestration layer for request flows.
   - It serves HTML templates and static assets, and it calls downstream gRPC services for catalog, cart, recommendations, currency conversion, shipping, checkout, and ad content.
   - This is a server-rendered web app, not a separate SPA frontend/backend split.

4. **Business microservices**
   - The domain is decomposed into small services under `src/`:
     - `productcatalogservice` for product data
     - `cartservice` for cart state
     - `recommendationservice` for personalized recommendations
     - `currencyservice` for currency conversion
     - `shippingservice` for shipping quotes/tracking
     - `paymentservice` for payment authorization/charge simulation
     - `emailservice` for order confirmation emails
     - `checkoutservice` for the checkout workflow
     - `adservice` for ad retrieval
     - `shoppingassistantservice` as an assistant-oriented extension
   - Most service-to-service communication is via **gRPC** using shared protobuf definitions.

5. **Typical data flow**
   - Browser request → **frontend** → reads catalog/cart/recommendations/currency/shipping data → renders page.
   - Checkout flow → **frontend** → **checkoutservice** → invokes **cart**, **currency**, **payment**, **shipping**, and **email** services.
   - Recommendations and ads are separate read-oriented dependencies rather than part of the checkout path.

6. **State and persistence boundaries**
   - The system is intentionally mixed between stateless services and pluggable state backends.
   - `cartservice` can use different stores: **Redis/Memorystore**, **Spanner**, or **AlloyDB** depending on the selected deployment component.
   - `productcatalogservice` is backed by local JSON content in the repo, making it effectively static data.
   - The shopping assistant component has its own AlloyDB setup scripts, indicating a more database-centric extension.

7. **Packaging and deployment options**
   - There are three main deployment abstractions:
     - raw **Kubernetes manifests** in `kubernetes-manifests/`
     - **Helm chart** in `helm-chart/`
     - **Kustomize** overlays/components in `kustomize/`
   - The Kustomize structure is especially important: `base` defines the core app, while `components` toggle features such as:
     - service mesh/Istio
     - network policies
     - non-public frontend
     - custom branding
     - container image registry/tag rewrites
     - backend choices like Memorystore, Spanner, AlloyDB

8. **Service mesh and traffic policy**
   - `istio-manifests/` and the Kustomize Istio component indicate optional **Istio** integration for gateway and egress control.
   - Network-policy components show a second layer of traffic restriction at the Kubernetes network layer.
   - This means the app can be diagrammed as either plain Kubernetes traffic or service-mesh-mediated traffic, depending on deployment variant.

9. **Infrastructure provisioning**
   - `EKS-cluster-terraform/` provisions the AWS EKS cluster and supporting AWS infrastructure.
   - The root `terraform/` folder in `Microservices/` appears to support app-related cloud resources, including a **Memorystore**-style backend variant.
   - The infra boundary is separate from the app boundary: Terraform creates the platform, Kubernetes deploys the services onto it.

10. **Image build and registry flow**
   - Container images are built from the per-service Dockerfiles in `src/*`.
   - Scripts like `build_push_imgs.sh`, `docker_image_buid_push.sh`, and `cloudbuild.yaml` automate image packaging and pushing.
   - The README calls out **AWS ECR** as the registry target, so the deployment path is: source → image build → registry → Kubernetes manifests referencing those images.

11. **CI/CD and validation**
   - `Jenkinsfile` provides a pipeline entry point for automated build/deploy in Jenkins.
   - GitHub Actions under `.github/workflows/` validate multiple layers: Terraform, Helm, Kustomize, and manifest hygiene.
   - This repo treats deployment artifacts as first-class code, with CI focused on both app images and infrastructure manifests.

12. **Observability**
   - `Monitor.sh` installs the **kube-prometheus-stack** Helm chart and exposes Grafana via LoadBalancer.
   - Monitoring is operationally separate from the app, but it sits alongside the cluster and watches the Kubernetes workloads.
   - The runtime architecture therefore includes an observability plane: Prometheus scraping services and Grafana visualizing cluster and app metrics.

13. **Extension and release packaging**
   - The `docs/`, `release/`, and `.github/release-cluster/` areas suggest the repo also ships packaged deployment sets for specific environments.
   - The `shoppingassistant` and `branding`/`non-public-frontend` components indicate optional product variants rather than a single fixed deployment.
   - Overall, the repo is designed as a modular microservices reference app with interchangeable infrastructure backends and deployment styles.

Main entry points: [`Microservices/kustomize/base`](https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/kustomize/base) (Kustomize Base), [`Microservices/src/frontend`](https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/src/frontend) (Frontend), [`Microservices/src/checkoutservice`](https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/src/checkoutservice) (Checkout), [`Jenkinsfile`](https://github.com/sujithchandran1/boutique_app/tree/main/Jenkinsfile) (CI Checks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_infra["Infrastructure"]
  node_eks_terraform[("EKS Terraform<br/>aws platform provisioning")]
  node_app_terraform[("App Terraform<br/>cloud backends")]
end

subgraph group_deploy["Deployment"]
  node_k8s_manifests["K8s Manifests<br/>raw manifests"]
  node_helm_chart["Helm Chart<br/>packaged deploy"]
  node_kustomize_base["Kustomize Base<br/>deployment base"]
  node_kustomize_components["Kustomize Components<br/>feature overlays"]
  node_istio_manifests["Istio Manifests<br/>service mesh"]
end

subgraph group_app["Application"]
  node_frontend["Frontend<br/>web edge service"]
  node_catalog["Catalog<br/>static product API"]
  node_cart["Cart"]
  node_recommendations["Recommendations<br/>personalization API"]
  node_currency["Currency<br/>conversion API"]
  node_shipping["Shipping<br/>quote API"]
  node_payment["Payment<br/>charge API"]
  node_email["Email<br/>notification API"]
  node_checkout["Checkout<br/>workflow service"]
  node_ad["Ads<br/>ad API"]
  node_assistant["Assistant"]
  node_loadgen(("Loadgen<br/>traffic generator<br/>[loadgenerator.yaml]"))
end

subgraph group_ops["Operations"]
  node_registry_ci["Build & Push<br/>image pipeline<br/>[build_push_imgs.sh]"]
  node_ci_validation["CI Checks<br/>pipeline validation"]
  node_monitoring[("Monitoring<br/>prometheus stack<br/>[Monitor.sh]")]
end

node_eks_terraform -->|"hosts"| node_k8s_manifests
node_eks_terraform -->|"hosts"| node_helm_chart
node_app_terraform -->|"backs"| node_kustomize_components
node_registry_ci -->|"feeds"| node_k8s_manifests
node_registry_ci -->|"feeds"| node_helm_chart
node_registry_ci -->|"feeds"| node_kustomize_base
node_ci_validation -->|"validates"| node_eks_terraform
node_ci_validation -->|"validates"| node_helm_chart
node_ci_validation -->|"validates"| node_kustomize_base
node_ci_validation -->|"validates"| node_k8s_manifests
node_istio_manifests -->|"mshields"| node_frontend
node_kustomize_base -->|"deploys"| node_frontend
node_kustomize_base -->|"deploys"| node_catalog
node_kustomize_base -->|"deploys"| node_cart
node_kustomize_base -->|"deploys"| node_recommendations
node_kustomize_base -->|"deploys"| node_currency
node_kustomize_base -->|"deploys"| node_shipping
node_kustomize_base -->|"deploys"| node_payment
node_kustomize_base -->|"deploys"| node_email
node_kustomize_base -->|"deploys"| node_checkout
node_kustomize_base -->|"deploys"| node_ad
node_kustomize_base -->|"deploys"| node_assistant
node_frontend -->|"reads"| node_catalog
node_frontend -->|"reads"| node_cart
node_frontend -->|"reads"| node_recommendations
node_frontend -->|"reads"| node_currency
node_frontend -->|"reads"| node_shipping
node_frontend -->|"reads"| node_ad
node_frontend -->|"calls"| node_checkout
node_checkout -->|"uses"| node_cart
node_checkout -->|"uses"| node_currency
node_checkout -->|"uses"| node_payment
node_checkout -->|"uses"| node_shipping
node_checkout -->|"uses"| node_email
node_loadgen -->|"exercises"| node_frontend
node_assistant -->|"extends"| node_frontend
node_monitoring -->|"scrapes"| node_frontend
node_monitoring -->|"scrapes"| node_checkout

click node_eks_terraform "https://github.com/sujithchandran1/boutique_app/tree/main/EKS-cluster-terraform"
click node_app_terraform "https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/terraform"
click node_k8s_manifests "https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/kubernetes-manifests"
click node_helm_chart "https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/helm-chart"
click node_kustomize_base "https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/kustomize/base"
click node_kustomize_components "https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/kustomize/components"
click node_istio_manifests "https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/istio-manifests"
click node_frontend "https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/src/frontend"
click node_catalog "https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/src/productcatalogservice"
click node_cart "https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/src/cartservice"
click node_recommendations "https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/src/recommendationservice"
click node_currency "https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/src/currencyservice"
click node_shipping "https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/src/shippingservice"
click node_payment "https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/src/paymentservice"
click node_email "https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/src/emailservice"
click node_checkout "https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/src/checkoutservice"
click node_ad "https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/src/adservice"
click node_assistant "https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/src/shoppingassistantservice"
click node_loadgen "https://github.com/sujithchandran1/boutique_app/blob/main/Microservices/kustomize/base/loadgenerator.yaml"
click node_registry_ci "https://github.com/sujithchandran1/boutique_app/blob/main/Microservices/build_push_imgs.sh"
click node_ci_validation "https://github.com/sujithchandran1/boutique_app/tree/main/Jenkinsfile"
click node_monitoring "https://github.com/sujithchandran1/boutique_app/blob/main/Monitor.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_eks_terraform,node_app_terraform toneBlue
class node_k8s_manifests,node_helm_chart,node_kustomize_base,node_kustomize_components,node_istio_manifests toneAmber
class node_frontend,node_catalog,node_cart,node_recommendations,node_currency,node_shipping,node_payment,node_email,node_checkout,node_ad,node_assistant,node_loadgen toneMint
class node_registry_ci,node_ci_validation,node_monitoring toneRose
```

## Components

### Infrastructure

AWS and Terraform layers that provision the platform and cloud backends.

- [EKS Terraform](https://github.com/sujithchandran1/boutique_app/tree/main/EKS-cluster-terraform): aws platform provisioning · Creates the AWS EKS cluster and supporting cluster infrastructure. · `EKS-cluster-terraform`
- [App Terraform](https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/terraform): cloud backends · Provisioning for application-adjacent cloud resources such as Memorystore-style backends. · `Microservices/terraform`

### Deployment

Kubernetes packaging, overlays, and release artifacts for running the app.

- [K8s Manifests](https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/kubernetes-manifests): raw manifests · Direct Kubernetes YAMLs for the core services. · `Microservices/kubernetes-manifests`
- [Helm Chart](https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/helm-chart): packaged deploy · Helm-based deployment template for the service stack. · `Microservices/helm-chart`
- [Kustomize Base](https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/kustomize/base): deployment base · Base Kubernetes resources that define the main application stack. · `Microservices/kustomize/base`
- [Kustomize Components](https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/kustomize/components): feature overlays · Optional deployment variants for storage, mesh, branding, policies, and image rewriting. · `Microservices/kustomize/components`
- [Istio Manifests](https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/istio-manifests): service mesh · Optional Istio gateway and egress configuration. · `Microservices/istio-manifests`

### Application

Runtime microservices and shared request flows.

- [Frontend](https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/src/frontend): web edge service · Server-rendered entrypoint that orchestrates most user-facing reads and checkout flows. · `Microservices/src/frontend`
- [Catalog](https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/src/productcatalogservice): static product API · Serves product data from repository-backed JSON content. · `Microservices/src/productcatalogservice`
- [Cart](https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/src/cartservice): stateful cart API · Maintains cart state with pluggable backends such as Redis, Spanner, or AlloyDB. · `Microservices/src/cartservice`
- [Recommendations](https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/src/recommendationservice): personalization API · Produces recommendation responses for browsing pages. · `Microservices/src/recommendationservice`
- [Currency](https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/src/currencyservice): conversion API · Converts prices between currencies for display and checkout. · `Microservices/src/currencyservice`
- [Shipping](https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/src/shippingservice): quote API · Calculates shipping quotes and related shipment data. · `Microservices/src/shippingservice`
- [Payment](https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/src/paymentservice): charge API · Simulates payment authorization and charging. · `Microservices/src/paymentservice`
- [Email](https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/src/emailservice): notification API · Sends order confirmation emails. · `Microservices/src/emailservice`
- [Checkout](https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/src/checkoutservice): workflow service · Coordinates checkout by calling cart, currency, payment, shipping, and email services. · `Microservices/src/checkoutservice`
- [Ads](https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/src/adservice): ad API · Serves ad content for the storefront. · `Microservices/src/adservice`
- [Assistant](https://github.com/sujithchandran1/boutique_app/tree/main/Microservices/src/shoppingassistantservice): assistant extension · Shopping-assistant service backed by its own AlloyDB-oriented setup. · `Microservices/src/shoppingassistantservice`
- [Loadgen](https://github.com/sujithchandran1/boutique_app/blob/main/Microservices/kustomize/base/loadgenerator.yaml): traffic generator · Synthetic client that exercises the whole system end to end. · `Microservices/kustomize/base/loadgenerator.yaml`

### Operations

CI/CD, registry flow, and observability.

- [Build & Push](https://github.com/sujithchandran1/boutique_app/blob/main/Microservices/build_push_imgs.sh): image pipeline · Scripts and CI jobs that build container images and publish them to the registry. · `Microservices/build_push_imgs.sh`
- [CI Checks](https://github.com/sujithchandran1/boutique_app/tree/main/Jenkinsfile): pipeline validation · GitHub Actions and Jenkins entry points that validate Terraform, Helm, Kustomize, and manifests. · `Jenkinsfile`
- [Monitoring](https://github.com/sujithchandran1/boutique_app/blob/main/Monitor.sh): prometheus stack · Prometheus and Grafana-based observability installed separately from the app stack. · `Monitor.sh`

## Connections

- EKS Terraform → K8s Manifests: hosts · EKS provides the cluster where Kubernetes workloads are deployed.
- EKS Terraform → Helm Chart: hosts · The cluster can also run Helm-packaged workloads.
- App Terraform → Kustomize Components: backs · App cloud resources support Kustomize-selected backends.
- Build & Push → K8s Manifests: feeds · Built images are referenced by raw Kubernetes deployment manifests.
- Build & Push → Helm Chart: feeds · Built images are parameterized into the Helm deployment.
- Build & Push → Kustomize Base: feeds · Kustomize base uses published container images.
- CI Checks → EKS Terraform: validates · Pipeline checks Terraform for infrastructure correctness.
- CI Checks → Helm Chart: validates · Pipeline checks Helm rendering and chart hygiene.
- CI Checks → Kustomize Base: validates · Pipeline checks Kustomize build outputs.
- CI Checks → K8s Manifests: validates · Pipeline checks manifest quality and consistency.
- Istio Manifests → Frontend: mshields · Optional Istio config fronts the public entrypoint and egress.
- Kustomize Base → Frontend: deploys · Base deployment defines the frontend service.
- Kustomize Base → Catalog: deploys · Base deployment defines the catalog service.
- Kustomize Base → Cart: deploys · Base deployment defines the cart service.
- Kustomize Base → Recommendations: deploys · Base deployment defines the recommendation service.
- Kustomize Base → Currency: deploys · Base deployment defines the currency service.
- Kustomize Base → Shipping: deploys · Base deployment defines the shipping service.
- Kustomize Base → Payment: deploys · Base deployment defines the payment service.
- Kustomize Base → Email: deploys · Base deployment defines the email service.
- Kustomize Base → Checkout: deploys · Base deployment defines the checkout service.
- Kustomize Base → Ads: deploys · Base deployment defines the ads service.
- Kustomize Base → Assistant: deploys · Base deployment can include the shopping assistant extension.
- Frontend → Catalog: reads · Frontend fetches product data for browsing pages.
- Frontend → Cart: reads · Frontend retrieves cart state for the shopper.
- Frontend → Recommendations: reads · Frontend requests personalized recommendations.
- Frontend → Currency: reads · Frontend converts displayed prices.
- Frontend → Shipping: reads · Frontend may show shipping estimates.
- Frontend → Ads: reads · Frontend loads ad content for product pages.
- Frontend → Checkout: calls · Frontend delegates purchase completion to checkout.
- Checkout → Cart: uses · Checkout reads and updates cart state.
- Checkout → Currency: uses · Checkout converts order totals.
- Checkout → Payment: uses · Checkout authorizes or simulates payment.
- Checkout → Shipping: uses · Checkout requests shipping quotes.
- Checkout → Email: uses · Checkout triggers confirmation emails.
- Loadgen → Frontend: exercises · Synthetic traffic enters through the storefront.
- Assistant → Frontend: extends · Assistant UI is exposed through the storefront experience.
- Monitoring → Frontend: scrapes · Observability watches cluster workloads including the frontend.
- Monitoring → Checkout: scrapes · Observability watches the workflow service.
