move-tech-cloud-computing · Nanda-Lopes · Aug 6, 2026
diff --git a/docs/adr/0001-banco-fora-do-cluster.md 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
@@ -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
@@ -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
@@ -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).