Release v0.4.0: Observability, RBAC, and Architecture Hardening

[raouf-b-dev]

🚀 Release v0.4.0: Observability, RBAC, and Architecture Hardening

This release represents a massive leap in production readiness. Over the past month (~180 commits), the architecture has been hardened with a full observability stack, a granular Role-Based Access Control (RBAC) system, enhanced security features, and strict API rate limiting.

✨ Key Features

🔍 Full Observability Stack (Logs, Metrics, Traces)

• Structured Logging: Replaced standard console logging with Winston. Logs are formatted as structured JSON and shipped to Loki via Promtail.
• Distributed Tracing: Integrated OpenTelemetry SDK with auto-instrumentation for HTTP, PostgreSQL, Redis, and BullMQ, exporting to Tempo via OTLP gRPC.
• Metrics: Integrated prom-client to expose a protected /metrics endpoint for Prometheus scraping. Captures both infrastructure metrics (latency, HTTP codes) and business domain events.
• Grafana Dashboards: Included a pre-provisioned Grafana setup via Docker Compose with 4 ready-to-use dashboards: API Overview, Business Metrics, Checkout SAGA, and Infrastructure.
• Async Correlation: Implemented a robust AsyncLocalStorage correlation service. X-Request-Id and trace contexts now propagate seamlessly across the HTTP boundary and into all 18 BullMQ background job workers.

🔐 RBAC & Security Hardening

• Normalized RBAC: Completely refactored the Auth module. Replaced static enums with a full database-backed Role and Permission entity model.
• Guards & Decorators: Introduced PermissionsGuard and @RequirePermissions decorators for granular endpoint protection without compromising cross-module boundaries.
• Auth Hardening: Extracted password hashing into a dedicated PasswordHasher port. Implemented user activation/deactivation flows and mustChangePassword security flags.
• API Rate Limiting: Added global Redis-backed rate limiting using @nestjs/throttler to protect against brute-force and DDoS attacks.

🏗️ Architecture & Infrastructure

• API Versioning: Enabled URI versioning (e.g., /v1/orders).
• Health Checks: Implemented @nestjs/terminus for robust /health endpoints covering PostgreSQL, Redis, and WebSocket readiness.
• Docker Production Ready: Overhauled the Dockerfile into a 4-stage optimized build. Updated docker-compose.prod.yml with health checks, dynamic image versioning, and proper network isolation.
• AI Agentic Ecosystem: Formalized AI assistant boundaries with .agents/ configuration, standardizing how AI tools interact with the repository's DDD rules.

🧹 Refactoring & Quality

• Stripped redundant generic wrappers and implemented thin-controller patterns across Notifications and Payments modules.
• Added 116 spec files spanning unit, repository, and controller levels.
• Resolved race conditions in WebSocket graceful shutdowns.

📦 Quick Start with the new stack

To spin up the entire API alongside the new Grafana/Prometheus/OTel observability stack:

# Start the full production stack including monitoring
npm run d:up:full:prod

---

This discussion was created from the release Release v0.4.0: Observability, RBAC, and Architecture Hardening.