Skip to content

GitLab

Arquitetura · Changes

Page history
Update Arquitetura authored by Maurício Gaspary's avatar Maurício Gaspary
Show whitespace changes
Inline Side-by-side
Arquitetura.md 0 → 100644
View page @ 6bc23608
| [Home](home) | [Escopo](escopo) | [Gerência](Gerência) | [Processo](processo) | [Design](design) | [Configuração](configuração) | [Arquitetura](arquitetura) | [Banco de Dados](Banco de Dados)
|-|-|-|-|-|-|-|-|
## Descrição
Esta seção aborda os detalhes sobre a arquitetura selecionada para o backend e frontend da Plataforma de Inovação de Caxias do Sul (BAH), além das 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)
- [Containerização](#containerização)
- [Diagrama do Sistema](#diagrama-do-sistema)
- [Diagrama de Componentes](#diagrama-de-componentes)
- [Backend](#backend)
- [Frontend](#frontend)
## 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 clara 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 REST. Já o **backend** por sua vez, gerencia a lógica de negócios, processamento de dados e interações com o banco de dados PostgreSQL.
A arquitetura utiliza uma abordagem modular 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.
### Principais características arquiteturais:
- **Separação de responsabilidades**: Frontend (React) e Backend (FastAPI) independentes
- **API RESTful**: Comunicação padronizada via HTTP/JSON
- **Containerização**: Uso do Docker para facilitar deploy e desenvolvimento
- **Banco de dados relacional**: PostgreSQL para persistência de dados
- **Migrações automatizadas**: Alembic para controle de versão do banco de dados
## Deploy
Deploy consiste no processo de colocar no ar uma aplicação já concluída. Ele pode ocorrer durante várias fases do projeto, bem como após a sua conclusão. A aplicação BAH utiliza containerização Docker para facilitar o processo de deploy e garantir consistência entre ambientes de desenvolvimento, teste e produção.
### Estratégia de Deploy
- **Containerização**: Aplicação empacotada em containers Docker
- **Orquestração**: Docker Compose para gerenciar múltiplos serviços
- **Banco de dados**: PostgreSQL em container separado
- **Migrações**: Processo automatizado via Alembic
- **Dados iniciais**: Script de seed para popular dados básicos
### Diagrama de Deploy
## Containerização
A aplicação utiliza Docker para containerização, proporcionando:
### Benefícios
- **Consistência de ambiente**: Mesmas dependências em dev/test/prod
- **Isolamento**: Cada serviço em seu próprio container
- **Escalabilidade**: Fácil replicação de serviços
- **Portabilidade**: Execução em qualquer ambiente que suporte Docker
### Serviços Docker
- **db**: PostgreSQL 15 Alpine
- **migrate**: Execução das migrações do banco
- **seed**: Inserção de dados iniciais
- **app**: Aplicação FastAPI principal
## Diagrama do Sistema
O diagrama apresenta a maneira que as camadas do sistema se comunicam. O sistema BAH funciona da seguinte maneira:
**Fluxo de funcionamento:**
1. O usuário interage com o frontend React
2. O frontend envia uma requisição HTTP através de uma chamada para a API REST do backend
3. O backend (FastAPI) processa a requisição e executa a lógica apropriada (validação de dados, autenticação, autorização)
4. O backend interage com o banco de dados PostgreSQL via SQLAlchemy para armazenar e/ou recuperar dados
5. O backend retorna uma resposta HTTP/JSON para a requisição
6. O frontend processa a resposta e atualiza a interface do usuário conforme esperado
## Diagrama de Componentes
O diagrama de componentes da aplicação apresenta a maneira que as classes e módulos do sistema estão organizados, levando em consideração as interfaces e componentes criados.
## Backend
https://tools.ages.pucrs.br/bah-plataforma-de-inova-o-de-caxias-do-sul/bah-backend
### Definições de Tecnologias
<table align="center">
<tr><td align="center">
**FastAPI** é um framework web moderno e de alta performance para construção de APIs com Python 3.7+ baseado em type hints padrão do Python. Oferece validação automática de dados, documentação interativa automática e alta performance comparável ao NodeJS.
<img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/fastapi/fastapi-original.svg" alt="FastAPI" width="64" height="64">
**SQLAlchemy** é o toolkit SQL mais popular do Python e Object Relational Mapper que oferece aos desenvolvedores de aplicações toda a potência e flexibilidade do SQL. Fornece um conjunto completo de padrões de persistência empresarial bem conhecidos.
<img src="https://raw.githubusercontent.com/devicons/devicon/master/icons/sqlalchemy/sqlalchemy-original-wordmark.svg" alt="SQLAlchemy" width="128" height="64">
**Alembic** é uma ferramenta de migração de banco de dados para SQLAlchemy. Permite criar, gerenciar e aplicar migrações de esquema de banco de dados de forma controlada e versionada.
<img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/python/python-original.svg" alt="Alembic (Python)" width="64" height="64">
**Pydantic** é uma biblioteca de validação de dados que usa type hints do Python. Garante que os dados de entrada estejam no formato correto e facilita a serialização/deserialização de dados.
<img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/python/python-original.svg" alt="Pydantic (Python)" width="64" height="64">
**PostgreSQL** é um sistema de banco de dados objeto-relacional (ORDBMS) baseado no POSTGRES, desenvolvido na Universidade da Califórnia em Berkeley. É conhecido por sua confiabilidade, robustez de recursos e performance.
<img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/postgresql/postgresql-original.svg" alt="PostgreSQL" width="64" height="64">
**Uvicorn** é um servidor ASGI lightning-fast, construído em uvloop e httptools. É ideal para executar aplicações FastAPI com alta performance.
<img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/python/python-original.svg" alt="Uvicorn (Python)" width="64" height="64">
**Docker** é uma plataforma de containerização que permite empacotar aplicações e suas dependências em containers leves e portáteis.
<img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/docker/docker-original.svg" alt="Docker" width="64" height="64">
</td></tr>
</table>
### Módulos do Sistema
A estrutura do backend foi organizada seguindo os princípios de Clean Architecture e separação de responsabilidades:
```
bah-backend/
├── app/
│ ├── config/ # Configurações da aplicação
│ │ ├── database.py # Configuração do banco de dados
│ │ ├── integration_settings.py # Configurações de integrações
│ │ └── settings.py # Configurações gerais
│ ├── controllers/ # Controladores/Endpoints
│ │ ├── admin_controller_example.py
│ │ ├── admin_iniciativa_controller.py
│ │ └── iniciativa_controller.py
│ ├── models/ # Modelos de dados (SQLAlchemy)
│ │ ├── base.py # Modelo base
│ │ ├── contato_model.py
│ │ ├── iniciativa_model.py
│ │ ├── organizador_model.py
│ │ ├── tag_model.py
│ │ └── usuario_model.py
│ ├── repositories/ # Camada de acesso a dados
│ │ ├── admin_iniciativa_repository.py
│ │ └── iniciativa_repository.py
│ ├── routes/ # Definição de rotas da API
│ │ ├── admin_iniciativa_route.py
│ │ └── iniciativa_route.py
│ ├── schemas/ # Schemas Pydantic para validação
│ │ ├── admin_iniciativa_schemas.py
│ │ └── iniciativa_schema.py
│ ├── services/ # Lógica de negócio
│ │ ├── admin_iniciativa_service.py
│ │ └── iniciativa_service.py
│ ├── scripts/ # Scripts utilitários
│ │ └── seed.py # Script para popular dados iniciais
│ └── utils/ # Utilitários
│ └── helpers.py
├── migrations/ # Migrações do banco de dados (Alembic)
├── tests/ # Testes automatizados
└── ai-search/ # Módulo de busca inteligente
```
## Frontend
https://tools.ages.pucrs.br/bah-plataforma-de-inova-o-de-caxias-do-sul/bah-frontend
### Definições de Tecnologias
<table align="center">
<tr><td align="center">
**React 19** é uma biblioteca front-end de JavaScript, utilizada para definir a parte lógica e criar componentes reutilizáveis para aplicações web de página única. A versão 19 inclui melhorias significativas em performance e novas funcionalidades.
<img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/react/react-original.svg" alt="React" width="64" height="64">
**TypeScript** é uma linguagem de programação de código aberto desenvolvida pela Microsoft. É um superconjunto sintático estrito de JavaScript e adiciona tipagem estática opcional à linguagem, proporcionando melhor experiência de desenvolvimento e menos erros.
<img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/typescript/typescript-original.svg" alt="TypeScript" width="64" height="64">
**Vite** é uma ferramenta de construção front-end moderna que melhora significativamente a experiência de desenvolvimento. Ele serve código via módulos ES nativos, permitindo um início rápido do servidor e substituição de módulos a quente (HMR).
<img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/vite/vite-original.svg" alt="Vite" width="64" height="64">
**Tailwind CSS v4** é uma estrutura CSS de código aberto utility-first. A principal característica desta biblioteca é que, ao contrário de outros frameworks CSS como Bootstrap, ela fornece classes utilitárias de baixo nível para construir designs personalizados.
<img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/tailwindcss/tailwindcss-original.svg" alt="Tailwind CSS" width="64" height="64">
**shadcn/ui** é uma coleção de componentes reutilizáveis construídos usando Radix UI e Tailwind CSS. Oferece componentes acessíveis e totalmente customizáveis que podem ser copiados e colados diretamente no projeto.
<img src="https://ui.shadcn.com/favicon.ico" alt="shadcn/ui" width="64" height="64">
**Lucide React** é uma biblioteca de ícones que fornece ícones SVG simples e consistentes para React. É uma alternativa moderna ao Feather Icons.
<img src="https://raw.githubusercontent.com/lucide-icons/lucide/main/docs/public/logo.light.svg" alt="Lucide React" width="64" height="64">
**React Hook Form** é uma biblioteca para gerenciamento de formulários em React com mínimo re-renders, validação fácil e melhor performance.
<img src="https://react-hook-form.com/images/logo/react-hook-form-logo-only.svg" alt="React Hook Form" width="64" height="64">
**Zod** é uma biblioteca de declaração e validação de dados TypeScript-first. Permite criar schemas com os requisitos de dados que você deseja validar, garantindo type safety em tempo de compilação e runtime.
<img src="https://github.com/colinhacks/zod/raw/main/logo.svg" alt="Zod" width="64" height="64">
**React Router DOM** é a biblioteca padrão para roteamento em aplicações React, permitindo navegação entre diferentes páginas/componentes.
<img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/react/react-original.svg" alt="React Router" width="64" height="64">
</td></tr>
</table>
### Diagrama de Fluxo
### Módulos do Sistema
A estrutura do frontend foi organizada seguindo boas práticas do React e separação de responsabilidades:
```
bah-frontend/
├── src/
│ ├── components/ # Componentes reutilizáveis
│ │ └── ui/ # Componentes UI (shadcn/ui)
│ ├── contexts/ # Contextos React (estado global)
│ ├── lib/ # Utilitários e configurações
│ ├── pages/ # Páginas/Telas da aplicação
│ ├── assets/ # Recursos estáticos (imagens, ícones)
│ ├── App.tsx # Componente principal
│ ├── main.tsx # Ponto de entrada da aplicação
│ └── index.css # Estilos globais
├── public/ # Arquivos públicos
├── package.json # Dependências e scripts
├── vite.config.ts # Configuração do Vite
├── tailwind.config.js # Configuração do Tailwind CSS
└── tsconfig.json # Configuração do TypeScript
```
### Principais funcionalidades:
- **Componentização**: Componentes reutilizáveis e modulares
- **Gerenciamento de Estado**: React Context e useState/useEffect
- **Roteamento**: React Router para navegação SPA
- **Validação**: React Hook Form + Zod para formulários
- **Estilização**: Tailwind CSS para design responsivo
- **Type Safety**: TypeScript para segurança de tipos
- **Build Otimizado**: Vite para desenvolvimento e build de produção