How miguel-higorre-ch/production-grade-microservices-platform works
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: ci-cd.yml GitHub Actions · api-gateway API Gateway · environments Terraform Stacks · observability Observability
Components 18
CI/CD
Developer control plane and release automation
- GitHub Actions · Pipeline orchestration for validation, build, deploy, and promotion
.github/workflows/ci-cd.yml - SonarQube Gate · Code quality checks used as a release gate
sonar-project.properties - Trivy Scans · Filesystem and image scanning enforced in the pipeline
.github/workflows/ci-cd.yml
Cloud Infra
AWS foundation provisioned with Terraform
- Terraform Stacks · Environment roots assembling AWS infrastructure modules
infrastructure/terraform/environments - Networking Module · VPC and subnet foundation for public and private topology
infrastructure/terraform/modules/networking/main.tf - EKS Module · Kubernetes cluster and worker-node provisioning
infrastructure/terraform/modules/eks/main.tf - ECR Module · Container registry for immutable service images
infrastructure/terraform/modules/ecr/main.tf
Kubernetes
Cluster deployment, packaging, and observability
- Base Chart · Reusable microservice chart with deployment, service, ingress, and monitoring primitives
helm/charts/microservice - Env Values · Dev, staging, prod, and canary overrides
helm/environments - Observability · Prometheus and Grafana configuration plus alert rules
helm/observability - Ingress · North-south traffic entry into the Kubernetes cluster
helm/charts/microservice/templates/ingress.yaml
Services
Node.js microservices and runtime boundaries
- API Gateway · Public entrypoint that routes and aggregates requests
services/api-gateway - Auth Service · Internal authentication service
services/auth-service - User Service · Internal user profile and backend API service
services/user-service - Node Runtime · Shared Node.js app/server pattern used by each service
services/api-gateway/src/server.js - Tests · Jest unit and integration coverage plus Postman/Newman E2E checks
tests - Docker Images · Per-service container builds used to publish images to ECR
services/api-gateway/Dockerfile
Other components
- Platform Repo · Reference microservices platform spanning app, infra, and delivery layers
Connections 23
- 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