Virtual Facility - Microservices Architecture

A production-ready microservices system built with NestJS, demonstrating event-driven architecture, distributed tracing, and inter-service communication patterns for managing building facilities and alarms.

📋 Overview

Virtual Facility is a comprehensive microservices-based application that implements modern distributed system patterns including:

• Event-Driven Architecture using NATS and RabbitMQ message brokers
• Orchestration & Choreography patterns for service communication
• Distributed Tracing with correlation IDs across all services
• API Gateway with rate limiting, caching, and security features
• Transactional Outbox Pattern for reliable message publishing
• Inbox Pattern for idempotent message processing
• Health Checks and observability built-in

🏗️ Architecture

Microservices

1. API Gateway (Port 3000)

• Single entry point for all client requests
• HTTP REST API with Swagger documentation
• Rate limiting and request throttling
• Redis-based response caching
• Security features (CORS, Helmet)
• Request/response logging and tracing
• Routes requests to appropriate backend services

2. Virtual Facility Service (Port 3001)

• Manages building data and operations
• PostgreSQL database for persistence
• REST API for CRUD operations on buildings
• Transactional Outbox pattern for reliable event publishing
• Publishes events to RabbitMQ

3. Workflows Service

• Orchestrates complex business workflows
• PostgreSQL database with Inbox pattern
• Listens to RabbitMQ events
• Idempotent message processing
• Manages workflow state and execution

4. Alarms Service

• Processes alarm events in real-time
• Orchestrates alarm classification and notifications
• Consumes events from NATS
• Implements orchestration pattern (coordinator)
• Communicates with classifier and notifications services

5. Alarms Generator

• Simulates alarm generation for testing
• Scheduled job to create random alarms
• Publishes alarm events to NATS
• Includes distributed tracing headers

6. Alarms Classifier Service

• AI/ML alarm classification logic
• Request/response pattern via NATS
• Categorizes alarms: critical, non-critical, or invalid
• Stateless service for horizontal scaling

7. Notifications Service

• Sends notifications about classified alarms
• Event-driven via RabbitMQ
• Handles multiple notification channels
• Asynchronous processing

Message Brokers

• NATS: High-performance pub/sub for synchronous request/response patterns
• RabbitMQ: Reliable message queue for asynchronous event processing
• Redis: In-memory cache and distributed locking

Databases

• PostgreSQL:
  • virtual-facility-db - Building data storage
  • workflows-db - Workflow state and inbox messages

🚀 Getting Started

Prerequisites

• Node.js 20+
• Docker & Docker Compose
• pnpm (package manager)

Installation

# Install dependencies
pnpm install

Running with Docker Compose

# Start all services
docker-compose up

# Start with live reload (development mode)
docker-compose watch

# Start specific services
docker-compose up api-gateway virtual-facility

# View logs
docker-compose logs -f [service-name]

# Stop all services
docker-compose down

Running Locally

# Development mode with watch
pnpm run start:dev

# Start specific microservice
pnpm run start:dev -- [service-name]

# Production mode
pnpm run start:prod

# Build all services
pnpm run build

📡 API Endpoints

API Gateway (http://localhost:3000)

Alarms

• POST /alarms - Create new alarm (fire-and-forget)
• POST /alarms/classify - Classify alarm synchronously (cached)

Buildings

• POST /buildings - Create new building (proxied to Virtual Facility)

Swagger Documentation

Access interactive API documentation at: http://localhost:3000/api

Health Checks

• GET /health - API Gateway health status

🔧 Configuration

Environment Variables

Each service can be configured via environment variables in docker-compose.yml:

API Gateway

PORT: 3000
NATS_URL: nats://nats:4222
RABBITMQ_URL: amqp://rabbitmq:5672
REDIS_URL: redis://redis:6379
CORS_ORIGIN: *
BROKER_TIMEOUT_MS: 3000
BROKER_RETRIES: 1
RATE_LIMIT_TTL: 60000
RATE_LIMIT: 300
IDEMPOTENCY_TTL_MS: 600000
CLASSIFY_CACHE_TTL: 5000

Services with PostgreSQL

POSTGRES_HOST: [service]-db
POSTGRES_PORT: 5432
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
POSTGRES_DB: [database-name]

🏛️ Design Patterns

1. API Gateway Pattern

Centralized entry point providing:

• Request routing
• Rate limiting
• Authentication/Authorization
• Response caching
• Cross-cutting concerns

2. Orchestration vs Choreography

Orchestration (Alarms Service):

// Alarms Service coordinates the workflow
const classification = await natsClient.send('alarm.classify', data);
await rabbitmqClient.emit('notification.send', { alarm, classification });

Choreography (Event-driven):

// Services react independently to events
@EventPattern('alarm.created')
async handleAlarm(@Payload() data) { ... }

3. Transactional Outbox Pattern

Ensures reliable event publishing with database transactions.

4. Inbox Pattern

Guarantees idempotent message processing using message deduplication.

5. Distributed Tracing

Correlation IDs propagated across all service calls:

const traceId = tracingService.generateTraceId();
headers.set('traceId', traceId);

📦 Project Structure

virtual-facility/
├── apps/                           # Microservices
│   ├── api-gateway/               # HTTP Gateway
│   ├── virtual-facility/          # Building management
│   ├── workflows-service/         # Workflow orchestration
│   ├── alarms-service/            # Alarm processing
│   ├── alarms-generator/          # Test data generator
│   ├── alarms-classifier-service/ # ML classification
│   └── notifications-service/     # Notification handling
├── libs/                          # Shared libraries
│   ├── alarms/                    # Alarm DTOs
│   ├── buildings/                 # Building DTOs
│   ├── workflows/                 # Workflow DTOs
│   └── tracing/                   # Distributed tracing
├── docker-compose.yml             # Service orchestration
├── Dockerfile                     # Multi-service build
└── package.json                   # Dependencies & scripts

🧪 Testing

# Unit tests
pnpm run test

# E2E tests
pnpm run test:e2e

# Test coverage
pnpm run test:cov

# Watch mode
pnpm run test:watch

🔍 Development Tools

Linting & Formatting

# Lint code
pnpm run lint

# Format code
pnpm run format

Management UIs

• RabbitMQ Management: http://localhost:15672 (guest/guest)
• Redis: Connect via redis-cli or GUI tools

📊 Observability

Logging

All services use structured logging with trace IDs for correlation.

Health Checks

Built-in health endpoints using @nestjs/terminus for:

• Service health
• Database connectivity
• Message broker status

Metrics

Metrics middleware tracks request duration and counts.

🔐 Security Features

• Helmet: Security headers
• CORS: Configurable origins
• Rate Limiting: Request throttling per client
• Input Validation: Class-validator decorators
• Request Size Limits: 1MB body limit

🚢 Deployment

Production Build

# Build all services
pnpm run build

# Run production mode
pnpm run start:prod

Docker Production

# Multi-stage build included in Dockerfile
docker build --build-arg APP_NAME=api-gateway -t virtual-facility-gateway .
docker run -p 3000:3000 virtual-facility-gateway

Scaling

Services support horizontal scaling:

# Scale workflows service to 3 replicas
docker-compose up --scale workflows-service=3

📚 Key Technologies

• Framework: NestJS 11.x
• Language: TypeScript 5.7
• Message Brokers: NATS 2.x, RabbitMQ 3.x
• Databases: PostgreSQL 13, Redis 7
• API Documentation: Swagger/OpenAPI
• Validation: class-validator, class-transformer
• HTTP Client: Axios
• ORM: TypeORM 0.3

🤝 Communication Patterns

Synchronous (Request/Response)

• API Gateway → Virtual Facility (HTTP)
• API Gateway → Classifier (NATS)

Asynchronous (Event-Driven)

• Alarms Generator → Alarms Service (NATS)
• Alarms Service → Notifications (RabbitMQ)
• Virtual Facility → Workflows (RabbitMQ)

📝 License

UNLICENSED - Private project

👨‍💻 Development Notes

This project demonstrates enterprise-grade microservices patterns suitable for:

• High-throughput event processing
• Complex workflow orchestration
• Distributed system reliability
• Scalable cloud-native applications