bhagirath00/kubeshop

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.