architecture-patterns

# Architecture Patterns - Design de Sistemas

Esta skill ajuda você a tomar decisões OBJETIVAS sobre arquitetura de software.

## Regra Fundamental: OBJETIVIDADE

```
┌─────────────────────────────────────────────────────────────┐
│  🚨 REGRA MAIS IMPORTANTE: SEJA OBJETIVO E ÚTIL            │
│                                                              │
│  ❌ NUNCA RESPONDA ASSIM:                                   │
│  "Depende dos requisitos do seu sistema..."                │
│  "Cada caso é único..."                                    │
│  "Você precisa avaliar trade-offs..."                      │
│                                                              │
│  ✅ SEMPRE RESPONDA ASSIM:                                  │
│  "Use monolito. Motivo: você tem <10 devs e <1M users"     │
│  "Pattern recomendado: Event Sourcing. Aqui está como..."  │
│  "Essa arquitetura está errada. Faça isso em vez disso..." │
│                                                              │
│  DÊ RECOMENDAÇÕES ESPECÍFICAS COM RAZÕES CLARAS.           │
└─────────────────────────────────────────────────────────────┘
```

## Quando Usar Esta Skill

- Decisões de arquitetura de sistema
- Escolha entre monolito vs microservices
- Design de APIs e comunicação entre serviços
- Escalabilidade e performance
- Organização de código e camadas

## Monolito vs Microservices

### Quando Usar Monolito

```
┌─────────────────────────────────────────────────────────────┐
│  USE MONOLITO QUANDO:                                        │
│                                                              │
│  ✅ Time < 10 desenvolvedores                                │
│  ✅ Produto ainda está descobrindo product-market fit       │
│  ✅ Domínio do negócio ainda está mudando                   │
│  ✅ Você precisa de velocidade de desenvolvimento           │
│  ✅ Não tem expertise em sistemas distribuídos              │
│                                                              │
│  EXEMPLOS DE EMPRESAS QUE COMEÇARAM COM MONOLITO:           │
│  → Shopify (Ruby monolito até bilhões em GMV)              │
│  → Basecamp (ainda é monolito)                             │
│  → GitHub (monolito por anos)                              │
│  → Airbnb (começou monolito)                               │
│                                                              │
│  "If you can't build a well-structured monolith,            │
│   what makes you think microservices are the answer?"       │
└─────────────────────────────────────────────────────────────┘
```

### Quando Usar Microservices

```
┌─────────────────────────────────────────────────────────────┐
│  USE MICROSERVICES QUANDO:                                   │
│                                                              │
│  ✅ Time > 50 desenvolvedores                                │
│  ✅ Domínios claramente separados e estáveis                │
│  ✅ Diferentes partes precisam escalar independentemente     │
│  ✅ Times autônomos com ownership claro                     │
│  ✅ Você tem DevOps/Platform team dedicado                  │
│                                                              │
│  CUSTOS DOS MICROSERVICES (que ninguém conta):              │
│  → Latência de rede entre serviços                         │
│  → Complexidade de debugging distribuído                   │
│  → Consistência eventual (transactions distribuídas)       │
│  → Infraestrutura: K8s, service mesh, observability        │
│  → Overhead operacional: deploy, monitoring de N serviços  │
│                                                              │
│  "Don't do microservices unless you have the team          │
│   and infrastructure to support them."                      │
└─────────────────────────────────────────────────────────────┘
```

### Decisão Rápida

```
FLOWCHART DE DECISÃO:

Quantos devs você tem?
│
├─ < 10 devs → MONOLITO (ponto final)
│
├─ 10-50 devs → MODULAR MONOLITH
│   │
│   └─ Monolito bem estruturado com módulos separados
│      que PODEM virar serviços se necessário
│
└─ > 50 devs → CONSIDERE microservices
    │
    ├─ Tem Platform Team? → Talvez microservices
    │
    └─ Não tem → Modular monolith
```

## Padrões de Arquitetura

### Clean Architecture / Hexagonal

```
┌─────────────────────────────────────────────────────────────┐
│  CLEAN ARCHITECTURE (Uncle Bob)                              │
│                                                              │
│  ┌───────────────────────────────────────┐                  │
│  │           FRAMEWORKS & DRIVERS        │ ← Web, DB, UI   │
│  │  ┌───────────────────────────────┐   │                  │
│  │  │      INTERFACE ADAPTERS       │   │ ← Controllers    │
│  │  │  ┌───────────────────────┐   │   │                  │
│  │  │  │     USE CASES         │   │   │ ← Business rules │
│  │  │  │  ┌───────────────┐   │   │   │                  │
│  │  │  │  │   ENTITIES    │   │   │   │ ← Domain objects │
│  │  │  │  └───────────────┘   │   │   │                  │
│  │  │  └───────────────────────┘   │   │                  │
│  │  └───────────────────────────────┘   │                  │
│  └───────────────────────────────────────┘                  │
│                                                              │
│  REGRA: Dependências apontam para DENTRO                    │
│  → Entities não conhecem Use Cases                         │
│  → Use Cases não conhecem Controllers                      │
│  → Controllers não conhecem Frameworks específicos         │
│                                                              │
├─────────────────────────────────────────────────────────────┤
│  QUANDO USAR:                                                │
│  ✅ Aplicações com lógica de negócio complexa               │
│  ✅ Quando você quer trocar de framework/DB facilmente      │
│  ✅ Projetos de longa duração (> 2 anos)                    │
│                                                              │
│  QUANDO NÃO USAR:                                            │
│  ❌ CRUDs simples                                            │
│  ❌ MVPs e protótipos                                        │
│  ❌ Time inexperiente (curva de aprendizado)                │
└─────────────────────────────────────────────────────────────┘
```

### CQRS (Command Query Responsibility Segregation)

```
┌─────────────────────────────────────────────────────────────┐
│  CQRS: SEPARE LEITURAS DE ESCRITAS                           │
│                                                              │
│  MODELO TRADICIONAL:                                         │
│  [Client] ←→ [API] ←→ [Service] ←→ [Database]              │
│                                                              │
│  MODELO CQRS:                                                │
│                                                              │
│  [Client] ─── Commands ──→ [Write Model] ─→ [Write DB]     │
│     │                           │                           │
│     │                           ▼ (eventos)                 │
│     │                      [Event Bus]                      │
│     │                           │                           │
│     │                           ▼                           │
│     └─── Queries ────→ [Read Model] ←─ [Read DB]           │
│                                                              │
├─────────────────────────────────────────────────────────────┤
│  QUANDO USAR:                                                │
│  ✅ Leituras >> Escritas (90% reads, 10% writes)            │
│  ✅ Requisitos de leitura diferentes de escrita             │
│  ✅ Performance de leitura é crítica                        │
│  ✅ Múltiplas views do mesmo dado                           │
│                                                              │
│  QUANDO NÃO USAR:                                            │
│  ❌ CRUD simples                                             │
│  ❌ Consistência forte necessária                           │
│  ❌ Time pequeno sem experiência                            │
│                                                              │
│  EXEMPLO PRÁTICO:                                            │
│  E-commerce: Catálogo de produtos                          │
│  → Escrita: Admin atualiza produto (raro)                  │
│  → Leitura: Milhões de pageviews (frequente)               │
│  → Read model pode ser denormalizado, cacheado, etc.       │
└─────────────────────────────────────────────────────────────┘
```

### Event Sourcing

```
┌─────────────────────────────────────────────────────────────┐
│  EVENT SOURCING: ARMAZENE EVENTOS, NÃO ESTADO               │
│                                                              │
│  TRADICIONAL:                                                │
│  User { name: "João", email: "joao@email.com" }            │
│  (só o estado atual)                                        │
│                                                              │
│  EVENT SOURCING:                                             │
│  1. UserCreated { name: "João", email: "j@email.com" }     │
│  2. EmailChanged { email: "joao@email.com" }               │
│  3. NameChanged { name: "João Silva" }                     │
│  → Estado atual = replay de todos os eventos               │
│                                                              │
├─────────────────────────────────────────────────────────────┤
│  VANTAGENS:                                                  │
│  ✅ Audit log completo (quem, quando, o quê)                │
│  ✅ Pode reconstruir estado em qualquer ponto no tempo     │
│  ✅ Debug fácil (replay eventos para reproduzir bug)        │
│  ✅ Integração natural com CQRS                             │
│                                                              │
│  DESVANTAGENS:                                               │
│  ❌ Complexidade muito maior                                 │
│  ❌ Storage cresce infinitamente                            │
│  ❌ Queries são mais complexas                              │
│  ❌ Evolução de schema de eventos é difícil                │
│                                                              │
├─────────────────────────────────────────────────────────────┤
│  QUANDO USAR:                                                │
│  ✅ Auditoria é requisito legal (financeiro, saúde)         │
│  ✅ Precisa de "time travel" (undo/redo)                    │
│  ✅ Domínio naturalmente baseado em eventos                 │
│                                                              │
│  QUANDO NÃO USAR (maioria dos casos):                       │
│  ❌ Você não tem requisito de auditoria                     │
│  ❌ CRUD é suficiente                                       │
│  ❌ Time não tem experiência com ES                         │
│                                                              │
│  "Event Sourcing is a very powerful pattern, but it's       │
│   also very complex. Don't use it unless you need it."      │
└─────────────────────────────────────────────────────────────┘
```

## Comunicação Entre Serviços

### Síncrona vs Assíncrona

```
┌─────────────────────────────────────────────────────────────┐
│  COMUNICAÇÃO SÍNCRONA (REST, gRPC)                          │
│                                                              │
│  [Service A] ──request──→ [Service B]                      │
│       ↑                        │                            │
│       └────── response ────────┘                            │
│                                                              │
│  A espera B responder                                       │
│                                                              │
│  USE QUANDO:                                                 │
│  ✅ Você PRECISA da resposta imediatamente                  │
│  ✅ Operações simples e rápidas (<100ms)                    │
│  ✅ User-facing requests                                    │
│                                                              │
├─────────────────────────────────────────────────────────────┤
│  COMUNICAÇÃO ASSÍNCRONA (Message Queue, Events)             │
│                                                              │
│  [Service A] ──event──→ [Queue] ──event──→ [Service B]     │
│       │                                                     │
│       └─ continua sem esperar                               │
│                                                              │
│  A NÃO espera B                                             │
│                                                              │
│  USE QUANDO:                                                 │
│  ✅ Operação pode demorar (processamento batch)             │
│  ✅ Não precisa de resposta imediata                        │
│  ✅ Desacoplamento é importante                             │
│  ✅ Retry automático é necessário                           │
│                                                              │
├─────────────────────────────────────────────────────────────┤
│  RECOMENDAÇÃO:                                               │
│                                                              │
│  User request → SÍNCRONO (REST/gRPC)                       │
│  Background jobs → ASSÍNCRONO (Queue)                       │
│  Entre microservices → ASSÍNCRONO quando possível          │
└─────────────────────────────────────────────────────────────┘
```

### Message Queues

```
QUAL USAR:

┌────────────────┬─────────────────────────────────────────┐
│ TECNOLOGIA     │ QUANDO USAR                             │
├────────────────┼─────────────────────────────────────────┤
│ RabbitMQ       │ Workload tradicional, routing complexo  │
│                │ Bom para: Tasks, RPC assíncrono         │
├────────────────┼─────────────────────────────────────────┤
│ Apache Kafka   │ High throughput, event streaming        │
│                │ Bom para: Logs, analytics, event store  │
├────────────────┼─────────────────────────────────────────┤
│ AWS SQS        │ Serverless, managed, simples            │
│                │ Bom para: Tarefas simples em AWS        │
├────────────────┼─────────────────────────────────────────┤
│ Redis Streams  │ Já usa Redis, precisa de speed          │
│                │ Bom para: Cache + queue em um           │
├────────────────┼─────────────────────────────────────────┤
│ BullMQ (Node)  │ App Node.js, já tem Redis               │
│                │ Bom para: Background jobs em Node       │
└────────────────┴─────────────────────────────────────────┘

REGRA SIMPLES:
→ Task queue simples? → BullMQ/SQS
→ Event streaming? → Kafka
→ Routing complexo? → RabbitMQ
→ Não sabe? → Comece com SQS/BullMQ
```

## Database Design

### Escolha de Banco de Dados

```
┌────────────────┬─────────────────────────────────────────┐
│ TIPO           │ QUANDO USAR                             │
├────────────────┼─────────────────────────────────────────┤
│ PostgreSQL     │ DEFAULT. Relacional, full-featured.     │
│                │ Use para: 90% dos casos                 │
├────────────────┼─────────────────────────────────────────┤
│ MongoDB        │ Documentos JSON, schema flexível        │
│                │ Use para: Conteúdo, catálogos           │
├────────────────┼─────────────────────────────────────────┤
│ Redis          │ Cache, sessões, filas                   │
│                │ Use para: Performance, dados efêmeros   │
├────────────────┼─────────────────────────────────────────┤
│ Elasticsearch  │ Full-text search, analytics             │
│                │ Use para: Busca, logs                   │
├────────────────┼─────────────────────────────────────────┤
│ ClickHouse     │ Analytics, time-series                  │
│                │ Use para: Dashboards, métricas          │
└────────────────┴─────────────────────────────────────────┘

REGRA: Se você não sabe, use PostgreSQL.
PostgreSQL pode fazer:
→ Relacional (óbvio)
→ JSON (JSONB)
→ Full-text search (basic)
→ Time-series (com extensões)
→ Vector search (pgvector)

"PostgreSQL is the everything database."
```

## Exemplo de Resposta OBJETIVA

**Usuário:** "Estou começando uma startup, devo usar microservices?"

**Resposta:**
```
NÃO. Use monolito.

RAZÕES:

1. VOCÊ NÃO TEM OS PROBLEMAS QUE MICROSERVICES RESOLVEM
   Microservices resolvem:
   → Times grandes (50+ devs) que não conseguem trabalhar junto
   → Partes do sistema que precisam escalar diferentemente
   → Deploys independentes por diferentes times

   Você tem:
   → Time pequeno (1-10 pessoas)
   → Domínio ainda em descoberta
   → Necessidade de velocidade, não escala

2. CUSTO VS BENEFÍCIO
   Microservices adicionam:
   → Latência de rede entre serviços
   → Complexidade de debugging
   → Infraestrutura (K8s, service mesh, etc.)
   → Overhead operacional

   Para uma startup, isso é MORTAL. Você vai gastar
   tempo resolvendo problemas de infra em vez de
   problemas de negócio.

3. O QUE FAZER EM VEZ DISSO:

   a) MONOLITO MODULAR
      → Separe código em módulos/packages
      → Defina interfaces claras entre módulos
      → Isso facilita extrair serviço DEPOIS se precisar

   b) ESTRUTURA SUGERIDA:
      /src
        /modules
          /users
            - controller.ts
            - service.ts
            - repository.ts
          /orders
            - controller.ts
            - service.ts
            - repository.ts
          /payments
            ...
        /shared
          - database.ts
          - auth.ts

   c) TECNOLOGIA:
      → Node.js + Express/Fastify ou
      → Python + FastAPI ou
      → Go + Chi
      → PostgreSQL
      → Redis para cache/sessions
      → Tudo em uma máquina ou container

4. QUANDO MIGRAR PARA MICROSERVICES:
   → Você tem 50+ devs
   → Deploys estão atrasando porque times se bloqueiam
   → Parte específica precisa escalar 10x mais que resto
   → Você tem time de plataforma dedicado

   Até lá: MONOLITO.

"If you can't build a well-structured monolith,
 what makes you think microservices are the answer?"
```

## Regras Imutáveis

```
1. SEJA OBJETIVO — dê recomendações específicas
2. Monolito primeiro, sempre (até 50 devs)
3. PostgreSQL é o default
4. Simplicidade > elegância arquitetural
5. Não adicione complexidade sem razão clara
6. "You ain't gonna need it" (YAGNI)
7. Escolha boring technology
8. Arquitetura evolui com o time e produto
9. Modular monolith é melhor que microservices ruins
10. Se não sabe explicar por que precisa, não precisa
```

---

**Esta skill ativa AUTOMATICAMENTE quando:**
- Decisões de arquitetura de sistema
- Monolito vs microservices
- Design de APIs e comunicação
- Escolha de banco de dados
- Escalabilidade e performance