Repository navigation
Estrategia de Solucao
⬅ Voltar para Documentação de Arquitetura
Esta seção documenta as decisões arquiteturais de alto nível tomadas para resolver os requisitos do sistema, explicando por que cada tecnologia ou padrão foi escolhido. As decisões são fortemente influenciadas pelas restrições documentadas na Seção 2.
A arquitetura do QuaLeiDer foi projetada para balancear simplicidade (time pequeno, orçamento zero) com qualidade (segurança, manutenibilidade, testabilidade). A estratégia central é:
"Monólito modular com Clean Architecture, usando tecnologias maduras do ecossistema Node.js/TypeScript, priorizando time-to-market sem sacrificar boas práticas de engenharia de software."
Decisão: Sistema único com módulos independentes (UsersModule, AnimalsModule, InvitesModule, etc.) ao invés de microserviços.
Justificativa:
| Critério | Monólito Modular ✅ | Microserviços ❌ |
|---|---|---|
| Equipe | 1-2 desenvolvedores conseguem manter | Exige time de 5+ pessoas |
| Complexidade | Deploy único, logs centralizados | Requer orquestração (Kubernetes), tracing distribuído |
| Latência | Chamadas de função (nanossegundos) | Chamadas HTTP entre serviços (milissegundos) |
| Transações | ACID nativo do PostgreSQL | Saga Pattern ou 2PC (complexo) |
Referência de Código:
// src/presentation/app.module.ts - Todos os módulos em um só monólito
@Module({
imports: [
ConfigModule.forRoot({
isGlobal: true,
envFilePath: [
path.resolve(process.cwd(), '.env'),
path.resolve(
process.cwd(),
`.env.${process.env.NODE_ENV || 'development'}`,
),
],
}),
WinstonModule.forRoot(winstonConfig),
ThrottlerModule.forRoot(throttlerConfig),
EventEmitterModule.forRoot(),
ScheduleModule.forRoot(),
PrismaModule,
InfrastructureModule,
UsersPresentationModule,
AnimalsPresentationModule,
DailyCollectionsPresentationModule,
AuthPresentationModule,
AssociationsPresentationModule,
InvitesPresentationModule,
NotificationsPresentationModule,
MailModule,
],
controllers: [],
providers: [
{
provide: APP_GUARD,
useClass: AppThrottlerGuard,
},
],
})
export class AppModule {}Decisão: Separar código em 4 camadas: Domain → Application → Infrastructure → Presentation.
Justificativa:
- Testabilidade: Lógica de negócio isolada da infraestrutura (mocks fáceis)
- Manutenibilidade: Mudanças em banco de dados não afetam regras de negócio
- Substituibilidade: Trocar Prisma por TypeORM exige mudanças apenas na camada Infrastructure
- Requisito Acadêmico: IFPE valoriza arquiteturas bem documentadas
Estrutura de Diretórios:
src/
├── domain/ # Entidades e regras de negócio puras
│ └── entities/ # User, Animal, DailyCollection
├── application/ # Casos de uso (Services)
│ └── services/ # UsersService, AnimalsService
├── infrastructure/ # Adaptadores externos
│ ├── prisma/ # ORM (substituível)
│ └── mail/ # Nodemailer (substituível)
└── presentation/ # Controllers (HTTP)
└── controllers/ # UsersController, AnimalsController
Regra de Dependência:

- Setas indicam dependência de código-fonte (imports), não fluxo de execução
Princípios:
- Domain (núcleo isolado) não conhece nenhuma outra camada
- Application depende apenas de Domain (usa entidades e interfaces)
- Presentation depende de Application (chama Services)
- Infrastructure implementa interfaces definidas em Domain/Application (Inversão de Dependência - DIP)
Benefício Concreto: 96.25% de cobertura de testes (582 testes) graças à separação de camadas.
Decisão: Tokens JWT assinados com HMAC-SHA256, sem armazenamento de sessão no servidor.
Justificativa:
| Aspecto | JWT Stateless ✅ | Sessions (Redis) ❌ |
|---|---|---|
| Escalabilidade | Horizontal (stateless) | Requer Redis compartilhado |
| Custo | Zero (sem dependência externa) | Redis $5/mês |
| Latência | Validação local (1ms) | Query Redis (5-10ms) |
| Revogação | Impossível (token válido até expirar) | Instantânea (delete key) |
| Complexidade | Baixa (biblioteca padrão) | Média (gerenciar conexões Redis) |
Configuração de Segurança:
// src/auth/auth.module.ts
JwtModule.registerAsync({
imports: [ConfigModule],
useFactory: async (configService: ConfigService) => ({
secret: configService.get<string>('JWT_SECRET'),
signOptions: { expiresIn: '1h' },
}),
inject: [ConfigService],
}),Trade-off Aceito:
- ❌ Não é possível revogar tokens antes de expirar (logout instantâneo impossível)
- ✅ Mitigação: Expiração curta (24h) + blacklist opcional para casos críticos
Alternativas Descartadas:
- Sessions (Express-Session + Redis): Requer infraestrutura adicional (custo)
- OAuth2: Overhead desnecessário para sistema interno sem SSO
Decisão: PostgreSQL 14+ como SGBD relacional com Prisma como ORM type-safe.
Justificativa para PostgreSQL:
- Requisito IFPE: Exigência institucional de banco relacional (ACID compliance)
-
Integridade Referencial: Foreign Keys garantem consistência (ex:
DailyCollection.userId → User.id) - Queries Complexas: Suporte nativo a JOINs, agregações, CTEs (necessário para relatórios)
Justificativa para Prisma:
| Aspecto | Prisma ORM ✅ | SQL Raw ❌ | TypeORM ❌ |
|---|---|---|---|
| Type-Safety | 100% (tipos gerados automaticamente) | 0% (strings SQL) | 80% (decorators podem quebrar) |
| SQL Injection | Impossível (prepared statements) | Alto risco (concatenação manual) | Baixo risco (query builder seguro) |
| Migrations | Automáticas (prisma migrate dev) |
Manuais (scripts SQL versionados) | Automáticas (mas verbosas) |
| Developer Experience | Autocomplete perfeito no VSCode | Nenhum | Médio |
| Performance | Boa (connection pooling nativo) | Ótima (controle total) | Boa |
Exemplo de Type-Safety:
// Exemplo real de implementação no repositório
async findByEmail(email: string) {
const user = await this.prisma.user.findUnique({
where: { email },
select: {
id: true,
name: true,
role: true
}
});
// O TypeScript sabe que 'user' tem apenas id, name e role
return user;
}
// Erro de compilação se tentar acessar campo inexistente
console.log(user.nonExistentField); // TypeScript Error!Trade-off Aceito:
- Queries N+1 podem ocorrer (requer
includeexplícito)
Mitigação:
- Usar
prisma.$queryRawpara otimizações críticas
Decisão: @nestjs/event-emitter para processamento assíncrono de emails, CRON jobs e notificações.
Justificativa:
| Aspecto | EventEmitter ✅ | RabbitMQ/Kafka ❌ |
|---|---|---|
| Custo | Zero (biblioteca nativa NestJS) | RabbitMQ: $10/mês |
| Complexidade | Baixa (decorators simples) | Alta (gerenciar brokers) |
| Persistência | Nenhuma (em memória) | Total (mensagens em disco) |
| Latência | < 1ms (mesma thread) | 5-10ms (rede) |
| Escalabilidade | Limitada (1 servidor) | Ilimitada (cluster) |
Casos de Uso Atuais:
// 1. Envio de emails assíncronos
this.eventEmitter.emit('invite.created', {
userId: 1,
token: 'abc123'
});
// 2. Auditoria de ações críticas
this.eventEmitter.emit('user.deleted', {
userId: 42,
deletedBy: 'admin@example.com'
});
// 3. Limpeza de dados expirados (CRON)
@Cron('0 2 * * *') // Diariamente às 02:00
async cleanupExpiredInvites() {
this.eventEmitter.emit('cleanup.invites');
}Limitação Conhecida:
- Perda de eventos ao reiniciar servidor (retry em memória não persiste)
Referência: Seção 3.2 (Dependências Externas) documenta esta limitação explicitamente.
Decisão: Docker para empacotamento e Docker Compose para orquestração local.
Justificativa:
- Paridade Dev/Prod: Mesmo ambiente PostgreSQL 14-alpine em desenvolvimento e produção
-
Onboarding Rápido: Novo desenvolvedor roda
docker-compose upe está pronto - CI/CD Simples: GitHub Actions builda imagem e faz push para registry
- Gratuito: Docker Desktop é free para uso educacional
docker-compose.yml (Desenvolvimento):
services:
postgres:
image: postgres:14-alpine
environment:
POSTGRES_DB: qualeider_db
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
ports:
- "5432:5432"
backend:
build: .
ports:
- "8080:8080"
depends_on:
- postgres
environment:
DATABASE_URL: postgresql://postgres:postgres@postgres:5432/qualeider_dbMulti-Stage Build (Otimização):
# Stage 1: Build
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
# Stage 2: Production
FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
CMD ["node", "dist/main.js"]Resultado: Imagem final de 180MB (meta: < 500MB) ✅
Alternativa Descartada:
- Kubernetes: Overhead desnecessário para 1 container (complexidade 10x maior)
Decisão: Todos os payloads HTTP validados via Data Transfer Objects (DTOs) com decorators.
Justificativa:
- Segurança: Previne SQL Injection, XSS, buffer overflow
- Documentação Automática: Swagger gera docs a partir dos decorators
- Fail-Fast: Erros de validação retornam 400 Bad Request antes de chegar ao banco
Exemplo de DTO:
// src/application/dtos/users/create-user.dto.ts
export class CreateUserDto {
@ApiProperty({ description: 'Nome do usuário', example: 'Silva Santos' })
@IsNotEmpty({ message: 'O nome não pode ser vazio.' })
@IsString({ message: 'O nome deve ser uma string.' })
@Length(3, 255, { message: 'O nome deve ter entre 3 e 255 caracteres.' })
name!: string;
@ApiProperty({
description: 'Email do usuário',
example: 'silva.santos@example.com',
})
@IsNotEmpty({ message: 'O email não pode ser vazio.' })
@IsEmail({}, { message: 'O email fornecido não é válido.' })
@Transform(({ value }) => value?.toLowerCase().trim())
email!: string;
@ApiProperty({ description: 'Senha do usuário', example: 'Leite@123' })
@IsNotEmpty({ message: 'A senha não pode ser vazia.' })
@IsString()
@MinLength(8, { message: 'A senha deve ter no mínimo 8 caracteres.' })
// [BR-003] Validação de Senha
@Matches(
/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]+$/,
{
message:
'A senha deve conter pelo menos uma letra maiúscula, uma minúscula, um número e um caractere especial (@$!%*?&).',
},
)
password!: string;Configuração nos Controllers:
// InvitesService (Publisher) - NÃO conhece MailService
this.eventEmitter.emit('invite.created', {
inviteId: invite.id,
token: invite.token,
userEmail: user.email,
associationName: association.name,
});
// InviteEmailListener (Subscriber) - escuta automaticamente
export class InviteEmailListener {
private readonly logger = new Logger(InviteEmailListener.name);
constructor(
private readonly mailService: MailService,
@Inject(IAssociationRepository)
private readonly associationRepository: IAssociationRepository,
) {}
/**
* Quando convite é criado, envia email para o usuário convidado
*/
@OnEvent('invite.created')
async handleInviteCreated(event: InviteCreatedEvent) {
const frontendUrl = process.env.FRONTEND_URL || 'http://localhost:3000';
const acceptUrl = `${frontendUrl}/invites/${event.token}?action=accept`;
const declineUrl = `${frontendUrl}/invites/${event.token}?action=decline`;
try {
this.logger.log(`Enviando email de convite para ${event.userEmail}...`);
await this.mailService.sendInviteEmail(
event.userEmail,
event.userName,
event.associationName,
event.message,
acceptUrl,
declineUrl,
event.expiresAt,
);
this.logger.log(
`Email de convite enviado com sucesso para ${event.userEmail}`,
);
} catch (error) {
this.logger.error(
`Erro ao enviar email de convite para ${event.userEmail}:`,
error,
);
}
}Nota: O projeto usa ValidationPipe em nível de controller com transform: true para converter tipos automaticamente.
Benefícios:
| Aspecto | Sem EventEmitter (Síncrono) | Com EventEmitter (Assíncrono) |
|---|---|---|
| Performance | 3s de resposta (espera envio email) | 100ms (retorna imediatamente) |
| Acoplamento | Service depende de MailService | Completamente desacoplado |
| Resiliência | Erro no email quebra criação | Falha no email não afeta DB |
| Extensibilidade | Difícil adicionar novos listeners | Fácil adicionar Notification, Audit |
| Testabilidade | Precisa mockar MailService | Testa Service isoladamente |
- Performance: Tempo de resposta < 100ms (email enviado em background)
-
Resiliência:
- Falha no envio de email não impede criação do convite
- Sistema de retry automático: 3 tentativas com intervalos de 5min, 15min e 30min
- Falhas definitivas são logadas para processamento manual posterior
-
Segurança: Token único gerado com
crypto.randomBytes(32), expiração em 7 dias -
Rastreabilidade: Evento
invite.createdlogado para auditoria, incluindo tentativas de retry