# miguel-higorre-ch/production-grade-microservices-platform architecture

> Architecture diagram of the GitHub repository miguel-higorre-ch/production-grade-microservices-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/miguel-higorre-ch/production-grade-microservices-platform
- Repository: https://github.com/miguel-higorre-ch/production-grade-microservices-platform

## Overview

1. **Overall shape**
   - This repo is a reference microservices platform, not a single application.
   - The main runtime system is three containerized Node.js services deployed to Kubernetes on AWS EKS:
     `api-gateway`, `auth-service`, and `user-service`.
   - Around that core is a delivery platform: GitHub Actions for CI/CD, Docker for packaging, Terraform for cloud infrastructure, and Helm for Kubernetes deployment.

2. **Request/data flow at runtime**
   - External traffic enters through Kubernetes Ingress.
   - The `api-gateway` is the public entrypoint and routes/aggregates requests to the backend services.
   - `auth-service` handles authentication-related requests.
   - `user-service` handles user profile/backend API behavior.
   - The services appear stateless in this repo; no application database is included, so stateful dependencies are either mocked, external, or intentionally out of scope.

3. **Service boundaries**
   - Each service is isolated in its own directory with its own `package.json`, Dockerfile, and tests.
   - Each service exposes a small Node.js app surface via `src/app.js` and `src/server.js`.
   - The gateway is the only internet-facing app; the other services are internal dependencies behind Kubernetes networking.

4. **Application runtime technology**
   - The application layer is Node.js.
   - Testing uses Jest, with `supertest`-style integration coverage for gateway behavior and Postman/Newman for end-to-end validation.
   - The repo also includes service-level Docker builds, so each microservice is independently buildable and deployable.

5. **Container packaging**
   - Every service has its own Dockerfile, indicating one image per service.
   - Images are pushed to Amazon ECR, with immutable tagging and scan-on-push enabled at the registry level.
   - This is the artifact boundary between application build and cluster deployment.

6. **Kubernetes deployment model**
   - Helm is the deployment abstraction for all services.
   - `helm/charts/microservice` is a reusable base chart with Kubernetes primitives such as Deployment, Service, Ingress, ConfigMap, Secret, HPA, ServiceAccount, and ServiceMonitor.
   - Environment-specific behavior is driven by values overlays in `helm/environments/dev`, `staging`, and `prod`.

7. **Production rollout pattern**
   - Production includes a canary path for `api-gateway`.
   - The repo has separate prod values for `api-gateway` and `api-gateway-canary`, which implies traffic-splitting through ingress annotations rather than a separate service mesh.
   - Backend services are deployed more conventionally; the gateway is the controlled release surface.

8. **Infrastructure provisioning**
   - Terraform is used to provision the cloud foundation under `infrastructure/terraform`.
   - There are reusable modules for networking, ECR, and EKS.
   - Environment roots for dev/staging/prod assemble those modules into complete stacks, showing a clear separation between shared infrastructure building blocks and per-environment state.

9. **Network and cluster topology**
   - The README describes a VPC with public and private subnets across three AZs.
   - EKS worker nodes run in private subnets, while ingress handles north-south traffic into the cluster.
   - This implies a standard secure cloud pattern: public entry at the edge, private compute for workloads, and AWS-managed registry/storage supporting the pipeline.

10. **CI/CD control plane**
    - GitHub Actions is the orchestration layer for validation, build, security scanning, infrastructure changes, and deployments.
    - The pipeline order is: test, analyze, scan, build images, push to ECR, apply Terraform, deploy with Helm, run smoke/E2E checks, then promote or roll back.
    - Pull requests are validation-only; main-branch or manual dispatch runs can deploy to a selected environment.

11. **Quality and security gates**
    - SonarQube is used as a code quality gate.
    - Trivy scans both filesystem content and built container images.
    - The pipeline is designed to fail on high-severity findings, making security checks part of the release boundary rather than a separate audit step.

12. **Observability**
    - `helm/observability` contains starter Prometheus/Grafana configuration and alert rules.
    - Services expose health/readiness endpoints, which Kubernetes and monitoring can use for rollout safety and alerting.
    - Observability is cluster-level, not embedded deeply in application code.

13. **Configuration and secrets**
    - Runtime configuration is externalized through Helm values, ConfigMaps, and Secrets.
    - Sensitive values are not meant to live in plaintext in tracked environment files.
    - The repo assumes cluster-provided secrets today, with AWS Secrets Manager/External Secrets noted as a likely extension.

14. **Diagramming takeaway**
    - A good architecture diagram should show four layers: developer/CI control plane, AWS infrastructure foundation, Kubernetes platform, and the three services.
    - The key arrows are: code commit to GitHub Actions; artifacts to ECR; Terraform to VPC/EKS/ECR; Helm to cluster; Ingress to `api-gateway`; gateway to internal services; Prometheus/Grafana observing the cluster.

Main entry points: [`.github/workflows/ci-cd.yml`](https://github.com/miguel-higorre-ch/production-grade-microservices-platform/blob/main/.github/workflows/ci-cd.yml) (GitHub Actions), [`services/api-gateway`](https://github.com/miguel-higorre-ch/production-grade-microservices-platform/tree/main/services/api-gateway) (API Gateway), [`infrastructure/terraform/environments`](https://github.com/miguel-higorre-ch/production-grade-microservices-platform/tree/main/infrastructure/terraform/environments) (Terraform Stacks), [`helm/observability`](https://github.com/miguel-higorre-ch/production-grade-microservices-platform/tree/main/helm/observability) (Observability)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_ci["CI/CD"]
  node_gha["GitHub Actions<br/>ci-cd<br/>[ci-cd.yml]"]
  node_sonar["SonarQube Gate<br/>quality"]
  node_trivy["Trivy Scans<br/>security<br/>[ci-cd.yml]"]
end

subgraph group_group_infra["Cloud Infra"]
  node_terraform_root["Terraform Stacks<br/>provisioning"]
  node_networking["Networking Module<br/>terraform-module<br/>[main.tf]"]
  node_eks["EKS Module<br/>terraform-module<br/>[main.tf]"]
  node_ecr["ECR Module<br/>terraform-module<br/>[main.tf]"]
end

subgraph group_group_k8s["Kubernetes"]
  node_helm_chart["Base Chart<br/>helm-chart"]
  node_helm_envs["Env Values<br/>helm-values"]
  node_observability["Observability<br/>monitoring-stack"]
  node_ingress["Ingress<br/>cluster-edge<br/>[ingress.yaml]"]
end

subgraph group_group_app["Services"]
  node_api_gateway["API Gateway<br/>node-service"]
  node_auth_service["Auth Service<br/>node-service"]
  node_user_service["User Service<br/>node-service"]
  node_service_runtime["Node Runtime<br/>app-runtime<br/>[server.js]"]
  node_service_tests["Tests<br/>verification"]
  node_docker_builds["Docker Images<br/>packaging"]
end

node_repo["Platform Repo<br/>monorepo"]

node_repo -->|"commit triggers"| node_gha
node_gha -->|"analyzes"| node_sonar
node_gha -->|"scans"| node_trivy
node_gha -->|"verifies"| node_service_tests
node_gha -->|"builds"| node_docker_builds
node_gha -->|"applies"| node_terraform_root
node_gha -->|"deploys"| node_helm_chart
node_terraform_root -->|"assembles"| node_networking
node_terraform_root -->|"assembles"| node_eks
node_terraform_root -->|"assembles"| node_ecr
node_ecr -->|"stores images"| node_docker_builds
node_networking -->|"hosts"| node_eks
node_helm_envs -->|"configures"| node_helm_chart
node_helm_chart -->|"renders"| node_ingress
node_ingress -->|"routes to"| node_api_gateway
node_api_gateway -->|"calls"| node_auth_service
node_api_gateway -->|"calls"| node_user_service
node_api_gateway -->|"runs on"| node_service_runtime
node_auth_service -->|"runs on"| node_service_runtime
node_user_service -->|"runs on"| node_service_runtime
node_observability -->|"watches"| node_api_gateway
node_observability -->|"watches"| node_auth_service
node_observability -->|"watches"| node_user_service

click node_gha "https://github.com/miguel-higorre-ch/production-grade-microservices-platform/blob/main/.github/workflows/ci-cd.yml"
click node_sonar "https://github.com/miguel-higorre-ch/production-grade-microservices-platform/blob/main/sonar-project.properties"
click node_trivy "https://github.com/miguel-higorre-ch/production-grade-microservices-platform/blob/main/.github/workflows/ci-cd.yml"
click node_terraform_root "https://github.com/miguel-higorre-ch/production-grade-microservices-platform/tree/main/infrastructure/terraform/environments"
click node_networking "https://github.com/miguel-higorre-ch/production-grade-microservices-platform/blob/main/infrastructure/terraform/modules/networking/main.tf"
click node_eks "https://github.com/miguel-higorre-ch/production-grade-microservices-platform/blob/main/infrastructure/terraform/modules/eks/main.tf"
click node_ecr "https://github.com/miguel-higorre-ch/production-grade-microservices-platform/blob/main/infrastructure/terraform/modules/ecr/main.tf"
click node_helm_chart "https://github.com/miguel-higorre-ch/production-grade-microservices-platform/tree/main/helm/charts/microservice"
click node_helm_envs "https://github.com/miguel-higorre-ch/production-grade-microservices-platform/tree/main/helm/environments"
click node_observability "https://github.com/miguel-higorre-ch/production-grade-microservices-platform/tree/main/helm/observability"
click node_ingress "https://github.com/miguel-higorre-ch/production-grade-microservices-platform/blob/main/helm/charts/microservice/templates/ingress.yaml"
click node_api_gateway "https://github.com/miguel-higorre-ch/production-grade-microservices-platform/tree/main/services/api-gateway"
click node_auth_service "https://github.com/miguel-higorre-ch/production-grade-microservices-platform/tree/main/services/auth-service"
click node_user_service "https://github.com/miguel-higorre-ch/production-grade-microservices-platform/tree/main/services/user-service"
click node_service_runtime "https://github.com/miguel-higorre-ch/production-grade-microservices-platform/blob/main/services/api-gateway/src/server.js"
click node_service_tests "https://github.com/miguel-higorre-ch/production-grade-microservices-platform/tree/main/tests"
click node_docker_builds "https://github.com/miguel-higorre-ch/production-grade-microservices-platform/tree/main/services/api-gateway/Dockerfile"

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_gha,node_sonar,node_trivy toneBlue
class node_terraform_root,node_networking,node_eks,node_ecr toneAmber
class node_helm_chart,node_helm_envs,node_observability,node_ingress toneMint
class node_api_gateway,node_auth_service,node_user_service,node_service_runtime,node_service_tests,node_docker_builds toneRose
class node_repo toneNeutral
```

## Components

### CI/CD

Developer control plane and release automation

- [GitHub Actions](https://github.com/miguel-higorre-ch/production-grade-microservices-platform/blob/main/.github/workflows/ci-cd.yml): ci-cd · Pipeline orchestration for validation, build, deploy, and promotion · `.github/workflows/ci-cd.yml`
- [SonarQube Gate](https://github.com/miguel-higorre-ch/production-grade-microservices-platform/blob/main/sonar-project.properties): quality · Code quality checks used as a release gate · `sonar-project.properties`
- [Trivy Scans](https://github.com/miguel-higorre-ch/production-grade-microservices-platform/blob/main/.github/workflows/ci-cd.yml): security · Filesystem and image scanning enforced in the pipeline · `.github/workflows/ci-cd.yml`

### Cloud Infra

AWS foundation provisioned with Terraform

- [Terraform Stacks](https://github.com/miguel-higorre-ch/production-grade-microservices-platform/tree/main/infrastructure/terraform/environments): provisioning · Environment roots assembling AWS infrastructure modules · `infrastructure/terraform/environments`
- [Networking Module](https://github.com/miguel-higorre-ch/production-grade-microservices-platform/blob/main/infrastructure/terraform/modules/networking/main.tf): terraform-module · VPC and subnet foundation for public and private topology · `infrastructure/terraform/modules/networking/main.tf`
- [EKS Module](https://github.com/miguel-higorre-ch/production-grade-microservices-platform/blob/main/infrastructure/terraform/modules/eks/main.tf): terraform-module · Kubernetes cluster and worker-node provisioning · `infrastructure/terraform/modules/eks/main.tf`
- [ECR Module](https://github.com/miguel-higorre-ch/production-grade-microservices-platform/blob/main/infrastructure/terraform/modules/ecr/main.tf): terraform-module · Container registry for immutable service images · `infrastructure/terraform/modules/ecr/main.tf`

### Kubernetes

Cluster deployment, packaging, and observability

- [Base Chart](https://github.com/miguel-higorre-ch/production-grade-microservices-platform/tree/main/helm/charts/microservice): helm-chart · Reusable microservice chart with deployment, service, ingress, and monitoring primitives · `helm/charts/microservice`
- [Env Values](https://github.com/miguel-higorre-ch/production-grade-microservices-platform/tree/main/helm/environments): helm-values · Dev, staging, prod, and canary overrides · `helm/environments`
- [Observability](https://github.com/miguel-higorre-ch/production-grade-microservices-platform/tree/main/helm/observability): monitoring-stack · Prometheus and Grafana configuration plus alert rules · `helm/observability`
- [Ingress](https://github.com/miguel-higorre-ch/production-grade-microservices-platform/blob/main/helm/charts/microservice/templates/ingress.yaml): cluster-edge · North-south traffic entry into the Kubernetes cluster · `helm/charts/microservice/templates/ingress.yaml`

### Services

Node.js microservices and runtime boundaries

- [API Gateway](https://github.com/miguel-higorre-ch/production-grade-microservices-platform/tree/main/services/api-gateway): node-service · Public entrypoint that routes and aggregates requests · `services/api-gateway`
- [Auth Service](https://github.com/miguel-higorre-ch/production-grade-microservices-platform/tree/main/services/auth-service): node-service · Internal authentication service · `services/auth-service`
- [User Service](https://github.com/miguel-higorre-ch/production-grade-microservices-platform/tree/main/services/user-service): node-service · Internal user profile and backend API service · `services/user-service`
- [Node Runtime](https://github.com/miguel-higorre-ch/production-grade-microservices-platform/blob/main/services/api-gateway/src/server.js): app-runtime · Shared Node.js app/server pattern used by each service · `services/api-gateway/src/server.js`
- [Tests](https://github.com/miguel-higorre-ch/production-grade-microservices-platform/tree/main/tests): verification · Jest unit and integration coverage plus Postman/Newman E2E checks · `tests`
- [Docker Images](https://github.com/miguel-higorre-ch/production-grade-microservices-platform/tree/main/services/api-gateway/Dockerfile): packaging · Per-service container builds used to publish images to ECR · `services/api-gateway/Dockerfile`

### Other components

- **Platform Repo**: monorepo · Reference microservices platform spanning app, infra, and delivery layers

## Connections

- Platform Repo → GitHub Actions: commit triggers · Repository changes start the CI/CD workflow
- GitHub Actions → SonarQube Gate: analyzes · Pipeline runs code quality checks
- GitHub Actions → Trivy Scans: scans · Pipeline enforces vulnerability and filesystem scanning
- GitHub Actions → Tests: verifies · Runs unit, integration, and E2E validation
- GitHub Actions → Docker Images: builds · Creates service container images
- GitHub Actions → Terraform Stacks: applies · Provisioning and environment changes are managed by Terraform
- GitHub Actions → Base Chart: deploys · Helm is used to release workloads to the cluster
- Terraform Stacks → Networking Module: assembles · Environment stacks compose the networking module
- Terraform Stacks → EKS Module: assembles · Environment stacks compose the EKS module
- Terraform Stacks → ECR Module: assembles · Environment stacks compose the ECR module
- ECR Module → Docker Images: stores images · Built images are pushed to the registry
- Networking Module → EKS Module: hosts · Worker nodes run in the private network boundary
- Env Values → Base Chart: configures · Environment overlays supply release-specific values
- Base Chart → Ingress: renders · Chart creates the ingress and workload primitives
- Ingress → API Gateway: routes to · External traffic enters through the gateway
- API Gateway → Auth Service: calls · Gateway forwards auth-related requests internally
- API Gateway → User Service: calls · Gateway forwards user-related requests internally
- API Gateway → Node Runtime: runs on · Gateway follows the shared Node.js app/server structure
- Auth Service → Node Runtime: runs on · Service follows the Node.js app/server structure
- User Service → Node Runtime: runs on · Service follows the Node.js app/server structure
- Observability → API Gateway: watches · Cluster monitoring consumes health and readiness signals
- Observability → Auth Service: watches · Cluster monitoring consumes health and readiness signals
- Observability → User Service: watches · Cluster monitoring consumes health and readiness signals
