# realatul/retail-store-sample-app architecture

> Architecture diagram of the GitHub repository realatul/retail-store-sample-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/realatul/retail-store-sample-app
- Repository: https://github.com/realatul/retail-store-sample-app

## Overview

##### Project Type & Purpose
This is a full-stack, microservices-based sample retail application. It comprises five independently-deployable containerized services (UI, Catalog, Cart, Orders, Checkout) running on Amazon EKS, managed via GitOps (ArgoCD) and deployed with Infrastructure-as-Code (Terraform).

##### High-Level File Structure & Architectural Patterns
- src/ui, src/catalog, src/cart, src/orders, src/checkout – each is a microservice, containing:
– Dockerfile & Helm chart (chart/ templates + values.yaml)
– Source code in Java (Spring Boot), Go, or Node (NestJS)
- src/app/chart – umbrella Helm chart for deploying all services together
- argocd/ – ArgoCD Application & Project manifests (retail-store-project)
- terraform/ – AWS infrastructure modules (VPC, EKS cluster, IAM, ArgoCD, ingress, cert-manager)
- CI/CD: GitHub Actions (trigger build → push to ECR → ArgoCD sync)

Architectural patterns:
– Microservices with language-agnostic APIs
– Kubernetes & Helm for container orchestration
– GitOps (ArgoCD) for continuous deployment
– IaC (Terraform) for provisioning AWS resources
– Service mesh (Istio) used by UI for routing (gateway + virtualservice)

##### Main Components
A. AWS VPC
- Public & private subnets
- Security groups, NAT gateways, Internet gateway
B. Amazon EKS Cluster
- Worker nodes (Auto Scaling groups)
- cert-manager, NGINX Ingress Controller, Istio Gateway
C. GitOps Platform
- ArgoCD control plane running in “argocd” namespace
D. CI/CD Pipeline
- GitHub Actions → Docker build → Amazon ECR → GitOps branch ←→ ArgoCD
E. Microservices (each in its own namespace “retail-store”)
1. UI Service (Java/Spring Boot + Thymeleaf)
2. Catalog Service (Go + MySQL StatefulSet)
3. Cart Service (Java + DynamoDB)
4. Orders Service (Java + PostgreSQL + RabbitMQ/SQS)
5. Checkout Service (Node/NestJS + Redis + external shipping/orders clients)
- Each service exposes a REST/gRPC API and is fronted by its own Kubernetes Service object
- Helm charts define Deployments, Services, ConfigMaps, Secrets, HPA, PDB
F. Data Stores & Messaging
- Amazon DynamoDB table for Cart
- Amazon RDS (MySQL) for Catalog
- Amazon RDS (PostgreSQL) for Orders + Flyway migrations
- Messaging: RabbitMQ or Amazon SQS for order events
- Redis for Checkout session/state

##### Relationships & Data Flows
- User → HTTPS → NGINX Ingress / Istio Gateway → UI Service
- UI → REST API calls → Catalog, Cart, Checkout, Orders endpoints
- Checkout → orchestrates calls: reads Cart, reserves inventory via Catalog, writes Order, enqueues events, writes to Redis, calls external shipping API
- Orders → persists to PostgreSQL, publishes/consumes events via messaging (RabbitMQ/SQS)
- ArgoCD continuously watches Git repos (umbrella & per-service Helm values) → applies to Kubernetes
- Terraform provisions & tears down all above AWS resources

##### Architectural Patterns & Principles
- Microservices: services are loosely coupled, independently deployable
- Twelve-Factor App: externalize config via ConfigMaps/Secrets, stateless services
- GitOps: declarative infra & app manifests in Git, ArgoCD enforces live state
- IaC: Terraform modules for VPC, EKS, IAM, ingress, ArgoCD
- Helm for packaging & templating Kubernetes resources
- Service Mesh (Istio) for advanced routing/observability

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% AWS Infrastructure
    subgraph "AWS Infrastructure"
        VPC["VPC"]:::infra
        Subnets["Public & Private Subnets"]:::infra
        IGW["Internet Gateway"]:::infra
        NAT["NAT Gateways"]:::infra
        SG["Security Groups"]:::infra
        EKS["EKS Cluster"]:::infra
        Nodes["Worker Nodes (ASG)"]:::infra
        CM["cert-manager"]:::infra
        NG["NGINX Ingress Controller"]:::infra
        Istio["Istio Gateway"]:::infra

        VPC --> Subnets
        Subnets --> IGW
        Subnets --> NAT
        Subnets --> SG
        Subnets --> EKS
        EKS --> Nodes
        EKS --> CM
        EKS --> NG
        EKS --> Istio
    end

    %% Platform & DevOps
    subgraph "Platform & DevOps"
        GitHub["GitHub Repo"]:::external
        GHAction["GitHub Actions CI/CD"]:::platform
        ECR["Amazon ECR"]:::platform
        ArgoCD["ArgoCD Control Plane"]:::platform
        Terraform["Terraform IaC"]:::platform

        GitHub --> GHAction
        GHAction --> ECR
        ECR --> ArgoCD
        ArgoCD --> EKS
        Terraform --> VPC
        Terraform --> EKS
        Terraform --> ArgoCD
    end

    %% Kubernetes Namespace
    subgraph "retail-store (namespace)"
        UI["UI Service\n(Java/Spring Boot)"]:::service
        Catalog["Catalog Service\n(Go + MySQL)"]:::service
        Cart["Cart Service\n(Java + DynamoDB)"]:::service
        Orders["Orders Service\n(Java + PostgreSQL)"]:::service
        Checkout["Checkout Service\n(Node/NestJS + Redis)"]:::service

        UI -->|REST API| Catalog
        UI -->|REST API| Cart
        UI -->|REST API| Orders
        UI -->|REST API| Checkout

        Checkout -->|reads/writes| CartDB
        Checkout -->|reserve inventory| Catalog
        Checkout -->|write order| Orders
        Checkout -->|write session| RedisDB
        Checkout -->|enqueue event| MQ

        Orders -->|persist| PostgreSQLDB
        Orders -- dashed --> MQ
        Cart -->|persist| DynamoDBDB
        Catalog -->|persist| MySQLDB
    end

    %% Data & Messaging
    subgraph "Data & Messaging"
        MySQLDB["Amazon RDS MySQL"]:::data
        PostgreSQLDB["Amazon RDS PostgreSQL"]:::data
        DynamoDBDB["Amazon DynamoDB"]:::data
        RedisDB["Redis"]:::data
        MQ["RabbitMQ/SQS"]:::data
    end

    %% External User
    User["User"]:::external
    User -->|HTTPS| NG
    NG -->|Ingress| UI

    %% Click Events
    click UI "https://github.com/realatul/retail-store-sample-app/tree/main/src/ui"
    click Catalog "https://github.com/realatul/retail-store-sample-app/tree/main/src/catalog"
    click Cart "https://github.com/realatul/retail-store-sample-app/tree/main/src/cart"
    click Orders "https://github.com/realatul/retail-store-sample-app/tree/main/src/orders"
    click Checkout "https://github.com/realatul/retail-store-sample-app/tree/main/src/checkout"
    click ArgoCD "https://github.com/realatul/retail-store-sample-app/blob/main/argocd/projects/retail-store-project.yaml"
    click Terraform "https://github.com/realatul/retail-store-sample-app/tree/main/terraform"
    click umbrella "https://github.com/realatul/retail-store-sample-app/tree/main/src/app/chart"

    %% Styles
    classDef infra fill:#D6E9F8,stroke:#31708F,color:#31708F;
    classDef platform fill:#DFF0D8,stroke:#3C763D,color:#3C763D;
    classDef service fill:#F2DEDE,stroke:#A94442,color:#A94442;
    classDef data fill:#FCF8E3,stroke:#8A6D3B,color:#8A6D3B;
    classDef external fill:#EEEEEE,stroke:#AAAAAA,color:#555555;
```
