Arquitetura.md

@@ -13,4 +13,111 @@
 </table>
 
 # Sumário
-[[_TOC_]]
+[[_TOC_]]
\ No newline at end of file
+
+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
+
+![diagrama_arquitetura_revforce](uploads/aef227eaa9b70a13ce20eab80f89d74c/diagrama_arquitetura_revforce.png)
+
+## 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.
\ No newline at end of file