Repository navigation
Blocos de Construcao e Execucao
⬅ Voltar para Documentação de Arquitetura
A visão de blocos de construção mostra a decomposição estática do sistema em blocos de construção (módulos, componentes, subsistemas) e seus relacionamentos.
No nível mais alto, o QuaLeiDer é um Monólito Modular construído sobre o framework NestJS. O sistema é composto por um único processo de servidor (AppModule) que orquestra diversos módulos de funcionalidade e infraestrutura.
O sistema divide-se em Módulos de Domínio (Features) e Módulos de Infraestrutura (Shared). O diagrama abaixo ilustra as dependências lógicas entre os principais módulos do sistema.

A tabela abaixo descreve as responsabilidades de cada módulo principal identificado na arquitetura.
| Bloco de Construção | Responsabilidade Principal | Colaboradores / Dependências |
|---|---|---|
| Auth Module | Gerencia a autenticação e emissão de tokens. Implementa estratégias Passport (JWT, Local) e Guards globais. | Depende de UsersModule para validar credenciais e JwtService para assinar tokens. |
| Users Module | Gerencia o ciclo de vida dos usuários (Produtores e Associações), perfis e dados cadastrais básicos. | Utiliza PrismaModule para persistência e HashService para segurança de senhas. |
| DailyCollections Module | (Core Domain) Gerencia o registro de coletas de leite, contendo as regras de negócio mais críticas sobre produção e validação de dados técnicos. | Depende de UsersModule (proprietário) e AnimalsModule (origem do leite). |
| Animals Module | Gerencia o rebanho dos produtores, rastreando características individuais (raça, idade, tipo) e status. | Vinculado fortemente ao UsersModule. |
| Invites Module | Gerencia o fluxo de crescimento viral da plataforma (Associações convidando Produtores). Controla tokens, expiração e envio de emails. | Usa MailModule para comunicação e EventEmitter para processamento assíncrono. |
| Associations Module | Gerencia dados corporativos das associações e visualização agregada de seus membros. | Relaciona-se com UsersModule (membros) e InvitesModule (origem dos convites). |
| Infrastructure Module | Fornece implementações concretas para as interfaces de porta (Ports) da camada de aplicação. Inclui Repositórios, HashService, etc. | Isola dependências externas como bibliotecas de criptografia. |
| Prisma Module | Encapsula o PrismaClient, gerenciando a conexão com o PostgreSQL e tratamento de erros de banco de dados. |
Usado por todos os Repositórios. |
| Mail Module | Abstração sobre o Nodemailer. Responsável pela renderização de templates Handlebars e transporte SMTP. |
Injetado principalmente em Listeners de eventos. |
Cada módulo de funcionalidade (ex: UsersModule) segue ESTRITAMENTE a Clean Architecture, organizando seus componentes internos para separar responsabilidades.
Exemplo: Anatomia do UsersModule
| Componente Interno | Camada (Clean Arch) | Descrição |
|---|---|---|
UsersController |
Presentation | Recebe HTTP, valida DTOs (CreateUserDto) e chama o Service. |
UsersService |
Application | Orquestra a lógica de negócio. Não conhece HTTP nem SQL. Executa regras como "Remover senha do retorno". |
UserEntity |
Domain | Define a estrutura pura do dado e regras invariantes do domínio. |
IUserRepository |
Domain (Port) | Interface que define o contrato de persistência. |
PrismaUserRepository |
Infrastructure (Adapter) | Implementação que usa o PrismaService para traduzir chamadas de domínio em queries de banco. |

Este diagrama ilustra o processo completo de autenticação JWT, desde a validação de credenciais até a geração do token de acesso.
Atores e Componentes:
- User: Usuário (Produtor, Associação) solicitando autenticação
- AuthController: Camada de apresentação (HTTP) que recebe credenciais
- AuthService: Camada de aplicação contendo lógica de autenticação
- UsersService: Serviço responsável por buscar usuários no banco
- JwtService: Serviço de infraestrutura para geração de tokens JWT
- ORM (Prisma): Camada de acesso a dados (PostgreSQL)
- PostgreSQL: Banco de dados relacional
Etapas do Fluxo:
-
Requisição HTTP: User envia
POST /auth/logincom{email, password} -
Validação de Credenciais: AuthService chama
validateUser(email, password) -
Busca de Usuário: UsersService consulta banco via
findByEmail(email) -
Query SQL: Prisma executa
SELECT * FROM "User" WHERE email = ? -
Validação de Senha: AuthService compara senha com
bcrypt.compare(password, hash) -
Remoção de Senha: Campo
passwordé removido do objeto antes de retornar - Geração de Token: AuthService cria payload JWT e solicita assinatura
- Assinatura JWT: JwtService gera token com algoritmo HS256 e secret
- Auditoria: Logger registra autenticação bem-sucedida com email do usuário
-
Resposta HTTP: Retorna
200 OKcom{access_token}válido por 24 horas
Validação de Credenciais:
// AuthService.validateUser()
async validateUser(email: string, password: string): Promise<any> {
const user = await this.userRepository.findByEmail(email);
if (user && (await this.hashService.compare(password, user.password))) {
const { password, ...result } = user;
return result;
}
throw new UnauthorizedException('Credenciais inválidas.');
}Payload do JWT:
// AuthService.login()
const payload = {
email: user.email,
sub: user.id,
associationId: user.associationId,
};
return {
access_token: this.jwtService.sign(payload),
};Configuração do Token:
| Propriedade | Valor | Descrição |
|---|---|---|
| Algoritmo | HS256 (HMAC-SHA256) | Assinatura simétrica |
| Secret | process.env.JWT_SECRET |
Chave secreta do servidor |
| Expiração | 24 horas | Token válido por 1 dia |
| Payload | {email, sub, associationId} |
Dados do usuário (sem informações sensíveis) |
| Stateless | Sim | Servidor não armazena sessão |
1. Usuário Não Encontrado:
POST /auth/login {email: "wrong@example.com", password: "123"}
→ UserRepository.findByEmail() retorna null
→ throw UnauthorizedException("Credenciais inválidas.")
→ Response: 401 Unauthorized
2. Senha Incorreta:
POST /auth/login {email: "user@example.com", password: "WrongPass"}
→ UserRepository.findByEmail() retorna user
→ HashService.compare() retorna false
→ throw UnauthorizedException("Credenciais inválidas.")
→ Response: 401 Unauthorized
Note: Por questões de segurança, ambos os erros retornam a mesma mensagem genérica "Credenciais inválidas" para não revelar se o email existe no sistema.
- Performance: Tempo de resposta < 200ms (validação + geração de token)
-
Segurança:
- Senhas hasheadas com bcrypt (12 rounds)
- JWT assinado com HS256 + secret forte
- Senha nunca retornada ao cliente
- Mensagens de erro genéricas (não revelam se email existe)
- Auditoria: Cada autenticação bem-sucedida é registrada em log com timestamp e email
- Escalabilidade: Autenticação stateless permite balanceamento de carga sem sessão compartilhada
Após autenticação bem-sucedida, o cliente deve incluir o token em todas as requisições protegidas:
GET /animals HTTP/1.1
Host: api.qualeider.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...O token é validado automaticamente pelo JwtAuthGuard em endpoints protegidos com decorator @UseGuards(JwtAuthGuard).

Este documento descreve o processo técnico de registro de uma coleta diária de leite
Atores e Componentes:
- User (Produtor): Produtor de leite registrando a coleta diária
- DailyCollectionsController: Camada de apresentação (HTTP)
- DailyCollectionsService: Camada de aplicação com lógica de negócio e validações
- ORM (Prisma): Camada de acesso a dados (PostgreSQL)
- PostgreSQL: Banco de dados relacional
Etapas do Fluxo:
-
Requisição HTTP: Produtor envia
POST /daily-collectionscom dados da coleta -
Validações de Pré-requisitos:
- Produtor existe e está ativo
-
Persistência: 2 operações SQL executadas em transação:
-
INSERT INTO "DailyCollection"(coleta principal)
-
-
Resposta HTTP: Retorna
201 Createdcom dados da coleta
-
Performance:
- Tempo médio de resposta: 250ms
- Meta: < 300ms para 95% das requisições
- 2 queries de validação + 1 INSERT atômico
-
Atomicidade:
- Transação Prisma garante criação de coleta + relacionamentos
- Rollback automático em caso de falha
-
Rastreabilidade:
- Histórico completo de coletas por produtor
- Dados técnicos para análise de produtividade (TO DO)
-
Validação Rigorosa:
- validações de negócio antes de persistir
- Garante integridade referencial
- Previne dados inconsistentes no banco