./src/swagger.ts: Configuração central da documentação Swagger/OpenAPI, incluindo título, descrição, versão, servidores, autenticação por cookies, CSRF, tags e rota da interface em /apiEvents/docs.

./src/assets: diretório para organizar recursos estáticos adicionais.

• certificate: Logo da Fatec Itu, assinatura da coordenadora e fontes (Poppins e Playfair Display, com as licenças OFL) usadas no PDF do certificado.
• readme: Pasta que irá armazenar nossas fotos para utilizar na documentação ( README )

./src/decorators: Pasta para decorators customizados.

• audit.decorator.ts: Define os decorators @Audit, que descreve como uma rota aparece na auditoria (ação, área, resumo e de onde vem o registro afetado), e @SkipAudit, para chamadas automáticas que não são um ato do usuário, como a renovação da sessão.
• public.decorator.ts: Define um decorator para liberar rotas publicas para usuários não autenticados.
• roles.decorator.ts: Define um decorator para indicar quais perfis de usuário têm permissão para acessar cada endpoint.

./src/guards: Pasta para guards de autenticação e autorização.

• jwt-auth.guard.ts: Garante que apenas requisições autenticadas com token JWT válido sejam aceitas e popula os dados do usuário na requisição.
• roles.guard.ts: Controla acesso a partir do perfil do usuário, liberando endpoints sem restrição e bloqueando quando o perfil não corresponde aos permitidos. Cada acesso negado fica registrado na auditoria.
• roles.guard.spec.ts: Testes do guard: perfil permitido, perfil recusado com registro na auditoria e requisição sem usuário.

./src/modules: A pasta modules reúne todos os módulos da aplicação, cada um em seu próprio diretório para manter lógica, controladores e provedores bem organizados e desacoplados, depois todos importados pelo módulo raiz (AppModule)

• audit: Módulo da trilha de auditoria: registra quem fez o quê, quando e com qual resultado, sem guardar senhas, códigos ou tokens.

  • dto: Data Transfer Objects da listagem (filtros e paginação) e das respostas resumida e detalhada.
  • audit.context.ts: Contexto da requisição (AsyncLocalStorage) que permite aos services informar o responsável, o registro afetado e detalhes extras, como no login ou na otimização de uma imagem.
  • audit.controller.ts: Expõe GET /audit (paginado, do mais recente para o mais antigo, com busca e filtros por resultado, área, ação e período em horário de Brasília) e GET /audit/:id (todos os detalhes), ambos exclusivos do ADMIN.
  • audit.interceptor.ts: Interceptor global que registra cada alteração feita pela API e as rotas marcadas com @Audit: lê o registro antes e depois, calcula o que mudou e guarda o resultado, inclusive quando a operação falha ou é recusada.
  • audit.interceptor.spec.ts: Testes do interceptor: edição com antes/depois, criação, login recusado, erro de regra de negócio, dados informados pelos services, senha como alteração protegida, visualização de lista e rotas com @SkipAudit.
  • audit.module.ts: Módulo global que registra o AuditService, o AuditController e o interceptor.
  • audit-sanitizer.ts: Funções que mascaram senhas, códigos, tokens, hashes e segredos, limitam o tamanho do que é guardado e calculam a diferença campo a campo.
  • audit-sanitizer.spec.ts: Testes do mascaramento, do limite de tamanho e do cálculo do que mudou.
  • audit.service.ts: Grava os registros (uma falha ao gravar nunca desfaz a operação do usuário), monta o retrato de cada registro afetado com os nomes das relações, lista e detalha os registros e apaga os mais antigos que o prazo de retenção.
  • audit.service.spec.ts: Testes da gravação sem credenciais, do retrato dos registros, da paginação com filtros e da retenção.
  • audit.utils.ts: Funções compartilhadas: responsável a partir da sessão, área a partir do controller, resultado a partir do código HTTP e origem da requisição.

• auth: Módulo dedicado a todo o fluxo de autenticação e autorização do usuário.

  • dto: Pasta com os Data Transfer Objects que definem o formato de entrada e saída das requisições de autenticação, em resumo, é a nossa "Tipagem".
  • auth.controller.ts: Expõe os endpoints de me, refresh, logout, request-login, login, request-reset-password e reset-password, gerencia cookies de acesso, refresh, 2FA e redefinição (criados e apagados com as mesmas opções, para serem removidos de verdade) e fornece uma rota própria para renovar sessão sem depender do carregamento inicial do front-end. O pedido de redefinição responde sempre a mesma mensagem, exista ou não o e-mail, e uma sessão encerrada também tem os cookies apagados.
  • auth.controller.spec.ts: Cobre testes de integração do controller, validando cenários de token válido, token expirado, renovação via refresh, sessão encerrada com cookies apagados, ausência de refresh token, logout, login com 2FA, resposta neutra da redefinição e reset de senha
  • auth.service.ts: Encapsula toda a lógica de negócio de autenticação — verificação de usuário, hash de senha, geração e verificação de tokens de acesso, rotação de refresh tokens (sempre com o perfil atual do banco e o sessionVersion; 3 dias sem uso, ou 30 dias com "Lembrar-me"), códigos de 2FA e redefinição de uso único guardados na tabela AuthCode, resposta igual para e-mails existentes ou não, encerramento das sessões na troca de senha, envio de e-mails em segundo plano e limpeza de tokens e códigos expirados
  • auth.service.spec.ts: Testa os fluxos do serviço de autenticação, garantindo comportamento correto em casos de credenciais inválidas, geração de tokens, códigos de uso único (inclusive após reiniciar a API), bloqueio após 5 tentativas, resposta neutra na redefinição, encerramento das sessões, perfil vindo do banco no refresh, revogação e renovação de refresh tokens
  • auth.module.ts: Configura o módulo de autenticação, importa PrismaModule, ConfigModule, JwtModule com chaves RSA carregadas de variáveis de ambiente, e registra AuthService, JwtStrategy e EmailService
  • jwt.strategy.ts: Extrai o JWT do cookie de acesso, valida sua assinatura e expiração usando a chave pública, confere no banco se o usuário existe e se o sessionVersion do token ainda é o atual, e fornece os dados de usuário (id, nome, e-mail e perfil vindo do banco) para os guards

• carousel: Pacote dedicado ao gerenciamento completo das coleções de imagens exibidas em carrossel no sistema, englobando todas as operações de CRUD e apresentação das fotos.

  • dto: Diretório que contém os Data Transfer Objects (CreateCarouselDto, UpdateCarouselDto e CarouselResponseDto) responsáveis por definir a forma dos dados de entrada e saída nas requisições de carrossel.
  • carousel.controller.ts: Define os endpoints REST para listagem (GET /carousel), criação (POST /carousel/post), atualização (PATCH /carousel/patch/:id), atualização apenas do campo de isActive (PATCH patch/toggle/:id) e remoção (DELETE /carousel/delete/:id) dos itens de imagem no carrossel.
  • carousel.controller.spec.ts: Testes de integração do controller, assegurando que cada rota encaminhe corretamente as chamadas ao CarouselService e retorne os códigos HTTP esperados.
  • carousel.service.ts: Implementa a lógica de negócio do carrossel — interage com o PrismaClient para buscar, inserir, alterar e excluir registros na tabela Carousel, e integração com o módulo de Cloudinary para salvar e excluir as imagens na claudinary.
  • carousel.service.spec.ts: Conjunto de testes unitários do serviço, com uma tabela em memória, cobrindo cenários de sucesso e falha para cada método exposto por CarouselService, inclusive a reorganização da ordem e a troca de imagem.
  • carousel.module.ts: Arquivo de configuração do módulo de carrossel, importando PrismaModule e CloudinaryModule, registrando CarouselService e CarouselController no contexto do NestJS. O upload da imagem é tratado pelo ImageUploadInterceptor.

• categories: Pacote dedicado ao gerenciamento completo de categorias, englobando todas as operações de CRUD.

  • dto: Diretório que contém os Data Transfer Objects (CreateCategoryDto, UpdateCategoryDto e CategoryResponseDto) responsáveis por modelar os dados de entrada e saída nas requisições de categorias.
  • categories.controller.ts: Define os endpoints REST para listagem (GET /categories), criação (POST /categories), atualização (PATCH /categories/:id) e remoção (DELETE /categories/:id) de categorias.
  • categories.controller.spec.ts: Testes de integração do controller, garantindo que cada rota encaminhe corretamente as chamadas ao CategoriesService e retorne os códigos HTTP esperados.
  • categories.service.ts: Implementa a lógica de negócio das categorias — interage com o PrismaClient para buscar, inserir, alterar e excluir registros na tabela Category.
  • categories.service.spec.ts: Conjunto de testes unitários do serviço, cobrindo cenários de sucesso e falha para cada método exposto pelo CategoriesService.
  • categories.module.ts: Arquivo de montagem do módulo de categorias, importando o PrismaModule e registrando o CategoriesService e CategoriesController no contexto do NestJS.

• certificates: Módulo responsável por armazenar e exportar a lógica de envio de certificado para os alunos que estão como presentes no evento.

  • certificates.module.ts: Importa o ScheduleModule.forRoot() e o PrismaModule e exporta o service para ser utilizado em outros locais do código
  • certificates.controller.ts: Disponibiliza a rota para validação se o certificado é real ou não e se pertence a pessoa.
  • certificates.service.ts: Toda a lógica para envio do certificado para os alunos que estavam presentes nos eventos do dia anterior, incluindo o desenho do PDF (A4 deitado, com logo, nome do participante, dados do evento, assinatura da coordenadora e QR Code de verificação).

• cloudinary: Exporta a opção de inserir ou remover fotos da cloudinary - ( serviço gratuito para salvar imagens, recomendo: https://cloudinary.com)

  • cloudinary.module.ts: Importa o nosso provider e service e exporta o service para ser utilizado em outros locais do código
  • cloudinary.provider.ts: Configura a conexão com a Cloudinary
  • cloudinary.service.ts: Exporta as funções para subir e deletar uma foto. Envia o arquivo do disco (ou da memória) para a Cloudinary depois de passar pelo otimizador e responde com uma mensagem amigável quando a Cloudinary recusa o envio.
  • image-optimizer.ts: Otimiza apenas imagens acima de 5 MB: reduz para no máximo 2560 px no maior lado e converte para WebP com o sharp. Se o resultado não ficar menor ou a imagem não puder ser processada, envia a original.
  • image-optimizer.spec.ts: Testes do otimizador: imagem leve mantida, imagem pesada reduzida e convertida com o arquivo temporário apagado e arquivo inválido enviado como está.

• common: Concentramos funcionalidades compartilhadas por vários módulos, é nesse nível que ficam componentes que não pertencem a um domínio específico.

  • csrf.controller.ts: Expõe um endpoint para obter o token CSRF do usuário, garantindo que cada chamada realmente venha da aplicação legítima e não de um site mal-intencionado, evitando CSRF.
  • csrf.ts: Cria a proteção CSRF com o csrf-csrf (substituto do csurf, descontinuado), mantendo o mesmo contrato com o front-end: GET /csrf-token devolve o token e toda alteração envia o cabeçalho X-CSRF-Token.
  • event-clock.ts: Converte o momento atual para o horário de Itu no mesmo formato em que os horários dos eventos são gravados, para que as comparações com "agora" (eventos públicos, datas disponíveis, inscrições e certificados) não dependam do fuso horário do servidor.
  • image-upload.interceptor.ts: Interceptor usado nos uploads de imagem (eventos, carrossel e foto de perfil): grava o arquivo na pasta temporária em vez da memória, aceita só JPG, PNG, WEBP, GIF ou AVIF conferindo os primeiros bytes do arquivo e apaga o arquivo temporário ao fim da requisição. Não limita o tamanho.
  • image-upload.interceptor.spec.ts: Testes da identificação das imagens pelos primeiros bytes e da recusa de arquivos que não são imagem.

• courses: Pacote dedicado ao gerenciamento completo de cursos, englobando todas as operações de CRUD.

• dto: Diretório que contém os Data Transfer Objects (CreateCourseDto, UpdateCourseDto e CourseResponseDto) responsáveis por modelar os dados de entrada e saída nas requisições de cursos.

• courses.controller.ts: Define os endpoints REST para listagem (GET /courses), criação (POST /courses), atualização (PATCH /courses/:id) e remoção (DELETE /courses/:id) de cursos.

• courses.controller.spec.ts: Testes de integração do controller, garantindo que cada rota encaminhe corretamente as chamadas ao coursesService e retorne os códigos HTTP esperados.

• courses.service.ts: Implementa a lógica de negócio das cursos — interage com o PrismaClient para buscar, inserir, alterar e excluir registros na tabela Course.

• courses.service.spec.ts: Conjunto de testes unitários do serviço, cobrindo cenários de sucesso e falha para cada método exposto pelo CoursesService.

• courses.module.ts: Arquivo de montagem do módulo de cursos, importando o PrismaModule e registrando o CoursesService e CoursesController no contexto do NestJS.

• events: Pacote dedicado ao gerenciamento completo de eventos, englobando operações de CRUD, upload de imagem, consulta de disponibilidade de datas e horários e validação de presença por palavra secreta.

  • dto: Diretório com os Data Transfer Objects (CreateEventDto, UpdateEventDto, ValidatePresenceDto e EventResponseDto) responsáveis por definir o formato dos dados de entrada e saída nas requisições de eventos.
  • events.controller.ts: Define os endpoints REST para listagem (GET /events), busca pública por ID (GET /events/:id, sem participantes nem palavra secreta), busca completa por ID para edição (GET /events/manage/:id), consulta das inscrições de um participante por e-mail (GET /events/manage/by-participant-email, apenas para ADMIN, COORDENADOR e AUXILIAR e registrada na auditoria), criação (POST /events/create), atualização parcial (PATCH /events/patch/:id), remoção (DELETE /events/delete/:id), confirmação de presença por palavra secreta e e-mail da inscrição (PATCH /events/:eventId/participants/:participantId/presence, limitada a 10 tentativas por minuto), disponibilidade de datas (GET /events/availability/dates) e disponibilidade de horários (GET /events/availability/times). Todos protegidos por JwtAuthGuard e RolesGuard, com decorator @Roles para perfis ADMIN e COORDENADOR, o ImageUploadInterceptor para o upload de imagem e códigos HTTP apropriados (201 para criação, 200 para remoção), apenas as rotas públicas não necessitam estar autenticadas, como a listagem pública de eventos e a confirmação de presença.
  • events.service.ts: Implementa toda a lógica de negócio de eventos — interage com o PrismaClient para operações de CRUD, valida conflitos de horários para evitar sobreposição, utiliza o CloudinaryService para upload e exclusão de imagens, calcula dinamicamente os slots livres de datas e horários conforme o local e data informados, garante que as rotas públicas retornem apenas os dados públicos do evento e valida a palavra secreta e o e-mail da inscrição para marcar o participante como presente.
  • events.service.spec.ts: Conjunto de testes unitários do EventsService, cobrindo cenários de criação sem arquivo, detecção de sobreposição de horários, criação bem-sucedida com upload de imagem, atualização com e sem novo arquivo (incluindo exclusão e upload no Cloudinary), cálculo de disponibilidade de horários e datas para diferentes locais, remoção de evento com exclusão de imagem, e tratamento de exceções ConflictException e NotFoundException.
  • events.controller.spec.ts: Testes do controller: consulta por e-mail exigindo login e perfil, registro na auditoria, ausência da antiga rota pública e repasse da confirmação de presença.
  • events.module.ts: Arquivo de configuração do módulo de eventos, importando PrismaModule e CloudinaryModule, e registrando EventsService e EventsController no contexto do NestJS.

• locations: Pacote dedicado ao gerenciamento completo de locais, englobando todas as operações de CRUD e servindo como base relacional para o cadastro de eventos.

  • dto: Diretório que contém os Data Transfer Objects (CreateLocationDto, UpdateLocationDto, LocationResponseDto e LocationPublicResponseDto) responsáveis por modelar os dados de entrada e saída nas requisições de locais.
  • locations.controller.ts: Define os endpoints REST para listagem administrativa (GET /locations), listagem pública (GET /locations/publicAllLocations), criação (POST /locations/create), atualização (PATCH /locations/patch/:id) e remoção (DELETE /locations/delete/:id) dos locais cadastrados no sistema.
  • locations.service.ts: Implementa a lógica de negócio dos locais — interage com o PrismaClient para buscar, inserir, alterar e excluir registros na tabela Location, incluindo validações de existência, conflitos de nome duplicado e proteção contra exclusão de locais vinculados a eventos.
  • locations.controller.spec.ts: Testes do controller: listagem pública liberada, repasse das operações ao service e registro na auditoria.
  • locations.service.spec.ts: Testes do service: nomes duplicados, local inexistente e bloqueio da exclusão de locais vinculados a eventos.
  • locations.module.ts: Arquivo de configuração do módulo de locais, importando o PrismaModule e registrando o LocationsService e LocationsController no contexto do NestJS.

• participants: Módulo dedicado ao fluxo completo de inscrição e controle de presença de participantes em eventos

  • dto: Contém os Data Transfer Objects (CreateParticipantDto, UpdateParticipantDto e ParticipantResponseDto) que definem a forma dos dados de entrada e saída nas operações de participantes
  • participants.controller.ts: Expõe os endpoints de cadastro (POST /participants/create) e de atualização de presença (PATCH /participants/patch/:id), aplica JwtAuthGuard e RolesGuard para ADMIN, COORDENADOR e AUXILIAR, e marca a rota de criação como pública
  • participants.controller.spec.ts: Conjunto de testes de integração que valida cadastro público, tentativas de acesso sem autenticação e atualização de presença autorizada
  • participants.service.ts: Encapsula toda a lógica de negócio de inscrição e presença, incluindo verificação de e-mail e RA duplicados por evento, validação de domínio institucional, incremento do contador de participantes, persistência do registro e envio de e-mail de confirmação
  • participants.service.spec.ts: Testes unitários do serviço, cobrindo cenários de conflito de e-mail/RA, criação de participante, atualização de presença e disparo de e-mail de confirmação
  • participants.module.ts: Configura o módulo de participantes importando PrismaModule, declarando ParticipantsService e EmailService como providers, e registrando ParticipantsController como controller

• prisma: Agrupa o PrismaModule (prisma.module.ts) e o PrismaService (prisma.service.ts), centralizando a integração do Prisma no NestJS.

  • prisma.module.ts: Define e exporta globalmente o módulo do Prisma no NestJS, registrando o PrismaService como provedor para permitir injeção em qualquer parte da aplicação.
  • prisma.service.ts: Estende o PrismaClient, gerenciando automaticamente a conexão ao banco de dados ao inicializar e desconectar no ciclo de vida do módulo.

• users: Módulo responsável por todas as operações de CRUD de usuários.

  • dto: Pasta com os Data Transfer Objects que definem o formato de entrada e saída das requisições de usuários, em resumo, é a nossa "Tipagem".
  • users.controller.ts: Expõe os endpoints de get, post, patch e delete para o crud de usuários.
  • users.controller.spec.ts: Testes de integração do controller, garantindo que cada rota invoque corretamente o UsersService.
  • users.service.ts: Lógica de negócio do módulo de usuários, tratando as requisições que chegam nas rotas do controller, buscando todos os usuários, registrando, atualizando e removendo. Ao trocar a senha ou o perfil de um usuário, aumenta o sessionVersion e revoga os refresh tokens, encerrando na hora todas as sessões abertas dele.
  • users.service.spec.ts: Testes unitários do UsersService, cobrindo cenários de sucesso e erro para cada método.
  • users.module.ts: Configura o UsersModule, importando PrismaModule e ConfigModule, e registrando UsersService e UsersController.

• ./src/services: Reúne classes injetáveis que encapsulam lógica de negócio, utilitários e integrações externas.

• email.service.ts: Temos as configurações para o envio de email e o método send que por onde realmente vamos utilizar para o envio dos e-mails