# jashif/customer-balance architecture

> Architecture diagram of the GitHub repository jashif/customer-balance, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jashif/customer-balance
- Repository: https://github.com/jashif/customer-balance

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    Client["Client / Event Producer"]:::external
    click Client "https://github.com/jashif/customer-balance/blob/main/utils/send-events.js"

    %% Local Dev Environment
    subgraph "Local Development" 
        direction TB
        DC["Docker-Compose"]:::infra
        click DC "https://github.com/jashif/customer-balance/blob/main/docker-compose.yml"
        DC -->|runs| BContainer
        DC -->|runs| PostgresLocal
    end

    %% Cloud Environment
    subgraph "Cloud Deployment"
        direction TB
        TF["Terraform"]:::infra
        click TF "https://github.com/jashif/customer-balance/blob/main/terraform/main.tf"
        TF -->|provisions| K8sCluster
        subgraph "Kubernetes Cluster"
            direction TB
            K8sCluster["Kubernetes Cluster"]:::infra
            K8sCluster -->|deploys| BContainerK8s
            K8sCluster -->|deploys| PostgresK8s
            click PostgresK8s "https://github.com/jashif/customer-balance/blob/main/deployment/kubernetes/postgres.yaml"
            click PostgresK8s "https://github.com/jashif/customer-balance/blob/main/deployment/kubernetes/postgres-configmap.yaml"
        end
    end

    %% Service Container (shared)
    subgraph "balance-event-api Container" 
        direction TB
        subgraph "HTTP Layer" 
            direction TB
            APIControllers["Controllers"]:::code
            click APIControllers "https://github.com/jashif/customer-balance/blob/main/services/balance-event-api/src/api/controllers/balance-controller.js"
            APIRoutes["Routes"]:::code
            click APIRoutes "https://github.com/jashif/customer-balance/blob/main/services/balance-event-api/src/api/routes/balance.route.js"
            click APIRoutes "https://github.com/jashif/customer-balance/blob/main/services/balance-event-api/src/api/routes/index.js"
            APIMid["Middlewares"]:::code
            click APIMid "https://github.com/jashif/customer-balance/tree/main/services/balance-event-api/src/api/middlewares/"
        end
        subgraph "Business Logic Layer" 
            direction TB
            Commands["Commands"]:::code
            click Commands "https://github.com/jashif/customer-balance/blob/main/services/balance-event-api/src/core/commands/customer-balance.command.js"
            Queries["Queries"]:::code
            click Queries "https://github.com/jashif/customer-balance/blob/main/services/balance-event-api/src/core/queries/get-balance.js"
            Models["Domain Models"]:::code
            click Models "https://github.com/jashif/customer-balance/blob/main/services/balance-event-api/src/core/models/balance-event.js"
        end
        subgraph "Data Access Layer" 
            direction TB
            Sequelize["Sequelize ORM"]:::code
            click Sequelize "https://github.com/jashif/customer-balance/blob/main/services/balance-event-api/src/infra/db/sequelize.js"
            CmdStore["Command Store"]:::code
            click CmdStore "https://github.com/jashif/customer-balance/blob/main/services/balance-event-api/src/infra/db/command-store.js"
        end
        Utils["Utility Helpers"]:::code
        click Utils "https://github.com/jashif/customer-balance/blob/main/services/balance-event-api/src/utils/logger.js"
        click Utils "https://github.com/jashif/customer-balance/blob/main/services/balance-event-api/src/utils/date-helper.js"
        Entry["Service Entrypoint"]:::code
        click Entry "https://github.com/jashif/customer-balance/blob/main/services/balance-event-api/src/index.js"
        EnvSample[".env.sample"]:::code
        click EnvSample "https://github.com/jashif/customer-balance/blob/main/services/balance-event-api/.env.sample"
        Dockerfile["Dockerfile"]:::infra
        click Dockerfile "https://github.com/jashif/customer-balance/tree/main/services/balance-event-api/dockerfile"
        DockerIgnore[".dockerignore"]:::infra
        click DockerIgnore "https://github.com/jashif/customer-balance/blob/main/services/balance-event-api/.dockerignore"
        Taskfile["Taskfile.yml"]:::infra
        click Taskfile "https://github.com/jashif/customer-balance/blob/main/Taskfile.yml"
    end

    %% Database
    PostgresLocal["PostgreSQL (Local)"]:::db
    PostgresK8s["PostgreSQL (K8s)"]:::db
    click PostgresLocal "https://github.com/jashif/customer-balance/blob/main/docker-compose.yml"
    
    %% Sample Docs
    Docs["Sample Payloads"]:::external
    click Docs "https://github.com/jashif/customer-balance/blob/main/docs/task-a.sample.json"
    click Docs "https://github.com/jashif/customer-balance/blob/main/docs/task-b.data.json"

    %% Connections - Requests
    Client -->|HTTP POST/GET| APIControllers
    APIControllers -->|calls| Commands
    APIControllers -->|calls| Queries
    APIRoutes -->|registers endpoints| APIControllers
    APIMid -->|applies| APIControllers

    Commands -->|writes| Sequelize
    Queries -->|reads| Sequelize
    Sequelize -->|executes SQL| PostgresLocal
    Sequelize -->|executes SQL| PostgresK8s

    %% Container runs
    BContainer["Container (Dev)"]:::infra
    BContainerK8s["Pod: balance-event-api"]:::infra
    BContainerK8s --> Entry
    BContainer --> Entry

    %% Documentation
    Entry -->|uses| EnvSample

    %% Styles
    classDef external fill:#ffa500,stroke:#333,stroke-width:1px
    classDef code fill:#87cefa,stroke:#333,stroke-width:1px
    classDef infra fill:#90ee90,stroke:#333,stroke-width:1px
    classDef db fill:#98fb98,stroke:#333,stroke-width:1px
```
