|
|
|
| [Home](Home) | [**Escopo**](Escopo) | [Processo](Processo) | [Sprints](Sprints) | [Design](Design) | [Arquitetura](Arquitetura) | [Repositórios](Repositórios) | [Banco de Dados](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](#arquitetura-geral-da-aplicação)
|
|
|
|
- [Deploy](#deploy)
|
|
|
|
- [Diagrama de Deploy](#diagrama-de-deploy)
|
|
|
|
- [AWS](#aws)
|
|
|
|
- [Azure](#azure)
|
|
|
|
- [Backend](#backend)
|
|
|
|
- [Definições de Tecnologias](#definições-de-linguagem-e-bibliotecas)
|
|
|
|
- [Módulos do Sistema](#módulos-do-sistema)
|
|
|
|
- [Frontend](#frontend)
|
|
|
|
- [Definições de Tecnologias](#definições-de-tecnologias-e-bibliotecas)
|
|
|
|
- [Módulos do Sistema](#módulos-do-sistema)
|
|
|
|
|
|
|
|
## 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
|
|
|
|
|
|
|
|
|
|
|
|
## 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. |
