Estrutura do monorepo e os cinco serviços

Objetivos

• Definir uma estrutura de pastas clara para serviços, contratos e infra
• Padronizar layout mínimo entre stacks diferentes
• Facilitar manutenção e onboarding no monorepo

Pré-requisitos

• Conclusão das aulas de Dockerfile e rede/volumes
• Repositório do curso disponível localmente
• Editor configurado para trabalhar com múltiplas linguagens

Conceito

Monorepo não é colocar tudo numa pasta só. Em microsserviços, o valor do monorepo está em compartilhar governança e automação sem compartilhar domínio. Se a estrutura não deixa isso explícito, cada time começa a "invadir" área do outro e o acoplamento aumenta.

Uma estrutura boa separa claramente: código de serviço (services), infraestrutura (infra) e contratos de integração (contracts). Assim, quando você mexe em evento ou compose, a mudança é localizável e revisável.

Nesta aula você cria um esqueleto de projeto que será usado até o fim do curso. O foco é previsibilidade: qualquer pessoa da equipe bate o olho e entende onde está API, domínio, dependência e documentação.

Estrutura de arquivos

.
├── contracts/
│   └── events/
│       ├── customer-created.v1.json
│       ├── order-created.v1.json
│       ├── payment-approved.v1.json
│       └── payment-failed.v1.json
├── infra/
│   └── docker-compose.yml
├── services/
│   ├── customer-service/
│   ├── order-service/
│   ├── payment-service/
│   ├── notification-service/
│   └── analytics-service/
├── Makefile
└── README.md

Passo a passo

1. Criar README.md raiz com visão do sistema

# Aprendi - Arquitetura de Microsserviços

## Serviços
- customer-service (Java Spring Boot)
- order-service (Python FastAPI)
- payment-service (Go Gin)
- notification-service (Ruby Sinatra)
- analytics-service (Node Express)

## Como subir
docker compose -f infra/docker-compose.yml up --build

2. Criar Makefile para operação padronizada

COMPOSE_FILE=infra/docker-compose.yml

up:
	docker compose -f $(COMPOSE_FILE) up --build

down:
	docker compose -f $(COMPOSE_FILE) down

logs:
	docker compose -f $(COMPOSE_FILE) logs -f

ps:
	docker compose -f $(COMPOSE_FILE) ps

3. Criar contrato inicial de evento em contracts/events/customer-created.v1.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "customer.created.v1",
  "type": "object",
  "required": ["eventId", "occurredAt", "customerId", "email", "fullName"],
  "properties": {
    "eventId": { "type": "string" },
    "occurredAt": { "type": "string", "format": "date-time" },
    "customerId": { "type": "string" },
    "email": { "type": "string", "format": "email" },
    "fullName": { "type": "string" }
  }
}

4. Criar README mínimo em cada serviço (exemplo services/payment-service/README.md)

# payment-service

Serviço responsável por iniciar e processar pagamentos.

## Stack
- Go 1.22
- Gin
- Kafka (consumidor/produtor)

## Endpoint inicial
- GET /health

Como testar

1. Validar a estrutura esperada:

rg --files services contracts infra | sort

2. Subir projeto com Make:

make up

3. Testar saúde dos serviços:

curl -s http://localhost:8081/health
curl -s http://localhost:8000/health
curl -s http://localhost:8080/health
curl -s http://localhost:4567/health
curl -s http://localhost:3000/health

Saída esperada: JSON com status: "ok" em todos.

Dicas de projeto

• Evite pasta shared para lógica de domínio; prefira contratos explícitos.
• Nomeie serviços, tópicos e variáveis com padrão único.
• Centralize automação em Makefile para reduzir comandos ad-hoc.
• Mantenha documentação de cada serviço curta e objetiva.

Erros comuns

• Colocar arquivo de infraestrutura dentro da pasta de serviço.
• Compartilhar modelo de entidade entre dois contextos.
• Criar scripts diferentes para o mesmo objetivo em cada stack.
• Deixar contratos de eventos espalhados pelo repositório.

Resumo

A estrutura do monorepo ficou explícita, padronizada e preparada para evolução. Esse desenho reduz atrito de time e sustenta os próximos módulos de APIs e Kafka sem retrabalho arquitetural.