📚 Proyecto: Sistema de Pedidos con Event-Driven Architecture

Para mis estudiantes

Este proyecto es un ejemplo práctico de cómo implementar una arquitectura basada en eventos en el mundo real. Lo he diseñado pensando en que aprendan conceptos avanzados de backend mientras desarrollan una aplicación que podrían encontrar en cualquier empresa.

🎯 ¿Qué vas a aprender?

• Event-Driven Architecture: Cómo los servicios se comunican sin conocerse directamente
• TypeScript avanzado: Tipos, interfaces, genéricos en un proyecto real
• Patrones de diseño: Singleton, Observer, Repository
• API REST: Diseño profesional de endpoints
• Manejo de estados: Transiciones válidas y consistencia de datos

🏗️ Conceptos Fundamentales

¿Qué es Event-Driven Architecture?

Imagina que estás en un restaurante:

• El mesero toma tu pedido (crear evento)
• La cocina se entera automáticamente y empieza a cocinar (reaccionar al evento)
• El cajero cobra automáticamente (otro handler del mismo evento)
• El repartidor se prepara para entregar (reacción en cadena)

Nadie le dice a nadie qué hacer directamente. Todo sucede por eventos.

Ventajas vs. Arquitectura Tradicional

❌ Forma tradicional (acoplada):

// OrderService llama directamente a otros servicios
class OrderService {
  createOrder(order) {
    this.orderRepo.save(order);
    this.paymentService.processPayment(order); // ❌ Acoplado
    this.emailService.sendConfirmation(order); // ❌ Acoplado
    this.inventoryService.updateStock(order);  // ❌ Acoplado
  }
}

✅ Con eventos (desacoplado):

// OrderService solo publica un evento
class OrderService {
  async createOrder(order) {
    this.orderRepo.save(order);
    await this.eventBus.publish('ORDER_CREATED', { order }); // ✅ Desacoplado
  }
}

🚀 Primeros Pasos

1. Instalar y ejecutar

npm install
npm run dev

2. Probar el health check

curl http://localhost:3000/health

3. Ver la información de la API

curl http://localhost:3000/

📖 Explorando el Código

Estructura que debes entender

src/
├── events/          # 🎯 El corazón del sistema
│   ├── EventBus.ts  # Singleton que maneja todos los eventos
│   └── types.ts     # Definiciones de cada evento
├── services/        # 🏢 Lógica de negocio
├── handlers/        # 👂 Quién escucha y reacciona a eventos
├── models/          # 📋 Interfaces y tipos
└── routes/          # 🌐 Endpoints HTTP

El EventBus - Tu nuevo mejor amigo

// Publicar un evento
await eventBus.publish('ORDER_CREATED', { order });

// Suscribirse a un evento
eventBus.subscribe('ORDER_CREATED', (event) => {
  console.log('¡Nuevo pedido!', event.payload.order);
});

🧪 Experimentos que debes hacer

Experimento 1: Crear tu primer pedido

curl -X POST http://localhost:3000/api/orders \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-1",
    "restaurantId": "restaurant-1", 
    "items": [{"menuItemId": "item-1", "quantity": 1, "price": 12.50}],
    "deliveryAddress": {
      "street": "Tu calle 123",
      "city": "Tu ciudad", 
      "state": "Tu estado",
      "zipCode": "12345"
    }
  }'

📝 Pregunta: ¿Qué eventos se generaron automáticamente?

Experimento 2: Observar el flujo de eventos

# Inmediatamente después de crear el pedido
curl http://localhost:3000/api/events/history

📝 Análisis: Cuenta cuántos eventos se generaron y en qué orden.

Experimento 3: Dashboard en tiempo real

curl http://localhost:3000/api/events/dashboard

📝 Reflexión: ¿Qué métricas te parecen más importantes para un negocio real?

🔍 Puntos Clave del Código

1. Cómo definir un evento (src/events/types.ts)

export interface OrderCreatedEvent extends BaseEvent {
  type: 'ORDER_CREATED';           // Nombre único del evento
  payload: {                       // Datos que transporta
    order: Order;
  };
}

2. Cómo publicar eventos (src/services/OrderService.ts)

// Guardar el pedido
this.repository.saveOrder(order);

// Avisar al mundo que se creó un pedido
await this.eventBus.publish<OrderCreatedEvent>({
  type: 'ORDER_CREATED',
  payload: { order }
});

3. Cómo escuchar eventos (src/handlers/OrderEventHandlers.ts)

public async handleOrderCreated(event: OrderCreatedEvent): Promise<void> {
  const { order } = event.payload;
  
  // Reaccionar al evento: iniciar el pago
  await this.paymentService.initiatePayment({
    orderId: order.id,
    amount: order.totalAmount,
    method: 'tarjeta_credito'
  });
}

💡 Desafíos para Practicar

Nivel Principiante

1. Agregar un nuevo campo: Añade un campo customerNotes al modelo Order
2. Nuevo endpoint: Crea GET /api/orders/recent que devuelva los últimos 5 pedidos
3. Filtros: Modifica GET /api/orders para filtrar por estado

Nivel Intermedio

4. Nuevo evento: Crea un evento ORDER_CANCELLED_BY_RESTAURANT
5. Nuevo handler: Implementa un handler que envíe notificaciones (simuladas)
6. Validaciones: Añade validación para que no se puedan hacer pedidos de más de €100

Nivel Avanzado

7. Nuevo servicio: Crea un NotificationService que se suscriba a múltiples eventos
8. Rollback: Implementa reversión automática cuando falla un pago
9. Métricas: Agrega un endpoint que calcule el tiempo promedio de entrega

🐛 Debugging y Logs

Ver qué está pasando

# Los logs del servidor te dirán todo
# Busca estos símbolos:
# 📢 = Evento publicado
# 🔄 = Handler procesando
# ✅ = Handler completado
# ❌ = Error en handler

Endpoints útiles para debugging

• GET /api/events/stats - Estadísticas de eventos
• GET /api/events/type/ORDER_CREATED - Solo eventos de un tipo
• DELETE /api/events/history - Limpiar historial para pruebas

🤔 Preguntas de Reflexión

1. ¿Qué pasaría si un handler falla? Busca en EventBus.ts cómo se maneja esto.

2. ¿Cómo agregarías un nuevo servicio sin modificar código existente? Piensa en términos de eventos.

3. ¿Qué eventos agregarías para un sistema de calificaciones? Diseña el flujo completo.

4. ¿Cómo implementarías notificaciones push? ¿Qué eventos necesitarías escuchar?

📚 Conceptos Teóricos Aplicados

Patrón Observer

• EventBus = Subject
• Handlers = Observers
• Eventos = Notifications

Patrón Singleton

• EventBus y Repository son únicos en toda la aplicación
• ¿Por qué es importante esto?

Separación de Responsabilidades

• Services = Lógica de negocio
• Handlers = Reacciones a eventos
• Routes = Interfaz HTTP
• Models = Estructura de datos

🚀 Próximos Pasos

Una vez que domines este proyecto, estarás listo para:

• Implementar Event Sourcing completo
• Usar message queues reales (RabbitMQ, Apache Kafka)
• Microservicios con eventos distribuidos
• CQRS (Command Query Responsibility Segregation)

📬 Ejercicio Final: Tu Propio Evento

Reto: Implementa un sistema de cupones de descuento que:

1. Se active cuando un usuario haga su 5° pedido
2. Genere un evento LOYALTY_REWARD_EARNED
3. Aplique automáticamente un 15% de descuento en el siguiente pedido

Pistas:

• ¿Qué eventos necesitas escuchar?
• ¿Dónde guardarías el contador de pedidos?
• ¿Cómo modificarías el cálculo del precio?

---

💬 Notas del Profesor

Este proyecto simula decisiones reales que toman empresas como Uber, Netflix o Amazon. Cada evento que implementamos resuelve un problema de escalabilidad o mantenibilidad que enfrentarían en producción.

Recuerda: En programación, como en la vida, es mejor que los componentes cooperen sin depender unos de otros. Los eventos son tu herramienta para lograr esa independencia.

¡Diviértete explorando y haciendo experimentos! 🎉