Descripción general de microservicios backend

Arquitectura de microservicios backend

Leyenda de verificación de documentación:

✅ Verificado - Información confirmada mediante revisión de archivos de código fuente
⚠️ Asumido/Patrón - Patrón arquitectónico o asunción basada en implementación típica; verificar contra código real cuando sea crítico
❌ No confirmado - No encontrado en código revisado; puede no estar implementado

Esta documentación distingue entre detalles verificados directamente en el código base y asunciones o patrones arquitectónicos previstos. Cuando la precisión es crítica, siempre consulte los archivos de código fuente referenciados en este documento.

1. Resumen ejecutivo

El backend de Algesta está construido como una arquitectura de microservicios utilizando NestJS, TypeScript y MongoDB. La plataforma sigue los principios de Clean Architecture con patrón CQRS, Domain-Driven Design (DDD) y comunicación event-driven vía Redis (desarrollo) y Apache Kafka (producción).

Resumen de stack tecnológico:

Framework: NestJS (ver package.json en cada servicio para la versión exacta)
Lenguaje: TypeScript (ver package.json en cada servicio para la versión exacta)
Base de datos: MongoDB con Mongoose ODM
Mensajería: Redis (vía librerías redis e ioredis) / Apache Kafka (vía kafkajs)
Autenticación: JWT vía @nestjs/jwt
Registro: Winston vía nest-winston
Documentación de API: Swagger/OpenAPI vía @nestjs/swagger

Referencias de Versión: Las versiones exactas de dependencias se mantienen en el archivo package.json de cada microservicio. Ver:

algesta-ms-orders-nestjs/package.json
algesta-ms-notifications-nestjs/package.json
algesta-ms-provider-nestjs/package.json

Patrones Arquitectónicos:

Clean Architecture: Separación de responsabilidades con capas Domain, Application e Infrastructure
CQRS: Command Query Responsibility Segregation usando @nestjs/cqrs
DDD: Domain-Driven Design con modelos de dominio ricos
Arquitectura Event-Driven: Comunicación asíncrona entre servicios

2. Catálogo de Microservicios

Nombre del Servicio	Repositorio	Descripción	Puerto	Base de datos	Responsabilidades Clave	Estado
Microservicio de Órdenes	`algesta-ms-orders-nestjs`	Lógica de negocio core para gestión del ciclo de vida de órdenes	3000	MongoDB (órdenes)	Órdenes, Activos, Ubicaciones, Mensajes, Técnicos, Clientes, Garantías, Pagos	✅ Activo
Microservicio de Notificaciones	`algesta-ms-notifications-nestjs`	Gestión de notificaciones por email	3000	MongoDB (notificaciones)	Notificaciones por email vía SendGrid, seguimiento de notificaciones, trabajos programados	✅ Activo
Microservicio de Proveedores	`algesta-ms-provider-nestjs`	Gestión de proveedores y sistema de subastas	3000	MongoDB (proveedores)	Registro de proveedores, validación de documentos, gestión de subastas, cotizaciones	✅ Activo

3. Patrones de Arquitectura Comunes

Capas de Clean Architecture

Todos los microservicios siguen una Clean Architecture de tres capas:

1. Capa de Dominio (src/domain/):

Entidades: Modelos de negocio core con lógica de negocio
Objetos de Valor: Objetos inmutables que representan conceptos de dominio
Eventos de Dominio: Eventos que representan cambios de estado del negocio
Propósito: Lógica de negocio pura, independiente del framework

2. Capa de Aplicación (src/application/):

Comandos: Operaciones de escritura (CreateOrderCommand, UpdateProviderCommand)
Consultas: Operaciones de lectura (GetOrderByIdQuery, ListProvidersQuery)
Manejadores: Manejadores de comandos y consultas que implementan casos de uso de negocio
DTOs: Objetos de Transferencia de Datos para entrada/salida
Propósito: Orquestar lógica de negocio, coordinar entre dominio e infraestructura

3. Capa de Infraestructura (src/infrastructure/):

Controladores: Controladores NestJS con decoradores MessagePattern
Repositorios: Acceso a datos MongoDB vía Mongoose
Módulos: Configuración de módulos NestJS
Servicios Externos: Integración con SendGrid, Azure Blob Storage, etc.
Propósito: Implementación específica del framework, integraciones externas

Patrón CQRS

Todos los servicios implementan CQRS usando @nestjs/cqrs. Tenga en cuenta que el registro del módulo CQRS varía según el servicio:

Orders MS: CqrsModule importado a nivel de AppModule raíz
Notifications MS: CqrsModule importado dentro del módulo de característica NotificationModule
Provider MS: CqrsModule importado dentro de módulos de características (ProviderModule, AuctionsModule, etc.)

Comandos (Operaciones de Escritura):

// Example: Create Order Command
export class CreateOrderCommand {
  constructor(public readonly data: CreateOrderDto) {}
}

// Command Handler
@CommandHandler(CreateOrderCommand)
export class CreateOrderHandler implements ICommandHandler<CreateOrderCommand> {
  async execute(command: CreateOrderCommand): Promise<Order> {
    // Business logic
  }
}

Consultas (Operaciones de Lectura):

// Example: Get Order Query
export class GetOrderByIdQuery {
  constructor(public readonly orderId: string) {}
}

// Query Handler
@QueryHandler(GetOrderByIdQuery)
export class GetOrderByIdHandler implements IQueryHandler<GetOrderByIdQuery> {
  async execute(query: GetOrderByIdQuery): Promise<Order> {
    // Read logic
  }
}

Comunicación Event-Driven

Los servicios se comunican de forma asíncrona a través de Redis (desarrollo) o Kafka (producción):

Convención de Message Pattern: service.action o service.entity.action

Ejemplos:

orders.create-order: Crear orden en Orders MS
notification.send-order-reminder: Enviar recordatorio vía Notifications MS
auction.publish: Publicar orden en subasta en Provider MS

Configuración de Transporte:

Desarrollo: Redis Pub/Sub (localhost:6379)
Producción: Apache Kafka con múltiples brokers
Patrón: Decoradores MessagePattern en controladores NestJS

Acceso a Base de Datos

MongoDB con Mongoose ODM:

Definición de esquemas con decoradores TypeScript (@Schema(), @Prop())
Modelos type-safe con tipos Documento de Mongoose
Patrón repositorio para acceso a datos
Connection pooling para rendimiento

Esquema de Ejemplo:

@Schema({ timestamps: true })
export class Order {
  @Prop({ required: true, unique: true })
  orderId: string;

  @Prop({ required: true, enum: OrderStatus })
  status: OrderStatus;

  @Prop({ type: Object })
  assignedProvider?: AssignedProvider;
}

Autenticación y Autorización

Autenticación basada en JWT:

Tokens emitidos por el API Gateway
Validación de tokens en cada Microservicio
Contexto de usuario pasado en metadatos del mensaje

Control de Acceso Basado en Roles (RBAC):

Roles: ADMIN, AGENT, PROVIDER, CLIENT, TECHNICIAN
Guards para protección de Endpoints
Verificación de roles en manejadores de comandos/consultas

Registro de Logs

Configuración de Winston Logger:

Registro estructurado con formato JSON
Niveles de log: error, warn, info, debug
IDs de correlación para rastreo distribuido
Listo para agregación de logs

Health Checks

Cada servicio implementa health checks:

/health: Estado general de salud
/health/Base de datos: Estado de conexión MongoDB
/health/messaging: Estado de conexión Redis/Kafka

Documentación de API

Estado de OpenAPI/Swagger (verificado):

Microservicios: ✅ Verificado - Los Microservicios individuales (Orders, Notifications, Provider) no exponen endpoints HTTP de documentación Swagger. Son servicios basados en mensajes que se comunican a través de decoradores MessagePattern.
API Gateway: ⚠️ Asumido - Se espera que la documentación de API esté centralizada a nivel del API Gateway, que expone endpoints HTTP REST a clientes y los traduce a llamadas MessagePattern a Microservicios. (Verificar en repositorio algesta-api-gateway-nestjs)
Documentación de DTOs: ✅ Verificado - Los Microservicios usan decoradores de @nestjs/swagger (ej., @ApiTags, @ApiOperation) en algunos controladores para potencial exposición HTTP futura o generación de documentación, pero Swagger UI no es servido actualmente por los Microservicios mismos.

Referencia: Para documentación de API autorizada, verificar la configuración de Swagger en el repositorio del API Gateway (algesta-api-gateway-nestjs).

4. Comunicación Entre Servicios

Comunicación Basada en MessagePattern

Los servicios se comunican a través de decoradores MessagePattern:

@Controller()
export class OrderController {
  @MessagePattern("orders.create-order")
  async createOrder(@Payload() data: CreateOrderDto): Promise<Order> {
    return this.commandBus.execute(new CreateOrderCommand(data));
  }
}

Estructura de Mensajes

Payload de Solicitud:

{
  messageId: string;           // Unique message ID for idempotency
  timestamp: string;           // ISO 8601 timestamp
  data: any;                   // Actual payload (DTO)
  metadata?: {
    ipAddress?: string;
    userAgent?: string;
    requestedBy?: string;
  };
  user?: {                     // Authenticated user
    userId: string;
    email: string;
    role: string;
  };
}

Payload de Respuesta:

{
  success: boolean;
  message: string;
  data?: any;
  errors?: string[];
}

Capa de Transporte

Redis (Desarrollo):

Host: localhost (configurable)
Puerto: 6379 (configurable)
Estrategia de reintento: Exponential backoff

Kafka (Producción):

Brokers: Configurable vía variables de entorno
Client ID: Nombre del servicio
Topics: Uno por servicio
Particiones: Basadas en clave de mensaje

5. Stack Tecnológico Matrix

Categoría	Tecnología	Versión	Usado en	Propósito
Framework	NestJS	Ver package.json	Todos los servicios	Framework backend
Lenguaje	TypeScript	Ver package.json	Todos los servicios	Lenguaje de programación
Runtime	Node.js	Ver Dockerfile/config de runtime	Todos los servicios	Runtime de JavaScript
Base de datos	MongoDB	Versión varía por despliegue	Todos los servicios	Base de datos primaria
ODM	Mongoose	Ver package.json	Todos los servicios	Modelado de objetos MongoDB
Mensajería	Redis	Vía librerías `redis` e `ioredis`	Todos (desarrollo)	Message broker
Mensajería	Kafka	Vía librería `kafkajs`	Todos (producción)	Message broker
CQRS	@nestjs/cqrs	Ver package.json	Todos los servicios	Separación Command/Query
Autenticación	@nestjs/jwt	Ver package.json	Todos los servicios	Tokens JWT
Logging	nest-winston	Ver package.json	Todos los servicios	Logging estructurado
Validación	class-validator	Ver package.json	Todos los servicios	Validación de DTOs
Transformación	class-transformer	Ver package.json	Todos los servicios	Transformación de objetos
Docs de API	@nestjs/swagger	Ver package.json	Todos los servicios	Documentación OpenAPI
Email	@sendgrid/mail	Ver package.json	Notifications MS	Envío de emails
Generación de PDF	Puppeteer	Ver package.json	Orders, Provider MS	Creación de PDFs
Almacenamiento	Azure Blob Storage	Vía librería `@azure/storage-blob`	Provider MS	Almacenamiento de archivos
Pruebas	Jest	Ver package.json	Todos los servicios	Pruebas unitarias/integración

Archivos de Referencia de Versiones (fuente autorizada para versiones exactas):

Orders MS: algesta-ms-orders-nestjs/package.json
Notifications MS: algesta-ms-notifications-nestjs/package.json
Provider MS: algesta-ms-provider-nestjs/package.json

6. Diagrama de Contexto del Sistema

graph TB
    Client["Cliente<br/>[Persona]<br/>Usuario final solicitando servicios"]
    Provider["Proveedor<br/>[Persona]<br/>Proveedor de servicios"]
    Admin["Administrador<br/>[Persona]<br/>Administrador de plataforma"]

    subgraph Algesta["Plataforma Algesta"]
        Gateway["API Gateway<br/>[Sistema]<br/>Punto de entrada, autenticación, enrutamiento"]
        Orders["Microservicio de Órdenes<br/>[Sistema]<br/>Gestión del ciclo de vida de órdenes"]
        Notifications["Microservicio de Notificaciones<br/>[Sistema]<br/>Notificaciones por email"]
        ProviderMS["Microservicio de Proveedores<br/>[Sistema]<br/>Gestión de proveedores y subastas"]
    end

    SendGrid["SendGrid<br/>[Sistema Externo]<br/>Servicio de email"]
    Azure["Azure Blob Storage<br/>[Sistema Externo]<br/>Almacenamiento de archivos"]
    MongoOrders["MongoDB Orders<br/>[Base de Datos]<br/>Base de datos de órdenes"]
    MongoNotif["MongoDB Notifications<br/>[Base de Datos]<br/>Base de datos de notificaciones"]
    MongoProvider["MongoDB Providers<br/>[Base de Datos]<br/>Base de datos de proveedores"]
    Kafka["Kafka/Redis<br/>[Cola de Mensajes]<br/>Message broker"]

    Client -->|"Usa<br/>HTTPS"| Gateway
    Provider -->|"Usa<br/>HTTPS"| Gateway
    Admin -->|"Usa<br/>HTTPS"| Gateway

    Gateway -->|"Envía solicitudes<br/>MessagePattern"| Orders
    Gateway -->|"Envía solicitudes<br/>MessagePattern"| Notifications
    Gateway -->|"Envía solicitudes<br/>MessagePattern"| ProviderMS

    Orders -->|"Publica eventos<br/>Kafka/Redis"| Kafka
    Notifications -->|"Se suscribe a eventos<br/>Kafka/Redis"| Kafka
    ProviderMS -->|"Publica/Se suscribe<br/>Kafka/Redis"| Kafka

    Orders -->|"Lee/Escribe<br/>Protocolo MongoDB"| MongoOrders
    Notifications -->|"Lee/Escribe<br/>Protocolo MongoDB"| MongoNotif
    ProviderMS -->|"Lee/Escribe<br/>Protocolo MongoDB"| MongoProvider

    Notifications -->|"Envía emails<br/>HTTPS/API"| SendGrid
    ProviderMS -->|"Almacena archivos<br/>HTTPS/API"| Azure

    style Client fill:#08427b,stroke:#052e56,color:#ffffff
    style Provider fill:#08427b,stroke:#052e56,color:#ffffff
    style Admin fill:#08427b,stroke:#052e56,color:#ffffff
    style Gateway fill:#1168bd,stroke:#0b4884,color:#ffffff
    style Orders fill:#1168bd,stroke:#0b4884,color:#ffffff
    style Notifications fill:#1168bd,stroke:#0b4884,color:#ffffff
    style ProviderMS fill:#1168bd,stroke:#0b4884,color:#ffffff
    style SendGrid fill:#999999,stroke:#6b6b6b,color:#ffffff
    style Azure fill:#999999,stroke:#6b6b6b,color:#ffffff
    style MongoOrders fill:#999999,stroke:#6b6b6b,color:#ffffff
    style MongoNotif fill:#999999,stroke:#6b6b6b,color:#ffffff
    style MongoProvider fill:#999999,stroke:#6b6b6b,color:#ffffff
    style Kafka fill:#999999,stroke:#6b6b6b,color:#ffffff

7. Diagrama de Flujo de Comunicación

<MermaidDiagram code={`sequenceDiagram participant Client participant Gateway as API Gateway participant Orders as Orders MS participant Provider as Provider MS participant Notifications as Notifications MS participant Kafka as Kafka/Redis participant SendGrid

Client->>Gateway: Create Order (REST)
Gateway->>Orders: orders.create-order (MessagePattern)
Orders->>Orders: Validate & Save to MongoDB
Orders->>Kafka: Publish order.created event
Orders-->>Gateway: Order created response
Gateway-->>Client: Order details (JSON)

Kafka->>Notifications: order.created event
Notifications->>SendGrid: Send welcome email

Note over Orders,Provider: Order Published to Auction
Orders->>Provider: auction.publish (MessagePattern)
Provider->>Provider: Create auction record
Provider->>Kafka: Publish auction.created event

Kafka->>Notifications: auction.created event
Notifications->>SendGrid: Notify providers

Note over Provider: Provider submits bid
Provider->>Provider: Save bid to auction
Provider->>Orders: orders.update-info (assigned)
Provider->>Kafka: Publish provider.assigned event

Kafka->>Notifications: provider.assigned event
Notifications->>SendGrid: Notify client`}

title=“Flujo de Comunicación de Microservicios” caption=“Ejemplo de flujo de solicitud mostrando interacción del cliente a través del API Gateway, mensajería entre servicios vía Kafka/Redis, y entrega de notificaciones externas” />

8. Arquitectura de Despliegue

Containerización Docker

Cada Microservicio está containerizado con Docker:

Estructura de Dockerfile:

FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
CMD ["node", "dist/main"]

Docker Compose (Desarrollo):

version: "3.8"
services:
  orders-ms:
    build: ./algesta-ms-orders-nestjs
    ports:
      - "3001:3000"
    environment:
      - NODE_ENV=development
      - MONGODB_URI=mongodb://mongo:27017/orders
      - REDIS_HOST=redis

  notifications-ms:
    build: ./algesta-ms-notifications-nestjs
    ports:
      - "3002:3000"
    environment:
      - NODE_ENV=development
      - MONGODB_URI=mongodb://mongo:27017/notifications
      - REDIS_HOST=redis

  provider-ms:
    build: ./algesta-ms-provider-nestjs
    ports:
      - "3003:3000"
    environment:
      - NODE_ENV=development
      - MONGODB_URI=mongodb://mongo:27017/providers
      - REDIS_HOST=redis

  mongo:
    image: mongo:8.16.0
    ports:
      - "27017:27017"

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

Variables de Entorno

Variables Comunes (Todos los Servicios):

# Application
NODE_ENV=development|production
PORT=3000

# Database
MONGODB_URI=mongodb://localhost:27017/database_name
DB_POOL_MAX=20
DB_POOL_MIN=5

# Messaging
MESSAGING_TYPE=REDIS|KAFKA
REDIS_HOST=localhost
REDIS_PORT=6379
KAFKA_BROKERS=localhost:9092

# Authentication
JWT_SECRET=your_secret_key
JWT_EXPIRES_IN=1d

# Logging
LOG_LEVEL=info|debug|error

Variables Específicas por Servicio:

Notifications MS:

SENDGRID_API_KEY=your_sendgrid_api_key
SENDGRID_FROM_EMAIL=noreply@algesta.com
SENDGRID_FROM_NAME=Algesta

Provider MS:

AZURE_STORAGE_CONNECTION_STRING=your_connection_string
AZURE_STORAGE_CONTAINER_NAME=documents
PDF_GENERATION_TIMEOUT=30000

Endpoints de Health Check

Todos los servicios implementan endpoints de health check vía HealthModule. Los endpoints expuestos pueden variar por servicio, pero típicamente incluyen:

Endpoints de Salud Básicos (patrón verificado):

GET /health: ✅ Verificado - Estado básico de salud del servicio (uptime, version, estado)
GET /health/detailed: ⚠️ Patrón típico - Salud completa incluyendo estado de dependencias (mensajería, API Gateway)

Endpoints de Salud de Infraestructura (patrón típico):

GET /health/redis: ⚠️ Patrón típico - Health check de conexión Redis/mensajería
GET /health/redis/detailed: ⚠️ Patrón típico - Métricas detalladas en tiempo real de salud de Redis
GET /health/circuit-breaker: ⚠️ Patrón típico - Estado y métricas de circuit breaker
GET /health/api-gateway: ⚠️ Patrón típico - Verificación de conectividad con API Gateway

Leyenda:

✅ Verificado - Confirmado en código base
⚠️ Patrón típico - Patrón de implementación común, verificar en servicio específico
❌ No implementado - No encontrado en código revisado

Nota: Los endpoints específicos disponibles dependen de la implementación del HealthController de cada Microservicio. Para definiciones de endpoints autorizadas, consultar:

Orders MS: algesta-ms-orders-nestjs/src/shared/health/health.controller.ts
Notifications MS: algesta-ms-notifications-nestjs/src/shared/health/health.controller.ts
Provider MS: algesta-ms-provider-nestjs/src/shared/health/health.controller.ts

Ejemplo de Respuesta de Health Check (GET /health):

{
  "status": "ok",
  "service": "ms-orders",
  "timestamp": "2025-11-19T10:00:00.000Z",
  "uptime": 123.45,
  "version": "1.0.0"
}

Ejemplo de Respuesta de Salud Detallada (GET /health/detailed):

{
  "status": "ok",
  "service": "ms-orders",
  "timestamp": "2025-11-19T10:00:00.000Z",
  "uptime": 123.45,
  "version": "1.0.0",
  "dependencies": {
    "messaging": {
      "status": "ok",
      "responseTime": 45,
      "lastCheck": "2025-11-19T10:00:00.000Z"
    },
    "apiGateway": {
      "status": "ok",
      "responseTime": 120,
      "lastCheck": "2025-11-19T10:00:00.000Z"
    }
  }
}

Monitoreo y Logging

Estrategia de Logging:

Formato: Logs estructurados en JSON
Niveles: error, warn, info, debug
IDs de Correlación: Rastreo de solicitudes entre servicios
Agregación: Colección centralizada de logs (ej., stack ELK)

Métricas a Monitorear:

Throughput de solicitudes (solicitudes/segundo)
Latencia de respuesta (p50, p95, p99)
Tasa de errores (errores/solicitudes totales)
Rendimiento de consultas de base de datos
Profundidad de cola de mensajes
Uso de memoria y CPU

Alertas:

Fallos de health check de servicios
Tasas de error altas (> 5%)
Respuestas lentas (> 1000ms)
Problemas de conexión a base de datos
Acumulación de cola de mensajes

9. Integración con API Gateway

Todos los Microservicios son accedidos a través del API Gateway, que sirve como el punto de entrada único para las solicitudes de clientes. El gateway maneja:

Enrutamiento: Reenvía solicitudes a Microservicios apropiados basándose en rutas URL
Autenticación: Valida tokens JWT antes de reenviar a Microservicios
Autorización: Aplica control de acceso basado en roles (RBAC)
Estandarización de Respuestas: Envuelve todas las respuestas en formato consistente con traceId
Manejo de Errores: Captura y formatea errores de Microservicios
Circuit Breaking: Previene fallos en cascada cuando Microservicios no están disponibles

Para información detallada sobre la arquitectura del API Gateway, patrones de enrutamiento y mecanismos de integración, ver:

Patrón de Comunicación

El gateway se comunica con Microservicios usando Redis o Kafka (configurable vía variable de entorno MESSAGING_TYPE). Ver Comunicación Entre Servicios para detalles sobre patrones de mensajes y protocolos.

Flujo Gateway → Microservicio:

Cliente envía solicitud HTTP al API Gateway
Gateway valida autenticación (si es requerida)
Controlador recibe solicitud y crea Comando/Consulta
Manejador ejecuta Comando/Consulta
Manejador envía mensaje a Microservicio vía ClientProxy
Microservicio procesa mensaje y retorna respuesta
Manejador procesa respuesta y retorna al controlador
Gateway formatea respuesta y envía al cliente

Patrones de Mensaje Usados:

orders.create-order → Orders MS
orders.update-info → Orders MS
notification.send-email → Notifications MS
auction.publish → Provider MS
provider.get-by-id → Provider MS

Para documentación completa de endpoints de API, ver Referencia de API del Gateway.

10. Integración con Frontend

El Dashboard React de Algesta (algesta-dashboard-react) sirve como la interfaz de usuario principal para la plataforma, integrándose con todos los Microservicios backend a través del API Gateway.

Arquitectura de Integración

C4Container
    title Diagrama de Contenedores - Integración Frontend

    Person(user, "Usuario", "Admin, Agente, Proveedor o Cliente")

    Container(dashboard, "Dashboard React", "React 19, TypeScript", "Aplicación web proporcionando UI para todos los roles de usuario")
    Container(gateway, "API Gateway", "NestJS", "Punto de entrada único para todas las solicitudes API")

    Container(ordersMS, "Orders MS", "NestJS", "Gestión de órdenes")
    Container(providerMS, "Provider MS", "NestJS", "Gestión de proveedores y subastas")
    Container(notificationsMS, "Notifications MS", "NestJS", "Notificaciones por email")

    ContainerDb(ordersDB, "Orders DB", "MongoDB", "Datos de órdenes y activos")
    ContainerDb(providerDB, "Provider DB", "MongoDB", "Datos de proveedores y subastas")

    Rel(user, dashboard, "Usa", "HTTPS")
    Rel(dashboard, gateway, "Hace llamadas API", "HTTPS/REST")
    Rel(gateway, ordersMS, "Enruta solicitudes", "Redis/Kafka")
    Rel(gateway, providerMS, "Enruta solicitudes", "Redis/Kafka")
    Rel(gateway, notificationsMS, "Enruta solicitudes", "Redis/Kafka")
    Rel(ordersMS, ordersDB, "Lee/Escribe")
    Rel(providerMS, providerDB, "Lee/Escribe")

Configuración del Cliente API

El dashboard usa Axios como cliente HTTP con configuración centralizada en src/lib/api-client.ts:

Base URL: Configurada vía variable de entorno (VITE_API_URL)
Autenticación JWT: Token agregado automáticamente a todas las solicitudes vía interceptor de solicitud
Manejo de Errores: Respuestas 401 activan logout automático y redirección al login
Retroalimentación al Usuario: Mensajes de error mostrados vía notificaciones toast

Ejemplo de Flujo de Solicitud:

// Dashboard makes API call
const response = await API_CLIENT.get("/api/orders", { params: filters });

// Request Interceptor adds token
config.headers.Authorization = `Bearer ${token}`;

// Response Interceptor handles errors
if (error.response?.status === 401) {
  SessionManager.clearSession(); // Logout and redirect
}

Mapeo de Funcionalidades a Microservicios

Leyenda: ✅ Verificado | ⚠️ Patrón asumido | ❌ No confirmado

Funcionalidad Frontend	Microservicio Primario	Endpoints API (Patrón)	Propósito	Estado
Órdenes	Orders MS	`/api/orders/*`	CRUD de órdenes, gestión de ciclo de vida	⚠️
Activos	Orders MS	`/api/assets/*`	Gestión y seguimiento de activos	⚠️
Marketplace/Subastas	Provider MS	`/api/auctions/`, `/api/bids/`	Sistema de subastas y ofertas	⚠️
Proveedores	Provider MS	`/api/providers/`, `/api/works/`	Gestión de proveedores y seguimiento	⚠️
Usuarios	Auth MS (vía Gateway)	`/api/users/*`	Gestión de usuarios	⚠️
Autenticación	Auth MS (vía Gateway)	`/api/auth/*`	Autenticación y registro	⚠️
Clientes	Orders MS	`/api/orders/*` (filtrado)	Vistas de órdenes orientadas al cliente	⚠️
Contratos y Pólizas	Orders MS	`/api/contracts/`, `/api/policies/`	Gestión de contratos	⚠️
Dashboard	Múltiples	Varios Endpoints	KPIs y métricas agregadas	⚠️
Monitoreo	Notifications MS	`/api/messages/*`	Monitoreo de mensajes	⚠️

Nota: Las rutas exactas de endpoints HTTP son patrones arquitectónicos y asunciones. Para la lista autorizada de rutas HTTP y sus mapeos a llamadas MessagePattern, consultar la documentación y código fuente del API Gateway (algesta-api-gateway-nestjs).

Ejemplo de Flujo de Datos - Creación de Orden

sequenceDiagram
    participant User
    participant Dashboard
    participant APIGateway
    participant OrdersMS
    participant MongoDB
    participant ProviderMS

    User->>Dashboard: Fill order form
    Dashboard->>Dashboard: Validate with Zod schema
    Dashboard->>APIGateway: POST /api/orders (with JWT)
    APIGateway->>APIGateway: Validate JWT
    APIGateway->>OrdersMS: Send CreateOrderCommand
    OrdersMS->>MongoDB: Save order
    OrdersMS->>ProviderMS: Emit OrderCreatedEvent
    ProviderMS->>ProviderMS: Create auction
    OrdersMS-->>APIGateway: Return order
    APIGateway-->>Dashboard: Return response
    Dashboard->>Dashboard: Invalidate orders query
    Dashboard->>Dashboard: Show success toast
    Dashboard->>User: Redirect to order details

Integración de Gestión de Estado

El dashboard usa React Query para gestionar todo el estado del servidor desde Microservicios:

Patrón de Consultas (solicitudes GET):

// API call function
export const getOrders = async (filters: OrderFilters) => {
  const response = await API_CLIENT.get("/api/orders", { params: filters });
  return response.data;
};

// React Query hook
export const useOrders = (filters: OrderFilters) => {
  return useQuery({
    queryKey: ["orders", filters],
    queryFn: () => getOrders(filters),
  });
};

Patrón de Mutaciones (solicitudes POST/PATCH/DELETE):

// Mutation hook
export const useCreateOrder = () => {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (data: CreateOrderDto) => createOrder(data),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ["orders"] });
      toast.success("Order created successfully");
    },
  });
};

Beneficios:

Caché automático e invalidación de caché
Actualizaciones optimistas para mejor UX
Refetch en segundo plano
Tiempo de obsolescencia de 1 minuto para datos en caché

Formato de Respuesta de API

Todos los Microservicios retornan formato de respuesta consistente vía API Gateway:

interface ApiResponse<T, M = undefined> {
  data: T; // Actual response data
  meta?: M; // Metadata (e.g., total count)
  pagination?: {
    // Pagination info (for list endpoints)
    page: number;
    limit: number;
    total: number;
    totalPages: number;
  };
}

Ejemplo de Respuesta:

{
  "data": [
    {
      "id": "123",
      "title": "Order 1",
      "status": "pending"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 50,
    "totalPages": 5
  }
}

Flujo de Autenticación

sequenceDiagram
    participant User
    participant Dashboard
    participant APIGateway
    participant AuthMS
    participant LocalStorage

    User->>Dashboard: Enter credentials
    Dashboard->>Dashboard: Validate with Zod
    Dashboard->>APIGateway: POST /api/auth/login
    APIGateway->>AuthMS: Forward login request
    AuthMS->>AuthMS: Validate credentials
    AuthMS-->>APIGateway: Return JWT + user data
    APIGateway-->>Dashboard: Return response
    Dashboard->>LocalStorage: Store token + user
    Dashboard->>User: Redirect to dashboard

    Note over Dashboard,APIGateway: Subsequent Requests
    Dashboard->>APIGateway: GET /api/orders (with JWT in header)
    APIGateway->>APIGateway: Validate JWT
    APIGateway->>OrdersMS: Forward request
    OrdersMS-->>APIGateway: Return data
    APIGateway-->>Dashboard: Return response

Manejo de Errores

Errores de Red:

Mostrados vía notificaciones toast
Lógica de reintento para fallos transitorios
Detección de desconexión

Errores de Validación:

Mostrados en línea en formularios
Validación de esquema Zod en cliente
Validación del lado del servidor como respaldo

Errores de Autenticación (401):

Logout automático vía interceptor de respuesta
Limpiar todos los datos de autenticación de localStorage
Redirección a página de login
Mostrar mensaje de sesión expirada

Errores de Autorización (403):

Redirección a ruta apropiada para rol de usuario
Mostrar mensaje de acceso denegado

Errores del Servidor (500):

Mensaje de error genérico mostrado
Error registrado para depuración
Opción de reintento para usuario

Actualizaciones en Tiempo Real

Implementación Actual:

Polling vía refetchInterval de React Query
Refetches automáticos en segundo plano
Invalidación de caché después de mutaciones

Mejoras Futuras:

Conexión WebSocket para actualizaciones en tiempo real
Server-Sent Events (SSE) para notificaciones
Integración con Redis Pub/Sub para actualizaciones de subastas en vivo
Actualizaciones de estado de órdenes en tiempo real

Optimización de Rendimiento

Optimización de Llamadas API:

Caché de React Query reduce llamadas API redundantes
Tiempo de obsolescencia de 1 minuto para datos en caché
Deduplicación automática de solicitudes
Refetch en segundo plano

Optimización de Bundle:

Code splitting por ruta (lazy loading)
Tree shaking de código no usado
Compresión (gzip/brotli)
CDN para assets estáticos

Obtención de Datos:

Paginación del lado del servidor para listas grandes
Estado de URL para filtros (URLs compartibles)
Actualizaciones optimistas para mejor UX

Referencias Cruzadas

Documentación Frontend:

Descripción General del Dashboard Frontend - Arquitectura y stack tecnológico
Autenticación Frontend - Flujo de autenticación y manejo de JWT
Gestión de Estado Frontend - Patrones de React Query

Documentación Backend:

Arquitectura del API Gateway - Enrutamiento y autenticación del Gateway
Microservicios Backend - Este documento
Comunicación Entre Servicios - Patrones de mensajes

Esta integración asegura una experiencia de usuario fluida mientras mantiene la separación de responsabilidades entre sistemas frontend y backend.

11. Integración con Bot de WhatsApp Jelou

La plataforma Algesta incluye una interfaz conversacional de WhatsApp impulsada por Jelou, una plataforma de IA sin código. El bot sirve como el canal principal orientado al cliente para solicitudes de servicio y seguimiento de órdenes.

Arquitectura del Bot

Plataforma: Jelou (IA conversacional sin código)
Canal: WhatsApp Business API
Bot ID: b65f501f-dbba-4e5c-a0ab-c51063cfe694
Skills: 7 flujos de trabajo conversacionales (registro, creación de órdenes, seguimiento, generación de PDF)
Modelos de IA: GPT-4/GPT-4o para clasificación de servicios y procesamiento de imágenes

Puntos de Integración con Microservicios Backend

El bot Jelou se integra con múltiples Microservicios backend vía APIs REST. Lo siguiente proporciona una descripción general de alto nivel de qué servicios están integrados y sus propósitos principales:

Microservicio de Orders

Creación de órdenes desde conversaciones de WhatsApp
Recuperación de órdenes para consultas de estado y seguimiento
Gestión de ubicaciones (validación y registro de direcciones de servicio)

Microservicio Auth/Notifications

Generación y validación de OTP para autenticación de usuarios
Soporte de OTP basado en teléfono (SMS) y email para usuarios individuales y empleados de empresas

Servicio de Documentos

Generación de PDF para confirmaciones de órdenes
Entrega de documentos vía WhatsApp

Servicio de Empresas

Validación y búsqueda de registro de empresas
Gestión de datos de empresas

Servicio de Empleados

Registro y gestión de empleados para departamentos de compras
Validación y autenticación de empleados

Servicio de Usuarios

Búsqueda y registro de usuarios individuales
Gestión de datos de usuarios para solicitudes de servicio

Servicio de Mensajes

Registro de conversaciones de WhatsApp para auditoría y cumplimiento

Nota: Las rutas detalladas de endpoints, payloads de solicitud/respuesta y uso de API específico por skill están documentados en jelou-whatsapp-integration.md, que sirve como la fuente autorizada para detalles de integración Jelou–backend.

Funcionalidades Clave

Clasificación de Servicios con IA: Usa GPT-4o para analizar la descripción del problema del usuario y clasificarlo automáticamente en 13 categorías de servicio (Plomería, Electricidad, Aires-Refrigeración, etc.)
Procesamiento de Imágenes para Identificación de Activos: GPT-4.1 Vision extrae números de serie, números de modelo y S/N de fotos de equipos para solicitudes de mantenimiento
Soporte Multi-Tipo de Usuario: Maneja tanto usuarios individuales como empleados de empresas con flujos de registro y validación distintos
Validación OTP: Validación OTP basada en teléfono (SMS) y email para autenticación segura de usuarios
Seguimiento de Órdenes: Los usuarios pueden consultar el estado de órdenes por ID o recuperar todas sus órdenes por número de teléfono
Generación de PDF: Genera y envía automáticamente PDFs de confirmación de órdenes vía WhatsApp

Flujos de Usuario

Creación de Orden de Usuario Individual:

Usuario contacta bot vía WhatsApp → Menú principal
Validación de teléfono con OTP → Búsqueda/registro de usuario
Descripción del problema → IA clasifica tipo de servicio
Carga de imagen → Recolección de dirección/ciudad
Selección de horario → Creación de orden
Generación de PDF → Confirmación

Creación de Orden de Empleado de Empresa:

Validación de NIT de empresa → Autenticación de empleado
Carga de foto de activo → IA extrae información del equipo
Descripción del problema → Clasificación de servicio
Imágenes adicionales → Selección de horario
Selección de contacto de compras → Creación de orden
Generación de PDF → Confirmación

Seguimiento de Órdenes:

Usuario solicita estado → ID de orden o validación de teléfono
Recuperar orden(es) → Mostrar estado actual
Soporte de FAQ para preguntas comunes

Flujo de Datos

sequenceDiagram
    participant User
    participant Jelou
    participant Gateway
    participant OrdersMS
    participant AuthMS
    participant DocsService

    User->>Jelou: WhatsApp message
    Jelou->>Gateway: POST /api/auth/otp/send
    Gateway->>AuthMS: Send OTP
    AuthMS-->>User: SMS with OTP
    User->>Jelou: Provide OTP
    Jelou->>Gateway: POST /api/auth/otp/validate
    Gateway->>AuthMS: Validate OTP
    AuthMS-->>Jelou: Validation success
    Note over Jelou: AI processes problem description
    Jelou->>Gateway: POST /api/orders
    Gateway->>OrdersMS: Create order
    OrdersMS-->>Jelou: Order created (ID)
    Jelou->>Gateway: GET /api/documents/generate-pdf
    Gateway->>DocsService: Generate PDF
    DocsService-->>Jelou: PDF URL
    Jelou->>User: Send PDF via WhatsApp

Configuración

Variable de Entorno: La variable dev almacena la URL base de la API (ej., https://api-dev.algesta.com)
Timeout: Timeout de 30 segundos para todas las solicitudes HTTP
Manejo de Errores: Las llamadas API fallidas activan mensajes de respaldo al usuario
Gestión de Estado: Variables almacenadas con TTL de 1 hora (3600 segundos)

Monitoreo y Observabilidad

Registro de Mensajes: Todos los mensajes de WhatsApp registrados vía Servicio de Mensajes para auditoría
Seguimiento de Órdenes: Órdenes creadas vía bot etiquetadas con channel: "whatsapp" para analítica
Registro de Errores: Nodos de código incluyen declaraciones console.log para depuración
Respaldo de Modelos IA: Los modelos GPT-4 primarios recurren a Azure GPT-4o en caso de fallo

Para documentación detallada del bot Jelou, ver Integración con WhatsApp Jelou.

Esta integración permite a Algesta proporcionar servicio al cliente automatizado 24/7 vía WhatsApp, reduciendo la entrada manual de órdenes y mejorando los tiempos de respuesta para solicitudes de servicio.

12. Requisitos y Contexto de Negocio

Para una comprensión integral de los requisitos de negocio y objetivos que dieron forma a esta arquitectura, consultar:

Requisitos de Negocio - Contexto de negocio, objetivos y decisiones estratégicas
Requisitos Funcionales - Requisitos funcionales detallados con trazabilidad
Requisitos No Funcionales - Requisitos de rendimiento, seguridad, escalabilidad con verificación
Resumen Ejecutivo - Estado del proyecto de alto nivel y hallazgos clave

13. Documentación Relacionada

Arquitectura del API Gateway
Autenticación del API Gateway
Patrones de Resiliencia del API Gateway
Referencia de API del Gateway
Arquitectura del Microservicio de Orders
Arquitectura del Microservicio de Notifications
Arquitectura del Microservicio de Provider
Comunicación Entre Servicios
[Esquemas de Base de Datos](/02-architecture/Base de datos-schemas/)
Descripción General del Dashboard Frontend
Autenticación Frontend
Gestión de Estado Frontend
Integración con WhatsApp Jelou

14. Referencias

Código Fuente:

Orders MS: algesta-ms-orders-nestjs/src/app.module.ts
Notifications MS: algesta-ms-notifications-nestjs/src/app.module.ts
Provider MS: algesta-ms-provider-nestjs/src/app.module.ts

Dependencias de Paquetes:

Orders MS: algesta-ms-orders-nestjs/package.json
Notifications MS: algesta-ms-notifications-nestjs/package.json
Provider MS: algesta-ms-provider-nestjs/package.json