Arquitetura

Home	Escopo	Gerência	Processo	Design	Configuração	Arquitetura	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
Deploy
- Diagrama de Deploy
Containerização
Diagrama do Sistema
Diagrama de Componentes
Backend
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:

O usuário interage com o frontend React
O frontend envia uma requisição HTTP através de uma chamada para a API REST do backend
O backend (FastAPI) processa a requisição e executa a lógica apropriada (validação de dados, autenticação, autorização)
O backend interage com o banco de dados PostgreSQL via SQLAlchemy para armazenar e/ou recuperar dados
O backend retorna uma resposta HTTP/JSON para a requisição
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

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.

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.

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.

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.

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.

Uvicorn é um servidor ASGI lightning-fast, construído em uvloop e httptools. É ideal para executar aplicações FastAPI com alta performance.

Docker é uma plataforma de containerização que permite empacotar aplicações e suas dependências em containers leves e portáteis.

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

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.

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.

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

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.

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.

Lucide React é uma biblioteca de ícones que fornece ícones SVG simples e consistentes para React. É uma alternativa moderna ao Feather Icons.

React Hook Form é uma biblioteca para gerenciamento de formulários em React com mínimo re-renders, validação fácil e melhor performance.

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.

React Router DOM é a biblioteca padrão para roteamento em aplicações React, permitindo navegação entre diferentes páginas/componentes.

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