Skip to content

GitLab

Last edited by Saccilotto
Page history

Arquitetura

Arquitetura

Home Escopo Processo Sprints Design Arquitetura Repositorios Gerencia 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 Atual (AWS Simplificado - Produção)

O processo de deploy atual utiliza GitHub Actions (CI/CD) com AWS como provedor principal:

Pipeline CI/CD:

  • Trigger: Merge em main
  • Build: Compilação TypeScript, testes (Jest/Vitest), lint
  • Publicação: Imagens Docker publicadas no Docker Hub
  • Deploy:
    • Frontend: AWS S3 static hosting (TanStack Router - SPA)
    • Backend: AWS EC2 (Ohio - us-east-2) com Docker containers
    • Database: PostgreSQL (container na EC2)
    • Serviços: Umami Analytics, Metabase BI (containers na EC2)

Motivação da arquitetura simplificada:

  • Redução de complexidade operacional
  • Vantagens do S3 para Single Page Applications (React + TanStack Router)
  • Descentralização de conhecimento técnico (evitar bus factor)
  • Facilidade de manutenção para toda a equipe

Infraestrutura de Backup (Multi-Cloud - Standby)

Repositório: https://github.com/Saccilotto/pro-mata-infra (pessoal - André Sacilotto Santos, AGES IV)

Stack Backup:

  • IaC: Terraform (provisionamento Azure VMs / AWS EC2)
  • CaC: Ansible (configuração Docker Swarm)
  • Orquestração: Docker Swarm (balanceamento nativo)
  • Proxy/LB: Traefik v3 (reverse proxy + SSL Let's Encrypt)
  • Observabilidade: Prometheus + Grafana
  • Multi-Cloud: Azure VMs (state em Blob Storage) + AWS EC2 (state em S3)
  • CDN/WAF: Cloudflare
  • Domínio: registro.br

Status:

  • Standby: Infraestrutura funcional, não utilizada em produção
  • Ativação: Configuração de variáveis de ambiente (< 4h para full deploy)
  • Sincronização: Consome imagens Docker Hub atualizadas automaticamente
  • Propósito: Redundância geográfica, tolerância a falhas, continuidade de negócio

Gestão de Riscos:

  • Mitiga risco de falha crítica em infraestrutura AWS (probabilidade baixa, impacto alto)
  • Recovery Time Objective (RTO): < 4h
  • Trade-off documentado: simplicidade operacional vs. redundância ativa

Diagrama de Deploy

image

AWS (Produção Atual)

A Amazon Web Services (AWS) é o provedor de nuvem principal do ambiente produtivo. A arquitetura atual prioriza simplicidade operacional sobre redundância multi-cloud ativa.

EC2 (Compute - Backend e Serviços)

  • Região: us-east-2 (Ohio)
  • Propósito: Execução de containers Docker
  • Serviços hospedados:
    • Backend (NestJS + Node.js 22)
    • PostgreSQL 15 (containerizado)
    • Umami Analytics
    • Metabase BI
  • Deploy: Imagens Docker do Docker Hub (CI/CD GitHub Actions)

S3 (Static Hosting - Frontend)

  • Propósito: Hospedagem estática do frontend (SPA)
  • Tecnologia: React 19 + TanStack Router (file-based routing)
  • Vantagens:
    • Baixa latência para conteúdo estático
    • Custo-benefício para SPAs
    • Sem necessidade de servidor para roteamento client-side
  • Deploy: GitHub Actions publica build otimizado

SES (E-mail Transacional) - TODO

  • Status: Planejado, não implementado
  • Propósito: Envio de e-mails transacionais (confirmações de reserva, recuperação de senha)
  • Recursos: SPF/DKIM, monitoramento de reputação

Azure (Infraestrutura Backup - Standby)

Status: Parte da infraestrutura de backup multi-cloud (não utilizada em produção atual)

A Microsoft Azure faz parte da solução de backup que proporciona redundância geográfica e continuidade de negócio. A infraestrutura é provisionada por Terraform, cujo estado permanece em Azure Blob Storage.

VMs (Compute - Backup)

  • Status: Standby (pronta para ativação)
  • Provisionamento: Terraform
  • Orquestração: Docker Swarm
  • Serviços: Espelha pilha completa (Database, Backend, Frontend, Traefik, Prometheus, Grafana, Metabase, Umami)
  • Propósito: Redundância geográfica, failover em caso de falha crítica AWS

Blob Storage (Estado Terraform)

  • Propósito: Armazenamento centralizado do state do Terraform
  • Benefícios: Controle de mudanças, reprodutibilidade, versionamento
  • Integração: Sincronizado com repositório de infraestrutura backup

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 (Backend)

  • 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 - Frontend

  • 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.