docs: arquitetura C2, requisitos, trade-offs, ADRs e melhorias

docs/architecture.md

@@ -0,0 +1,90 @@
+# Arquitetura da Solução
+
+## Visão geral
+
+API de pedidos containerizada, rodando em um cluster K3s (nó único) numa VM
+na Magalu Cloud, com banco PostgreSQL gerenciado externo, imagens no Container
+Registry e deploy automatizado pelo GitHub Actions.
+
+## Diagrama C2 · Container
+
+# Arquitetura da Solução
+
+## Visão Geral
+
+API de pedidos containerizada, rodando em um cluster K3s (nó único) numa VM na Magalu Cloud, com banco PostgreSQL gerenciado externo, imagens no Container Registry e deploy automatizado pelo GitHub Actions.
+
+## Diagrama C2 · Container
+
+```mermaid
+flowchart LR
+    cliente["Cliente HTTP"]
+    gh["GitHub Actions"]
+
+    subgraph mgc["Magalu Cloud"]
+        subgraph vm["VM BV2-2-40 · K3s"]
+            kube["K3s API Server :6443"]
+            svc["Klipper ServiceLB :80"]
+            app["cloud-application · 2 pods (FastAPI)"]
+        end
+        db[("DBaaS PostgreSQL · orders, items")]
+        reg["Container Registry"]
+    end
+
+    cliente -->|HTTP / JSON · TCP 80| svc
+    svc -->|HTTP / JSON · TCP 8000| app
+    app -->|SQL · TCP 5432| db
+    gh -->|Docker Push · HTTPS 443| reg
+    gh -->|kubectl apply · HTTPS 6443| kube
+    kube -->|Aplica manifests| app
+    reg -->|Pull Image · HTTPS 443| app
+```
+
+## Componentes
+
+| Componente | Serviço MGC | Função |
+|------------|-------------|--------|
+| API | K3s (VM single node) — 2 réplicas | Processa as requisições HTTP |
+| Banco de dados | DBaaS PostgreSQL | Persiste pedidos e itens |
+| Imagens | Container Registry | Armazena versões da aplicação |
+| Tráfego externo | Klipper ServiceLB (IP da VM, porta 80) | Distribui entre as réplicas e dá acesso externo |
+| CI/CD | GitHub Actions | Automatiza testes, build e deploy |
+
+## Requisitos não-funcionais
+
+| Requisito | Como medir | Alvo |
+|---|---|---|
+| Disponibilidade | Erros 5xx e uptime das probes no Grafana | 99,5% mensal |
+| Latência | `histogram_quantile(0.95, ...)` do `/metrics` | P95 < 500 ms |
+| Escalabilidade | Teste de carga (k6) + `rate(http_requests_total)` | 300 req/s sem degradar |
+| Custo | VM + DBaaS + IP na calculadora MGC | Teto definido em ADR |
+
+## Estilo arquitetural
+
+A solução é um **monolito em camadas** (apresentação → serviço → dados),
+implantado como container único com duas réplicas. O estilo-alvo, caso o
+domínio de notificações cresça, seria extrair um segundo serviço — um próximo
+passo, não uma decisão desta entrega.
+
+## Trade-offs das decisões
+
+| Aspecto | Decisão tomada | Alternativa não escolhida | Motivo da escolha |
+|---------|---------------|--------------------------|-------------------|
+| Deploy | K3s em VM | MKS (Kubernetes Gerenciado) | Custo menor, provisionamento < 2 min, manifests idênticos |
+| Banco | DBaaS gerenciado | PostgreSQL em container | Backup automático, sem administração |
+| CI/CD | GitHub Actions | Deploy manual | Consistência e rastreabilidade |
+| Réplicas | 2 pods | 1 pod | Disponibilidade mínima sem custo excessivo |
+| API | FastAPI (Python) | Node.js, Go, Java | Curva de aprendizado baixa, alta produtividade |
+
+## Pontos de melhoria e próximos passos
+
+| Melhoria | Por quê |
+|----------|---------|
+| HTTPS / TLS | Toda API em produção deve ser acessada por HTTPS |
+| Autoscaler (HPA) | Escala o número de réplicas automaticamente conforme a carga de CPU |
+| Versionamento de API (`/v1/orders`) | Evoluir sem quebrar clientes existentes |
+| Rate limiting | Evita abuso e protege o banco de sobrecargas |
+| Migrações de schema (Alembic) | Controle de versão das mudanças no banco |
+| Testes de carga (k6) | Valida o comportamento sob alto tráfego |
+| Migrar para MKS | Quando precisar de HA real: como os manifests são idênticos, basta trocar o kubeconfig |
+

docs/docs/adr/000-template.md

@@ -0,0 +1,18 @@
+# ADR NNN — Título curto da decisão
+
+**Status:** Aceito | Proposto | Rejeitado | Substituído por NNN
+**Data:** AAAA-MM-DD
+
+## Contexto
+Qual problema ou necessidade gerou a decisão, e quais restrições existiam.
+
+## Alternativas consideradas
+- **Opção A** — prós e contras
+- **Opção B** — prós e contras
+
+## Decisão
+O que foi escolhido e por qual critério.
+
+## Consequências
+**Positivas:** o que melhora.
+**Negativas:** o que piora ou passa a ser risco.

docs/docs/adr/001-kubernetes-deploy.md

@@ -0,0 +1,25 @@
+# ADR 001 — Uso de K3s em VM na Magalu Cloud para Deploy
+
+**Status:** Aceito  
+**Data:** 2026-08-04
+
+## Contexto
+A aplicação precisa ser executada em ambiente containerizado com orquestração de containers, capacidade de autorrecuperação (self-healing) e facilidade para atualização sem parada (rolling update). O orçamento é limitado para a fase atual do projeto.
+
+## Alternativas Consideradas
+- **K3s em VM BV2-2-40 (Ubuntu 24.04)** — Distribuição Kubernetes leve, de rápido provisionamento e baixo custo operacional. Requer gestão manual do nó da VM.
+- **MKS (Magalu Kubernetes Service)** — Cluster Kubernetes totalmente gerenciado. Possui alta disponibilidade no control plane, porém com custo mais elevado e tempo de provisionamento maior para o escopo atual.
+- **VM com Docker Compose** — Solução simples de containerização, mas carece de recursos nativos de orquestração como autorrecuperação de pods, ServiceLB e escalabilidade simplificada via manifests standard de K8s.
+
+## Decisão
+Utilizar o **K3s em uma VM única (BV2-2-40)** na Magalu Cloud. O critério decisivo foi o equilíbrio entre o custo reduzido e a compatibilidade total com os manifests padrão do Kubernetes (Deployments, Services, Secrets), garantindo um caminho direto de migração para o MKS no futuro caso a aplicação necessite de HA no cluster.
+
+## Consequências
+**Positivas:**
+- Baixo custo mensal de infraestrutura.
+- Provisionamento do ambiente em menos de 2 minutos.
+- Uso de manifests universais de Kubernetes.
+
+**Negativas:**
+- Ponto único de falha (SPOF) no nível do nó/VM.
+- A manutenção do nó (S.O., runtime K3s) é de responsabilidade interna.

docs/docs/adr/002-dbaas-postgresql.md

@@ -0,0 +1,31 @@
+# ADR 002 — Usar DBaaS PostgreSQL da Magalu Cloud
+
+**Status:** Aceito
+**Data:** 2026-08-04
+
+## Contexto
+A aplicação precisa de um banco relacional durável, que sobreviva a
+reinicializações de containers e atenda múltiplas réplicas da API ao mesmo
+tempo. O cluster K3s roda em uma única VM.
+
+## Alternativas consideradas
+- **DBaaS PostgreSQL gerenciado (externo)** — backup, patch e HA pelo provedor;
+  custo maior; menos controle fino sobre configurações.
+- **PostgreSQL em pod com PVC** — custo baixo, tudo em um lugar; volume, backup
+  e recuperação por nossa conta; o dado morre junto com o cluster.
+
+## Decisão
+Usar o serviço DBaaS PostgreSQL da Magalu Cloud, fora do cluster, acessado via
+`Secret db-secret`. Critério decisivo: disponibilidade e custo de operação —
+estado é caro de operar manualmente.
+
+## Consequências
+**Positivas:**
+- Backup automático e patches de segurança pelo provedor.
+- O banco sobrevive a qualquer redeploy do cluster.
+- Conexões simultâneas de múltiplos pods sem conflito.
+
+**Negativas:**
+- Custo por hora de uso, mesmo com pouco tráfego.
+- Menor controle sobre configurações avançadas do PostgreSQL.
+- Dependência de conectividade de rede entre o cluster e o DBaaS.