Skip to content

GitLab

Last edited by João Henrique Pires Bergallo
Page history

Arquitetura

Home Escopo Processo Sprints Design Arquitetura Repositórios Banco de Dados

Descrição

Esta seção irá abordar os detalhes sobre a arquitetura selecionada para o backend e frontend, além da informações relacionadas ao deploy.

Sumário

Arquitetura geral da aplicação

Baseando-se no que foi planejado para o nosso banco de dados, levantamento dos requisitos e o entendimento geral do time sobre o projeto a ser desenvolvido, optamos por uma arquitetura de Cliente-Servidor, onde há uma separação entre o frontend e backend.

O frontend é responsável por apresentar a interface ao usuário e interagir com o backend via chamadas de API. Já o backend por sua vez, gerencia a lógica de negócios, processamento de dados e interações com o banco de dados.

Além disso a estrutura conta com módulos que facilita a reutilização de código e melhor organização do projeto. Ao construirmos a arquitetura desta maneira permitimos uma escalabilidade maior, fácil manutenção e um desenvolvimento mais ágil para cada parte do sistema.

Deploy

Deploy é o processo de colocar no ar a aplicação pronta. No nosso fluxo, o código é construído em uma pipeline de CI/CD (Github Actions), que gera as imagens de backend, frontend, migrações e banco otimizado e publica tudo no Docker Hub. O Ansible então atualiza os clusters Docker Swarm em duas nuvens: AWS (EC2 em us-east-2/Ohio) e Azure (VMs em us-east-2). Na AWS usamos S3 para armazenamento e SES para e-mail; no Azure a infraestrutura é criada com Terraform, com o estado no Blob Storage. O tráfego é roteado pelo Traefik, a observabilidade fica com Prometheus/Grafana, e Metabase e Umami dão suporte a BI e analytics. A camada de domínio é gerenciada pela Cloudflare (com registros no registro.br), garantindo publicação automatizada, redundância multi-cloud e alta disponibilidade.

Diagrama de Deploy

image

AWS

A Amazon Web Services (AWS) compõe parte da infraestrutura em nuvem do ambiente produtivo. Nessa provedora são executadas instâncias EC2 que integram um cluster Docker Swarm, além de serviços de apoio, como S3 (armazenamento de objetos) e SES (e-mail transacional). A adoção da AWS prioriza elasticidade, disponibilidade e integração com serviços gerenciados.

EC2

O Amazon EC2 oferece capacidade de computação sob demanda para a execução dos contêineres. As instâncias participam de um Docker Swarm com balanceamento de carga nativo, permitindo escalar serviços como Backend, Webpage, Traefik, Prometheus, Grafana, Metabase e Umami conforme a demanda.

S3

O Amazon S3 é utilizado para armazenamento de objetos com alta durabilidade e versionamento, adequado para arquivos estáticos, mídias e artefatos do sistema, bem como para distribuição de conteúdo de baixa latência quando integrado à camada de borda.

SES

O Amazon Simple Email Service (SES) é empregado para o envio de e-mails transacionais e notificações, com suporte a autenticações SPF/DKIM e monitoramento de reputação.

Azure

A Microsoft Azure hospeda um segundo cluster Docker Swarm composto por duas VMs, proporcionando redundância geográfica e continuidade de negócio. A infraestrutura é provisionada por Terraform, cujo estado permanece em Azure Blob Storage, assegurando controle de mudanças e reprodutibilidade.

VMs (Compute)

As máquinas virtuais da Azure espelham a pilha de serviços executada na AWS (Database, Backend, Webpage, Traefik, Prometheus, Grafana, Metabase e Umami), elevando a resiliência do ambiente.

Blob Storage (estado do Terraform)

O Azure Blob Storage armazena o state do Terraform de maneira centralizada e segura, evitando divergências de configuração entre execuções.

Backend

Repositório: https://tools.ages.pucrs.br/pro-mata/backend

Definições de linguagem e bibliotecas

  • NestJS — Framework Node.js para construção de APIs escaláveis com injeção de dependência, módulos, controladores e serviços.
  • TypeScript — Superset tipado de JavaScript, adotado integralmente no projeto (tsconfig.json com target: ES2023, emitDecoratorMetadata, experimentalDecorators).
  • npm — Gerenciador de pacotes e scripts de desenvolvimento (build, start, testes, prisma).
  • Prisma ORM — Mapeamento objeto-relacional para PostgreSQL. Cliente gerado em generated/prisma, schema em prisma/schema.prisma, migrações em prisma/migrations.
  • Zod / nestjs-zod — Esquemas e DTOs tipados/validados (pipes globais via ZodValidationPipe).
  • JWT (@nestjs/jwt) — Emissão e verificação de tokens para autenticação.
  • argon2 — Hashing e verificação de senhas com argon2id.
  • @nestjs/swagger — Geração e exposição de documentação Swagger (/api) com esquema Bearer JWT.
  • Jest / ts-jest / supertest — Testes unitários e de integração (e2e).
  • ESLint / Prettier — Lint e formatação padronizada.
  • @umami/node — Coleta de analytics de eventos de aplicação (módulo dedicado).

Módulos do Sistema

  • Analytics
    Responsável pela integração com o Umami. Inicializa o cliente de analytics, publica eventos (ex.: trackHello, trackPasswordChange) e evita execução em ambientes de test/CI. Parametrizado por UMAMI_URL e UMAMI_WEBSITE_ID.

  • Auth
    Autenticação baseada em JWT e autorização por papéis.

    • AuthGuard: extrai e valida token, carrega o usuário e rejeita tokens inválidos.
    • RoleGuard: aplica controle de acesso via decorator @Roles(...) com mapeamento de hierarquias (ROLE_MAP).
    • DTOs com Zod para login, criação de usuário, troca de senha e fluxo de recuperação de senha.
    • Senhas: argon2id para hash e verificação; comparação constante para verificação de confirmação.

  • Database
    Módulo global que expõe o PrismaClient (via DatabaseService). Realiza conexão na inicialização do módulo e desconexão ordenada no encerramento, com logs de status.

  • User
    Operações de perfil e administração de usuários: atualização parcial com DTOs Zod, inativação lógica (active: false), busca com filtros, e endpoints protegidos por @Roles.

  • Experience
    Endpoints de CRUD para experiências (campos como categoria, capacidade, preço, horários/WeekDay, etc.), com rotas admin e públicas. Validações e transformações de tipos via Zod.

Frontend

Repositório: https://tools.ages.pucrs.br/pro-mata/frontend

Definições de Tecnologias e Bibliotecas

  • React 19 — Construção de interfaces declarativas com componentes reutilizáveis.
  • TypeScript — Tipagem estática (configuração em tsconfig.json, moduleResolution: "bundler", baseUrl, paths @/*).
  • Vite 6 — Dev server e build otimizados; plugin @tanstack/router-plugin com autoCodeSplitting e geração de src/routeTree.gen.ts; plugin @tailwindcss/vite.
  • Tailwind CSS (v4) — Utilitários CSS, tokens/temas em src/styles/globals.css (variações claro/escuro).
  • TanStack Router — Roteamento file-based em src/routes/**, com beforeLoad/guards, code-splitting e devtools.
  • TanStack Query — Cache e invalidação de dados; QueryClient injetado no contexto do Router.
  • shadcn/ui + Radix UI — Componentes acessíveis (dialog, popover, select, table, sheet, etc.) com variantes (CVA).
  • Zod + React Hook Form — Esquemas de validação tipados e formulários controlados.
  • Zustand — Estado leve e local (stores de UI e filtros).
  • Axios — Cliente HTTP com interceptor de autenticação (Bearer).
  • ESLint/Prettier — Lint e formatação padronizada.
  • Vitest — Testes unitários com run, watch e UI.
  • Node.js / npm — Toolchain e scripts de desenvolvimento.

Módulos do Sistema

  • App (Bootstrap) — Inicialização do Router/QueryClient, importação de estilos globais e provisionamento de toasts (Sonner).
  • Rotas (TanStack Router) — Arquitetura file-based; rotas públicas em /(index) e seção administrativa em /admin com beforeLoad para verificação de permissões.
  • Camada de API — Módulos api/* para operações de domínio (usuários, experiências, CEP), baseados em core/api.ts.
  • Formulários e Validação — Integração Zod + React Hook Form com esquemas tipados para autenticação, cadastro e operações administrativas.
  • UI/Design System — Conjunto de componentes shadcn/ui com acessibilidade Radix e variantes (CVA).
  • Estado e Hooks — Zustand para estados locais; hooks para autenticação, filtros, consultas de CEP, fluxos de cadastro/recuperação, etc.
  • Utilitários — Funções de máscaras, construção de query params e filtros seguros.