# Módulo 5: Estrutura Real de um Site Moderno
# Aula 4 — Logs e Monitoramento
## Curso: Arquitetura Web 10X – Domine o que a IA Não Domina

Uma aplicação em produção sem logs e sem monitoramento é uma caixa preta a voar às cegas. Quando algo corre mal — e vai correr mal — você fica sem pistas, sem visibilidade, reduzido a adivinhar o que aconteceu.

A engenharia de software profissional não é sobre escrever código que nunca falha; é sobre construir sistemas que são **observáveis**, ou seja, sistemas que nos dão a informação necessária para entender o seu estado interno a partir do seu output externo.

**Logs** são o registo do que *aconteceu* no passado. **Monitoramento** é a visão do que está a *acontecer agora*. Juntos, eles formam a base da **Observabilidade**. A IA pode analisar um ficheiro de log e encontrar uma anomalia, mas não pode decidir quais métricas de negócio são cruciais para monitorizar ou qual o nível de log correto para a sua aplicação. Essa é uma decisão de arquitetura.

---

### 🎯 1. Logs: Deixando um Rasto de Pão Digital

Um log é um registo de um evento que ocorreu na sua aplicação, com carimbo de data/hora. É a sua ferramenta de depuração mais importante em produção.

**Os Níveis de Log (a importância de não gritar tudo):**
Registrar tudo é tão inútil como não registrar nada. Usamos níveis de severidade para filtrar o ruído:
-   **DEBUG:** Informação granular para depuração durante o desenvolvimento. (Ex: "Valor da variável X é 25"). Deve ser desligado em produção.
-   **INFO:** Eventos normais e significativos da aplicação. (Ex: "Utilizador 123 fez login", "Servidor iniciado na porta 3000").
-   **WARN (Warning):** Ocorrências inesperadas que não são erros, mas que podem indicar um problema futuro. (Ex: "Uso de memória a atingir 80%", "API de terceiros demorou 3 segundos a responder").
-   **ERROR:** Falhas que impediram que uma operação fosse concluída. (Ex: "Não foi possível conectar à base de dados", "Falha ao processar pagamento para o pedido XYZ").
-   **FATAL (ou CRITICAL):** Um erro tão grave que a aplicação não consegue continuar a funcionar e precisa de ser terminada. (Ex: "Ficheiro de configuração essencial em falta").

**O que faz um bom log? (Não é um `print`):**
Um log não é um `console.log('deu erro')`. Um log útil é **estruturado**, geralmente em formato **JSON**, e contém contexto.

-   **Mau:** `Erro ao processar o pedido.`
-   **Bom (JSON Estruturado):**
    ```json
    {
      "timestamp": "2025-11-16T18:30:00Z",
      "level": "ERROR",
      "message": "Falha ao validar o pedido de criação de utilizador",
      "error": {
        "code": "VALIDATION_FAILED",
        "details": "O campo 'email' é inválido"
      },
      "context": {
        "requestId": "abc-123-xyz-789",
        "userId": null,
        "sourceIp": "198.51.100.2"
      }
    }
    ```
Este log estruturado pode ser facilmente pesquisado, filtrado e analisado.

**Centralização de Logs:**
Num sistema com múltiplos servidores ou microserviços, aceder a cada máquina para ver os logs é impraticável. A solução é a **centralização de logs**. Cada serviço envia os seus logs para um sistema centralizado, como o **stack ELK (Elasticsearch, Logstash, Kibana)** ou serviços na nuvem como **Datadog, Splunk ou AWS CloudWatch Logs**.

---

### 🎯 2. Monitoramento: O Painel de Controlo em Tempo Real

Se os logs são a visão forense, o monitoramento é o eletrocardiograma da sua aplicação. É a recolha e visualização de **métricas** (dados numéricos ao longo do tempo).

Existem quatro tipos de sinais dourados a monitorizar (Método USE e RED):

**Para Recursos (Método USE):**
-   **Utilization (Utilização):** A percentagem de um recurso que está ocupada. (Ex: CPU a 85%).
-   **Saturation (Saturação):** Uma medida de "fila". Quão sobrecarregado está o recurso. (Ex: Carga média do sistema).
-   **Errors (Erros):** A contagem de eventos de erro. (Ex: Erros de disco).

**Para Serviços/APIs (Método RED):**
-   **Rate (Taxa):** O número de pedidos que o serviço está a receber por segundo.
-   **Errors (Erros):** A contagem de pedidos que resultaram em erro (tipicamente respostas 5xx).
-   **Duration (Duração):** A distribuição da latência dos pedidos. Quanto tempo os pedidos estão a demorar (ex: p95, p99).

**Como Funciona:**
1.  A sua aplicação ou infraestrutura **expõe** estas métricas num endpoint (ex: `/metrics`).
2.  Um sistema de monitoramento, como o **Prometheus** (um padrão da indústria), "raspa" (scrape) este endpoint a cada poucos segundos e armazena os dados numa base de dados de séries temporais.
3.  Uma ferramenta de visualização, como a **Grafana**, é usada para criar dashboards com gráficos e alertas a partir dos dados do Prometheus.

**Alertas (Alerting):**
O monitoramento proativo depende de alertas. Um arquiteto define regras de alerta para ser notificado (via Slack, PagerDuty, etc.) **antes** de um problema se tornar catastrófico.
-   **Mau Alerta:** "CPU   95%". (Pode ser um pico momentâneo e normal).
-   **Bom Alerta:** "CPU   95% por mais de 5 minutos E a latência p99 da API de login é superior a 500ms". (Este alerta é acionável e correlaciona um sintoma de infraestrutura com um impacto no utilizador).

---

### 🚀 Conclusão

Logs e monitoramento transformam o caos da produção num sistema compreensível. Eles são os seus olhos e ouvidos. Sem eles, você está a operar com base em suposições.

-   **Logs** dizem-lhe *porquê* algo falhou.
-   **Métricas** dizem-lhe *que* algo está a falhar.
-   **Alertas** dizem-lhe que algo está prestes a falhar.

A IA pode ser uma ferramenta incrível para detetar anomalias em terabytes de logs ou métricas. Mas a decisão sobre *o que* logar, *o que* monitorizar e *quando* alertar um humano é uma decisão de engenharia profundamente ligada ao negócio e aos objetivos do sistema. É a sua responsabilidade construir um sistema que lhe diga quando está doente.

Na última aula deste módulo, vamos juntar tudo e discutir as duas principais filosofias arquiteturais para estruturar a sua aplicação: **Arquiteturas Monolíticas vs. Distribuídas (Microserviços).**

# Módulo 6: Web Services e APIs (antes do código)
# Aula 5 — CORS Explicado de Forma Definitiva
## Curso: Arquitetura Web 10X – Domine o que a IA Não Domina

  "Access to fetch at 'https://api.meusite.com/data' from origin 'https://app.meusite.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource."

Se você já desenvolveu uma aplicação frontend que consome uma API, é quase garantido que já se deparou com esta mensagem de erro. Para muitos, a reação instintiva é procurar no Stack Overflow por uma solução mágica para "desativar o CORS", muitas vezes acabando com a perigosa configuração `Access-Control-Allow-Origin: *`.

Esta abordagem é o equivalente a reagir a um alarme de incêndio destruindo o alarme em vez de verificar se há fogo.

**CORS não é um erro na sua aplicação. É uma funcionalidade de segurança no browser.**

Um júnior luta contra o CORS. Um arquiteto entende que o CORS é uma conversa controlada entre o browser e o servidor, e a sua função é ensinar o servidor a dar as respostas certas nessa conversa. A IA pode dar-lhe o header para resolver um problema de CORS, mas não pode raciocinar sobre a política de segurança que esse header implica.

---

### 🎯 1. Relembrando a Base: A Same-Origin Policy (SOP)

Como vimos no Módulo 3, a SOP é a regra de segurança fundamental do browser. Ela impede que um script de uma **Origem A** (ex: `https://evil.com`) possa ler dados de uma resposta vinda da **Origem B** (ex: `https://meubanco.com`).

Isto é ótimo para a segurança, mas péssimo para a web moderna, onde é perfeitamente legítimo que a sua aplicação frontend na `https://app.meusite.com` precise de aceder à sua API em `https://api.meusite.com`. Lembre-se, mesmo que o domínio principal seja o mesmo, o subdomínio `api` torna-as **origens diferentes**.

É aqui que entra o **CORS (Cross-Origin Resource Sharing)**. O CORS é o mecanismo que permite ao servidor na Origem B dizer, de forma explícita e segura, "Eu confio na Origem A. Browser, você tem a minha permissão para entregar a resposta ao script dela."

---

### 🎯 2. A Conversa CORS: Requisições Simples vs. Preflight

O diálogo do CORS pode acontecer de duas formas, dependendo da complexidade do pedido.

**Cenário 1: A Requisição "Simples"**

Uma requisição é considerada "simples" se cumprir todas as seguintes condições:
-   **Método:** `GET`, `HEAD` ou `POST`.
-   **Headers:** Apenas headers simples como `Accept`, `Content-Type` (com valores limitados como `text/plain`), etc.

Neste caso, o fluxo é direto:
1.  **O Browser envia o pedido:** O browser faz a requisição `GET` para a API, mas adiciona automaticamente um header crucial:
    `Origin: https://app.meusite.com`
2.  **O Servidor responde:** O servidor recebe o pedido. A sua lógica de CORS verifica se a origem `https://app.meusite.com` está na sua lista de permissões. Se estiver, ele processa o pedido e inclui um header na resposta:
    `Access-Control-Allow-Origin: https://app.meusite.com`
3.  **O Browser valida:** O browser recebe a resposta, vê que o header `Access-Control-Allow-Origin` corresponde à sua própria origem e, só então, entrega os dados da resposta ao seu código JavaScript. Se o header estiver em falta ou não corresponder, ele bloqueia a resposta e lança o erro de CORS.

**Cenário 2: A Requisição "Não Simples" e o Preflight**

Qualquer requisição que não cumpra os critérios de "simples" (ex: usa os métodos `PUT`, `PATCH`, `DELETE` ou inclui headers personalizados como `Authorization`) exige um passo extra de segurança chamado **Preflight Request (Pedido de Verificação)**.

1.  **O Browser envia um "Preflight":** Antes de enviar a requisição real (`DELETE`), o browser envia um pedido de "sondagem" usando o método **`OPTIONS`**. Este pedido pergunta ao servidor: "Olá, um script de `https://app.meusite.com` quer enviar um pedido `DELETE` com um header `Authorization`. Isso é permitido?"

    ```http
    OPTIONS /users/123 HTTP/1.1
    Host: api.meusite.com
    Origin: https://app.meusite.com
    Access-Control-Request-Method: DELETE
    Access-Control-Request-Headers: Authorization
    ```

2.  **O Servidor responde ao Preflight:** O servidor responde a este pedido `OPTIONS` com um conjunto de headers que funcionam como a "política de permissões" para aquele endpoint.

    ```http
    HTTP/1.1 204 No Content
    Access-Control-Allow-Origin: https://app.meusite.com
    Access-Control-Allow-Methods: GET, POST, DELETE
    Access-Control-Allow-Headers: Content-Type, Authorization
    Access-Control-Max-Age: 86400
    ```
    -   `Allow-Origin`: Diz qual origem é permitida.
    -   `Allow-Methods`: Lista os métodos HTTP permitidos.
    -   `Allow-Headers`: Lista os headers personalizados permitidos.
    -   `Max-Age`: Diz ao browser para fazer cache desta resposta de preflight por 24 horas, para que não precise de perguntar novamente a cada pedido.

3.  **O Browser decide:** O browser analisa esta resposta. Se as permissões concedidas pelo servidor corresponderem ao que o pedido real quer fazer, ele prossegue e envia a requisição `DELETE` real. Se não, ele bloqueia o pedido, lança o erro de CORS e a requisição `DELETE` **nunca é enviada**.

---

### 🎯 3. O Perigo do `Access-Control-Allow-Origin: *`

A solução "fácil" que se encontra online é configurar o servidor para responder sempre com `Access-Control-Allow-Origin: *`. O asterisco (`*`) é um wildcard que significa "qualquer origem é permitida".

**Por que isto é perigoso?**
-   Se a sua API requer autenticação baseada em cookies ou sessões, usar `*` em conjunto com `Access-Control-Allow-Credentials: true` é geralmente proibido pelos browsers por razões de segurança.
-   Mesmo para APIs públicas, isto significa que **qualquer site na internet** pode fazer pedidos à sua API a partir do browser dos seus utilizadores. Um site malicioso pode usar o poder de processamento dos seus visitantes para sobrecarregar a sua API com pedidos.

**A Solução do Arquiteto:**
A abordagem correta é a da **lista de permissões (allow-list)**. A sua configuração de CORS no servidor deve manter uma lista explícita de origens que são permitidas. Ao receber um pedido, o servidor verifica se o header `Origin` está nessa lista. Se estiver, ele reflete essa origem no header `Access-Control-Allow-Origin`.

---

### 🚀 Conclusão do Módulo 6

CORS não é um bug para ser contornado. É um diálogo de segurança essencial entre o browser e o servidor, projetado para proteger os utilizadores.

Ao dominar o fluxo do CORS, tanto para requisições simples como para as que exigem preflight, você deixa de lutar contra o sistema e passa a trabalhar com ele. Você consegue projetar APIs que são simultaneamente flexíveis para os seus clientes legítimos e seguras contra o acesso não autorizado de origens maliciosas.

Com esta aula, fechamos a nossa exploração dos contratos de comunicação. Você agora entende as filosofias de REST, GraphQL e WebSockets, os formatos de dados que eles usam e as políticas de segurança que governam a sua interação.

**No próximo módulo, vamos finalmente falar de código. Mas faremos isso de uma forma diferente, com o contexto sistémico que construímos até agora. Vamos explorar HTML, CSS e JS não como linguagens, mas como o browser as interpreta.**

# Módulo 5: Estrutura Real de um Site Moderno
# Aula 5 — Arquiteturas Monolíticas vs. Distribuídas
## Curso: Arquitetura Web 10X – Domine o que a IA Não Domina

Até agora, neste módulo, discutimos os componentes individuais de uma aplicação web. Agora, vamos dar um passo atrás e olhar para o quadro geral. Como é que organizamos o nosso código e os nossos serviços numa estrutura coesa?

Existem duas filosofias principais para responder a esta pergunta:
1.  **A Arquitetura Monolítica:** Construir tudo como uma única unidade coesa.
2.  **A Arquitetura Distribuída (ou de Microserviços):** Construir tudo como um conjunto de pequenos serviços independentes que colaboram entre si.

A escolha entre estas duas abordagens é uma das decisões de arquitetura de mais longo alcance que uma equipa pode tomar. Não existe uma "melhor" resposta — apenas trade-offs. Um júnior pode repetir a propaganda de que "microserviços são o futuro". Um arquiteto entende os custos e benefícios de cada abordagem e escolhe a que se alinha com a maturidade da sua equipa, a complexidade do seu domínio e os seus objetivos de negócio.

A IA pode gerar código para um microserviço ou para um módulo de um monólito. Mas ela não pode tomar a decisão estratégica fundamental de qual padrão arquitetural adotar.

---

### 🎯 1. A Arquitetura Monolítica: O Poder da Simplicidade

Um monólito é a forma tradicional e natural de construir software.

-   **A Estrutura:** Uma única base de código, um único processo de build, um único artefacto de deploy (um ficheiro `.war`, um executável, uma imagem Docker). Toda a lógica de negócio — utilizadores, produtos, pagamentos, notificações — vive junta na mesma aplicação e, muitas vezes, partilha a mesma base de dados.

-   **A Analogia:** Um restaurante com uma única grande cozinha onde todos os chefs (módulos) trabalham juntos, partilhando os mesmos utensílios e ingredientes (base de dados).

**Vantagens (e são muitas):**
-   **Simplicidade de Desenvolvimento:** É fácil de começar. Não há complexidade de rede entre componentes. Chamar uma função de outro módulo é uma simples chamada de função na mesma linguagem.
-   **Simplicidade de Deploy:** Existe apenas uma "coisa" para fazer deploy.
-   **Performance:** A comunicação entre componentes acontece na memória do processo, o que é ordens de magnitude mais rápido do que chamadas de rede.
-   **Transações Atómicas:** É trivial garantir a consistência dos dados, pois a maioria das operações acontece dentro de uma única transação de base de dados.

**Desvantagens (quando a escala aumenta):**
-   **Acoplamento Forte:** Com o tempo, os módulos tornam-se emaranhados. Mudar uma parte do sistema pode ter efeitos inesperados e indesejados noutra parte.
-   **Escalabilidade "Tudo ou Nada":** Se o módulo de "processamento de imagens" está a consumir muita CPU, você tem de escalar a aplicação inteira (fazer deploy de mais cópias do monólito completo), mesmo que os outros 95% da aplicação estejam ociosos. É ineficiente.
-   **Barreira Tecnológica:** É muito difícil adotar novas tecnologias. Se a aplicação foi escrita em Ruby on Rails, toda a gente tem de trabalhar em Ruby on Rails. Introduzir um novo serviço em Python é quase impossível.
-   **Lentidão no Desenvolvimento (em equipas grandes):** Com dezenas ou centenas de engenheiros a trabalhar na mesma base de código, os conflitos de merge, os tempos de build e a coordenação tornam-se um pesadelo.

---

### 🎯 2. A Arquitetura de Microserviços: O Poder da Independência

Os microserviços surgiram como uma resposta direta aos problemas dos grandes monólitos.

-   **A Estrutura:** A aplicação é dividida num conjunto de pequenos serviços, cada um focado numa única capacidade de negócio (ex: um serviço de Utilizadores, um de Pagamentos, um de Notificações). Cada serviço tem a sua própria base de código, o seu próprio pipeline de deploy e, crucialmente, a sua **própria base de dados**. A comunicação entre eles é feita através da rede, usando APIs (geralmente REST ou gRPC) ou filas de mensagens.

-   **A Analogia:** Uma praça de alimentação com vários restaurantes especializados (food trucks). Cada um tem a sua própria cozinha, os seus próprios ingredientes e os seus próprios chefs. Eles são independentes, mas colaboram (um cliente pode comprar uma bebida num e comida noutro).

**Vantagens:**
-   **Equipas Autónomas:** Cada serviço pode ser detido por uma pequena equipa que tem total autonomia sobre a sua tecnologia, o seu desenvolvimento e o seu ciclo de deploy.
-   **Escalabilidade Granular:** Se o serviço de Pagamentos está sobrecarregado, você pode escalar apenas esse serviço, adicionando mais instâncias dele, sem tocar nos outros. É altamente eficiente.
-   **Liberdade Tecnológica (Poliglota):** O serviço de Utilizadores pode ser escrito em Go, o de Recomendações em Python (para usar bibliotecas de machine learning), e o de Frontend em Node.js. Usa-se a melhor ferramenta para cada trabalho.
-   **Resiliência:** Se o serviço de Notificações falhar, o resto da aplicação (como o login e os pagamentos) pode continuar a funcionar (se a arquitetura for bem desenhada com padrões como Circuit Breakers).

**Desvantagens (e são enormes):**
-   **Complexidade Operacional:** Você não tem uma aplicação para fazer deploy, tem dezenas. A complexidade de deploy, monitoramento, logging e gestão de rede explode. Isto é conhecido como a **"taxa dos microserviços"**.
-   **Complexidade Distribuída:** Todos os problemas de sistemas distribuídos tornam-se os seus problemas: latência de rede, consistência eventual de dados, descoberta de serviços, tolerância a falhas.
-   **Consistência de Dados:** Garantir a consistência entre as múltiplas bases de dados é extremamente difícil e requer padrões complexos como Sagas.

---

### 🚀 A Decisão do Arquiteto: Comece Simples

A recomendação da indústria, popularizada por especialistas como Martin Fowler, é quase unânime:

  **"Não comece com microserviços."**

A menos que você tenha uma equipa muito experiente e um domínio de problema que seja inerentemente distribuído, a sobrecarga operacional dos microserviços irá matar a sua produtividade na fase inicial.

O caminho do arquiteto sábio é:
1.  **Comece com um Monólito Bem Estruturado:** Construa a sua aplicação como um monólito, mas com uma disciplina rigorosa. Mantenha os módulos bem definidos e com baixo acoplamento (o chamado "monólito modular").
2.  **Identifique as Costuras:** À medida que a aplicação cresce, observe os limites entre os módulos.
3.  **Extraia o Primeiro Microserviço:** Quando um módulo específico se torna um gargalo de escala, ou quando requer uma tecnologia diferente, ou quando uma equipa dedicada precisa de o gerir, **só então** extraia-o cuidadosamente para o seu primeiro microserviço.

---

### 🚀 Conclusão do Módulo 5

Compreender a estrutura de uma aplicação moderna é compreender os trade-offs entre simplicidade e independência. Um monólito otimiza para a velocidade de desenvolvimento inicial. Os microserviços otimizam para a velocidade de desenvolvimento a longo prazo em equipas grandes e para a escalabilidade granular.

A sua função como arquiteto não é ser um evangelista de uma ou de outra. É entender profundamente os prós e contras e guiar a sua equipa e a sua organização na escolha do padrão que maximiza as suas hipóteses de sucesso no seu contexto atual.

**No próximo módulo, "Web Services e APIs (antes do código)", vamos focar-nos na cola que une os sistemas distribuídos: os contratos de comunicação entre serviços.**