Saltar al contenido principal

SwapBits Packages

Biblioteca Centralizada de Componentes Compartidos

Colección modular de servicios, schemas, guards y utilidades que potencian toda la arquitectura de microservicios de SwapBits

Versión Actual

Versión 3.0.0 – Última actualización: 19 de octubre de 2025

Esta biblioteca contiene más de 30 schemas, 18 DTOs, 13 guards y 15 servicios que proporcionan la base técnica para todos los microservicios de la plataforma.

Stack Tecnológico​

Tecnologías Principales

La biblioteca está construida sobre un stack tecnológico moderno y probado:

  • NestJS – Framework principal para microservicios con arquitectura modular
  • MongoDB – Base de datos principal con más de 30 schemas optimizados
  • Redis – Cache y gestión de sesiones para alto rendimiento
  • Socket.io – Comunicación en tiempo real para chat y notificaciones
  • Docker – Containerización completa para despliegue consistente

¿Qué es SwapBits Packages?​

SwapBits Packages es una biblioteca modular que centraliza todos los componentes compartidos utilizados por los microservicios de la plataforma. Su objetivo es mantener el código desacoplado, reutilizable y escalable, evitando duplicación y facilitando el mantenimiento.

Propósito Principal​

Esta biblioteca actúa como el núcleo común de toda la infraestructura, proporcionando:

  • Schemas unificados – Modelos de MongoDB compartidos entre todos los servicios
  • DTOs validados – Objetos de transferencia de datos con validaciones integradas
  • Servicios globales – Lógica de negocio reutilizable (autenticación, notificaciones, analytics)
  • Guards y middlewares – Capas de seguridad y control de acceso
  • Herramientas de monitoreo – Health checks, métricas y logging centralizado

Arquitectura Modular

Cada módulo en la biblioteca está autocontenido y puede ser importado independientemente según las necesidades de cada microservicio. Esto permite una arquitectura flexible donde cada servicio solo incluye lo que necesita.

Estructura del Repositorio​

La biblioteca está organizada en 16 módulos principales, cada uno con una responsabilidad específica:

Árbol de directorios de packages/
packages/
├── analytics/           # Sistema de analytics y dashboard de métricas
├── chat/                # Módulo de chat en tiempo real
├── controllers/         # Controladores compartidos (admin, analytics, PIN)
├── dtos/                # Data Transfer Objects con validaciones
├── email/               # Servicio de email con templates
├── examples/            # Ejemplos de uso e implementación
├── gateways/            # WebSocket gateways (chat en tiempo real)
├── guards/              # Guards de autenticación y autorización
├── health/              # Sistema de health checks y monitoreo de containers
├── interceptors/        # Interceptores para analytics, rate limiting y auditoría
├── jwt/                 # Módulo JWT compartido
├── logs/                # Sistema completo de auditoría y logging
├── middleware/          # Middlewares de analytics y rate limiting
├── rate-limiting/       # Sistema de rate limiting avanzado
├── redis/               # Servicio centralizado de Redis
├── schemas/             # Mongoose Schemas para MongoDB (30+ schemas)
├── services/            # Servicios compartidos (notifications, chat, analytics, PIN)
├── tasks/               # Tareas programadas (cleanup, mantenimiento)
└── utils/               # Utilidades (códigos de error, HTTP helpers)

Organización Lógica

Cada directorio agrupa componentes relacionados por funcionalidad. Por ejemplo, guards/ contiene todos los guards de autenticación, mientras que schemas/ centraliza todos los modelos de MongoDB. Esta organización facilita encontrar y mantener los componentes.

Características Principales​

Sistema de Seguridad Integrado​

La biblioteca incluye un ecosistema completo de seguridad con múltiples capas de protección:

  • Rate Limiting Inteligente – Control de tasa por IP, usuario, email y API key con escalación automática
  • Sistema PIN Avanzado – Autenticación de segundo factor con sesiones temporales y protección anti-brute-force
  • Guards Múltiples – JWT, KYC, PIN, Rate Limit, Roles, Device Auth y filtrado de IPs
  • Protección Anti-Brute-Force – Bloqueos automáticos escalables basados en comportamiento
  • Filtrado de IPs – Whitelist y blacklist dinámica para control de acceso

Arquitectura de Capas

El sistema de seguridad funciona en capas superpuestas. Cada request pasa por múltiples validaciones:

  1. Filtrado de IP – Verifica si la IP está bloqueada o en whitelist
  2. Rate Limiting – Controla la frecuencia de requests
  3. Autenticación JWT – Valida token y sesión en Redis
  4. Verificación KYC – Confirma estado de verificación del usuario
  5. PIN Security – Requiere sesión PIN aprobada para operaciones sensibles
  6. Roles y Permisos – Valida autorizaciones específicas

Analytics y Monitoreo​

Sistema completo de métricas y estadísticas en tiempo real:

  • Dashboard Analytics – Métricas de uso, estadísticas por endpoint y análisis de comportamiento
  • Endpoint Analytics – Tracking detallado de cada endpoint con tiempos de respuesta
  • Analytics Interceptor – Captura automática de métricas sin impactar performance
  • Cleanup Automático – Retención inteligente y limpieza de datos históricos

Comunicación en Tiempo Real​

Infraestructura WebSocket para interacción instantánea:

  • Chat Gateway – Sistema de chat completo con Socket.io
  • Chat Redis Service – Cache y persistencia de mensajes con alta disponibilidad
  • Chat Guards – Autenticación específica para conexiones WebSocket
  • Admin Chat Client – Cliente administrativo para moderación y gestión

Health Monitoring​

Sistema avanzado de monitoreo y salud de la infraestructura:

  • Container Health – Monitoreo del estado de todos los containers
  • Metrics Aggregator – Agregación y análisis de métricas del sistema
  • Console Logs Service – Captura centralizada de logs para debugging
  • Health Reporter – Reportes automáticos de estado y alertas

Gestión de Datos​

Infraestructura completa de persistencia y cache:

  • 30+ Schemas MongoDB – Modelos optimizados con índices y validaciones
  • 18+ DTOs Validados – Objetos de transferencia con validaciones automáticas
  • Redis Centralizado – Cache de sesiones, rate limiting y datos temporales
  • Chat Persistence – Almacenamiento de threads y mensajes

Módulos Disponibles​

Explora cada módulo en detalle en las siguientes secciones:

📚 Documentación Detallada por Módulo

Cada módulo tiene su propia documentación completa con detalles técnicos, componentes incluidos y casos de uso:

  • Autenticación y Seguridad – Guards, JWT, PIN Security y control de acceso
  • Rate Limiting – Sistema de control de tasa y bloqueo de IPs
  • Analytics y Monitoreo – Métricas, estadísticas y dashboard
  • Chat y WebSocket – Comunicación en tiempo real
  • Health Monitoring – Salud de containers y métricas del sistema
  • Schemas y DTOs – Modelos de datos y validaciones
  • Servicios Globales – Servicios compartidos entre microservicios

Estadísticas del Proyecto​

📁 30+ Schemas

MongoDB optimizados con índices

📝 18+ DTOs

Con validaciones completas

🛡️ 13+ Guards

Autenticación y autorización

⚙️ 15+ Services

Globales reutilizables

📋 3+ Controllers

De administración

🔧 3+ Middlewares

Seguridad avanzada

Documentación en Evolución

Esta documentación se actualiza continuamente conforme se añaden nuevos módulos y funcionalidades. Cada sección está diseñada para proporcionar la información necesaria para entender qué contiene cada módulo sin entrar en detalles de implementación.