# bhagirath00/kubeshop architecture

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

- Interactive diagram: https://gitdiagram.com/bhagirath00/kubeshop
- Repository: https://github.com/bhagirath00/kubeshop

## Overview

1. **What this repo is**
   KubeShop is a polyglot e-commerce microservices system built to run on Kubernetes, primarily on AWS EKS. The repo includes not just application code, but the full platform stack: Terraform infrastructure, Kubernetes manifests, CI/CD automation, observability, and load/security testing.

2. **Top-level runtime boundary**
   The main runtime boundary is the Kubernetes cluster. External traffic enters through an AWS Load Balancer and NGINX Ingress Controller, then gets routed to internal services. Most application components are not directly exposed; they are reached through Ingress paths or service-to-service DNS inside the cluster.

3. **User-facing frontend**
   `app/frontend` is a Next.js/TypeScript application that serves the UI at `/`. It also acts as the browser-facing client for backend APIs. Its pages include product browsing and cart-related views, with shared UI components under `src/components`. The frontend is the only direct presentation layer.

4. **API microservices and their responsibilities**
   The backend is split into five domain services under `app/`:
   - `catalog` in Go handles product listing and search.
   - `identity` in Python handles authentication and JWT issuance.
   - `cart` in Node.js handles cart state and user cart operations.
   - `order` in Java/Spring Boot handles order creation and retrieval.
   - `ai-recs` in Python provides recommendations and also serves as an autoscaling example.
   Each service is packaged as its own container image with its own Dockerfile and runtime dependencies.

5. **Data stores and state ownership**
   Persistence is intentionally separated by service. `catalog` uses MongoDB, `identity` and `order` use PostgreSQL, and `cart` uses Redis. These databases are defined as Kubernetes manifests under `k8s/databases/`, and the apps consume credentials and connection URLs from the shared `kubeshop-secrets` Secret. This makes the architecture stateful at the service boundary, not shared through a single monolith database.

6. **Internal service-to-service flow**
   The most important backend flow is order placement. The browser talks to the frontend, which calls APIs through Ingress paths. The `order` service depends on `catalog` for product details and on PostgreSQL for durable order storage. The `ai-recs` service depends on the `order` service for recommendation data. `cart` also integrates with `identity` and Redis to keep carts associated with users.

7. **Ingress and public API surface**
   Public routing is centralized in `k8s/ingress/ingress-rules.yaml`. The key routes are `/` to frontend, `/api/products` and `/api/search` to catalog, `/api/auth` to identity, `/api/cart` to cart, `/api/orders` to order, `/api/recommend` to ai-recs, and `/grafana` to Grafana. This makes Ingress the main API boundary for external clients and separates browser traffic from internal cluster traffic.

8. **Platform and infrastructure layer**
   `infra/terraform/` provisions the AWS-side foundation, including EKS and supporting networking/cluster resources. Kubernetes manifests under `k8s/` define namespaces, services, ingress, databases, and secrets. This repo is therefore split between infrastructure-as-code and workload manifests, with Terraform creating the substrate and Kubernetes defining what runs on it.

9. **Delivery model: CI plus GitOps**
   Delivery is a two-step flow. Jenkins, defined in `cicd/jenkins/Jenkinsfile`, is used for build/test/security stages and image publishing to a registry such as ECR. Argo CD, defined under `cicd/argocd/`, watches the repo and syncs Kubernetes manifests into the cluster. The architecture assumes the desired state lives in Git and the cluster converges toward it automatically.

10. **Observability stack**
    Observability is built around Prometheus and Grafana, with manifests under `monitoring/`. Services expose metrics endpoints, Prometheus scrapes them, and Grafana visualizes them via dashboards such as `kubeshop-overview.json`. Grafana is also exposed through Ingress, so observability is treated as a first-class workload inside the cluster rather than an external SaaS dependency.

11. **Testing and validation**
    The repo includes cluster-based load testing with Locust under `tests/locust/`, which is designed to run inside the Kubernetes environment and hit the public app endpoints. Security scanning is supported via Trivy config under `tests/security/`. These are auxiliary workflows, but they matter architecturally because they validate the behavior and risk profile of the deployed system.

12. **Local development path**
    For local work, the repo supports Docker Compose via `docker-compose.yaml` and `make up` / `make down`. This mirrors the service breakdown without requiring AWS. The local path is a developer convenience layer; the production architecture is still Kubernetes-first.

13. **Important architectural conventions**
    The system uses mixed technology stacks by service, but the integration pattern is consistent: HTTP APIs at the edge, Kubernetes DNS for internal calls, and dedicated backing stores per domain. Secrets are centralized in Kubernetes, metrics are standardized, and workloads are deployed as separate containers rather than a shared runtime. That combination is the main shape to capture in a diagram.

14. **How to draw it**
    A faithful architecture diagram should show:
    - browser/client traffic entering AWS Load Balancer → NGINX Ingress
    - Ingress routing to frontend and API services
    - each API service linked to its own datastore where applicable
    - Jenkins and Argo CD as the delivery pipeline into EKS
    - Prometheus scraping services and Grafana reading from Prometheus
    - Locust and Trivy as supporting test/security subsystems
    This repo is best understood as a full DevSecOps reference architecture, not just an application codebase.

Main entry points: [`k8s/ingress/ingress-rules.yaml`](https://github.com/bhagirath00/kubeshop/blob/main/k8s/ingress/ingress-rules.yaml) (NGINX Ingress), [`monitoring/prometheus/prometheus-config.yaml`](https://github.com/bhagirath00/kubeshop/blob/main/monitoring/prometheus/prometheus-config.yaml) (Prometheus), [`app/catalog/main.go`](https://github.com/bhagirath00/kubeshop/blob/main/app/catalog/main.go) (Catalog), [`k8s/secrets.yaml.example`](https://github.com/bhagirath00/kubeshop/blob/main/k8s/secrets.yaml.example) (K8s Secrets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_browser(("Browser<br/>client"))
  node_frontend["Frontend<br/>nextjs app<br/>[page.tsx]"]
  node_catalog["Catalog<br/>go service<br/>[main.go]"]
  node_identity["Identity<br/>python auth<br/>[main.py]"]
  node_cart["Cart<br/>node service<br/>[server.js]"]
  node_order["Order<br/>spring service"]
  node_recs["AI Recs<br/>python service<br/>[model.py]"]
end

subgraph group_platform["Platform"]
  node_lb{{"Load Balancer<br/>aws entry<br/>[main.tf]"}}
  node_ingress["NGINX Ingress<br/>routing<br/>[ingress-rules.yaml]"]
  node_mongo[("MongoDB<br/>datastore<br/>[mongodb.yaml]")]
  node_postgres[("Postgres<br/>datastore<br/>[postgres.yaml]")]
  node_redis[("Redis<br/>datastore<br/>[redis.yaml]")]
  node_secrets["K8s Secrets<br/>config secret"]
  node_terraform["Terraform<br/>infra as code<br/>[main.tf]"]
  node_prometheus["Prometheus<br/>metrics"]
  node_grafana["Grafana<br/>dashboards"]
end

subgraph group_delivery["Delivery"]
  node_argocd["Argo CD<br/>gitops<br/>[application.yaml]"]
  node_jenkins["Jenkins<br/>ci pipeline"]
end

subgraph group_validation["Validation"]
  node_locust["Locust<br/>load test<br/>[locustfile.py]"]
  node_trivy["Trivy<br/>security scan<br/>[trivy-config.yaml]"]
end

node_browser -->|"traffic"| node_lb
node_lb -->|"forward"| node_ingress
node_ingress -->|"route /"| node_frontend
node_ingress -->|"/api/products"| node_catalog
node_ingress -->|"/api/search"| node_catalog
node_ingress -->|"/api/auth"| node_identity
node_ingress -->|"/api/cart"| node_cart
node_ingress -->|"/api/orders"| node_order
node_ingress -->|"/api/recommend"| node_recs
node_ingress -->|"/grafana"| node_grafana
node_frontend -->|"browse"| node_catalog
node_frontend -->|"cart ops"| node_cart
node_cart -->|"user auth"| node_identity
node_cart -->|"store state"| node_redis
node_catalog -->|"store products"| node_mongo
node_identity -->|"store users"| node_postgres
node_order -->|"product lookup"| node_catalog
node_order -->|"store orders"| node_postgres
node_recs -->|"signals"| node_order
node_terraform -->|"provisions"| node_ingress
node_argocd -->|"syncs"| node_ingress
node_jenkins -->|"publishes"| node_argocd
node_prometheus -.->|"scrape"| node_frontend
node_prometheus -.->|"scrape"| node_catalog
node_prometheus -.->|"scrape"| node_identity
node_prometheus -.->|"scrape"| node_cart
node_prometheus -.->|"scrape"| node_order
node_prometheus -.->|"scrape"| node_recs
node_grafana -->|"reads metrics"| node_prometheus
node_locust -->|"load test"| node_ingress
node_trivy -.->|"scan gate"| node_jenkins
node_secrets -.->|"config"| node_frontend
node_secrets -.->|"config"| node_catalog
node_secrets -.->|"config"| node_identity
node_secrets -.->|"config"| node_cart
node_secrets -.->|"config"| node_order
node_secrets -.->|"config"| node_recs

click node_lb "https://github.com/bhagirath00/kubeshop/blob/main/infra/terraform/main.tf"
click node_ingress "https://github.com/bhagirath00/kubeshop/blob/main/k8s/ingress/ingress-rules.yaml"
click node_frontend "https://github.com/bhagirath00/kubeshop/blob/main/app/frontend/src/app/page.tsx"
click node_catalog "https://github.com/bhagirath00/kubeshop/blob/main/app/catalog/main.go"
click node_identity "https://github.com/bhagirath00/kubeshop/blob/main/app/identity/main.py"
click node_cart "https://github.com/bhagirath00/kubeshop/blob/main/app/cart/server.js"
click node_order "https://github.com/bhagirath00/kubeshop/blob/main/app/order/src/main/java/com/kubeshop/order/OrderApplication.java"
click node_recs "https://github.com/bhagirath00/kubeshop/blob/main/app/ai-recs/model.py"
click node_mongo "https://github.com/bhagirath00/kubeshop/blob/main/k8s/databases/mongodb.yaml"
click node_postgres "https://github.com/bhagirath00/kubeshop/blob/main/k8s/databases/postgres.yaml"
click node_redis "https://github.com/bhagirath00/kubeshop/blob/main/k8s/databases/redis.yaml"
click node_secrets "https://github.com/bhagirath00/kubeshop/blob/main/k8s/secrets.yaml.example"
click node_terraform "https://github.com/bhagirath00/kubeshop/blob/main/infra/terraform/main.tf"
click node_argocd "https://github.com/bhagirath00/kubeshop/blob/main/cicd/argocd/application.yaml"
click node_jenkins "https://github.com/bhagirath00/kubeshop/tree/main/cicd/jenkins/Jenkinsfile"
click node_prometheus "https://github.com/bhagirath00/kubeshop/blob/main/monitoring/prometheus/prometheus-config.yaml"
click node_grafana "https://github.com/bhagirath00/kubeshop/blob/main/monitoring/grafana/dashboards/kubeshop-overview.json"
click node_locust "https://github.com/bhagirath00/kubeshop/blob/main/tests/locust/locustfile.py"
click node_trivy "https://github.com/bhagirath00/kubeshop/blob/main/tests/security/trivy-config.yaml"

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_browser,node_frontend,node_catalog,node_identity,node_cart,node_order,node_recs toneBlue
class node_lb,node_ingress,node_mongo,node_postgres,node_redis,node_secrets,node_terraform,node_prometheus,node_grafana toneAmber
class node_argocd,node_jenkins toneMint
class node_locust,node_trivy toneRose
```

## Components

### Runtime

Customer-facing app and in-cluster services

- **Browser**: client · End-user traffic source
- [Frontend](https://github.com/bhagirath00/kubeshop/blob/main/app/frontend/src/app/page.tsx): nextjs app · Browser UI and API client · `app/frontend/src/app/page.tsx`
- [Catalog](https://github.com/bhagirath00/kubeshop/blob/main/app/catalog/main.go): go service · Product listing and search API · `app/catalog/main.go`
- [Identity](https://github.com/bhagirath00/kubeshop/blob/main/app/identity/main.py): python auth · Authentication and JWT issuance · `app/identity/main.py`
- [Cart](https://github.com/bhagirath00/kubeshop/blob/main/app/cart/server.js): node service · Cart state and user cart operations · `app/cart/server.js`
- [Order](https://github.com/bhagirath00/kubeshop/blob/main/app/order/src/main/java/com/kubeshop/order/OrderApplication.java): spring service · Order creation and retrieval · `app/order/src/main/java/com/kubeshop/order/OrderApplication.java`
- [AI Recs](https://github.com/bhagirath00/kubeshop/blob/main/app/ai-recs/model.py): python service · Recommendations and scaling example · `app/ai-recs/model.py`

### Platform

Infrastructure, Kubernetes, ingress, data, and observability

- [Load Balancer](https://github.com/bhagirath00/kubeshop/blob/main/infra/terraform/main.tf): aws entry · Cloud entrypoint before cluster ingress · `infra/terraform/main.tf`
- [NGINX Ingress](https://github.com/bhagirath00/kubeshop/blob/main/k8s/ingress/ingress-rules.yaml): routing · Public HTTP routing for app and ops endpoints · `k8s/ingress/ingress-rules.yaml`
- [MongoDB](https://github.com/bhagirath00/kubeshop/blob/main/k8s/databases/mongodb.yaml): datastore · Catalog persistence · `k8s/databases/mongodb.yaml`
- [Postgres](https://github.com/bhagirath00/kubeshop/blob/main/k8s/databases/postgres.yaml): datastore · Identity and order persistence · `k8s/databases/postgres.yaml`
- [Redis](https://github.com/bhagirath00/kubeshop/blob/main/k8s/databases/redis.yaml): datastore · Cart state store · `k8s/databases/redis.yaml`
- [K8s Secrets](https://github.com/bhagirath00/kubeshop/blob/main/k8s/secrets.yaml.example): config secret · Shared credentials and connection settings · `k8s/secrets.yaml.example`
- [Terraform](https://github.com/bhagirath00/kubeshop/blob/main/infra/terraform/main.tf): infra as code · AWS and EKS foundation · `infra/terraform/main.tf`
- [Prometheus](https://github.com/bhagirath00/kubeshop/blob/main/monitoring/prometheus/prometheus-config.yaml): metrics · Scrapes service metrics · `monitoring/prometheus/prometheus-config.yaml`
- [Grafana](https://github.com/bhagirath00/kubeshop/blob/main/monitoring/grafana/dashboards/kubeshop-overview.json): dashboards · Metrics dashboards and visualization · `monitoring/grafana/dashboards/kubeshop-overview.json`

### Delivery

Build, deploy, and GitOps automation

- [Argo CD](https://github.com/bhagirath00/kubeshop/blob/main/cicd/argocd/application.yaml): gitops · Cluster sync from Git · `cicd/argocd/application.yaml`
- [Jenkins](https://github.com/bhagirath00/kubeshop/tree/main/cicd/jenkins/Jenkinsfile): ci pipeline · Build, test, scan, and publish images · `cicd/jenkins/Jenkinsfile`

### Validation

Load and security testing

- [Locust](https://github.com/bhagirath00/kubeshop/blob/main/tests/locust/locustfile.py): load test · Cluster-based traffic validation · `tests/locust/locustfile.py`
- [Trivy](https://github.com/bhagirath00/kubeshop/blob/main/tests/security/trivy-config.yaml): security scan · Container and config security scanning · `tests/security/trivy-config.yaml`

## Connections

- Browser → Load Balancer: traffic · User requests enter the cloud entrypoint
- Load Balancer → NGINX Ingress: forward · Load balancer hands off HTTP to cluster ingress
- NGINX Ingress → Frontend: route / · Public UI route
- NGINX Ingress → Catalog: /api/products · Product API
- NGINX Ingress → Catalog: /api/search · Search API
- NGINX Ingress → Identity: /api/auth · Authentication API
- NGINX Ingress → Cart: /api/cart · Cart API
- NGINX Ingress → Order: /api/orders · Order API
- NGINX Ingress → AI Recs: /api/recommend · Recommendation API
- NGINX Ingress → Grafana: /grafana · Ops dashboard route
- Frontend → Catalog: browse · UI fetches product and search data
- Frontend → Cart: cart ops · UI reads and updates cart state
- Cart → Identity: user auth · Cart associates state with authenticated users
- Cart → Redis: store state · Cart persistence in Redis
- Catalog → MongoDB: store products · Catalog data in MongoDB
- Identity → Postgres: store users · Identity data in PostgreSQL
- Order → Catalog: product lookup · Order flow depends on catalog data
- Order → Postgres: store orders · Durable order storage
- AI Recs → Order: signals · Recommendation service consumes order data
- Terraform → NGINX Ingress: provisions · Terraform creates AWS and cluster substrate
- Argo CD → NGINX Ingress: syncs · GitOps applies Kubernetes desired state
- Jenkins → Argo CD: publishes · CI produces deployable artifacts and updates delivery flow
- Prometheus → Frontend: scrape · Metrics collection from workloads
- Prometheus → Catalog: scrape · Metrics collection from workloads
- Prometheus → Identity: scrape · Metrics collection from workloads
- Prometheus → Cart: scrape · Metrics collection from workloads
- Prometheus → Order: scrape · Metrics collection from workloads
- Prometheus → AI Recs: scrape · Metrics collection from workloads
- Grafana → Prometheus: reads metrics · Dashboards query Prometheus
- Locust → NGINX Ingress: load test · Synthetic traffic against public endpoints
- Trivy → Jenkins: scan gate · Security validation in delivery pipeline
- K8s Secrets → Frontend: config · Shared secret access pattern
- K8s Secrets → Catalog: config · Shared secret access pattern
- K8s Secrets → Identity: config · Shared secret access pattern
- K8s Secrets → Cart: config · Shared secret access pattern
- K8s Secrets → Order: config · Shared secret access pattern
- K8s Secrets → AI Recs: config · Shared secret access pattern