🛒 Ecommerce Broker Architecture - Desafio de Arquiteturas de Software

📚 Sobre o Projeto

Este projeto foi desenvolvido como parte do Desafio de Arquiteturas de Software demonstrando uma implementação completa da Broker Architecture usando .NET 9, RabbitMQ e PostgreSQL. É um sistema de e-commerce minimalista com comunicação assíncrona entre serviços através de mensageria.

🎯 Objetivo

Implementar um sistema de e-commerce utilizando Broker Architecture com comunicação assíncrona via message broker, demonstrando boas práticas de desenvolvimento de sistemas distribuídos e organização de código.

🏗️ Arquitetura

O projeto segue os princípios da Broker Architecture com serviços independentes e comunicação assíncrona:

┌─────────────────────────────────────┐
│           API Layer                 │ ← Controllers, Program.cs
├─────────────────────────────────────┤
│        Application Layer            │ ← Handlers, DTOs, Services
├─────────────────────────────────────┤
│          Domain Layer               │ ← Entities, Value Objects
├─────────────────────────────────────┤
│      Infrastructure Layer           │ ← Repositories, DbContext
├─────────────────────────────────────┤
│        Messaging Layer              │ ← Producers, Consumers, Events
└─────────────────────────────────────┘

📋 Serviços

UsersService: Gerenciamento de usuários (CRUD)
ProductsService: Gerenciamento de produtos (CRUD)
OrdersService: Criação e consulta de pedidos + gerenciamento de itens

🎯 Padrões Implementados

✅ Broker Architecture: Comunicação assíncrona via RabbitMQ
✅ Event Sourcing: Comandos e eventos para coordenação
✅ Database per Service: Cada serviço tem seu próprio PostgreSQL
✅ CQRS: Separação entre comandos e consultas
✅ Producer/Consumer: Padrão de mensageria com MassTransit
✅ Microservices: Serviços independentes e escaláveis

🛠️ Tecnologias Utilizadas

.NET 9 - Framework de desenvolvimento
RabbitMQ - Message broker para comunicação assíncrona
PostgreSQL - Banco de dados (3 instâncias isoladas)
MassTransit - Biblioteca de mensageria para .NET
Entity Framework Core - ORM para acesso a dados
Docker & Docker Compose - Containerização da infraestrutura
Swagger/OpenAPI - Documentação da API
Makefile - Automação de comandos de desenvolvimento
Broker Architecture - Arquitetura de mensageria

📁 Estrutura do Projeto

broker-arch-demo/
├── docker-compose.yml          # Configuração da infraestrutura
├── Makefile                    # Comandos de automação
├── README.md                   # Esta documentação
├── scripts/                    # Scripts de desenvolvimento
│   ├── dev-setup.sh           # Configuração inicial
│   ├── start-infrastructure.sh # Inicia RabbitMQ + PostgreSQL
│   ├── start-apis.sh          # Inicia APIs .NET
│   ├── start-workers.sh       # Inicia Workers .NET
│   ├── stop-apis.sh           # Para APIs
│   ├── stop-workers.sh        # Para Workers
│   └── stop-all.sh            # Para tudo
└── src/
    ├── Contracts/              # DTOs compartilhados
    │   ├── Commands/           # Comandos de mensageria
    │   └── Events/             # Eventos de domínio
    ├── Common/                 # Configuração MassTransit
    │   └── Messaging/          # BusConfigurator, RabbitMqSettings
    ├── Users/
    │   ├── Users.Api/          # API REST + Producer
    │   │   ├── Controllers/    # UsersController
    │   │   ├── Application/    # CreateUserHandler
    │   │   ├── Domain/         # User entity
    │   │   └── Infrastructure/ # DbContext, Repositories
    │   └── Users.Worker/       # Consumer (opcional)
    ├── Products/
    │   └── Products.Api/       # API REST + Producer
    │       ├── Controllers/    # ProductsController
    │       ├── Application/    # CreateProductHandler
    │       ├── Domain/         # Product entity
    │       └── Infrastructure/ # DbContext, Repositories
    └── Orders/
        ├── Orders.Api/         # API REST + Producer (Orders + OrderItems)
        │   ├── Controllers/    # OrdersController
        │   ├── Application/    # CreateOrderHandler, AddOrderItemHandler
        │   ├── Domain/         # Order, OrderItem entities
        │   └── Infrastructure/ # DbContext, Repositories
        └── Orders.Worker/      # Consumer (CreateOrder + AddOrderItem)
            ├── Domain/         # Order, OrderItem entities
            ├── Infrastructure/ # DbContext
            └── Messaging/      # Consumers

📋 Pré-requisitos

.NET 9 SDK (versão 9.0 ou superior)
Docker Desktop
Git
Make (recomendado para automação)

⚡ Como Executar

🚀 Método Super Rápido (Make - Recomendado)

# Clone o repositório
git clone https://github.com/torneseumprogramador/Broker-Architecture.git
cd Broker-Architecture

# Execute TUDO com um comando só! 🎉
make dev

🛠️ Comandos Make Disponíveis

# Comandos principais
make dev                    # 🚀 Inicia TUDO (infraestrutura + migrações + APIs + workers)
make up                     # 🐳 Inicia apenas a infraestrutura (Docker)
make start-apis            # 🌐 Inicia apenas as APIs .NET
make start-workers         # ⚙️ Inicia apenas os Workers .NET
make stop-all              # 🛑 Para TUDO

# Comandos de banco de dados
make add-migrations        # 📝 Cria migrações iniciais
make migrate              # 🗄️ Executa migrações
make setup-db             # 💾 Setup completo do banco (migrations + update)

# Comandos utilitários
make build                # 🔨 Build dos containers Docker
make ps                   # 📋 Status dos containers
make logs                 # 📜 Logs dos containers
make clean                # 🧹 Limpeza completa

📜 Método com Scripts (Alternativo)

# Execute passo a passo
./scripts/dev-setup.sh           # Configura ambiente
./scripts/start-infrastructure.sh # Inicia RabbitMQ + PostgreSQL  
./scripts/start-apis.sh          # Inicia APIs .NET
./scripts/start-workers.sh       # Inicia Workers .NET

Comandos Disponíveis nos Scripts

./scripts/dev-setup.sh           # Configura ambiente e restaura dependências
./scripts/start-infrastructure.sh # Inicia RabbitMQ + PostgreSQL
./scripts/start-apis.sh          # Inicia todas as APIs .NET
./scripts/start-workers.sh       # Inicia todos os Workers .NET
./scripts/stop-apis.sh           # Para todas as APIs
./scripts/stop-workers.sh        # Para todos os Workers
./scripts/stop-all.sh            # Para tudo (APIs + Workers + Infraestrutura)

Desenvolvimento com Docker (Alternativo)

Se preferir rodar tudo via Docker:

# Build e execução completa
make build
make up

# Verificar status
make ps

# Acompanhar logs
make logs

🌐 Acessando as APIs

Após executar o projeto, as APIs estarão disponíveis em:

🏠 Home Pages das APIs (Novidade!)

Users API: http://localhost:8081/ - Informações da API
Products API: http://localhost:8082/ - Informações da API
Orders API: http://localhost:8083/ - Informações da API

📚 Documentação Swagger

Users API: http://localhost:8081/swagger
Products API: http://localhost:8082/swagger
Orders API: http://localhost:8083/swagger

🏥 Health Checks

Users API: http://localhost:8081/health
Products API: http://localhost:8082/health
Orders API: http://localhost:8083/health

🐰 Infraestrutura

RabbitMQ Management: http://localhost:15672 (guest/guest)

🆕 Novidades Implementadas

🏠 HomeController para cada API

Cada API agora possui uma página inicial informativa que exibe:

Nome e versão do serviço
Descrição da funcionalidade
Informações do ambiente
Links para endpoints importantes
Configurações de banco de dados
Configurações de mensageria

Exemplo de resposta:

{
  "service": "Users API",
  "version": "1.0.0",
  "description": "API responsável pelo gerenciamento de usuários",
  "environment": "Production",
  "timestamp": "2025-09-01T09:42:33.337502Z",
  "endpoints": {
    "swagger": "/swagger",
    "health": "/health",
    "users": "/api/users"
  },
  "database": {
    "provider": "PostgreSQL",
    "host": "localhost",
    "port": 5433,
    "database": "usersdb"
  },
  "messaging": {
    "provider": "RabbitMQ",
    "host": "localhost",
    "port": 5672
  }
}

🏥 Health Check Endpoints

Cada API possui um endpoint de health check em /health que retorna:

Status da aplicação
Nome do serviço
Timestamp atual
Tempo de atividade (uptime)

🛠️ Makefile Completo

Sistema completo de automação com comandos para:

Desenvolvimento: make dev (inicia tudo)
Infraestrutura: make up/down (Docker)
Aplicações: make start-apis/start-workers
Banco de dados: make migrate/add-migrations
Utilitários: make clean/logs/ps

📦 Atualização para .NET 9

Migração completa para .NET 9
Atualização de todas as dependências
Compatibilidade com versões mais recentes

📖 Endpoints da API

👥 Usuários (Users)

Método	Endpoint	Descrição
POST	`/api/users`	Criar usuário
GET	`/api/users`	Listar todos os usuários
GET	`/api/users/{id}`	Buscar usuário por ID
DELETE	`/api/users/{id}`	Remover usuário

📦 Produtos (Products)

Método	Endpoint	Descrição
POST	`/api/products`	Criar produto
GET	`/api/products`	Listar todos os produtos
GET	`/api/products/{id}`	Buscar produto por ID
DELETE	`/api/products/{id}`	Remover produto

🛒 Pedidos (Orders)

Método	Endpoint	Descrição
POST	`/api/orders`	Criar pedido
GET	`/api/orders`	Listar todos os pedidos
GET	`/api/orders/{id}`	Buscar pedido por ID (com itens)
GET	`/api/orders/user/{userId}`	Pedidos por usuário
POST	`/api/orders/items`	Adicionar item ao pedido
GET	`/api/orders/items`	Listar todos os itens
GET	`/api/orders/items/{id}`	Buscar item por ID
GET	`/api/orders/{orderId}/items`	Itens de um pedido específico

🧪 Exemplos de Uso

Criar Usuário

curl -X POST "http://localhost:8081/api/users" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Silva",
    "email": "joao@email.com"
  }'

Criar Produto

curl -X POST "http://localhost:8082/api/products" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Smartphone XYZ",
    "price": 1299.99
  }'

Criar Pedido

curl -X POST "http://localhost:8083/api/orders" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "guid-do-usuario"
  }'

Adicionar Item ao Pedido

curl -X POST "http://localhost:8083/api/orders/items" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "guid-do-pedido",
    "productId": "guid-do-produto",
    "quantity": 2,
    "unitPrice": 1299.99
  }'

Consultar Pedido Completo

curl "http://localhost:8083/api/orders/guid-do-pedido"

🏛️ Conceitos de Broker Architecture Implementados

📦 Entidades de Domínio

User (Usuário) - Entidade de usuário
Product (Produto) - Entidade de produto
Order (Pedido) - Entidade de pedido
OrderItem (Item do Pedido) - Entidade de item

🔄 Fluxo de Mensageria

Criação de Pedido

POST /api/orders → Publica CreateOrderCommand
Orders.Worker consome CreateOrderCommand → grava no DB → publica OrderCreatedEvent

Adição de Item

POST /api/orders/items → Publica AddOrderItemCommand
Orders.Worker consome AddOrderItemCommand → grava no DB → publica OrderItemAddedEvent

📨 Eventos Publicados

UserCreatedEvent (quando usuário é criado)
ProductCreatedEvent (quando produto é criado)
OrderCreatedEvent (quando pedido é processado)
OrderItemAddedEvent (quando item é adicionado)

🎯 Comandos Processados

CreateOrderCommand (criar pedido)
AddOrderItemCommand (adicionar item ao pedido)

🔧 Configuração do Banco de Dados

O projeto utiliza PostgreSQL rodando em Docker com bancos isolados por serviço:

Serviço	Host	Porta	Database	Usuário
Users	localhost	5433	usersdb	users
Products	localhost	5434	productsdb	products
Orders	localhost	5435	ordersdb	orders

Connection Strings

{
  "ConnectionStrings": {
    "Default": "Host=localhost;Database=usersdb;Username=users;Password=userspwd"
  }
}

🛡️ Tratamento de Erros

A API possui um sistema robusto de tratamento de erros que garante respostas consistentes:

📋 Tipos de Erro

Código	Tipo	Descrição
400	`ValidationError`	Erro de validação (dados obrigatórios, etc.)
400	`BusinessError`	Erro de negócio (email já existe, etc.)
404	`NotFoundError`	Recurso não encontrado
500	`InternalServerError`	Erro interno do servidor

📝 Formato da Resposta de Erro

{
  "message": "Usuário não encontrado",
  "type": "NotFoundError",
  "timestamp": "2024-01-15T10:30:00Z"
}

🧹 Limpeza

Para parar e remover tudo:

./scripts/stop-all.sh
# ou
make clean
# ou
docker compose down -v
docker system prune -f

📝 Comandos Úteis

🛠️ Comandos Make (Recomendados)

# 🚀 Desenvolvimento
make dev                         # Inicia TUDO (infraestrutura + migrações + APIs + workers)
make stop-all                    # Para TUDO

# 🐳 Infraestrutura  
make up                          # Inicia containers Docker (RabbitMQ + PostgreSQL)
make down                        # Para containers Docker
make build                       # Build dos containers

# 🌐 Aplicações .NET
make start-apis                  # Inicia todas as APIs .NET
make start-workers               # Inicia todos os Workers .NET  
make stop-apis                   # Para todas as APIs
make stop-workers                # Para todos os Workers

# 🗄️ Banco de Dados
make add-migrations              # Cria migrações iniciais
make migrate                     # Executa migrações
make setup-db                    # Setup completo (add-migrations + migrate)

# 🔍 Monitoramento
make ps                          # Status dos containers
make logs                        # Logs dos containers  
make clean                       # Limpeza completa (para tudo + remove volumes)

📜 Scripts Alternativos

# Scripts de desenvolvimento
./scripts/dev-setup.sh           # Configuração inicial
./scripts/start-infrastructure.sh # Inicia infraestrutura
./scripts/start-apis.sh          # Inicia APIs
./scripts/start-workers.sh       # Inicia Workers
./scripts/stop-all.sh            # Para tudo

🎓 Aprendizados do Projeto

Este projeto demonstra os seguintes conceitos de arquitetura de software:

Broker Architecture
- Comunicação assíncrona via message broker
- Desacoplamento entre serviços
- Event-driven architecture
Microservices
- Serviços independentes e escaláveis
- Database per service
- API Gateway pattern
Padrões de Mensageria
- Producer/Consumer pattern
- Command/Event pattern
- Message routing
Boas Práticas
- SOLID Principles
- Clean Architecture
- Separation of Concerns

🐛 Troubleshooting

Problema: Serviços não conseguem se conectar ao RabbitMQ

Solução: Verifique se o RabbitMQ está rodando:

docker compose logs rabbitmq

Problema: Banco de dados não conecta

Solução: Verifique se os bancos estão rodando:

docker compose ps | grep db

Problema: Worker não processa mensagens

Solução: Verifique logs do worker:

docker compose logs orders-worker

📚 Próximos Passos

Implementar testes unitários
Adicionar validação com FluentValidation
Implementar logging estruturado com Serilog
Adicionar métricas e monitoramento
Implementar circuit breaker
Adicionar autenticação e autorização
Implementar saga pattern para transações distribuídas

🤝 Contribuição

Este projeto foi desenvolvido como parte de um desafio educacional. Contribuições são bem-vindas através de issues e pull requests.

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

Desenvolvido com ❤️ seguindo os princípios da Broker Architecture

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
scripts		scripts
src		src
.gitignore		.gitignore
Makefile		Makefile
README.md		README.md
docker-compose.yml		docker-compose.yml

torneseumprogramador/Broker-Architecture

Folders and files

Latest commit

History

Repository files navigation