Sumário

• Sumário
  • Diagrama Geral de Arquitetura
  • Visão de Alto Nível
  • Arquitetura do Backend
    • Principais Camadas
  • Arquitetura do Frontend
    • Descrição das Pastas
  • Conclusão

Esta página descreve, a arquitetura geral do projeto RevForce — incluindo a organização do backend (FastAPI/Python) e do frontend (React/TypeScript). A ideia é dar uma visão clara dos componentes, das camadas envolvidas e de como tudo se conecta.

Diagrama Geral de Arquitetura

Visão de Alto Nível

1. O usuário carrega a página do frontend (HTML, CSS e JS) via CDN.

   • O CloudFront busca e entrega os arquivos estáticos armazenados no S3 diretamente ao navegador.

2. O React inicializa e faz uma chamada ao backend (FastAPI) para obter dados.

   • A requisição é enviada ao endpoint da API na instância EC2 para obter as informações iniciais.

3. O backend recebe a requisição, valida, executa lógica de negócio, acessa o PostgreSQL e retorna um JSON.

   • O FastAPI processa parâmetros, consulta o banco e devolve a resposta em formato JSON.

4. O frontend renderiza as informações na tela.

   • O React atualiza os componentes e exibe os dados de forma dinâmica, sem recarregar a página inteira.

Arquitetura do Backend

Padrão adotado: Arquitetura em camadas (Layered Architecture), inspirada em Clean Architecture.
Benefícios resumidos:

• Separação de responsabilidades: cada camada trata de uma preocupação específica (API, validação, regras de negócio, persistência).
• Manutenção facilitada: mudanças em regras de negócio ou acesso a dados não afetam diretamente as rotas nem os modelos de dados.
• Testabilidade: serviços podem ser testados isoladamente, repositórios podem ser mockados nos testes.

Principais Camadas

1. routers/ (Controllers / Camada de API)

   • Define os endpoints HTTP com FastAPI (@router.get, @router.post etc.).
   • Recebe requisições, extrai parâmetros, chama serviços e retorna respostas.

2. schemas/ (DTOs / Validação)

   • Modelos Pydantic para validar/serializar dados de entrada e saída (requests/responses).
   • Garante que somente dados válidos cheguem à camada de serviços.

3. services/ (Lógica de Negócio)

   • Implementa regras de negócio e orquestra chamadas aos repositórios.
   • Exemplos: validações complexas, execução de processos transacionais, coordenação de múltiplos repositórios.

4. repositories/ (Data Access / Persistência)

   • Métodos que executam operações CRUD e consultas SQL no banco (PostgreSQL) usando ORM (por exemplo, SQLAlchemy).
   • Responsável por abstrair detalhes de acesso ao banco, retornando objetos de modelo.

5. models/ (ORM Models / Definição de Tabelas)

   • Classes que mapeiam tabelas e relacionamentos do PostgreSQL.
   • Ex.: User, Campaign, Account com colunas, chaves estrangeiras e índices.

6. config/ (Configurações)

   • Lê variáveis de ambiente e define parâmetros de aplicação (string de conexão, segredos, CORS, loggers).

7. scripts/ (Scripts Auxiliares)

   • Tarefas de manutenção, migrações customizadas ou ETL, seed de dados iniciais, geração de relatórios via CLI.

8. main.py (Entry Point / Inicialização)

   • Cria instância FastAPI(), registra os routers, configura middlewares, eventos de startup/shutdown e executa o servidor.

Arquitetura do Frontend

O frontend em React/TypeScript segue uma organização feature-based que separa responsabilidades:

Descrição das Pastas

1. main.tsx

   • Ponto de entrada da aplicação: renderiza <App />, configura provedores (por exemplo, roteamento, contexto de autenticação).

2. routes/

   • Define as rotas principais com React Router (páginas como Login, Dashboard, Relatórios).

3. components/

   • Componentes reutilizáveis de interface (botões, cards, tabelas, formulários, modais).

4. api/

   • Funções que fazem chamadas HTTP ao backend (FastAPI), centralizando URL base, interceptors e tratamento de erros.

5. hooks/

   • Hooks customizados (ex.: useAuth, useFetchData, useDebounce) para compartilhar lógica de estado e efeitos.

6. lib/

   • Funções utilitárias e constantes de aplicação (formatadores de data, validadores, helpers).

7. assets/

   • Imagens, ícones, fontes e outros arquivos estáticos específicos do frontend.

8. Arquivos de Configuração

   • index.css: estilos globais.
   • routeTree.gen.ts: tipagens ou roteamento gerado (dependendo de alguma ferramenta de geração automática).
   • vite-env.d.ts: tipagens adicionais para o Vite e TypeScript.

Conclusão

A arquitetura do RevForce se apoia em:

• Backend: camada de API (routers), validação (schemas), lógica de negócio (services), acesso a dados (repositories) e modelos (models), permitindo um código organizado, de fácil manutenção e testável.
• Frontend: estrutura feature-based em React/TypeScript, separando rotas, componentes, chamadas à API, hooks e utilitários para garantir modularidade e escalabilidade.
• Integração: o frontend consome APIs FastAPI, enquanto pipelines CI/CD (GitLab) fazem build dos bundles e imagens Docker, mantendo o ambiente de produção sempre atualizado.

Essa combinação de camadas e responsabilidades assegura que cada parte do sistema tenha seu foco claro, facilitando a colaboração entre equipes e mantendo alta qualidade de código.