How jashif/customer-balance works
Project type and purpose
• This is a single microservice (balance-event-api) written in Node.js that exposes a simple REST API to record balance events and retrieve customer balances.
• It’s packaged and deployed via Docker, Docker-Compose, Kubernetes (YAML under deployment/kubernetes) and Infrastructure-as-Code in Terraform.
• Supporting scripts live in utils/send-events.js and Taskfile.yml to bootstrap local runs.
File structure
• Top-level directories:
• services/balance-event-api: the only microservice
• deployment: Kubernetes manifests
• docker-compose.yml: local container orchestration
• terraform: IaC definitions
• utils: ad hoc scripts (send-events.js)
• docs: sample JSON payloads
• Inside services/balance-event-api/src: a layered pattern
• api/controllers, routes, middlewares → HTTP layer
• core/commands, queries, models → business/domain logic
• infra/db → persistence (Sequelize + command-store)
• utils → helpers (date, logger)
README
• Confirms REST endpoints: POST /api/events/:retailUnitCode/:customerId and GET /api/events/:retailUnitCode/:customerId/:reason/:period
• Describes start-up routines via Yarn, Taskfile, Docker, PostgreSQL
• Highlights layered design: api, core, infra, utils
a. Main components
1) Client / Consumer – any HTTP client or internal script (e.g. utils/send-events.js)
2) balance-event-api Service
• HTTP Layer (Express controllers & routes)
• Business Logic Layer (Commands & Queries)
• Data Access Layer (Sequelize + custom command-store)
3) PostgreSQL Database
4) DevOps Layer
• Docker / Docker-Compose
• Kubernetes (Pods, Service, ConfigMap)
• Terraform (GKE cluster or other cloud infra)
b. Relationships & interactions
• Client → HTTP Layer: JSON request → controllers → routes
• Controllers → Business Logic: invoke commands or queries
• Business Logic → Data Access: read/write to PostgreSQL
• Service Container runs in Docker / Kubernetes
• Terraform provisions Kubernetes resources and the database config
• utils/send-events.js can act as an external producer to the POST endpoint
c. Architectural patterns & principles
• Layered (Clean Architecture-inspired): separation between API, domain, persistence
• Microservice: standalone, containerized service per bounded context (customer balance)
• Infrastructure as code: Terraform for cluster, Kubernetes manifests for deployment
• Twelve-factor apps: env vars, logging, config via ConfigMap and .env.sample
d. Key technologies & frameworks
• Node.js, Express.js
• Sequelize ORM + custom command-store
• PostgreSQL
• Docker / Docker-Compose, Kubernetes YAML
• Terraform for infra provisioning
• Yarn v3 Workspaces