### Install Required Tools

Source: https://github.com/delose/personal-finance-management-system/blob/master/KUBERNETES_DEPLOYMENT_GUIDE.md

Installs Terraform, Helm, Google Cloud SDK, and kubectl using Homebrew.

```bash
brew install terraform

brew install helm

brew install google-cloud-sdk

brew install kubectl
```

--------------------------------

### Start Dockerized DB

Source: https://github.com/delose/personal-finance-management-system/blob/master/notification-service/README.md

Starts a Docker container for a MySQL database using the latest MongoDB image. Ensure the port mapping is correct for your setup.

```bash
docker run -d -e MONGO_INITDB_ROOT_USERNAME=admin -e MONGO_INITDB_ROOT_PASSWORD=secret --name notifdb -p 3308:27017 mongo:latest
```

--------------------------------

### Install MySQL using Helm

Source: https://github.com/delose/personal-finance-management-system/blob/master/KUBERNETES_DEPLOYMENT_GUIDE.md

Installs a MySQL database instance using the Bitnami Helm chart. Ensure you replace 'your-db-password' with a strong password.

```bash
helm install mysql bitnami/mysql \
  --namespace pfms \
  --set auth.rootPassword=your-db-password \
  --set auth.database=pfms
```

--------------------------------

### Run Config Server with Maven

Source: https://github.com/delose/personal-finance-management-system/blob/master/jaeger/README.md

Starts the configuration server required by the budget service. This service should be running before the budget service starts.

```bash
cd /path/to/pfms/config-server
mvn spring-boot:run
```

--------------------------------

### Run All Services

Source: https://github.com/delose/personal-finance-management-system/blob/master/README.md

Starts all microservices in the Personal Finance Management System.

```bash
./run-pfms.sh
```

--------------------------------

### Start the Reporting Service Application

Source: https://github.com/delose/personal-finance-management-system/blob/master/reporting-service/README.md

Starts the reporting service application using the provided start script.

```bash
./start.sh
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/delose/personal-finance-management-system/blob/master/account-service/README.md

Installs all necessary packages for the NestJS project. Run this after cloning the repository.

```bash
$ npm install
```

--------------------------------

### Install NGINX Ingress Controller with Helm

Source: https://github.com/delose/personal-finance-management-system/blob/master/KUBERNETES_DEPLOYMENT_GUIDE.md

Installs the NGINX Ingress Controller using Helm. Adds the Helm repository and installs the chart into a dedicated namespace.

```bash
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm install ingress-nginx ingress-nginx/ingress-nginx \
  --namespace ingress-nginx \
  --create-namespace
```

--------------------------------

### Install Redis with Helm

Source: https://github.com/delose/personal-finance-management-system/blob/master/KUBERNETES_DEPLOYMENT_GUIDE.md

Installs Redis using the Bitnami Helm chart. Requires specifying the namespace and setting the authentication password.

```bash
helm repo add bitnami https://charts.bitnami.com/bitnami
helm install redis bitnami/redis \
  --namespace pfms \
  --set auth.password=your-redis-password
```

--------------------------------

### Start Project in Production Mode

Source: https://github.com/delose/personal-finance-management-system/blob/master/transaction-service/README.md

Compiles and runs the project in production mode.

```bash
$ npm run start:prod
```

--------------------------------

### Start Kafka with Docker Compose

Source: https://github.com/delose/personal-finance-management-system/blob/master/jaeger/README.md

Starts Kafka services using Docker Compose. Ensure you navigate to the correct directory first. Allow approximately 10 seconds for Kafka to become ready.

```bash
cd /path/to/pfms/kafka
docker compose up -d
```

--------------------------------

### Install kubectl using Homebrew

Source: https://github.com/delose/personal-finance-management-system/blob/master/k8s/README.md

Installs the Kubernetes CLI tool using the Homebrew package manager on macOS.

```bash
brew install kubectl
```

--------------------------------

### Install Terraform using Homebrew

Source: https://github.com/delose/personal-finance-management-system/blob/master/KUBERNETES_CHECKLIST.md

Installs the Terraform CLI on macOS using the Homebrew package manager. Ensure Homebrew is installed first.

```bash
brew install terraform
```

--------------------------------

### GCP Setup and Configuration

Source: https://github.com/delose/personal-finance-management-system/blob/master/KUBERNETES_DEPLOYMENT_GUIDE.md

Logs into GCP, sets the project ID, and enables necessary APIs for GKE deployment.

```bash
gcloud auth login
gcloud auth application-default login

export PROJECT_ID="your-gcp-project-id"
gcloud config set project $PROJECT_ID

gcloud services enable container.googleapis.com
gcloud services enable compute.googleapis.com
gcloud services enable iam.googleapis.com
```

--------------------------------

### Start Jaeger with Docker Compose

Source: https://github.com/delose/personal-finance-management-system/blob/master/jaeger/README.md

Starts the Jaeger all-in-one distribution using Docker Compose. After starting, Jaeger UI can be accessed at http://localhost:16686.

```bash
cd /path/to/pfms/jaeger
docker compose up -d
```

--------------------------------

### Install MySQL using Helm

Source: https://github.com/delose/personal-finance-management-system/blob/master/KUBERNETES_CHECKLIST.md

Installs MySQL, a relational database management system, using the Bitnami Helm chart. It is deployed in the 'pfms' namespace.

```bash
helm install mysql bitnami/mysql -n pfms
```

--------------------------------

### Execute Artisan Commands via Docker

Source: https://github.com/delose/personal-finance-management-system/blob/master/expense-service/README.md

Example of how to execute an Artisan command (e.g., make:model) within the Docker container. This is useful for performing development tasks without local PHP installation.

```bash
docker compose exec laravel.test php artisan make:model Expense -mcr --api
```

--------------------------------

### Install NestJS Mau CLI

Source: https://github.com/delose/personal-finance-management-system/blob/master/transaction-service/README.md

Installs the Mau CLI globally, which is used for deploying NestJS applications.

```bash
$ npm install -g @nestjs/mau
```

--------------------------------

### Install Redis using Helm

Source: https://github.com/delose/personal-finance-management-system/blob/master/KUBERNETES_CHECKLIST.md

Installs Redis, an in-memory data structure store, using the Bitnami Helm chart. It is deployed in the 'pfms' namespace.

```bash
helm install redis bitnami/redis -n pfms
```

--------------------------------

### Verify Helm Installation

Source: https://github.com/delose/personal-finance-management-system/blob/master/pfms-chart/README.md

Checks if Helm is installed and displays its version. Ensure Helm is installed before proceeding.

```bash
helm version
```

--------------------------------

### Run the Config Server

Source: https://github.com/delose/personal-finance-management-system/blob/master/config-server/README.md

Starts the Config Server on port 8888 using Maven.

```bash
mvn spring-boot:run
```

--------------------------------

### Run Discovery Server with Maven

Source: https://github.com/delose/personal-finance-management-system/blob/master/jaeger/README.md

Starts the discovery server (Eureka) required for API Gateway routing. This service should be running before the API Gateway starts.

```bash
cd /path/to/pfms/discovery-server
mvn spring-boot:run
```

--------------------------------

### Start NestJS Application

Source: https://github.com/delose/personal-finance-management-system/blob/master/account-service/README.md

Commands to start the NestJS application in different modes. 'start:dev' enables watch mode for automatic restarts during development.

```bash
# development
$ npm run start

# watch mode
$ npm run start:dev

# production mode
$ npm run start:prod
```

--------------------------------

### Start Project in Development Mode

Source: https://github.com/delose/personal-finance-management-system/blob/master/transaction-service/README.md

Compiles and runs the project in development mode, typically with hot-reloading enabled.

```bash
$ npm run start:dev
```

--------------------------------

### Start Dockerized MySQL DB

Source: https://github.com/delose/personal-finance-management-system/blob/master/api-gateway/README.md

Launches a Docker container for MySQL, initializing the database for the API Gateway. Sets up port mapping and environment variables.

```bash
docker run -d -e MYSQL_ROOT_PASSWORD=secret -e MYSQL_DATABASE=apigwdb --name apigwdb -p 3307:3306 mysql:8.0
```

--------------------------------

### Clone and Run System

Source: https://github.com/delose/personal-finance-management-system/blob/master/README.md

Commands to clone the repository and launch the entire personal finance management system using a shell script. Assumes Docker and Docker Compose are installed.

```bash
# Clone the repository
git clone https://github.com/delose/personal-finance-management-system.git
cd pfms

# Run the entire system
./run-pfms.sh

# Open the application
open http://localhost:3000
```

--------------------------------

### AI Advisor Context Building Example

Source: https://github.com/delose/personal-finance-management-system/blob/master/docs/RESEARCH.md

Illustrates how context is built for the AI Advisor by gathering user financial data and constructing a system prompt. This includes fetching goals, recent spending trends, and current budgets.

```text
User prompt: "Am I on track for my vacation fund?"

Context builder gathers:
  1. GET /api/goals?userId={id}&category=VACATION  -> goal details
  2. GET /api/analytics/income-vs-expense?months=3  -> recent trends
  3. GET /v1/api/budgets?userId={id}                -> current budgets

System prompt includes:
  - User's financial snapshot (goals, budgets, recent spending)
  - Guardrails: "Be encouraging, avoid jargon, suggest specific actions"
  - Tool definitions for taking action
```

--------------------------------

### End-to-End Smoke Test Setup

Source: https://github.com/delose/personal-finance-management-system/blob/master/docs/SPECIFICATIONS.md

This bash script demonstrates the steps to set up and run end-to-end smoke tests for the Personal Finance Management System.

```bash
# 1. Start everything
docker compose up -d

# 2. Register user
curl -X POST localhost:8080/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"test@pfms.dev","password":"test1234","fullName":"Test User"}'

# 3. Login
TOKEN=$(curl -s -X POST localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@pfms.dev","password":"test1234"}' | jq -r '.token')

# 4. Create account
curl -X POST localhost:3004/account \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Checking","type":"CHECKING"}'
```

--------------------------------

### Run Budget Service

Source: https://github.com/delose/personal-finance-management-system/blob/master/jaeger/README.md

Starts the budget service. This is one of the three instrumented microservices. Ensure prerequisite services are running.

```bash
cd /path/to/pfms/budget-service
mvn spring-boot:run
```

--------------------------------

### Install gcloud SDK using Homebrew

Source: https://github.com/delose/personal-finance-management-system/blob/master/KUBERNETES_CHECKLIST.md

Installs the Google Cloud SDK on macOS using Homebrew. This SDK is required for interacting with Google Cloud services.

```bash
brew install google-cloud-sdk
```

--------------------------------

### Install Prometheus Monitoring with Helm

Source: https://github.com/delose/personal-finance-management-system/blob/master/KUBERNETES_DEPLOYMENT_GUIDE.md

Installs the kube-prometheus-stack Helm chart for monitoring Kubernetes clusters. This requires adding the Prometheus Community Helm repository first.

```bash
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm install prometheus prometheus-community/kube-prometheus-stack -n monitoring --create-namespace
```

--------------------------------

### Install NGINX Ingress Controller

Source: https://github.com/delose/personal-finance-management-system/blob/master/KUBERNETES_CHECKLIST.md

Installs the NGINX Ingress controller using Helm. This component manages external access to services within the cluster.

```bash
helm install ingress-nginx ingress-nginx/ingress-nginx
```

--------------------------------

### Get All Budgets via API

Source: https://github.com/delose/personal-finance-management-system/blob/master/budget-service/README.md

Retrieves a list of all budget entries by sending a GET request to the /v1/api/budgets endpoint.

```shell
curl localhost:8082/v1/api/budgets
```

--------------------------------

### Install Helm using Homebrew

Source: https://github.com/delose/personal-finance-management-system/blob/master/KUBERNETES_CHECKLIST.md

Installs the Helm package manager for Kubernetes on macOS using Homebrew. Helm is used for managing Kubernetes applications.

```bash
brew install helm
```

--------------------------------

### List All Expenses via API

Source: https://github.com/delose/personal-finance-management-system/blob/master/expense-service/README.md

Example using curl to fetch all expense records from the API. The output is piped to 'jq' for pretty-printing JSON.

```bash
curl http://localhost/api/expenses | jq
# or
curl -X GET http://localhost/api/expenses | jq
```

--------------------------------

### Get Service Info

Source: https://github.com/delose/personal-finance-management-system/blob/master/budget-service/README.md

Retrieves application information from the /actuator/info endpoint. Uses jq for formatted output.

```shell
curl http://localhost:8082/actuator/info |jq
```

--------------------------------

### Run API Gateway

Source: https://github.com/delose/personal-finance-management-system/blob/master/jaeger/README.md

Starts the API Gateway service. This is one of the three instrumented microservices. Ensure prerequisite services are running.

```bash
cd /path/to/pfms/api-gateway
mvn spring-boot:run
```

--------------------------------

### Check kubectl Version

Source: https://github.com/delose/personal-finance-management-system/blob/master/k8s/README.md

Displays the version of the installed Kubernetes CLI tool.

```bash
kubectl version
```

--------------------------------

### Get Environment Details

Source: https://github.com/delose/personal-finance-management-system/blob/master/budget-service/README.md

Retrieves environment-specific properties and configurations from the /actuator/env endpoint. Output is formatted using jq.

```shell
curl http://localhost:8082/actuator/env | jq
```

--------------------------------

### Run Notification Service

Source: https://github.com/delose/personal-finance-management-system/blob/master/jaeger/README.md

Starts the notification service. This is one of the three instrumented microservices. Ensure prerequisite services are running.

```bash
cd /path/to/pfms/notification-service
mvn spring-boot:run
```

--------------------------------

### Kubernetes Resource Quota Example

Source: https://github.com/delose/personal-finance-management-system/blob/master/KUBERNETES_DEPLOYMENT_GUIDE.md

Sets resource quotas for a namespace, limiting the total requested and limited CPU and memory resources for pods.

```yaml
apiVersion: v1
kind: ResourceQuota
metadata:
  name: pfms-quota
spec:
  hard:
    requests.cpu: "10"
    requests.memory: 20Gi
    limits.cpu: "20"
    limits.memory: 40Gi
```

--------------------------------

### Deploy NestJS Application with Mau

Source: https://github.com/delose/personal-finance-management-system/blob/master/account-service/README.md

Steps to deploy a NestJS application to AWS using the Mau CLI. Requires global installation of the Mau package.

```bash
$ npm install -g @nestjs/mau
$ mau deploy
```

--------------------------------

### Create an Expense via API

Source: https://github.com/delose/personal-finance-management-system/blob/master/expense-service/README.md

Example using curl to send a POST request to create a new expense record. Ensure the 'entry_date' is in 'YYYY-MM-DD' format.

```bash
curl -X POST http://localhost/api/expenses \
     -H "Content-Type: application/json" \
     -d '{ "title": "Coffee", "amount": 4.50, "category": "Food", "entry_date": "2026-01-13" }'
```

--------------------------------

### Initialize Reporting Service Project

Source: https://github.com/delose/personal-finance-management-system/blob/master/reporting-service/README.md

Initializes the reporting service project using `uv init --app` and creates necessary directory structure and files.

```bash
cd reporting-service
uv init --app

mkdir -p app/domain app/application app/infrastructure app/interfaces

touch app/__init__.py app/domain/__init__.py app/application/__init__.py \
      app/infrastructure/__init__.py app/interfaces/__init__.py
      
mv main.py app/main.py
```

--------------------------------

### Search Latest Dependency Versions

Source: https://github.com/delose/personal-finance-management-system/blob/master/pfms-chart/README.md

Searches Helm repositories for the latest available versions of specified dependencies like RabbitMQ, Consul, Kafka, and PostgreSQL. Use 'head -2' to get the latest version and its app version.

```bash
helm search repo bitnami/rabbitmq --versions | head -2
helm search repo bitnami/consul --versions | head -2
helm search repo bitnami/kafka --versions | head -2
helm search repo bitnami/postgresql --versions | head -2
```

--------------------------------

### Initialize Go Module with Docker

Source: https://github.com/delose/personal-finance-management-system/blob/master/analytics-service/README.md

Run this command to initialize the Go module when adding new dependencies. It ensures the Go environment is managed within Docker.

```bash
./run-docker.sh
```

--------------------------------

### Initialize Terraform

Source: https://github.com/delose/personal-finance-management-system/blob/master/KUBERNETES_CHECKLIST.md

Initializes the Terraform working directory. This downloads necessary provider plugins and prepares Terraform for use.

```bash
terraform init
```

--------------------------------

### View All Resources in Namespace

Source: https://github.com/delose/personal-finance-management-system/blob/master/KUBERNETES_CHECKLIST.md

Displays all Kubernetes resources (pods, services, deployments, etc.) within the specified namespace.

```bash
kubectl get all -n pfms
```

--------------------------------

### Create a Budget

Source: https://github.com/delose/personal-finance-management-system/blob/master/jaeger/README.md

Creates a new budget entry. This action triggers the full traced flow across services, including HTTP requests and Kafka messages.

```bash
curl -v -X POST http://localhost:8080/v1/api/budgets \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ "userId": "trace-user-1", "category": "FOOD", "amount": 500.00, "startDate": "2026-02-01", "endDate": "2026-02-28" }'
```

--------------------------------

### GET /api/analytics/monthly-summary

Source: https://github.com/delose/personal-finance-management-system/blob/master/docs/CONTRACTS.md

Provides a summary of financial activity for specified months.

```APIDOC
## GET /api/analytics/monthly-summary

### Description
Provides a summary of financial activity for specified months.

### Method
GET

### Endpoint
/api/analytics/monthly-summary

### Parameters
#### Query Parameters
- **userId** (string) - Required - The ID of the user.
- **months** (string) - Required - A comma-separated list of months in YYYY-MM format.

### Response
#### Success Response (200)
- **userId** (string) - The ID of the user.
- **months** (array) - An array of monthly summaries.
  - **month** (string (YYYY-MM)) - The month for the summary.
  - **totalIncome** (string (decimal)) - The total income for the month.
  - **totalExpense** (string (decimal)) - The total expense for the month.
  - **netSavings** (string (decimal)) - The net savings for the month.
  - **topCategory** (string) - The spending category with the highest expenditure.
  - **budgetAdherence** (number) - The percentage of adherence to the budget (0-100).
```

--------------------------------

### Verify Configurations

Source: https://github.com/delose/personal-finance-management-system/blob/master/config-server/README.md

Verifies that configurations are present for various services and environments.

```bash
curl http://localhost:8888/budget-service/dev | jq
curl http://localhost:8888/budget-service/docker | jq
curl http://localhost:8888/api-gateway/dev | jq
curl http://localhost:8888/api-gateway/docker | jq
curl http://localhost:8888/discovery-server/dev | jq
curl http://localhost:8888/discovery-server/docker | jq
```

--------------------------------

### GET /accounts/:id

Source: https://github.com/delose/personal-finance-management-system/blob/master/docs/CONTRACTS.md

Retrieves the details of a specific account by its ID.

```APIDOC
## GET /accounts/:id

### Description
Retrieves the details of a specific account by its ID.

### Method
GET

### Endpoint
/accounts/:id

### Parameters
#### Path Parameters
- **id** (string (uuid)) - Required - The unique identifier of the account.

### Response
#### Success Response (200)
- **id** (string (uuid)) - The unique identifier of the account.
- **userId** (string) - The identifier of the user who owns the account.
- **name** (string) - The name of the account.
- **type** (string (enum: CHECKING | SAVINGS | CREDIT)) - The type of the account.
- **balance** (string (decimal)) - The current balance of the account.
- **currency** (string (ISO 4217)) - The currency of the account balance.
```

--------------------------------

### GET /api/analytics/income-vs-expense

Source: https://github.com/delose/personal-finance-management-system/blob/master/docs/CONTRACTS.md

Analyzes income versus expenses over a specified period and granularity.

```APIDOC
## GET /api/analytics/income-vs-expense

### Description
Analyzes income versus expenses over a specified period and granularity.

### Method
GET

### Endpoint
/api/analytics/income-vs-expense

### Parameters
#### Query Parameters
- **userId** (string) - Required - The ID of the user.
- **from** (string) - Optional - The start date for the period (format: date).
- **to** (string) - Optional - The end date for the period (format: date).
- **granularity** (string (enum: DAILY | WEEKLY | MONTHLY)) - Optional - The granularity of the data points.

### Response
#### Success Response (200)
- **userId** (string) - The ID of the user.
- **granularity** (string (enum: DAILY | WEEKLY | MONTHLY)) - The granularity of the data points.
- **dataPoints** (array) - An array of data points for income and expense.
  - **date** (string) - The date of the data point.
  - **income** (string (decimal)) - The total income for the period.
  - **expense** (string (decimal)) - The total expense for the period.
  - **net** (string (decimal)) - The net savings (income - expense) for the period.
```

--------------------------------

### Get Kafka Network ID

Source: https://github.com/delose/personal-finance-management-system/blob/master/kafka/README.md

Retrieves the network ID for the global-service-kafka container.

```bash
docker inspect global-service-kafka -f '{{range $net,$v := .NetworkSettings.Networks}}{{$net}}{{end}}'
```

--------------------------------

### Deploy Applications with Helm

Source: https://github.com/delose/personal-finance-management-system/blob/master/KUBERNETES_DEPLOYMENT_GUIDE.md

Deploys applications using Helm charts in a specified order. Includes waiting for a critical service to be ready before proceeding.

```bash
# Deploy in dependency order
helm install discovery-server ./helm/discovery-server -n pfms
helm install config-server ./helm/config-server -n pfms

# Wait for discovery-server to be ready
kubectl wait --for=condition=ready pod -l app.kubernetes.io/name=discovery-server -n pfms --timeout=300s

# Deploy microservices
helm install api-gateway ./helm/api-gateway -n pfms
helm install user-service ./helm/user-service -n pfms
helm install budget-service ./helm/budget-service -n pfms
# ... etc
```

--------------------------------

### Create Budget

Source: https://github.com/delose/personal-finance-management-system/blob/master/docs/SPECIFICATIONS.md

Use this endpoint to create a new budget category with a specified amount and date range. Ensure the Authorization token and Content-Type are correctly set.

```bash
curl -X POST localhost:8080/v1/api/budgets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"category":"FOOD","amount":"500.00","startDate":"2026-02-01","endDate":"2026-02-28"}'
```

--------------------------------

### GET /api/analytics/spending-by-category

Source: https://github.com/delose/personal-finance-management-system/blob/master/docs/CONTRACTS.md

Retrieves a breakdown of spending by category for a given user and time period.

```APIDOC
## GET /api/analytics/spending-by-category

### Description
Retrieves a breakdown of spending by category for a given user and time period.

### Method
GET

### Endpoint
/api/analytics/spending-by-category

### Parameters
#### Query Parameters
- **userId** (string) - Required - The ID of the user.
- **from** (string) - Optional - The start date for the period (format: date).
- **to** (string) - Optional - The end date for the period (format: date).

### Response
#### Success Response (200)
- **userId** (string) - The ID of the user.
- **period** (object) - The time period for the analytics.
  - **from** (date) - The start date of the period.
  - **to** (date) - The end date of the period.
- **categories** (array) - An array of spending categories.
  - **category** (string) - The name of the category.
  - **amount** (string (decimal)) - The total amount spent in this category.
  - **percent** (number) - The percentage of total spending this category represents.
```

--------------------------------

### Create Helm Chart Directory Structure

Source: https://github.com/delose/personal-finance-management-system/blob/master/KUBERNETES_CHECKLIST.md

Creates the basic directory structure for a Helm chart for a specific microservice. Replace SERVICE_NAME with the actual service name.

```bash
mkdir -p helm/SERVICE_NAME/templates
```

--------------------------------

### List All Expenses

Source: https://github.com/delose/personal-finance-management-system/blob/master/expense-service/README.md

Retrieves a list of all expense entries. Supports both GET and POST methods for this endpoint.

```APIDOC
## GET /api/expenses

### Description
Retrieves a list of all expense entries.

### Method
GET

### Endpoint
/api/expenses

### Response
#### Success Response (200)
- **field1** (type) - Description

### Response Example
{
  "example": "response body"
}
```

--------------------------------

### Create Docker Network

Source: https://github.com/delose/personal-finance-management-system/blob/master/jaeger/README.md

Creates a Docker network for the microservices. Run this command once if the network does not exist.

```bash
docker network create pfms-network
```

--------------------------------

### Run Tests

Source: https://github.com/delose/personal-finance-management-system/blob/master/config-server/README.md

Executes the tests for the Config Server using Maven.

```bash
mvn test
```

--------------------------------

### GET /accounts/:id/balance-history

Source: https://github.com/delose/personal-finance-management-system/blob/master/docs/CONTRACTS.md

Retrieves the balance history for a specific account within a given date range and granularity.

```APIDOC
## GET /accounts/:id/balance-history

### Description
Retrieves the balance history for a specific account within a given date range and granularity.

### Method
GET

### Endpoint
/accounts/:id/balance-history

### Parameters
#### Path Parameters
- **id** (string (uuid)) - Required - The unique identifier of the account.

#### Query Parameters
- **from** (string) - Optional - The start date for the balance history (format: date).
- **to** (string) - Optional - The end date for the balance history (format: date).
- **granularity** (string (enum: DAILY | WEEKLY | MONTHLY)) - Optional - The granularity of the data points.

### Response
#### Success Response (200)
- **accountId** (string (uuid)) - The unique identifier of the account.
- **granularity** (string (enum: DAILY | WEEKLY | MONTHLY)) - The granularity of the data points.
- **dataPoints** (array) - An array of balance data points.
  - **date** (string (date)) - The date of the data point.
  - **balance** (string (decimal)) - The account balance on that date.
```

--------------------------------

### Create Account via Transaction Service

Source: https://github.com/delose/personal-finance-management-system/blob/master/transaction-service/README.md

Creates a test account by sending a POST request to the transaction service's /account endpoint. This is for logging purposes only.

```bash
curl -X POST http://localhost:3004/account \
     -H 'Content-Type: application/json' \
     -d '{"email": "aaa@aaa.com", "password" : "pw123", "fullName": "Ziggy"}'
```

--------------------------------

### Deploy Budget Service using Helm

Source: https://github.com/delose/personal-finance-management-system/blob/master/KUBERNETES_CHECKLIST.md

Deploys the budget service microservice using its Helm chart. This service manages budget-related functionalities.

```bash
helm install budget-service ./helm/budget-service -n pfms
```

--------------------------------

### Terraform Initialization and Planning

Source: https://github.com/delose/personal-finance-management-system/blob/master/KUBERNETES_DEPLOYMENT_GUIDE.md

Commands to initialize a Terraform project and plan infrastructure changes. Requires specifying the project ID.

```bash
cd terraform
terraform init
terraform plan -var="project_id=your-project-id"
```

--------------------------------

### Transaction Service Health Check

Source: https://github.com/delose/personal-finance-management-system/blob/master/transaction-service/README.md

Performs a health check on the transaction service by sending a GET request to its root endpoint.

```bash
curl localhost:3004
```

--------------------------------

### Run Unit Tests

Source: https://github.com/delose/personal-finance-management-system/blob/master/transaction-service/README.md

Executes the unit tests for the project.

```bash
$ npm run test
```

--------------------------------

### Run Consul Server

Source: https://github.com/delose/personal-finance-management-system/blob/master/consul-server/README.md

Starts a Consul server in detached mode. It exposes the UI on port 8500 and binds to all client interfaces.

```bash
docker run -d --name=consul-server -p 8500:8500 hashicorp/consul agent -server -ui -node=server-1 -bootstrap-expect=1 -client=0.0.0.0

```

--------------------------------

### Wait for Discovery Server Pod Readiness

Source: https://github.com/delose/personal-finance-management-system/blob/master/KUBERNETES_CHECKLIST.md

Waits until the discovery server pods are ready before proceeding with further deployments. This ensures the discovery service is available.

```bash
kubectl wait --for=condition=ready pod -l app=discovery-server -n pfms
```

--------------------------------

### Deploy Goal Service using Helm

Source: https://github.com/delose/personal-finance-management-system/blob/master/KUBERNETES_CHECKLIST.md

Deploys the goal service microservice using its Helm chart. This service manages financial goals.

```bash
helm install goal-service ./helm/goal-service -n pfms
```

--------------------------------

### Login and Get JWT Token

Source: https://github.com/delose/personal-finance-management-system/blob/master/jaeger/README.md

Logs in a user and extracts the JWT token from the response. This token is required for authenticated API requests.

```bash
# Login
TOKEN=$(curl -s -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"trace@test.dev","password":"test1234"}' | grep -o '"token":"[^"]*"' | cut -d'"' -f4)

echo $TOKEN
```

--------------------------------

### Get JVM Memory Usage

Source: https://github.com/delose/personal-finance-management-system/blob/master/budget-service/README.md

Fetches the current JVM memory usage metrics from the /actuator/metrics/jvm.memory.used endpoint. Formats the output with jq.

```shell
curl http://localhost:8082/actuator/metrics/jvm.memory.used | jq
```

--------------------------------

### Check Services in Namespace

Source: https://github.com/delose/personal-finance-management-system/blob/master/KUBERNETES_CHECKLIST.md

Lists all services running in the 'pfms' namespace. Helps in verifying network configurations.

```bash
kubectl get svc -n pfms
```

--------------------------------

### Deploy Discovery Server using Helm

Source: https://github.com/delose/personal-finance-management-system/blob/master/KUBERNETES_CHECKLIST.md

Deploys the discovery server microservice using its Helm chart. This service is crucial for service registration and discovery.

```bash
helm install discovery-server ./helm/discovery-server -n pfms
```

--------------------------------

### Deploy Helm Chart

Source: https://github.com/delose/personal-finance-management-system/blob/master/pfms-chart/README.md

Upgrades or installs the PFMS Helm chart in the cluster. It deploys all defined charts together and creates the namespace if it doesn't exist.

```bash
helm upgrade --install pfms-prod . -n pfms-namespace --create-namespace
```

--------------------------------

### Build Helm Dependencies

Source: https://github.com/delose/personal-finance-management-system/blob/master/pfms-chart/README.md

Builds and downloads all the dependencies defined for the current Helm chart. Ensure you are in the chart's root directory.

```bash
helm dependency build .
```

--------------------------------

### Run Spring Boot App (Default)

Source: https://github.com/delose/personal-finance-management-system/blob/master/budget-service/README.md

Executes the Spring Boot application using default configurations. Assumes the script is executable.

```bash
./springboot-run.sh
```

--------------------------------

### Run All Tests

Source: https://github.com/delose/personal-finance-management-system/blob/master/README.md

Executes all unit, integration, and end-to-end tests for the project.

```bash
./run-tests.sh
```

--------------------------------

### Ask AI Advisor

Source: https://github.com/delose/personal-finance-management-system/blob/master/docs/SPECIFICATIONS.md

Interact with the AI advisor by sending a natural language query. This endpoint is useful for getting insights or advice based on your financial data.

```bash
curl -X POST localhost:3010/api/advisor/ask \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Am I on track for my vacation?"}'
```

--------------------------------

### Demo Credentials

Source: https://github.com/delose/personal-finance-management-system/blob/master/README.md

Username and password for accessing the demo environment of the personal finance management system.

```text
Username: demo@pfms.dev
Password: demo123
```

--------------------------------

### Verify Kafka Topics

Source: https://github.com/delose/personal-finance-management-system/blob/master/jaeger/README.md

Lists Kafka topics to confirm the Kafka service is running and accessible.

```bash
docker exec global-service-kafka kafka-topics --bootstrap-server localhost:9092 --list
```

--------------------------------

### Log Correlation Example

Source: https://github.com/delose/personal-finance-management-system/blob/master/jaeger/README.md

Demonstrates how trace IDs in log messages correlate with traces in the Jaeger UI, enabling end-to-end request tracking across services.

```text
INFO [budget-service,abc123def456,789xyz...]  Produced budget message topic: notification_requests_topic
INFO [notification-service,abc123def456,qrs456...]  Received message in consumer: BudgetNotification{...}
```

--------------------------------

### View Deployment Logs

Source: https://github.com/delose/personal-finance-management-system/blob/master/KUBERNETES_CHECKLIST.md

Streams the logs from a specific deployment in real-time. Replace SERVICE_NAME with the target deployment's name.

```bash
kubectl logs -f deployment/api-gateway -n pfms
```

--------------------------------

### REST API: Transaction Query DTO

Source: https://github.com/delose/personal-finance-management-system/blob/master/docs/CONTRACTS.md

Data Transfer Object for querying transactions via GET /transactions. Supports filtering by date range, category, type, and pagination.

```yaml
# GET /transactions?from=&to=&category=&type=&cursor=&limit=
TransactionQueryDto:
  from:     string (optional, format: date)
  to:       string (optional, format: date)
  category: string (optional)
  type:     string (optional, enum: INCOME | EXPENSE)
  cursor:   string (optional, opaque cursor)
  limit:    integer (optional, default: 20, max: 100)
```

--------------------------------

### Check Spending Analytics

Source: https://github.com/delose/personal-finance-management-system/blob/master/docs/SPECIFICATIONS.md

Query the analytics service to get spending by category within a specified date range for a given user ID. This helps in understanding spending patterns.

```bash
curl "localhost:8081/api/analytics/spending-by-category?userId=<id>&from=2026-02-01&to=2026-02-28"
```

--------------------------------

### Kubernetes Network Policy Example

Source: https://github.com/delose/personal-finance-management-system/blob/master/KUBERNETES_DEPLOYMENT_GUIDE.md

Defines a NetworkPolicy to control ingress and egress traffic for the 'api-gateway' pod. It allows ingress from the 'ingress-nginx' namespace and egress to the 'discovery-server' on port 8761.

```yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: api-gateway-netpol
spec:
  podSelector:
    matchLabels:
      app: api-gateway
  policyTypes:
  - Ingress
  - Egress
  ingress:
  - from:
    - namespaceSelector:
        matchLabels:
          name: ingress-nginx
  egress:
  - to:
    - podSelector:
        matchLabels:
          app: discovery-server
    ports:
    - protocol: TCP
      port: 8761
```

--------------------------------

### Deploy Config Server using Helm

Source: https://github.com/delose/personal-finance-management-system/blob/master/KUBERNETES_CHECKLIST.md

Deploys the configuration server microservice using its Helm chart. This service centralizes application configuration.

```bash
helm install config-server ./helm/config-server -n pfms
```

--------------------------------

### Jaeger Trace Waterfall Example

Source: https://github.com/delose/personal-finance-management-system/blob/master/jaeger/README.md

Illustrates the expected span hierarchy in Jaeger for a successful trace of the 'Create a budget' operation. This helps in verifying trace propagation and service interactions.

```text
api-gateway
  └─ GET /v1/api/budgets/**  (Spring Cloud Gateway routing)
      └─ budget-service
          └─ POST /v1/api/budgets  (controller handling)
              └─ notification_requests_topic send  (Kafka producer)
                  └─ notification-service
                      └─ notification_requests_topic process  (Kafka consumer)
```

--------------------------------

### Custom Hooks for TanStack Query

Source: https://github.com/delose/personal-finance-management-system/blob/master/docs/RESEARCH.md

Examples of custom hooks using TanStack Query for server state management. These hooks abstract data fetching and mutation logic, replacing manual useState and useEffect patterns.

```typescript
useBudgets.ts     -> useQuery(['budgets', month, year], fetchBudgets)
useGoals.ts       -> useQuery(['goals'], fetchGoals) + useMutation(contributeToGoal)
useTransactions.ts -> useInfiniteQuery(['transactions'], fetchTransactions)
useAccounts.ts    -> useQuery(['accounts'], fetchAccounts)
useAnalytics.ts   -> useQuery(['analytics', dateRange], fetchAnalytics)
```

--------------------------------

### Unified Docker Compose Configuration

Source: https://github.com/delose/personal-finance-management-system/blob/master/docs/SPECIFICATIONS.md

This YAML file defines the Docker Compose setup for the PFMS project, including profiles for infrastructure, backend services, and observability. It specifies health checks, shared networks, and volume mounts for database persistence.

```yaml
# Profiles:
#   default       = infra + backend
#   infra         = postgres, mysql, mongodb, kafka, rabbitmq, consul, redis
#   backend       = all 10 services
#   observability = prometheus, grafana, loki, jaeger
#
# Health checks on all services with depends_on conditions
# Shared network: pfms-network
# Volume mounts for database persistence

```

--------------------------------

### Register New User

Source: https://github.com/delose/personal-finance-management-system/blob/master/api-gateway/README.md

Registers a new user with the API Gateway by sending a POST request to the signup endpoint. Requires email, password, and full name.

```bash
curl -X POST http://localhost:8080/auth/signup \
     -H 'Content-Type: application/json' \
     -d '{"email": "aaa@aaa.com", "password" : "pw123", "fullName": "Ziggy"}'
```

--------------------------------

### Plan Terraform Apply

Source: https://github.com/delose/personal-finance-management-system/blob/master/KUBERNETES_CHECKLIST.md

Generates an execution plan for Terraform, showing what changes will be made to your infrastructure. Use -var to specify project ID.

```bash
terraform plan -var="project_id=YOUR_PROJECT_ID"
```

--------------------------------

### Reset Demo Data

Source: https://github.com/delose/personal-finance-management-system/blob/master/README.md

Resets the system to its initial demo data state.

```bash
./reset-demo-data.sh
```