Saltar a contenido

🏗️ Patrones Arquitectónicos para Proyectos de Software

Esta guía presenta diferentes patrones arquitectónicos que puedes aplicar en tus proyectos, con ejemplos específicos para cada tecnología y sus mejores prácticas.

📋 Índice de Patrones

  1. MVC (Model-View-Controller)
  2. Arquitectura Hexagonal (Ports & Adapters)
  3. Clean Architecture
  4. Arquitectura por Capas (Layered)
  5. CQRS (Command Query Responsibility Segregation)
  6. Event-Driven Architecture
  7. Microservicios

MVC (Model-View-Controller)

📖 Descripción

Patrón que separa la aplicación en tres componentes principales: Modelo (datos), Vista (interfaz) y Controlador (lógica de control).

🎯 Cuándo Usar

  • Aplicaciones web tradicionales
  • APIs REST simples
  • Proyectos con equipos pequeños
  • Aplicaciones CRUD básicas

📁 Estructura por Tecnología

.NET Web API (MVC)

MyApp.WebApi/
├── Controllers/
│   ├── BaseController.cs
│   ├── UsersController.cs
│   └── ProductsController.cs
├── Models/
│   ├── User.cs
│   ├── Product.cs
│   ├── ViewModels/
│   │   ├── UserViewModel.cs
│   │   └── ProductViewModel.cs
│   └── DTOs/
│       ├── CreateUserDto.cs
│       └── UpdateUserDto.cs
├── Views/ (si usas Razor)
│   ├── Users/
│   └── Products/
├── Services/
│   ├── IUserService.cs
│   └── UserService.cs
├── Data/
│   ├── ApplicationDbContext.cs
│   └── Repositories/
│       ├── IUserRepository.cs
│       └── UserRepository.cs
└── Program.cs

Java Spring Boot (MVC)

src/main/java/com/myapp/
├── controller/
│   ├── BaseController.java
│   ├── UserController.java
│   └── ProductController.java
├── model/
│   ├── entity/
│   │   ├── User.java
│   │   └── Product.java
│   └── dto/
│       ├── UserDto.java
│       └── ProductDto.java
├── service/
│   ├── UserService.java
│   └── ProductService.java
├── repository/
│   ├── UserRepository.java
│   └── ProductRepository.java
├── config/
│   └── DatabaseConfig.java
└── MyAppApplication.java

Node.js/Express (MVC)

src/
├── controllers/
│   ├── baseController.js
│   ├── userController.js
│   └── productController.js
├── models/
│   ├── User.js
│   ├── Product.js
│   └── index.js
├── views/ (si usas templates)
│   ├── users/
│   └── products/
├── services/
│   ├── userService.js
│   └── productService.js
├── routes/
│   ├── userRoutes.js
│   └── productRoutes.js
├── middleware/
│   └── authMiddleware.js
└── app.js

✅ Mejores Prácticas MVC

Controladores

// .NET - Controlador delgado
[ApiController]
[Route("api/[controller]")]
public class UsersController : BaseController
{
    private readonly IUserService _userService;

    public UsersController(IUserService userService)
    {
        _userService = userService;
    }

    [HttpGet("{id}")]
    public async Task<ActionResult<UserDto>> GetUser(int id)
    {
        var user = await _userService.GetUserByIdAsync(id);
        return user != null ? Ok(user) : NotFound();
    }

    [HttpPost]
    public async Task<ActionResult<UserDto>> CreateUser(CreateUserDto dto)
    {
        var user = await _userService.CreateUserAsync(dto);
        return CreatedAtAction(nameof(GetUser), new { id = user.Id }, user);
    }
}

Servicios

// .NET - Lógica de negocio en servicios
public class UserService : IUserService
{
    private readonly IUserRepository _repository;
    private readonly IMapper _mapper;

    public UserService(IUserRepository repository, IMapper mapper)
    {
        _repository = repository;
        _mapper = mapper;
    }

    public async Task<UserDto> CreateUserAsync(CreateUserDto dto)
    {
        // Validaciones de negocio
        if (await _repository.ExistsByEmailAsync(dto.Email))
            throw new BusinessException("Email already exists");

        var user = _mapper.Map<User>(dto);
        user.CreatedAt = DateTime.UtcNow;

        await _repository.AddAsync(user);
        return _mapper.Map<UserDto>(user);
    }
}

Arquitectura Hexagonal (Ports & Adapters)

📖 Descripción

Aísla la lógica de negocio del mundo exterior mediante puertos (interfaces) y adaptadores (implementaciones).

🎯 Cuándo Usar

  • Aplicaciones complejas con múltiples integraciones
  • Sistemas que requieren alta testabilidad
  • Proyectos con requisitos de escalabilidad
  • Cuando necesitas independencia de frameworks

📁 Estructura por Tecnología

.NET (Arquitectura Hexagonal)

MyApp/
├── MyApp.Domain/                    # Núcleo de la aplicación
│   ├── Entities/
│   │   ├── User.cs
│   │   └── Product.cs
│   ├── ValueObjects/
│   │   ├── Email.cs
│   │   └── Money.cs
│   ├── Ports/                      # Interfaces (Puertos)
│   │   ├── IUserRepository.cs
│   │   ├── IEmailService.cs
│   │   └── IPaymentGateway.cs
│   └── Services/                   # Servicios de dominio
│       ├── UserDomainService.cs
│       └── OrderDomainService.cs
├── MyApp.Application/              # Casos de uso
│   ├── UseCases/
│   │   ├── CreateUser/
│   │   │   ├── CreateUserCommand.cs
│   │   │   ├── CreateUserHandler.cs
│   │   │   └── CreateUserValidator.cs
│   │   └── GetUser/
│   │       ├── GetUserQuery.cs
│   │       └── GetUserHandler.cs
│   └── DTOs/
│       ├── UserDto.cs
│       └── ProductDto.cs
├── MyApp.Infrastructure/           # Adaptadores
│   ├── Persistence/
│   │   ├── ApplicationDbContext.cs
│   │   ├── Repositories/
│   │   │   ├── UserRepository.cs   # Implementa IUserRepository
│   │   │   └── ProductRepository.cs
│   │   └── Configurations/
│   │       └── UserConfiguration.cs
│   ├── ExternalServices/
│   │   ├── EmailService.cs         # Implementa IEmailService
│   │   └── PaymentGateway.cs       # Implementa IPaymentGateway
│   └── Messaging/
│       └── EventBus.cs
└── MyApp.WebApi/                   # Adaptador de entrada
    ├── Controllers/
    │   ├── UsersController.cs
    │   └── ProductsController.cs
    ├── Middleware/
    │   └── ExceptionMiddleware.cs
    └── Program.cs

Java (Arquitectura Hexagonal)

src/main/java/com/myapp/
├── domain/                         # Núcleo
│   ├── model/
│   │   ├── User.java
│   │   └── Product.java
│   ├── port/
│   │   ├── in/                     # Puertos de entrada
│   │   │   ├── CreateUserUseCase.java
│   │   │   └── GetUserUseCase.java
│   │   └── out/                    # Puertos de salida
│   │       ├── UserRepository.java
│   │       └── EmailService.java
│   └── service/
│       ├── UserService.java        # Implementa casos de uso
│       └── ProductService.java
├── infrastructure/                 # Adaptadores
│   ├── persistence/
│   │   ├── UserJpaRepository.java  # Implementa UserRepository
│   │   └── UserEntity.java
│   ├── messaging/
│   │   └── EmailServiceImpl.java   # Implementa EmailService
│   └── configuration/
│       └── BeanConfiguration.java
└── application/                    # Adaptador de entrada
    ├── controller/
    │   ├── UserController.java
    │   └── ProductController.java
    └── MyAppApplication.java

✅ Mejores Prácticas Hexagonal

Definición de Puertos

// Puerto de salida (Domain)
public interface IUserRepository
{
    Task<User> GetByIdAsync(UserId id);
    Task<User> GetByEmailAsync(Email email);
    Task SaveAsync(User user);
    Task<bool> ExistsByEmailAsync(Email email);
}

// Puerto de entrada (Application)
public interface ICreateUserUseCase
{
    Task<UserDto> ExecuteAsync(CreateUserCommand command);
}

Implementación de Casos de Uso

// Application Layer
public class CreateUserHandler : ICreateUserUseCase
{
    private readonly IUserRepository _userRepository;
    private readonly IEmailService _emailService;
    private readonly IDomainEventDispatcher _eventDispatcher;

    public CreateUserHandler(
        IUserRepository userRepository,
        IEmailService emailService,
        IDomainEventDispatcher eventDispatcher)
    {
        _userRepository = userRepository;
        _emailService = emailService;
        _eventDispatcher = eventDispatcher;
    }

    public async Task<UserDto> ExecuteAsync(CreateUserCommand command)
    {
        // Validar reglas de negocio
        var email = new Email(command.Email);
        if (await _userRepository.ExistsByEmailAsync(email))
            throw new DomainException("Email already exists");

        // Crear entidad de dominio
        var user = User.Create(
            command.FirstName,
            command.LastName,
            email);

        // Persistir
        await _userRepository.SaveAsync(user);

        // Enviar eventos de dominio
        await _eventDispatcher.DispatchAsync(user.DomainEvents);

        // Enviar email de bienvenida
        await _emailService.SendWelcomeEmailAsync(user.Email);

        return UserDto.FromDomain(user);
    }
}

Clean Architecture

📖 Descripción

Arquitectura en capas concéntricas donde las dependencias apuntan hacia adentro, manteniendo el núcleo independiente de frameworks y tecnologías externas.

🎯 Cuándo Usar

  • Aplicaciones empresariales complejas
  • Sistemas con ciclo de vida largo
  • Proyectos que requieren alta mantenibilidad
  • Aplicaciones con múltiples interfaces (web, mobile, desktop)

📁 Estructura por Tecnología

.NET (Clean Architecture)

MyApp/
├── MyApp.Domain/                   # Capa más interna
│   ├── Entities/
│   │   ├── BaseEntity.cs
│   │   ├── User.cs
│   │   └── Product.cs
│   ├── ValueObjects/
│   │   ├── Email.cs
│   │   ├── Money.cs
│   │   └── Address.cs
│   ├── Enums/
│   │   ├── UserStatus.cs
│   │   └── OrderStatus.cs
│   ├── Events/
│   │   ├── UserCreatedEvent.cs
│   │   └── OrderPlacedEvent.cs
│   ├── Exceptions/
│   │   ├── DomainException.cs
│   │   └── BusinessRuleException.cs
│   └── Interfaces/
│       └── IDomainEventDispatcher.cs
├── MyApp.Application/              # Casos de uso
│   ├── Common/
│   │   ├── Interfaces/
│   │   │   ├── IApplicationDbContext.cs
│   │   │   ├── IEmailService.cs
│   │   │   └── ICurrentUserService.cs
│   │   ├── Models/
│   │   │   ├── Result.cs
│   │   │   └── PaginatedList.cs
│   │   └── Behaviors/
│   │       ├── ValidationBehavior.cs
│   │       └── LoggingBehavior.cs
│   ├── Users/
│   │   ├── Commands/
│   │   │   ├── CreateUser/
│   │   │   │   ├── CreateUserCommand.cs
│   │   │   │   ├── CreateUserCommandHandler.cs
│   │   │   │   └── CreateUserCommandValidator.cs
│   │   │   └── UpdateUser/
│   │   │       ├── UpdateUserCommand.cs
│   │   │       └── UpdateUserCommandHandler.cs
│   │   ├── Queries/
│   │   │   ├── GetUser/
│   │   │   │   ├── GetUserQuery.cs
│   │   │   │   └── GetUserQueryHandler.cs
│   │   │   └── GetUsers/
│   │   │       ├── GetUsersQuery.cs
│   │   │       └── GetUsersQueryHandler.cs
│   │   └── DTOs/
│   │       ├── UserDto.cs
│   │       └── UserListDto.cs
│   └── Products/
│       ├── Commands/
│       ├── Queries/
│       └── DTOs/
├── MyApp.Infrastructure/           # Implementaciones externas
│   ├── Persistence/
│   │   ├── ApplicationDbContext.cs
│   │   ├── Repositories/
│   │   │   ├── UserRepository.cs
│   │   │   └── ProductRepository.cs
│   │   ├── Configurations/
│   │   │   ├── UserConfiguration.cs
│   │   │   └── ProductConfiguration.cs
│   │   └── Migrations/
│   ├── Services/
│   │   ├── EmailService.cs
│   │   ├── CurrentUserService.cs
│   │   └── DateTimeService.cs
│   ├── Identity/
│   │   ├── IdentityService.cs
│   │   └── ApplicationUser.cs
│   └── ExternalServices/
│       ├── PaymentGateway.cs
│       └── NotificationService.cs
└── MyApp.WebApi/                   # Capa de presentación
    ├── Controllers/
    │   ├── BaseController.cs
    │   ├── UsersController.cs
    │   └── ProductsController.cs
    ├── Filters/
    │   ├── ApiExceptionFilterAttribute.cs
    │   └── ValidationFilterAttribute.cs
    ├── Services/
    │   └── CurrentUserService.cs
    ├── Extensions/
    │   ├── ServiceCollectionExtensions.cs
    │   └── ApplicationBuilderExtensions.cs
    └── Program.cs

Python (Clean Architecture)

myapp/
├── domain/                         # Capa de dominio
│   ├── entities/
│   │   ├── __init__.py
│   │   ├── base_entity.py
│   │   ├── user.py
│   │   └── product.py
│   ├── value_objects/
│   │   ├── __init__.py
│   │   ├── email.py
│   │   └── money.py
│   ├── events/
│   │   ├── __init__.py
│   │   ├── user_created.py
│   │   └── order_placed.py
│   └── exceptions/
│       ├── __init__.py
│       ├── domain_exception.py
│       └── business_rule_exception.py
├── application/                    # Casos de uso
│   ├── common/
│   │   ├── __init__.py
│   │   ├── interfaces/
│   │   │   ├── __init__.py
│   │   │   ├── repository.py
│   │   │   ├── email_service.py
│   │   │   └── unit_of_work.py
│   │   └── models/
│   │       ├── __init__.py
│   │       └── result.py
│   ├── users/
│   │   ├── __init__.py
│   │   ├── commands/
│   │   │   ├── __init__.py
│   │   │   ├── create_user.py
│   │   │   └── update_user.py
│   │   ├── queries/
│   │   │   ├── __init__.py
│   │   │   ├── get_user.py
│   │   │   └── get_users.py
│   │   └── dtos/
│   │       ├── __init__.py
│   │       └── user_dto.py
│   └── products/
│       ├── commands/
│       ├── queries/
│       └── dtos/
├── infrastructure/                 # Implementaciones
│   ├── __init__.py
│   ├── persistence/
│   │   ├── __init__.py
│   │   ├── database.py
│   │   ├── repositories/
│   │   │   ├── __init__.py
│   │   │   ├── user_repository.py
│   │   │   └── product_repository.py
│   │   └── models/
│   │       ├── __init__.py
│   │       ├── user_model.py
│   │       └── product_model.py
│   ├── services/
│   │   ├── __init__.py
│   │   ├── email_service.py
│   │   └── notification_service.py
│   └── external/
│       ├── __init__.py
│       └── payment_gateway.py
└── presentation/                   # Capa de presentación
    ├── __init__.py
    ├── api/
    │   ├── __init__.py
    │   ├── dependencies.py
    │   ├── routers/
    │   │   ├── __init__.py
    │   │   ├── users.py
    │   │   └── products.py
    │   └── middleware/
    │       ├── __init__.py
    │       └── exception_handler.py
    └── main.py

✅ Mejores Prácticas Clean Architecture

Entidades de Dominio

// Domain Layer - Entidad rica en comportamiento
public class User : BaseEntity
{
    private readonly List<DomainEvent> _domainEvents = new();

    public string FirstName { get; private set; }
    public string LastName { get; private set; }
    public Email Email { get; private set; }
    public UserStatus Status { get; private set; }

    private User() { } // Para EF Core

    private User(string firstName, string lastName, Email email)
    {
        FirstName = firstName;
        LastName = lastName;
        Email = email;
        Status = UserStatus.Active;
        CreatedAt = DateTime.UtcNow;

        AddDomainEvent(new UserCreatedEvent(this));
    }

    public static User Create(string firstName, string lastName, string email)
    {
        var emailVO = new Email(email);
        return new User(firstName, lastName, emailVO);
    }

    public void UpdateEmail(string newEmail)
    {
        var emailVO = new Email(newEmail);
        if (Email.Equals(emailVO))
            return;

        Email = emailVO;
        AddDomainEvent(new UserEmailChangedEvent(this, emailVO));
    }

    public void Deactivate()
    {
        if (Status == UserStatus.Inactive)
            throw new DomainException("User is already inactive");

        Status = UserStatus.Inactive;
        AddDomainEvent(new UserDeactivatedEvent(this));
    }

    private void AddDomainEvent(DomainEvent domainEvent)
    {
        _domainEvents.Add(domainEvent);
    }

    public IReadOnlyCollection<DomainEvent> DomainEvents => _domainEvents.AsReadOnly();

    public void ClearDomainEvents()
    {
        _domainEvents.Clear();
    }
}

Casos de Uso con CQRS

// Application Layer - Command Handler
public class CreateUserCommandHandler : IRequestHandler<CreateUserCommand, Result<UserDto>>
{
    private readonly IApplicationDbContext _context;
    private readonly IEmailService _emailService;
    private readonly ILogger<CreateUserCommandHandler> _logger;

    public CreateUserCommandHandler(
        IApplicationDbContext context,
        IEmailService emailService,
        ILogger<CreateUserCommandHandler> logger)
    {
        _context = context;
        _emailService = emailService;
        _logger = logger;
    }

    public async Task<Result<UserDto>> Handle(CreateUserCommand request, CancellationToken cancellationToken)
    {
        try
        {
            // Verificar si el email ya existe
            var existingUser = await _context.Users
                .FirstOrDefaultAsync(u => u.Email.Value == request.Email, cancellationToken);

            if (existingUser != null)
                return Result<UserDto>.Failure("Email already exists");

            // Crear nueva entidad
            var user = User.Create(request.FirstName, request.LastName, request.Email);

            // Persistir
            _context.Users.Add(user);
            await _context.SaveChangesAsync(cancellationToken);

            // Enviar email de bienvenida
            await _emailService.SendWelcomeEmailAsync(user.Email.Value, user.FirstName);

            _logger.LogInformation("User created successfully with ID: {UserId}", user.Id);

            return Result<UserDto>.Success(UserDto.FromDomain(user));
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Error creating user with email: {Email}", request.Email);
            return Result<UserDto>.Failure("An error occurred while creating the user");
        }
    }
}

Arquitectura por Capas (Layered)

📖 Descripción

Organiza el código en capas horizontales donde cada capa solo puede comunicarse con la capa inmediatamente inferior.

🎯 Cuándo Usar

  • Aplicaciones empresariales tradicionales
  • Sistemas con separación clara de responsabilidades
  • Proyectos con equipos especializados por capa
  • Aplicaciones con requisitos de auditoría

📁 Estructura por Tecnología

Java Spring Boot (Capas)

src/main/java/com/myapp/
├── presentation/                   # Capa de Presentación
│   ├── controller/
│   │   ├── UserController.java
│   │   └── ProductController.java
│   ├── dto/
│   │   ├── request/
│   │   │   ├── CreateUserRequest.java
│   │   │   └── UpdateUserRequest.java
│   │   └── response/
│   │       ├── UserResponse.java
│   │       └── ProductResponse.java
│   └── mapper/
│       ├── UserMapper.java
│       └── ProductMapper.java
├── business/                       # Capa de Negocio
│   ├── service/
│   │   ├── UserService.java
│   │   ├── ProductService.java
│   │   └── OrderService.java
│   ├── validator/
│   │   ├── UserValidator.java
│   │   └── ProductValidator.java
│   └── exception/
│       ├── BusinessException.java
│       └── ValidationException.java
├── persistence/                    # Capa de Persistencia
│   ├── repository/
│   │   ├── UserRepository.java
│   │   └── ProductRepository.java
│   ├── entity/
│   │   ├── UserEntity.java
│   │   └── ProductEntity.java
│   └── config/
│       └── DatabaseConfig.java
└── infrastructure/                 # Capa de Infraestructura
    ├── security/
    │   ├── SecurityConfig.java
    │   └── JwtTokenProvider.java
    ├── messaging/
    │   ├── EmailService.java
    │   └── NotificationService.java
    └── external/
        ├── PaymentGateway.java
        └── ExternalApiClient.java

Node.js (Capas)

src/
├── presentation/                   # Capa de Presentación
│   ├── controllers/
│   │   ├── userController.js
│   │   └── productController.js
│   ├── middleware/
│   │   ├── authMiddleware.js
│   │   ├── validationMiddleware.js
│   │   └── errorMiddleware.js
│   ├── routes/
│   │   ├── userRoutes.js
│   │   └── productRoutes.js
│   └── validators/
│       ├── userValidator.js
│       └── productValidator.js
├── business/                       # Capa de Negocio
│   ├── services/
│   │   ├── userService.js
│   │   ├── productService.js
│   │   └── orderService.js
│   ├── models/
│   │   ├── User.js
│   │   ├── Product.js
│   │   └── Order.js
│   └── exceptions/
│       ├── BusinessError.js
│       └── ValidationError.js
├── persistence/                    # Capa de Persistencia
│   ├── repositories/
│   │   ├── userRepository.js
│   │   ├── productRepository.js
│   │   └── baseRepository.js
│   ├── entities/
│   │   ├── userEntity.js
│   │   └── productEntity.js
│   └── database/
│       ├── connection.js
│       └── migrations/
└── infrastructure/                 # Capa de Infraestructura
    ├── security/
    │   ├── jwtService.js
    │   └── encryptionService.js
    ├── messaging/
    │   ├── emailService.js
    │   └── smsService.js
    └── external/
        ├── paymentGateway.js
        └── externalApiClient.js

✅ Mejores Prácticas por Capas

Capa de Presentación

// Node.js - Controlador delgado
class UserController {
    constructor(userService) {
        this.userService = userService;
    }

    async createUser(req, res, next) {
        try {
            // Solo manejo de HTTP, delegación a capa de negocio
            const userData = req.body;
            const user = await this.userService.createUser(userData);

            res.status(201).json({
                success: true,
                data: user,
                message: 'User created successfully'
            });
        } catch (error) {
            next(error); // Delegar manejo de errores al middleware
        }
    }

    async getUsers(req, res, next) {
        try {
            const { page = 1, limit = 10, search } = req.query;
            const users = await this.userService.getUsers({ page, limit, search });

            res.json({
                success: true,
                data: users,
                pagination: {
                    page: parseInt(page),
                    limit: parseInt(limit),
                    total: users.total
                }
            });
        } catch (error) {
            next(error);
        }
    }
}

Capa de Negocio

// Node.js - Servicio con lógica de negocio
class UserService {
    constructor(userRepository, emailService, validationService) {
        this.userRepository = userRepository;
        this.emailService = emailService;
        this.validationService = validationService;
    }

    async createUser(userData) {
        // Validaciones de negocio
        await this.validationService.validateUserData(userData);

        // Verificar reglas de negocio
        const existingUser = await this.userRepository.findByEmail(userData.email);
        if (existingUser) {
            throw new BusinessError('Email already exists', 'DUPLICATE_EMAIL');
        }

        // Crear usuario
        const user = new User({
            ...userData,
            createdAt: new Date(),
            status: 'ACTIVE'
        });

        // Persistir
        const savedUser = await this.userRepository.save(user);

        // Procesos adicionales
        await this.emailService.sendWelcomeEmail(savedUser.email, savedUser.name);

        return savedUser.toDTO();
    }

    async getUsers({ page, limit, search }) {
        // Lógica de búsqueda y paginación
        const filters = {};
        if (search) {
            filters.name = { $regex: search, $options: 'i' };
        }

        const users = await this.userRepository.findPaginated(filters, page, limit);
        return {
            users: users.data.map(user => user.toDTO()),
            total: users.total,
            page,
            limit
        };
    }
}

Capa de Persistencia

// Node.js - Repositorio
class UserRepository extends BaseRepository {
    constructor(database) {
        super(database, 'users');
    }

    async findByEmail(email) {
        return await this.collection.findOne({ email });
    }

    async findPaginated(filters, page, limit) {
        const skip = (page - 1) * limit;

        const [data, total] = await Promise.all([
            this.collection.find(filters).skip(skip).limit(limit).toArray(),
            this.collection.countDocuments(filters)
        ]);

        return { data, total };
    }

    async save(user) {
        if (user.id) {
            await this.collection.updateOne(
                { _id: user.id },
                { $set: user.toDocument() }
            );
        } else {
            const result = await this.collection.insertOne(user.toDocument());
            user.id = result.insertedId;
        }
        return user;
    }
}

CQRS (Command Query Responsibility Segregation)

📖 Descripción

Separa las operaciones de lectura (queries) de las operaciones de escritura (commands), permitiendo optimizar cada una independientemente.

🎯 Cuándo Usar

  • Sistemas con alta carga de lectura vs escritura
  • Aplicaciones que requieren diferentes modelos de datos para lectura y escritura
  • Sistemas con requisitos de escalabilidad complejos
  • Aplicaciones con Event Sourcing

📁 Estructura por Tecnología

.NET (CQRS con MediatR)

MyApp/
├── MyApp.Application/
│   ├── Commands/                   # Operaciones de escritura
│   │   ├── Users/
│   │   │   ├── CreateUser/
│   │   │   │   ├── CreateUserCommand.cs
│   │   │   │   ├── CreateUserCommandHandler.cs
│   │   │   │   └── CreateUserCommandValidator.cs
│   │   │   ├── UpdateUser/
│   │   │   │   ├── UpdateUserCommand.cs
│   │   │   │   └── UpdateUserCommandHandler.cs
│   │   │   └── DeleteUser/
│   │   │       ├── DeleteUserCommand.cs
│   │   │       └── DeleteUserCommandHandler.cs
│   │   └── Products/
│   │       ├── CreateProduct/
│   │       ├── UpdateProduct/
│   │       └── DeleteProduct/
│   ├── Queries/                    # Operaciones de lectura
│   │   ├── Users/
│   │   │   ├── GetUser/
│   │   │   │   ├── GetUserQuery.cs
│   │   │   │   ├── GetUserQueryHandler.cs
│   │   │   │   └── UserDto.cs
│   │   │   ├── GetUsers/
│   │   │   │   ├── GetUsersQuery.cs
│   │   │   │   ├── GetUsersQueryHandler.cs
│   │   │   │   └── UserListDto.cs
│   │   │   └── SearchUsers/
│   │   │       ├── SearchUsersQuery.cs
│   │   │       └── SearchUsersQueryHandler.cs
│   │   └── Products/
│   │       ├── GetProduct/
│   │       ├── GetProducts/
│   │       └── SearchProducts/
│   ├── Common/
│   │   ├── Interfaces/
│   │   │   ├── ICommand.cs
│   │   │   ├── IQuery.cs
│   │   │   ├── ICommandHandler.cs
│   │   │   └── IQueryHandler.cs
│   │   └── Behaviors/
│   │       ├── ValidationBehavior.cs
│   │       ├── LoggingBehavior.cs
│   │       └── PerformanceBehavior.cs
│   └── Events/
│       ├── UserCreatedEvent.cs
│       ├── UserUpdatedEvent.cs
│       └── EventHandlers/
│           ├── UserCreatedEventHandler.cs
│           └── UserUpdatedEventHandler.cs
├── MyApp.Infrastructure/
│   ├── Persistence/
│   │   ├── Write/                  # Base de datos de escritura
│   │   │   ├── WriteDbContext.cs
│   │   │   └── Repositories/
│   │   │       ├── UserWriteRepository.cs
│   │   │       └── ProductWriteRepository.cs
│   │   └── Read/                   # Base de datos de lectura
│   │       ├── ReadDbContext.cs
│   │       └── Repositories/
│   │           ├── UserReadRepository.cs
│   │           └── ProductReadRepository.cs
│   └── EventStore/
│       ├── EventStoreRepository.cs
│       └── EventProjections/
│           ├── UserProjection.cs
│           └── ProductProjection.cs
└── MyApp.WebApi/
    ├── Controllers/
    │   ├── UsersController.cs      # Maneja Commands y Queries
    │   └── ProductsController.cs
    └── Program.cs

Python (CQRS)

myapp/
├── application/
│   ├── commands/                   # Operaciones de escritura
│   │   ├── __init__.py
│   │   ├── base.py
│   │   ├── users/
│   │   │   ├── __init__.py
│   │   │   ├── create_user.py
│   │   │   ├── update_user.py
│   │   │   └── delete_user.py
│   │   └── products/
│   │       ├── create_product.py
│   │       ├── update_product.py
│   │       └── delete_product.py
│   ├── queries/                    # Operaciones de lectura
│   │   ├── __init__.py
│   │   ├── base.py
│   │   ├── users/
│   │   │   ├── __init__.py
│   │   │   ├── get_user.py
│   │   │   ├── get_users.py
│   │   │   └── search_users.py
│   │   └── products/
│   │       ├── get_product.py
│   │       ├── get_products.py
│   │       └── search_products.py
│   ├── handlers/
│   │   ├── __init__.py
│   │   ├── command_handlers.py
│   │   ├── query_handlers.py
│   │   └── event_handlers.py
│   └── events/
│       ├── __init__.py
│       ├── user_events.py
│       └── product_events.py
├── infrastructure/
│   ├── persistence/
│   │   ├── write/                  # Base de datos de escritura
│   │   │   ├── __init__.py
│   │   │   ├── write_db.py
│   │   │   └── repositories/
│   │   │       ├── user_write_repo.py
│   │   │       └── product_write_repo.py
│   │   └── read/                   # Base de datos de lectura
│   │       ├── __init__.py
│   │       ├── read_db.py
│   │       └── repositories/
│   │           ├── user_read_repo.py
│   │           └── product_read_repo.py
│   └── event_store/
│       ├── __init__.py
│       ├── event_store.py
│       └── projections/
│           ├── user_projection.py
│           └── product_projection.py
└── presentation/
    ├── api/
    │   ├── routers/
    │   │   ├── users.py            # Maneja Commands y Queries
    │   │   └── products.py
    │   └── dependencies.py
    └── main.py

✅ Mejores Prácticas CQRS

Commands (Escritura)

// Command
public record CreateUserCommand(
    string FirstName,
    string LastName,
    string Email) : IRequest<Result<int>>;

// Command Handler
public class CreateUserCommandHandler : IRequestHandler<CreateUserCommand, Result<int>>
{
    private readonly IWriteDbContext _writeContext;
    private readonly IEventBus _eventBus;
    private readonly ILogger<CreateUserCommandHandler> _logger;

    public CreateUserCommandHandler(
        IWriteDbContext writeContext,
        IEventBus eventBus,
        ILogger<CreateUserCommandHandler> logger)
    {
        _writeContext = writeContext;
        _eventBus = eventBus;
        _logger = logger;
    }

    public async Task<Result<int>> Handle(CreateUserCommand request, CancellationToken cancellationToken)
    {
        try
        {
            // Validar reglas de negocio
            var existingUser = await _writeContext.Users
                .FirstOrDefaultAsync(u => u.Email == request.Email, cancellationToken);

            if (existingUser != null)
                return Result<int>.Failure("Email already exists");

            // Crear entidad
            var user = new User
            {
                FirstName = request.FirstName,
                LastName = request.LastName,
                Email = request.Email,
                CreatedAt = DateTime.UtcNow,
                Status = UserStatus.Active
            };

            // Persistir en base de escritura
            _writeContext.Users.Add(user);
            await _writeContext.SaveChangesAsync(cancellationToken);

            // Publicar evento para actualizar base de lectura
            await _eventBus.PublishAsync(new UserCreatedEvent
            {
                UserId = user.Id,
                FirstName = user.FirstName,
                LastName = user.LastName,
                Email = user.Email,
                CreatedAt = user.CreatedAt
            }, cancellationToken);

            _logger.LogInformation("User created with ID: {UserId}", user.Id);

            return Result<int>.Success(user.Id);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Error creating user");
            return Result<int>.Failure("An error occurred while creating the user");
        }
    }
}

Queries (Lectura)

// Query
public record GetUsersQuery(
    int Page = 1,
    int PageSize = 10,
    string? Search = null) : IRequest<Result<PagedList<UserListDto>>>;

// Query Handler
public class GetUsersQueryHandler : IRequestHandler<GetUsersQuery, Result<PagedList<UserListDto>>>
{
    private readonly IReadDbContext _readContext;
    private readonly IMemoryCache _cache;
    private readonly ILogger<GetUsersQueryHandler> _logger;

    public GetUsersQueryHandler(
        IReadDbContext readContext,
        IMemoryCache cache,
        ILogger<GetUsersQueryHandler> logger)
    {
        _readContext = readContext;
        _cache = cache;
        _logger = logger;
    }

    public async Task<Result<PagedList<UserListDto>>> Handle(GetUsersQuery request, CancellationToken cancellationToken)
    {
        try
        {
            var cacheKey = $"users_page_{request.Page}_size_{request.PageSize}_search_{request.Search}";

            if (_cache.TryGetValue(cacheKey, out PagedList<UserListDto>? cachedResult))
            {
                _logger.LogDebug("Returning cached users for page {Page}", request.Page);
                return Result<PagedList<UserListDto>>.Success(cachedResult!);
            }

            // Query optimizada para lectura
            var query = _readContext.UserReadModels.AsQueryable();

            if (!string.IsNullOrEmpty(request.Search))
            {
                query = query.Where(u => 
                    u.FullName.Contains(request.Search) || 
                    u.Email.Contains(request.Search));
            }

            var totalCount = await query.CountAsync(cancellationToken);

            var users = await query
                .OrderBy(u => u.FullName)
                .Skip((request.Page - 1) * request.PageSize)
                .Take(request.PageSize)
                .Select(u => new UserListDto
                {
                    Id = u.Id,
                    FullName = u.FullName,
                    Email = u.Email,
                    Status = u.Status,
                    CreatedAt = u.CreatedAt
                })
                .ToListAsync(cancellationToken);

            var result = new PagedList<UserListDto>(users, totalCount, request.Page, request.PageSize);

            // Cache por 5 minutos
            _cache.Set(cacheKey, result, TimeSpan.FromMinutes(5));

            return Result<PagedList<UserListDto>>.Success(result);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Error retrieving users");
            return Result<PagedList<UserListDto>>.Failure("An error occurred while retrieving users");
        }
    }
}

Event Handlers para Sincronización

// Event Handler para mantener sincronizada la base de lectura
public class UserCreatedEventHandler : INotificationHandler<UserCreatedEvent>
{
    private readonly IReadDbContext _readContext;
    private readonly ILogger<UserCreatedEventHandler> _logger;

    public UserCreatedEventHandler(
        IReadDbContext readContext,
        ILogger<UserCreatedEventHandler> logger)
    {
        _readContext = readContext;
        _logger = logger;
    }

    public async Task Handle(UserCreatedEvent notification, CancellationToken cancellationToken)
    {
        try
        {
            // Crear modelo optimizado para lectura
            var userReadModel = new UserReadModel
            {
                Id = notification.UserId,
                FullName = $"{notification.FirstName} {notification.LastName}",
                Email = notification.Email,
                Status = "Active",
                CreatedAt = notification.CreatedAt,
                // Campos adicionales optimizados para queries
                SearchText = $"{notification.FirstName} {notification.LastName} {notification.Email}".ToLower()
            };

            _readContext.UserReadModels.Add(userReadModel);
            await _readContext.SaveChangesAsync(cancellationToken);

            _logger.LogInformation("User read model created for user ID: {UserId}", notification.UserId);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Error creating user read model for user ID: {UserId}", notification.UserId);
            throw; // Re-throw para que el event bus pueda manejar el retry
        }
    }
}

Event-Driven Architecture

📖 Descripción

Arquitectura basada en la producción, detección y reacción a eventos, promoviendo el desacoplamiento entre componentes.

🎯 Cuándo Usar

  • Sistemas distribuidos complejos
  • Aplicaciones que requieren alta escalabilidad
  • Microservicios que necesitan comunicación asíncrona
  • Sistemas con workflows complejos

📁 Estructura por Tecnología

.NET (Event-Driven)

MyApp/
├── MyApp.Events/                   # Definiciones de eventos
│   ├── Common/
│   │   ├── IEvent.cs
│   │   ├── IDomainEvent.cs
│   │   └── IIntegrationEvent.cs
│   ├── Domain/
│   │   ├── UserEvents/
│   │   │   ├── UserCreatedEvent.cs
│   │   │   ├── UserUpdatedEvent.cs
│   │   │   └── UserDeletedEvent.cs
│   │   └── OrderEvents/
│   │       ├── OrderPlacedEvent.cs
│   │       ├── OrderConfirmedEvent.cs
│   │       └── OrderCancelledEvent.cs
│   └── Integration/
│       ├── UserRegisteredIntegrationEvent.cs
│       ├── OrderProcessedIntegrationEvent.cs
│       └── PaymentCompletedIntegrationEvent.cs
├── MyApp.EventHandlers/            # Manejadores de eventos
│   ├── Domain/
│   │   ├── UserEventHandlers/
│   │   │   ├── UserCreatedEventHandler.cs
│   │   │   ├── UserUpdatedEventHandler.cs
│   │   │   └── SendWelcomeEmailHandler.cs
│   │   └── OrderEventHandlers/
│   │       ├── OrderPlacedEventHandler.cs
│   │       └── UpdateInventoryHandler.cs
│   └── Integration/
│       ├── UserRegisteredHandler.cs
│       ├── OrderProcessedHandler.cs
│       └── PaymentCompletedHandler.cs
├── MyApp.EventBus/                 # Infraestructura de eventos
│   ├── Abstractions/
│   │   ├── IEventBus.cs
│   │   ├── IEventHandler.cs
│   │   └── IEventStore.cs
│   ├── InMemory/
│   │   ├── InMemoryEventBus.cs
│   │   └── InMemoryEventStore.cs
│   ├── RabbitMQ/
│   │   ├── RabbitMQEventBus.cs
│   │   └── RabbitMQConnection.cs
│   └── Azure/
│       ├── ServiceBusEventBus.cs
│       └── EventHubEventStore.cs
├── MyApp.Projections/              # Proyecciones de eventos
│   ├── UserProjections/
│   │   ├── UserListProjection.cs
│   │   └── UserStatisticsProjection.cs
│   └── OrderProjections/
│       ├── OrderHistoryProjection.cs
│       └── SalesReportProjection.cs
└── MyApp.Sagas/                    # Procesos de negocio largos
    ├── OrderProcessingSaga.cs
    ├── UserOnboardingSaga.cs
    └── PaymentProcessingSaga.cs

Node.js (Event-Driven)

src/
├── events/                         # Definiciones de eventos
│   ├── base/
│   │   ├── event.js
│   │   ├── domainEvent.js
│   │   └── integrationEvent.js
│   ├── domain/
│   │   ├── userEvents.js
│   │   ├── orderEvents.js
│   │   └── productEvents.js
│   └── integration/
│       ├── userRegisteredEvent.js
│       ├── orderProcessedEvent.js
│       └── paymentCompletedEvent.js
├── eventHandlers/                  # Manejadores de eventos
│   ├── domain/
│   │   ├── userEventHandlers.js
│   │   ├── orderEventHandlers.js
│   │   └── productEventHandlers.js
│   └── integration/
│       ├── userRegisteredHandler.js
│       ├── orderProcessedHandler.js
│       └── paymentCompletedHandler.js
├── eventBus/                       # Infraestructura de eventos
│   ├── abstractions/
│   │   ├── eventBus.js
│   │   ├── eventHandler.js
│   │   └── eventStore.js
│   ├── implementations/
│   │   ├── inMemoryEventBus.js
│   │   ├── redisEventBus.js
│   │   └── rabbitMQEventBus.js
│   └── middleware/
│       ├── eventLogger.js
│       ├── eventValidator.js
│       └── retryHandler.js
├── projections/                    # Proyecciones de eventos
│   ├── userProjections.js
│   ├── orderProjections.js
│   └── analyticsProjections.js
├── sagas/                          # Procesos de negocio largos
│   ├── orderProcessingSaga.js
│   ├── userOnboardingSaga.js
│   └── paymentProcessingSaga.js
└── workflows/                      # Orquestación de eventos
    ├── userRegistrationWorkflow.js
    ├── orderFulfillmentWorkflow.js
    └── paymentProcessingWorkflow.js

✅ Mejores Prácticas Event-Driven

Definición de Eventos

// Evento de dominio
public record UserCreatedEvent : IDomainEvent
{
    public Guid UserId { get; init; }
    public string FirstName { get; init; } = string.Empty;
    public string LastName { get; init; } = string.Empty;
    public string Email { get; init; } = string.Empty;
    public DateTime CreatedAt { get; init; }
    public Guid EventId { get; init; } = Guid.NewGuid();
    public DateTime OccurredAt { get; init; } = DateTime.UtcNow;
}

// Evento de integración
public record UserRegisteredIntegrationEvent : IIntegrationEvent
{
    public Guid UserId { get; init; }
    public string Email { get; init; } = string.Empty;
    public string FullName { get; init; } = string.Empty;
    public DateTime RegistrationDate { get; init; }
    public Guid EventId { get; init; } = Guid.NewGuid();
    public DateTime OccurredAt { get; init; } = DateTime.UtcNow;
    public string EventType { get; init; } = nameof(UserRegisteredIntegrationEvent);
    public int Version { get; init; } = 1;
}

Event Handlers

// Handler para eventos de dominio
public class SendWelcomeEmailHandler : IEventHandler<UserCreatedEvent>
{
    private readonly IEmailService _emailService;
    private readonly ILogger<SendWelcomeEmailHandler> _logger;

    public SendWelcomeEmailHandler(
        IEmailService emailService,
        ILogger<SendWelcomeEmailHandler> logger)
    {
        _emailService = emailService;
        _logger = logger;
    }

    public async Task Handle(UserCreatedEvent @event, CancellationToken cancellationToken)
    {
        try
        {
            await _emailService.SendWelcomeEmailAsync(
                @event.Email,
                @event.FirstName,
                cancellationToken);

            _logger.LogInformation(
                "Welcome email sent to user {UserId} at {Email}",
                @event.UserId,
                @event.Email);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex,
                "Failed to send welcome email to user {UserId}",
                @event.UserId);
            throw; // Re-throw para retry automático
        }
    }
}

// Handler para eventos de integración
public class UserRegisteredHandler : IEventHandler<UserRegisteredIntegrationEvent>
{
    private readonly IAnalyticsService _analyticsService;
    private readonly ICrmService _crmService;
    private readonly ILogger<UserRegisteredHandler> _logger;

    public UserRegisteredHandler(
        IAnalyticsService analyticsService,
        ICrmService crmService,
        ILogger<UserRegisteredHandler> logger)
    {
        _analyticsService = analyticsService;
        _crmService = crmService;
        _logger = logger;
    }

    public async Task Handle(UserRegisteredIntegrationEvent @event, CancellationToken cancellationToken)
    {
        try
        {
            // Actualizar analytics
            await _analyticsService.TrackUserRegistrationAsync(@event.UserId, @event.RegistrationDate);

            // Sincronizar con CRM
            await _crmService.CreateContactAsync(new CreateContactRequest
            {
                ExternalId = @event.UserId.ToString(),
                Email = @event.Email,
                FullName = @event.FullName,
                Source = "Application"
            });

            _logger.LogInformation(
                "User registration processed for user {UserId}",
                @event.UserId);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex,
                "Failed to process user registration for user {UserId}",
                @event.UserId);
            throw;
        }
    }
}

Event Bus Implementation

public class EventBus : IEventBus
{
    private readonly IServiceProvider _serviceProvider;
    private readonly IEventStore _eventStore;
    private readonly ILogger<EventBus> _logger;
    private readonly Dictionary<Type, List<Type>> _handlers = new();

    public EventBus(
        IServiceProvider serviceProvider,
        IEventStore eventStore,
        ILogger<EventBus> logger)
    {
        _serviceProvider = serviceProvider;
        _eventStore = eventStore;
        _logger = logger;
    }

    public async Task PublishAsync<T>(T @event, CancellationToken cancellationToken = default) 
        where T : IEvent
    {
        try
        {
            // Almacenar evento
            await _eventStore.SaveEventAsync(@event, cancellationToken);

            // Obtener handlers registrados
            var eventType = typeof(T);
            if (!_handlers.ContainsKey(eventType))
            {
                _logger.LogWarning("No handlers registered for event type {EventType}", eventType.Name);
                return;
            }

            var handlerTasks = new List<Task>();

            foreach (var handlerType in _handlers[eventType])
            {
                var handler = _serviceProvider.GetService(handlerType);
                if (handler != null)
                {
                    var handleMethod = handlerType.GetMethod("Handle");
                    if (handleMethod != null)
                    {
                        var task = (Task)handleMethod.Invoke(handler, new object[] { @event, cancellationToken })!;
                        handlerTasks.Add(task);
                    }
                }
            }

            // Ejecutar todos los handlers en paralelo
            await Task.WhenAll(handlerTasks);

            _logger.LogInformation(
                "Event {EventType} with ID {EventId} published successfully",
                eventType.Name,
                @event.EventId);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex,
                "Failed to publish event {EventType} with ID {EventId}",
                typeof(T).Name,
                @event.EventId);
            throw;
        }
    }

    public void Subscribe<T, TH>() 
        where T : IEvent 
        where TH : IEventHandler<T>
    {
        var eventType = typeof(T);
        var handlerType = typeof(TH);

        if (!_handlers.ContainsKey(eventType))
        {
            _handlers[eventType] = new List<Type>();
        }

        if (!_handlers[eventType].Contains(handlerType))
        {
            _handlers[eventType].Add(handlerType);
            _logger.LogInformation(
                "Handler {HandlerType} subscribed to event {EventType}",
                handlerType.Name,
                eventType.Name);
        }
    }
}

Microservicios

📖 Descripción

Arquitectura que estructura una aplicación como una colección de servicios pequeños, autónomos y desplegables independientemente.

🎯 Cuándo Usar

  • Aplicaciones grandes y complejas
  • Equipos de desarrollo distribuidos
  • Necesidad de escalabilidad independiente
  • Diferentes tecnologías por servicio
  • Ciclos de despliegue independientes

📁 Estructura por Tecnología

.NET (Microservicios)

MyApp.Microservices/
├── src/
│   ├── Services/
│   │   ├── User/
│   │   │   ├── MyApp.User.API/
│   │   │   │   ├── Controllers/
│   │   │   │   ├── Program.cs
│   │   │   │   └── Dockerfile
│   │   │   ├── MyApp.User.Application/
│   │   │   │   ├── Commands/
│   │   │   │   ├── Queries/
│   │   │   │   └── Services/
│   │   │   ├── MyApp.User.Domain/
│   │   │   │   ├── Entities/
│   │   │   │   ├── ValueObjects/
│   │   │   │   └── Events/
│   │   │   └── MyApp.User.Infrastructure/
│   │   │       ├── Persistence/
│   │   │       ├── ExternalServices/
│   │   │       └── Messaging/
│   │   ├── Order/
│   │   │   ├── MyApp.Order.API/
│   │   │   ├── MyApp.Order.Application/
│   │   │   ├── MyApp.Order.Domain/
│   │   │   └── MyApp.Order.Infrastructure/
│   │   ├── Payment/
│   │   │   ├── MyApp.Payment.API/
│   │   │   ├── MyApp.Payment.Application/
│   │   │   ├── MyApp.Payment.Domain/
│   │   │   └── MyApp.Payment.Infrastructure/
│   │   └── Notification/
│   │       ├── MyApp.Notification.API/
│   │       ├── MyApp.Notification.Application/
│   │       ├── MyApp.Notification.Domain/
│   │       └── MyApp.Notification.Infrastructure/
│   ├── ApiGateways/
│   │   ├── MyApp.Gateway.Web/
│   │   │   ├── Program.cs
│   │   │   ├── ocelot.json
│   │   │   └── Dockerfile
│   │   └── MyApp.Gateway.Mobile/
│   │       ├── Program.cs
│   │       ├── ocelot.json
│   │       └── Dockerfile
│   ├── BuildingBlocks/             # Componentes compartidos
│   │   ├── MyApp.Common/
│   │   │   ├── Events/
│   │   │   ├── Exceptions/
│   │   │   ├── Extensions/
│   │   │   └── Models/
│   │   ├── MyApp.EventBus/
│   │   │   ├── Abstractions/
│   │   │   ├── RabbitMQ/
│   │   │   └── ServiceBus/
│   │   └── MyApp.Logging/
│   │       ├── Serilog/
│   │       └── Extensions/
│   └── WebApps/                    # Aplicaciones cliente
│       ├── MyApp.Web/
│       │   ├── Controllers/
│       │   ├── Services/
│       │   └── Program.cs
│       └── MyApp.Admin/
│           ├── Controllers/
│           ├── Services/
│           └── Program.cs
├── tests/
│   ├── Services/
│   │   ├── User.UnitTests/
│   │   ├── User.IntegrationTests/
│   │   ├── Order.UnitTests/
│   │   └── Order.IntegrationTests/
│   └── ApiGateways/
│       └── Gateway.IntegrationTests/
├── docker-compose.yml
├── docker-compose.override.yml
└── k8s/                            # Kubernetes manifests
    ├── user-service/
    ├── order-service/
    ├── payment-service/
    └── gateway/

Python (Microservicios)

myapp-microservices/
├── services/
│   ├── user-service/
│   │   ├── app/
│   │   │   ├── __init__.py
│   │   │   ├── main.py
│   │   │   ├── api/
│   │   │   │   ├── __init__.py
│   │   │   │   └── v1/
│   │   │   │       ├── __init__.py
│   │   │   │       └── users.py
│   │   │   ├── domain/
│   │   │   │   ├── __init__.py
│   │   │   │   ├── entities/
│   │   │   │   ├── events/
│   │   │   │   └── services/
│   │   │   ├── infrastructure/
│   │   │   │   ├── __init__.py
│   │   │   │   ├── database/
│   │   │   │   ├── messaging/
│   │   │   │   └── external/
│   │   │   └── application/
│   │   │       ├── __init__.py
│   │   │       ├── commands/
│   │   │       ├── queries/
│   │   │       └── handlers/
│   │   ├── requirements.txt
│   │   ├── Dockerfile
│   │   └── tests/
│   ├── order-service/
│   │   ├── app/
│   │   ├── requirements.txt
│   │   ├── Dockerfile
│   │   └── tests/
│   ├── payment-service/
│   │   ├── app/
│   │   ├── requirements.txt
│   │   ├── Dockerfile
│   │   └── tests/
│   └── notification-service/
│       ├── app/
│       ├── requirements.txt
│       ├── Dockerfile
│       └── tests/
├── gateway/
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py
│   │   ├── middleware/
│   │   ├── routing/
│   │   └── auth/
│   ├── requirements.txt
│   └── Dockerfile
├── shared/
│   ├── events/
│   ├── exceptions/
│   ├── logging/
│   └── messaging/
├── docker-compose.yml
├── docker-compose.dev.yml
└── k8s/
    ├── user-service/
    ├── order-service/
    ├── payment-service/
    └── gateway/

✅ Mejores Prácticas Microservicios

Comunicación entre Servicios

// .NET - Cliente HTTP para comunicación entre servicios
public class OrderServiceClient : IOrderServiceClient
{
    private readonly HttpClient _httpClient;
    private readonly ILogger<OrderServiceClient> _logger;
    private readonly OrderServiceOptions _options;

    public OrderServiceClient(
        HttpClient httpClient,
        IOptions<OrderServiceOptions> options,
        ILogger<OrderServiceClient> logger)
    {
        _httpClient = httpClient;
        _options = options.Value;
        _logger = logger;
    }

    public async Task<OrderDto?> GetOrderAsync(int orderId, CancellationToken cancellationToken = default)
    {
        try
        {
            var response = await _httpClient.GetAsync($"/api/orders/{orderId}", cancellationToken);

            if (response.StatusCode == HttpStatusCode.NotFound)
                return null;

            response.EnsureSuccessStatusCode();

            var content = await response.Content.ReadAsStringAsync(cancellationToken);
            return JsonSerializer.Deserialize<OrderDto>(content, new JsonSerializerOptions
            {
                PropertyNamingPolicy = JsonNamingPolicy.CamelCase
            });
        }
        catch (HttpRequestException ex)
        {
            _logger.LogError(ex, "Error calling Order Service for order {OrderId}", orderId);
            throw new ServiceCommunicationException("Order Service", ex);
        }
    }

    public async Task<bool> CreateOrderAsync(CreateOrderRequest request, CancellationToken cancellationToken = default)
    {
        try
        {
            var json = JsonSerializer.Serialize(request, new JsonSerializerOptions
            {
                PropertyNamingPolicy = JsonNamingPolicy.CamelCase
            });

            var content = new StringContent(json, Encoding.UTF8, "application/json");
            var response = await _httpClient.PostAsync("/api/orders", content, cancellationToken);

            return response.IsSuccessStatusCode;
        }
        catch (HttpRequestException ex)
        {
            _logger.LogError(ex, "Error creating order in Order Service");
            throw new ServiceCommunicationException("Order Service", ex);
        }
    }
}

API Gateway con Ocelot (.NET)

// ocelot.json
{
  "Routes": [
    {
      "DownstreamPathTemplate": "/api/users/{everything}",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "user-service",
          "Port": 80
        }
      ],
      "UpstreamPathTemplate": "/api/users/{everything}",
      "UpstreamHttpMethod": [ "GET", "POST", "PUT", "DELETE" ],
      "AuthenticationOptions": {
        "AuthenticationProviderKey": "Bearer",
        "AllowedScopes": []
      },
      "RateLimitOptions": {
        "ClientWhitelist": [],
        "EnableRateLimiting": true,
        "Period": "1m",
        "PeriodTimespan": 60,
        "Limit": 100
      }
    },
    {
      "DownstreamPathTemplate": "/api/orders/{everything}",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "order-service",
          "Port": 80
        }
      ],
      "UpstreamPathTemplate": "/api/orders/{everything}",
      "UpstreamHttpMethod": [ "GET", "POST", "PUT", "DELETE" ],
      "AuthenticationOptions": {
        "AuthenticationProviderKey": "Bearer"
      }
    }
  ],
  "GlobalConfiguration": {
    "BaseUrl": "http://localhost:5000",
    "RateLimitOptions": {
      "DisableRateLimitHeaders": false,
      "QuotaExceededMessage": "Rate limit exceeded",
      "HttpStatusCode": 429
    }
  }
}

Event-Driven Communication

// Evento de integración entre microservicios
public record UserRegisteredIntegrationEvent : IIntegrationEvent
{
    public Guid UserId { get; init; }
    public string Email { get; init; } = string.Empty;
    public string FullName { get; init; } = string.Empty;
    public DateTime RegistrationDate { get; init; }
    public Guid EventId { get; init; } = Guid.NewGuid();
    public DateTime OccurredAt { get; init; } = DateTime.UtcNow;
}

// Handler en el servicio de notificaciones
public class UserRegisteredIntegrationEventHandler : IIntegrationEventHandler<UserRegisteredIntegrationEvent>
{
    private readonly INotificationService _notificationService;
    private readonly ILogger<UserRegisteredIntegrationEventHandler> _logger;

    public UserRegisteredIntegrationEventHandler(
        INotificationService notificationService,
        ILogger<UserRegisteredIntegrationEventHandler> logger)
    {
        _notificationService = notificationService;
        _logger = logger;
    }

    public async Task Handle(UserRegisteredIntegrationEvent @event)
    {
        try
        {
            // Enviar email de bienvenida
            await _notificationService.SendWelcomeEmailAsync(
                @event.Email,
                @event.FullName);

            // Crear notificación en la app
            await _notificationService.CreateInAppNotificationAsync(
                @event.UserId,
                "¡Bienvenido a nuestra plataforma!",
                "Tu cuenta ha sido creada exitosamente.");

            _logger.LogInformation(
                "Welcome notifications sent for user {UserId}",
                @event.UserId);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex,
                "Failed to send welcome notifications for user {UserId}",
                @event.UserId);
            throw;
        }
    }
}

Docker Compose para Desarrollo

# docker-compose.yml
version: '3.8'

services:
  # API Gateway
  gateway:
    build:
      context: ./src/ApiGateways/MyApp.Gateway.Web
      dockerfile: Dockerfile
    ports:
      - "5000:80"
    environment:
      - ASPNETCORE_ENVIRONMENT=Development
    depends_on:
      - user-service
      - order-service
      - payment-service
    networks:
      - myapp-network

  # User Service
  user-service:
    build:
      context: ./src/Services/User
      dockerfile: MyApp.User.API/Dockerfile
    environment:
      - ASPNETCORE_ENVIRONMENT=Development
      - ConnectionStrings__DefaultConnection=Server=user-db;Database=UserDb;User=sa;Password=YourPassword123!;TrustServerCertificate=true
      - EventBus__Connection=amqp://guest:guest@rabbitmq:5672
    depends_on:
      - user-db
      - rabbitmq
    networks:
      - myapp-network

  user-db:
    image: mcr.microsoft.com/mssql/server:2022-latest
    environment:
      - ACCEPT_EULA=Y
      - SA_PASSWORD=YourPassword123!
    volumes:
      - user-db-data:/var/opt/mssql
    networks:
      - myapp-network

  # Order Service
  order-service:
    build:
      context: ./src/Services/Order
      dockerfile: MyApp.Order.API/Dockerfile
    environment:
      - ASPNETCORE_ENVIRONMENT=Development
      - ConnectionStrings__DefaultConnection=Server=order-db;Database=OrderDb;User=sa;Password=YourPassword123!;TrustServerCertificate=true
      - EventBus__Connection=amqp://guest:guest@rabbitmq:5672
      - ExternalServices__UserService=http://user-service
    depends_on:
      - order-db
      - rabbitmq
    networks:
      - myapp-network

  order-db:
    image: mcr.microsoft.com/mssql/server:2022-latest
    environment:
      - ACCEPT_EULA=Y
      - SA_PASSWORD=YourPassword123!
    volumes:
      - order-db-data:/var/opt/mssql
    networks:
      - myapp-network

  # Payment Service
  payment-service:
    build:
      context: ./src/Services/Payment
      dockerfile: MyApp.Payment.API/Dockerfile
    environment:
      - ASPNETCORE_ENVIRONMENT=Development
      - ConnectionStrings__DefaultConnection=Server=payment-db;Database=PaymentDb;User=sa;Password=YourPassword123!;TrustServerCertificate=true
      - EventBus__Connection=amqp://guest:guest@rabbitmq:5672
    depends_on:
      - payment-db
      - rabbitmq
    networks:
      - myapp-network

  payment-db:
    image: mcr.microsoft.com/mssql/server:2022-latest
    environment:
      - ACCEPT_EULA=Y
      - SA_PASSWORD=YourPassword123!
    volumes:
      - payment-db-data:/var/opt/mssql
    networks:
      - myapp-network

  # Message Broker
  rabbitmq:
    image: rabbitmq:3-management
    ports:
      - "15672:15672"  # Management UI
      - "5672:5672"    # AMQP port
    environment:
      - RABBITMQ_DEFAULT_USER=guest
      - RABBITMQ_DEFAULT_PASS=guest
    volumes:
      - rabbitmq-data:/var/lib/rabbitmq
    networks:
      - myapp-network

  # Monitoring
  seq:
    image: datalust/seq:latest
    ports:
      - "5341:80"
    environment:
      - ACCEPT_EULA=Y
    volumes:
      - seq-data:/data
    networks:
      - myapp-network

volumes:
  user-db-data:
  order-db-data:
  payment-db-data:
  rabbitmq-data:
  seq-data:

networks:
  myapp-network:
    driver: bridge

📋 Guía de Selección de Patrones

🎯 Matriz de Decisión

Criterio MVC Hexagonal Clean Capas CQRS Event-Driven Microservicios
Complejidad del Proyecto Baja Media-Alta Alta Media Alta Alta Muy Alta
Tamaño del Equipo Pequeño Medio Grande Medio Grande Grande Muy Grande
Requisitos de Escalabilidad Baja Media Alta Media Muy Alta Alta Muy Alta
Independencia de Tecnología Baja Alta Muy Alta Media Media Media Muy Alta
Facilidad de Testing Media Alta Muy Alta Media Alta Media Alta
Curva de Aprendizaje Baja Media Alta Baja Alta Alta Muy Alta
Mantenibilidad a Largo Plazo Media Alta Muy Alta Media Alta Alta Alta

🚀 Recomendaciones por Escenario

Proyectos Pequeños/Medianos (1-5 desarrolladores)

  • Recomendado: MVC o Arquitectura por Capas
  • Razón: Simplicidad, rapidez de desarrollo, menor overhead

Proyectos Empresariales (5-15 desarrolladores)

  • Recomendado: Clean Architecture o Arquitectura Hexagonal
  • Razón: Mejor separación de responsabilidades, alta testabilidad

Sistemas de Alta Escala (15+ desarrolladores)

  • Recomendado: Microservicios + CQRS + Event-Driven
  • Razón: Escalabilidad independiente, equipos autónomos

Sistemas con Requisitos de Performance Extrema

  • Recomendado: CQRS + Event-Driven
  • Razón: Optimización independiente de lectura/escritura

💡 Consejos de Implementación

  1. Comienza Simple: Inicia con MVC y evoluciona según las necesidades
  2. No Sobre-Ingenierices: Usa la arquitectura más simple que resuelva tus problemas
  3. Considera el Contexto: Evalúa el tamaño del equipo, experiencia y requisitos
  4. Evolución Gradual: Puedes migrar de una arquitectura a otra gradualmente
  5. Documentación: Mantén documentada la arquitectura elegida y las razones

💡 Recuerda: No existe una arquitectura perfecta para todos los casos. La mejor arquitectura es la que mejor se adapta a tu contexto específico: tamaño del equipo, complejidad del dominio, requisitos de escalabilidad y restricciones tecnológicas.