Microservices Architecture

Budget Management API

A Comprehensive, Production-Ready Backend Platform

Full-featured microservices API built with Node.js, Express, TypeScript, supporting REST, GraphQL, gRPC, and WebSockets. Integrated with MongoDB, PostgreSQL, Redis, RabbitMQ, Kafka, and Elasticsearch.

Swagger Docs View on GitHub Frontend Demo
API Online MongoDB Connected Redis Active Kafka Running
REST API
GraphQL
gRPC
WebSocket

9

Microservices

7

Databases

40+

API Endpoints

4

Protocols

Project Overview

Purpose

The Budget Management API is a comprehensive backend platform designed to demonstrate modern microservices architecture, showcasing integration of multiple technologies and best practices in building scalable, production-ready applications.

Key Capabilities

  • Budget & expense tracking
  • User authentication & management
  • Real-time notifications
  • Advanced search with Elasticsearch
  • Asynchronous task processing
  • Multi-protocol API support

Why This Project?

Perfect for developers looking to learn or reference modern backend development practices. It demonstrates real-world implementation of microservices, message queuing, caching strategies, container orchestration, and CI/CD pipelines.

System Architecture

The Budget Management API follows a microservices architecture pattern, allowing independent development, deployment, and scaling of services. Each service handles a specific domain and communicates through well-defined interfaces.

Microservices Architecture

graph TB Client[Client Applications] APIGateway[API Gateway / NGINX] subgraph Services[Microservices Layer] Auth[Authentication Service] Budget[Budget Service] Expense[Expense Service] Customer[Customer Service] Order[Order Service] Transaction[Transaction Service] Search[Search Service] Notification[Notification Service] Task[Task Service] end subgraph Data[Data Layer] MongoDB[(MongoDB)] PostgreSQL[(PostgreSQL)] MySQL[(MySQL)] Redis[(Redis Cache)] Elastic[(Elasticsearch)] end subgraph Messaging[Message Queue Layer] RabbitMQ[RabbitMQ] Kafka[Apache Kafka] end Client --> APIGateway APIGateway --> Auth APIGateway --> Budget APIGateway --> Expense APIGateway --> Customer APIGateway --> Order APIGateway --> Transaction APIGateway --> Search APIGateway --> Notification Auth --> MongoDB Budget --> MongoDB Expense --> MongoDB Customer --> MongoDB Order --> MongoDB Transaction --> PostgreSQL Search --> Elastic Budget --> Redis Expense --> Redis Task --> RabbitMQ Notification --> Kafka Order --> Kafka style Client fill:#4CAF50,stroke:#4CAF50,color:#fff style APIGateway fill:#2196F3,stroke:#2196F3,color:#fff style Auth fill:#FF9800,stroke:#FF9800,color:#fff style Budget fill:#FF9800,stroke:#FF9800,color:#fff style Expense fill:#FF9800,stroke:#FF9800,color:#fff style Customer fill:#FF9800,stroke:#FF9800,color:#fff style Order fill:#FF9800,stroke:#FF9800,color:#fff style Transaction fill:#FF9800,stroke:#FF9800,color:#fff style Search fill:#FF9800,stroke:#FF9800,color:#fff style Notification fill:#FF9800,stroke:#FF9800,color:#fff style Task fill:#FF9800,stroke:#FF9800,color:#fff style MongoDB fill:#9C27B0,stroke:#9C27B0,color:#fff style PostgreSQL fill:#9C27B0,stroke:#9C27B0,color:#fff style MySQL fill:#9C27B0,stroke:#9C27B0,color:#fff style Redis fill:#9C27B0,stroke:#9C27B0,color:#fff style Elastic fill:#9C27B0,stroke:#9C27B0,color:#fff style RabbitMQ fill:#F44336,stroke:#F44336,color:#fff style Kafka fill:#F44336,stroke:#F44336,color:#fff

Service Communication Flow

flowchart LR FE[Frontend UI] CLI[CLI Tool] APIGW[API Gateway] GRPC[gRPC Server] CORE[Application Core] Mongo[MongoDB] Postgres[PostgreSQL] Elastic[Elasticsearch] Redis[Redis] Queue[RabbitMQ/Kafka] External[External Services] FE -->|HTTP/GraphQL| APIGW CLI -->|gRPC Calls| GRPC APIGW <--> GRPC APIGW -->|REST/WebSocket| CORE GRPC --> CORE CORE --> Mongo CORE --> Postgres CORE --> Elastic CORE --> Redis CORE --> Queue Queue -->|Async Tasks| External style FE fill:#4CAF50,stroke:#4CAF50,color:#fff style CLI fill:#2196F3,stroke:#2196F3,color:#fff style APIGW fill:#FF9800,stroke:#FF9800,color:#fff style GRPC fill:#673AB7,stroke:#673AB7,color:#fff style CORE fill:#9C27B0,stroke:#9C27B0,color:#fff style Mongo fill:#47A248,stroke:#47A248,color:#fff style Postgres fill:#336791,stroke:#336791,color:#fff style Elastic fill:#005571,stroke:#005571,color:#fff style Redis fill:#DC382D,stroke:#DC382D,color:#fff style Queue fill:#FF6600,stroke:#FF6600,color:#fff style External fill:#607D8B,stroke:#607D8B,color:#fff

Technology Stack

Backend

Node.js Express.js TypeScript

Databases

MongoDB PostgreSQL MySQL Redis Elasticsearch

Messaging

RabbitMQ Apache Kafka

Protocols

REST API GraphQL gRPC WebSocket

DevOps

Docker Kubernetes Jenkins GitHub Actions

Monitoring

Prometheus Grafana

Core Features & Integrations

Authentication & Security

JWT-based authentication, bcrypt password hashing, role-based access control, and secure session management.

  • User registration & login
  • Email verification
  • Password reset
  • Token-based auth

GraphQL Support

Flexible data queries with GraphQL, allowing clients to request exactly what they need.

  • Query budgets & expenses
  • GraphiQL interface
  • Real-time subscriptions
  • Type-safe schema

gRPC Integration

High-performance RPC framework for inter-service communication with protocol buffers.

  • Low latency calls
  • Binary protocol
  • Strong typing
  • Bidirectional streaming

WebSocket Real-time

Real-time bidirectional communication for live notifications and updates.

  • Live notifications
  • Real-time updates
  • Chat support
  • Event broadcasting

Elasticsearch Search

Advanced full-text search capabilities with filtering, aggregations, and analytics.

  • Full-text search
  • Fuzzy matching
  • Aggregations
  • Real-time indexing

Redis Caching

In-memory caching for improved performance and reduced database load.

  • Session management
  • Data caching
  • Rate limiting
  • Pub/Sub messaging

Message Queuing

Asynchronous task processing with RabbitMQ and Kafka for reliable message delivery.

  • Task queuing
  • Event streaming
  • Guaranteed delivery
  • Load balancing

Containerization

Fully containerized with Docker and orchestrated with Kubernetes for scalability.

  • Docker Compose
  • Kubernetes manifests
  • Auto-scaling
  • Health checks

CI/CD Pipeline

Automated testing and deployment with Jenkins and GitHub Actions.

  • Automated tests
  • Blue-green deployment
  • Canary releases
  • Rollback support

Project Structure

Directory Organization

graph TD Root[Budget Management API] Root --> CoreFiles[Core Files] Root --> Services[Services Layer] Root --> Controllers[Controllers] Root --> Models[Data Models] Root --> Infrastructure[Infrastructure] Root --> Additional[Additional] CoreFiles --> EntryPoint[index.js - Entry Point] CoreFiles --> CLI[cli.js - CLI Tool] CoreFiles --> GRPC[grpcServer.js - gRPC Server] CoreFiles --> Docker[docker-compose.yml - Docker Config] Services --> Auth[Authentication Service] Services --> Budget[Budget Management] Services --> Expense[Expense Tracking] Services --> Search[Search & Analytics] Services --> Notif[Notifications] Services --> TaskQ[Task Queue] Controllers --> AuthCtrl[authController] Controllers --> BudgetCtrl[budgetController] Controllers --> ExpenseCtrl[expenseController] Controllers --> SearchCtrl[searchController] Controllers --> TaskCtrl[taskController] Models --> UserModel[User Schema] Models --> BudgetModel[Budget Schema] Models --> ExpenseModel[Expense Schema] Models --> OrderModel[Order Schema] Models --> TaskModel[Task Schema] Infrastructure --> DockerInfra[Docker] Infrastructure --> K8s[Kubernetes] Infrastructure --> Nginx[NGINX] Infrastructure --> Jenkins[Jenkins CI/CD] Additional --> Spring[Spring Boot Backend] Additional --> Dotnet[.NET Core Backend] Additional --> Frontend[Frontend Demo] Additional --> Tests[Testing Suite] style Root fill:#4CAF50,stroke:#4CAF50,color:#fff style CoreFiles fill:#2196F3,stroke:#2196F3,color:#fff style Services fill:#FF9800,stroke:#FF9800,color:#fff style Controllers fill:#9C27B0,stroke:#9C27B0,color:#fff style Models fill:#673AB7,stroke:#673AB7,color:#fff style Infrastructure fill:#F44336,stroke:#F44336,color:#fff style Additional fill:#00BCD4,stroke:#00BCD4,color:#fff style EntryPoint fill:#1976D2,stroke:#1976D2,color:#fff style CLI fill:#1976D2,stroke:#1976D2,color:#fff style GRPC fill:#1976D2,stroke:#1976D2,color:#fff style Docker fill:#1976D2,stroke:#1976D2,color:#fff

Key Directories

/controllers

API endpoint handlers and business logic

/services

External service integrations (Redis, RabbitMQ, Elasticsearch)

/models

MongoDB/Mongoose schemas for data models

/routes

Express route definitions and API routing

/middleware

Authentication, validation, and error handling

/graphql

GraphQL schema and resolver definitions

/proto

gRPC protocol buffer definitions

/kubernetes

K8s deployment manifests and configs

/frontend

React-based demo UI application

/docs

Swagger/OpenAPI documentation

Getting Started

1

Clone Repository

git clone https://github.com/hoangsonww/Budget-Management-Backend-API.git
cd Budget-Management-Backend-API
2

Install Dependencies

npm install
3

Configure Environment

cp .env.example .env
# Edit .env with your configuration

Required Environment Variables:

  • MONGO_DB_URI - MongoDB connection string
  • REDIS_URL - Redis connection URL
  • RABBITMQ_URL - RabbitMQ connection string
  • KAFKA_BROKER - Kafka broker address
  • JWT_SECRET - Secret key for JWT tokens
  • ELASTIC_SEARCH_URL - Elasticsearch endpoint
  • POSTGRES_URL - PostgreSQL connection string
4

Start with Docker (Recommended)

docker-compose up --build

This starts all services: API, MongoDB, Redis, RabbitMQ, Kafka, Elasticsearch

5

Or Start Locally

npm start
# API available at http://localhost:3000
# Swagger docs at http://localhost:3000/docs

Alternative Setups

CLI Usage

npm link
budget-manager --help
budget-manager seed
budget-manager list-budgets

Kubernetes Deployment

kubectl apply -f kubernetes/
kubectl get pods
kubectl get services

Frontend Demo

cd frontend
npm install
npm start

API Documentation

The Budget Management API provides 40+ endpoints across multiple services. Full interactive documentation is available via Swagger UI.

Authentication

POST /api/auth/register Register new user
POST /api/auth/login Login and get JWT token
POST /api/auth/verify-email Verify email address
POST /api/auth/reset-password Reset user password

Budget Management

GET /api/budgets Get all budgets
POST /api/budgets Create new budget
GET /api/budgets/:id Get budget by ID
PUT /api/budgets/:id Update budget
DELETE /api/budgets/:id Delete budget

Expense Tracking

GET /api/expenses Get all expenses
POST /api/expenses Add new expense
GET /api/expenses/:budgetId Get expenses for budget
PUT /api/expenses/:id Update expense

Search & Analytics

POST /api/search/expenses Search expenses with Elasticsearch
POST /api/graphql GraphQL query endpoint

Protocol Examples

REST API

curl -X POST https://budget-management-backend-api.onrender.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password123"}'

GraphQL

query {
  budgets {
    id
    name
    limit
    createdAt
  }
}

gRPC

const client = new BudgetServiceClient('localhost:50051');
client.getBudget({ id: '123' }, (err, response) => {
  console.log(response);
});

WebSocket

const ws = new WebSocket('ws://localhost:3000');
ws.onmessage = (event) => {
  console.log('Notification:', event.data);
};

Deployment Strategies

Blue-Green Deployment

Zero-downtime deployment with instant rollback capability. Switch traffic between blue and green environments.

graph LR LB[Load Balancer] Blue[Blue Environment v1.0] Green[Green Environment v2.0] LB -->|100% Traffic| Blue LB -.->|0% Traffic| Green style Blue fill:#2196F3,stroke:#2196F3,color:#fff style Green fill:#4CAF50,stroke:#4CAF50,color:#fff style LB fill:#FF9800,stroke:#FF9800,color:#fff

Canary Deployment

Gradual rollout with traffic shifting. Test new version with small percentage of users first.

graph LR LB[Load Balancer] Stable[Stable v1.0] Canary[Canary v2.0] LB -->|90% Traffic| Stable LB -->|10% Traffic| Canary style Stable fill:#2196F3,stroke:#2196F3,color:#fff style Canary fill:#FFC107,stroke:#FFC107,color:#000 style LB fill:#FF9800,stroke:#FF9800,color:#fff

Rolling Deployment

Gradual update of instances one at a time, ensuring service availability throughout the process.

graph TD Start[Start Rolling Update] Update1[Update Instance 1] Update2[Update Instance 2] Update3[Update Instance 3] Complete[Deployment Complete] Start --> Update1 Update1 --> Update2 Update2 --> Update3 Update3 --> Complete style Start fill:#4CAF50,stroke:#4CAF50,color:#fff style Update1 fill:#FF9800,stroke:#FF9800,color:#fff style Update2 fill:#FF9800,stroke:#FF9800,color:#fff style Update3 fill:#FF9800,stroke:#FF9800,color:#fff style Complete fill:#2196F3,stroke:#2196F3,color:#fff

Testing & Quality Assurance

Test Coverage

Comprehensive test suite with unit tests, integration tests, and end-to-end testing.

npm test              # Run all tests
npm test:watch        # Watch mode
npm test:coverage     # Coverage report
npm run test:mocha    # Mocha tests

Security Audits

Regular security scanning and vulnerability checks using npm audit and OWASP tools.

npm audit             # Security audit
npm audit fix         # Auto-fix vulnerabilities

Code Quality

ESLint and Prettier for code consistency and quality standards enforcement.

npm run format        # Format code
npm run lint          # Lint code

Additional Resources

Swagger Documentation

Interactive API documentation with try-it-out functionality

Frontend Demo

Live React-based UI demonstrating API integration

GitHub Repository

Source code, issues, and contribution guidelines

Documentation

Comprehensive guides in the /docs directory

CLI Tool

Command-line interface for direct API interaction

Docker Hub

Pre-built Docker images for quick deployment

About the Author

Son Nguyen

Full Stack Developer & Software Engineer

Built with ❤️ to demonstrate modern backend development practices and microservices architecture. This project showcases real-world implementation of scalable, production-ready applications.

Website GitHub LinkedIn Email