Sistema de Microservicios E-commerce con DDD y Kafka

Este proyecto demuestra una arquitectura de microservicios aplicando Domain-Driven Design (DDD) y comunicación asíncrona con Apache Kafka.

Arquitectura

Microservicios

✅ Implementados

1. orders-service - Gestión de órdenes de compra
2. inventory-service - Gestión de inventario

🚧 En Desarrollo

3. payments-service - Procesamiento de pagos
4. notifications-service - Envío de notificaciones

Tecnologías

• FastAPI - Framework web para APIs
• Apache Kafka - Mensajería asíncrona
• PostgreSQL - Base de datos principal (orders, payments, notifications)
• MongoDB - Base de datos para inventario
• Redis - Cache y sesiones
• Docker & Docker Compose - Containerización

Patrones DDD Implementados

• Aggregates - Entidades principales con reglas de negocio
• Value Objects - Objetos de valor inmutables (Money, Address, IDs)
• Domain Events - Eventos de dominio para comunicación entre servicios
• Saga Pattern - Para transacciones distribuidas
• CQRS - Separación de comandos y consultas
• Event Sourcing - Para auditoría y compensación
• Repository Pattern - Abstracción del acceso a datos
• Factory Pattern - Creación de entidades de dominio
• Mapper Pattern - Conversión entre dominio y DTOs

🔄 Flujo de Negocio

Flujo Implementado (Actual)

1. Cliente crea orden → Orders Service
2. Orders Service publica → order.created
3. Inventory Service recibe → order.created
4. Inventory Service valida inventario:
   ✅ Producto existe
   ✅ Stock suficiente
   ✅ Cantidad válida
5. Si válido → inventory.reserved
6. Si inválido → order.cancelled (automático)
7. Orders Service recibe → inventory.reserved o order.cancelled
8. Orders Service actualiza estado de orden
9. Cliente recibe respuesta final

Flujo Completo (Futuro)

1. Cliente crea orden → Orders Service
2. Orders Service publica → order.created
3. Inventory Service valida y reserva inventario
4. Payment Service procesa pago
5. Notification Service envía confirmación
6. Cliente recibe confirmación completa

Validación Automática de Inventario

El sistema implementa validación automática que puede resultar en cancelación automática de órdenes:

• Producto No Existe: Orden cancelada automáticamente
• Stock Insuficiente: Orden cancelada automáticamente
• Cantidad Inválida: Orden cancelada automáticamente
• Error de Reserva: Orden cancelada automáticamente

Beneficios:

• Consistencia de datos entre servicios
• Respuesta inmediata sobre disponibilidad
• Trazabilidad completa del flujo
• Logs detallados para debugging

Comunicación por Eventos

Eventos Implementados

Orders Service:

• order.created - Nueva orden creada
• order.cancelled - Orden cancelada (manual o automática)

Inventory Service:

• inventory.reserved - Inventario reservado exitosamente
• inventory.released - Inventario liberado (con idempotencia)
• order.cancelled - Orden cancelada automáticamente por falta de inventario

Payment Service (en desarrollo):

• payment.processed - Pago procesado exitosamente
• payment.failed - Pago fallido

Flujo de Eventos

order.created → inventory.reserved → order.cancelled (si falla)
     ↓              ↓
Orders Service  Inventory Service

Características:

• Asíncrono: Los servicios se comunican sin bloqueo
• Desacoplado: Cada servicio es independiente
• Resiliente: Manejo de errores y reintentos
• Trazable: Todos los eventos tienen correlación ID

Ejecutar el Proyecto

Usando Makefile (Recomendado)

# Ver todos los comandos disponibles
make help

# Construir y levantar servicios
make build
make up

# Ver logs
make logs

# Detener servicios
make down

# Formatear código con ruff
make format

# Lintear código
make lint

# Formatear y lintear
make format-lint

Usando Docker Compose directamente

# Levantar toda la infraestructura
docker-compose up -d

# Ver logs
docker-compose logs -f

# Detener servicios
docker-compose down

Monitorear eventos Kafka

Accede a http://localhost:9090 para ver los eventos en tiempo real.

Endpoints Principales

✅ Servicios Implementados

• Orders Service: http://localhost:8001
• Inventory Service: http://localhost:8003
• Kafka UI: http://localhost:9090

🚧 Servicios Futuros

• Payments Service: http://localhost:8002
• Notifications Service: http://localhost:8004

Endpoints de Inventario

• GET /api/v1/inventory/products - Listar productos
• POST /api/v1/inventory/products - Crear producto
• GET /api/v1/inventory/products/{id} - Obtener producto
• PUT /api/v1/inventory/products/{id} - Actualizar producto
• DELETE /api/v1/inventory/products/{id} - Eliminar producto
• POST /api/v1/inventory/products/{id}/stock - Agregar stock
• GET /api/v1/inventory/products/low-stock - Productos con stock bajo

Estructura del Proyecto

kafka-microservices/
├── orders-service/
│   ├── src/
│   │   ├── domain/
│   │   │   ├── entities.py          # Entidades puras del dominio
│   │   │   ├── value_objects.py     # Value objects del dominio
│   │   │   └── services.py          # Servicios de dominio
│   │   ├── application/
│   │   │   ├── services.py          # Casos de uso
│   │   │   ├── event_handlers.py    # Handlers de eventos Kafka
│   │   │   └── event_consumer.py    # Consumidor de eventos
│   │   ├── infrastructure/
│   │   │   ├── database.py          # Modelos de BD
│   │   │   └── repositories.py      # Repositorios
│   │   ├── api/
│   │   │   ├── dto.py               # DTOs para API
│   │   │   ├── mappers.py           # Conversores dominio-DTO
│   │   │   └── routes.py            # Rutas de API
│   │   ├── config.py                # Configuración
│   │   └── main.py                  # Aplicación principal
│   ├── requirements.txt
│   └── Dockerfile
├── inventory-service/
│   ├── src/
│   │   ├── domain/
│   │   │   └── entities.py          # Entidades del dominio
│   │   ├── application/
│   │   │   ├── services.py          # Casos de uso
│   │   │   ├── event_handlers.py    # Handlers de eventos Kafka
│   │   │   └── event_consumer.py    # Consumidor de eventos
│   │   ├── infrastructure/
│   │   │   ├── database.py          # Conexión MongoDB
│   │   │   └── repositories.py      # Repositorios
│   │   ├── api/
│   │   │   ├── dto.py               # DTOs para API
│   │   │   ├── mappers.py           # Conversores dominio-DTO
│   │   │   └── routes.py            # Rutas de API
│   │   ├── config.py                # Configuración
│   │   └── main.py                  # Aplicación principal
│   ├── requirements.txt
│   └── Dockerfile
├── payments-service/        # 🚧 En desarrollo
├── notifications-service/   # 🚧 En desarrollo
├── shared/                          # Código compartido
│   ├── events.py                    # Eventos de dominio
│   ├── kafka_client.py              # Cliente Kafka
│   └── config.py                    # Configuración compartida
├── infra/                           # Configuración de infraestructura
│   ├── docker-compose.yml           # Desarrollo con hot reload
│   ├── docker-compose.prod.yml      # Producción
│   ├── nginx.conf                   # Configuración Nginx
│   └── README.md                    # Documentación de infraestructura
├── docs/                            # Documentación
├── Makefile                         # Comandos de desarrollo
├── pyproject.toml                   # Configuración de herramientas
├── .gitignore                       # Archivos a ignorar
└── README.md

🛠️ Herramientas de Desarrollo

Makefile

El proyecto incluye un Makefile completo con comandos útiles:

# Comandos principales
make help              # Ver todos los comandos
make build             # Construir imágenes Docker
make up                # Levantar servicios
make down              # Detener servicios
make logs              # Ver logs
make format            # Formatear código con ruff
make lint              # Lintear código
make clean             # Limpiar archivos temporales

# Comandos de desarrollo
make dev               # Modo desarrollo con logs

# Comandos específicos por servicio
make build-inventory   # Construir solo inventory-service
make shell-inventory   # Shell en inventory-service
make logs-service SERVICE=inventory-service  # Logs de un servicio

# Comandos de base de datos
make db-mongo          # Conectar a MongoDB
make db-postgres       # Conectar a PostgreSQL
make backup            # Crear backup de BD

# Comandos de monitoreo
make health            # Verificar health de servicios
make kafka-topics      # Listar topics de Kafka
make benchmark         # Ejecutar benchmarks

Herramientas de Código

• Ruff: Formateo y linting de código Python
• pyproject.toml: Configuración centralizada de herramientas
• Git hooks: Para formateo automático (opcional)

Configuración de Ruff

El proyecto usa ruff para formateo y linting con configuración en pyproject.toml:

# Formatear código
make format

# Lintear código
make lint

# Formatear y lintear
make format-lint

🚧 Roadmap y TODOs

Próximos Microservicios

• payments-service - Procesamiento de pagos con Stripe/PayPal
• notifications-service - Envío de emails y notificaciones push

Mejoras Planificadas

• Autenticación y Autorización - JWT tokens y roles
• API Gateway - Nginx configurado como reverse proxy
• Monitoreo - Prometheus y Grafana
• Logging Centralizado - ELK Stack
• Tests Unitarios - pytest con coverage
• Tests de Integración - TestContainers
• CI/CD Pipeline - GitHub Actions
• Documentación API - OpenAPI/Swagger mejorado
• Rate Limiting - Protección contra abuso
• Circuit Breaker - Patrón de resiliencia