diff --git a/docs/adr/0001-banco-fora-do-cluster.md b/docs/adr/0001-banco-fora-do-cluster.md new file mode 100644 index 0000000..92ef813 --- /dev/null +++ b/docs/adr/0001-banco-fora-do-cluster.md @@ -0,0 +1,37 @@ +# ADR 0001 - Banco de Dados PostgreSQL fora do Cluster Kubernetes (Dados / Persistência) + +## Status +Aceito (Accepted) + +## Data +2026-08-05 + +## Contexto +A API precisa salvar dados de pedidos e itens de forma permanente. Como contêineres são efêmeros, qualquer reinicialização de pod causaria perda total do histórico de transações se o banco de dados rodasse localmente no cluster. +Além disso, o time é pequeno e não há DBA dedicado para gerenciar backups diários, segurança e alta disponibilidade na mão. + + + +## Alternativas Consideradas + +### Alternativa 1: PostgreSQL autogerenciado no cluster (StatefulSet) +Subir um contêiner Postgres nativo usando recursos do Kubernetes como PersistentVolumes (PV) e PersistentVolumeClaims (PVC). +* **Prós**: Sem custo extra de licenciamento e gerenciamento centralizado na mesma esteira do Kubernetes. +* **Contras**: Sobrecarrega o time com a manutenção manual do banco de dados (scripts de backup, atualizações de sistema operacional e patches). + +### Alternativa 2: PostgreSQL gerenciado (DBaaS PostgreSQL) +Delegar o provisionamento e a manutenção da base de dados relacional para a plataforma gerenciada da nuvem. +* **Prós**: O provedor cuida de backups diários automáticos, patches de segurança física e lógica e alta disponibilidade. +* **Contras**: Adiciona um custo fixo mensal à fatura de infraestrutura. + +## Decisão +Adoção da **Alternativa 2: (DBaaS PostgreSQL)**. O banco foi provisionado na sub-rede privada da VPC, sem IP público e completamente isolado da internet. Toda a comunicação com a API ocorre de forma interna e segura por meio de variáveis de ambiente (`DATABASE_URL`) injetadas via Kubernetes Secret (`db-secret`) . + +## Consequências +* Positivas: Maior segurança de rede, alta disponibilidade nativa e eliminação de tarefas manuais de administração de servidores. +* Negativas: Adição de um custo mensal de infraestrutura. + +## Estimativa de Custo Mensal (Magalu Cloud) +* Serviço: DBaaS PostgreSQL (Instância básica BV1-4-10 para desenvolvimento). +* Preço: R$ 39,90 mensais. +* Orçamento: Compatível com o limite de gastos de R$ 150,00 do projeto. diff --git a/docs/adr/0002-exposicao-do-servico.md b/docs/adr/0002-exposicao-do-servico.md new file mode 100644 index 0000000..c66dfca --- /dev/null +++ b/docs/adr/0002-exposicao-do-servico.md @@ -0,0 +1,45 @@ +# ADR 0002 - Estratégia de Exposição Pública da API REST (Rede e Roteamento) + +## Status +Aceito (Accepted) + +## Data +2026-08-05 + +## Contexto +A API REST instalada no cluster Kubernetes gerenciado precisa de exposição pública para receber pedidos dos clientes na internet. É necessário prover um ponto estável de entrada de rede, distribuir o tráfego de forma balanceada e impedir erros HTTP 503 aos usuários durante a atualização de novas réplicas de contêineres. + +## Contexto +A API precisa de um endereço público estável na internet para receber pedidos. Como os IPs dos pods do Kubernetes são efêmeros, a mudança constante torna inviável expor os contêineres diretamente para os clientes. +Além disso, durante novos deploys, as réplicas novas levam um tempo de inicialização. Caso elas comecem a receber tráfego antes de estarem totalmente prontas, os usuários receberão erros HTTP 503 de indisponibilidade. + + +## Alternativas Consideradas + +### Alternativa 1: Service do tipo LoadBalancer +Usar o recurso nativo do Kubernetes que gerencia um balanceador de carga externo na Magalu Cloud. +* **Prós**: Extremamente simples de configurar via YAML e gera um IP público estável de forma automatizada. +* **Contras**: Cada LoadBalancer provisionado gera uma nova cobrança na fatura de infraestrutura, o que pode não escalar financeiramente se o número de serviços expostos crescer muito. + +### Alternativa 2: Ingress Controller (Traefik / Nginx) + Service ClusterIP +Instalação de um controlador de entrada de camada 7 para gerenciar múltiplas rotas de rede sob um único balanceador físico. +* Prós: Alta escalabilidade para cenários com múltiplos microsserviços sob um único IP faturado. +* Contras: Complexidade de configuração inicial. + +### Alternativa 2: Ingress Controller (Traefik / Nginx) + Service tipo ClusterIP +Instalar um controlador de entrada de camada 7 para centralizar várias rotas sob um único balanceador físico. +* **Prós**: Permite economizar em escala distribuída, roteando múltiplos sub-caminhos de rede usando o mesmo IP público faturado. +* **Contras**: Complexidade de configuração desnecessária para uma aplicação que atualmente possui apenas um ponto de entrada unificado. + + +## Decisão +Adoção da **Alternativa 1: Service do tipo LoadBalancer**. Sendo um monolito unificado com apenas um ponto de entrada, o recurso simplifica o gerenciamento de infraestrutura. Configura-se uma **Readiness Probe** na rota `/health` com tolerância inicial de 45 segundos para validar a integridade dos contêineres antes de liberá-los para o tráfego do balanceador, mitigando erros lógicos durante atualizações. + +## Consequências +* Positivas: IP público unificado e estável, com deploys automatizados e sem tempo de inatividade. +* Negativas: Se novos microsserviços forem acoplados futuramente, será obrigatória a migração para Ingress para evitar custos multiplicados com balanceadores físicos. + +## Estimativa de Custo Mensal (Magalu Cloud) +* Serviço: Load Balancer gerenciado + IP público vinculado. +* Preço: R$ 30,00 por mês. +* Orçamento: Compatível com o teto estabelecido de R$ 150,00 mensais. diff --git a/docs/adr/0003-granularidade-dos-servicos.md b/docs/adr/0003-granularidade-dos-servicos.md new file mode 100644 index 0000000..c3f6fef --- /dev/null +++ b/docs/adr/0003-granularidade-dos-servicos.md @@ -0,0 +1,36 @@ +# ADR 0003 - Definição de Granularidade de Serviços: Monolito vs. Microsserviços (Estrutura) + +## Status +Aceito + +## Data +2026-08-05 + +## Contexto +O e-commerce precisa suportar novas capacidades (como processamento de pagamentos e envio de notificações). É necessário determinar a estrutura física de deploy e distribuição desses componentes para otimizar o orçamento e simplificar a operação pela equipe. + +## Alternativas Consideradas + +### Alternativa 1: Arquitetura Monolito em Camadas (Layered Monolith) +Manter todo o processamento de pedidos, pagamentos e notificações no mesmo repositório e sob a mesma unidade física de deploy (FastAPI). +* **Prós**: Ciclo rápido de desenvolvimento, depuração simplificada em ambiente local, consistência transacional imediata e menor consumo de recursos. +* **Contras**: Limitação de escala independente e risco de falhas em cascata. + +### Alternativa 2: Arquitetura de Microsserviços Distribuída +Divisão física do sistema em múltiplos serviços independentes (como pedidos, faturamento e avisos) com bancos de dados isolados. +* **Prós**: Escalabilidade e deploys autônomos por serviço. +* **Contras**: Complexidade operacional, custos de rede adicionais e necessidade de brokers de mensagens. + +## Decisão +Adoção da **Alternativa 1: Monolito em Camadas (Layered Monolith)**. Devido ao estágio inicial do produto (MVP) e o time ser pequeno, a simplicidade de operação e o baixo consumo de recursos justificam a escolha. + +Atenção para gatilho de evolução que, caso o serviço de notificações (dependente de APIs de terceiros lentas) afete a estabilidade do fluxo de pedidos, será feita a extração do módulo de notificações para um microsserviço assíncrono utilizando filas de mensageria com timeout curto e disjuntores (Circuit Breakers). + +## Consequências +* Positivas: Redução de custos operacionais e simplificação da esteira CI/CD do projeto. +* Negativas: Chamadas para APIs externas lentas podem comprometer o tempo de resposta se não houver um tratamento de timeouts adequado. + +## Estimativa de Custo Mensal (Magalu Cloud) +* Serviço: Rateado no cluster Kubernetes já ativo (2 Pods da API). +* Preço: Sem custo adicional direto. +* Orçamento: Mantém a infraestrutura dentro da estimativa planejada. diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..ef10193 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,45 @@ +# Arquitetura da Solução e Infraestrutura + + +* **Aluno**: Fernanda Lopes +* **Repositório do Projeto**: https://github.com/Nanda-Lopes/move-tech-cloud-application-comp-6 + + +Este documento detalha o desenho arquitetural, a infraestrutura física, o fluxo de comunicação e os requisitos não-funcionais da API de pedidos de e-commerce na [Magalu Cloud](https://magalu.cloud/). + +1. Mapeamento de Recursos (Cluster & Cloud) +* Cluster Kubernetes (K3s / Magalu Cloud): + - App API (Container em FastAPI / Python) + - Service LoadBalancer (Roteamento de Entrada) + - Prometheus & Grafana (Agentes de Observabilidade) + +* Serviços Externos / Managed Services: + - Banco de Dados PostgreSQL Gerenciado (DBaaS) + - Magalu Cloud Container Registry (MCR) + - Object Storage (Armazenamento de Mídias) + - CDN (Content Delivery Network) + +--- + +## 2. Diagrama C2 (Nível de Containers) + +```mermaid +graph TD + User([Usuário / Cliente]) -->|HTTP / HTTPS| LB[Service LoadBalancer] + LB -->|TCP / Port 8000| App[API Container - Pod K8s] + App -->|TCP / Port 5432| DB[(PostgreSQL Gerenciado)] + App -->|HTTPS / TLS| MCR[Magalu Container Registry] + User -->|HTTPS / Port 443| CDN[CDN] + CDN -->|HTTPS / Port 443| Storage[Object Storage] + Prometheus[Prometheus Server] -->|HTTP Scrape / Port 9090| App +``` + +--- + +## 3. Requisitos Não-Funcionais (RNFs) & Estilo Arquitetural + +- **Estilo Arquitetural:** Monolito Modular em Camadas com Implantação Cloud-Native em Contêineres. +- **Disponibilidade Alvo:** 99.9% (SLA). +- **Latência P95:** < 200ms sob carga normal. +- **Vazão Alvo:** 500 requisições por segundo (RPS). +- **Teto de Custo (FinOps):** R$ 150,00/mês (alocação otimizada de recursos). \ No newline at end of file