7. Design Doc

A maioria das decisões de arquitetura nas empresas de verdade não é tomada na frente de um quadro branco: ela é tomada em um design doc que os colegas leem, questionam e aprovam — e nas ADRs (Architecture Decision Records) que lembram a todos, um ano depois, por que as coisas são como são. Em uma entrevista, o mesmo raciocínio acontece em voz alta, em 45 minutos. Neste exercício você faz os dois: escreve um design doc completo com ADRs para um problema clássico de system design e depois o defende oralmente, incluindo uma mudança de requisitos que você não viu chegando.

Contexto

A estrutura de um bom design doc segue o roteiro de entrevista da Aula 1 — esclarecer → estimar → API e modelo de dados → design de alto nível → aprofundamentos → gargalos e trade-offs → fechamento — e o guia de entrevista. Os estudos de caso da Aula 16 mostram exemplos completos resolvidos; o catálogo de componentes dá o vocabulário (use os ids da paleta nos seus diagramas). Um design doc não é uma lista de tecnologias: cada componente precisa ser justificado por um requisito ou um número, e cada escolha importante precisa citar a alternativa que você descartou¹.

Tarefa

1. Você recebe um problema da lista abaixo por sorteio (no máximo dois alunos por problema).
2. Escreva um design doc seguindo o template, na escala indicada no problema.
3. Registre pelo menos três ADRs para as decisões mais importantes.
4. Opcionalmente, faça um protótipo do design no playground (partindo de blank) e anexe o JSON exportado.
5. Defenda o design em uma defesa oral de 15 minutos.

Requisitos

• (obrigatório) Design doc com todas as seções do template (uma seção pode dizer "não se aplica — porque …").
• (obrigatório) Pelo menos três ADRs, cada uma com contexto, opções consideradas, decisão e consequências (positivas e negativas).
• (obrigatório) Defesa oral realizada (reprovar nela, ou não comparecer, leva o exercício a I).
• Requisitos: 3–6 funcionais, não funcionais com números (percentis de latência, disponibilidade, durabilidade, escala), lista explícita do que está fora do escopo.
• Estimativas: QPS (médio e de pico, leituras/escritas), armazenamento, banda, cache, número de servidores — com as fórmulas (como no exercício de estimativas).
• API (endpoints ou mensagens, com requisição/resposta) e modelo de dados (entidades, chaves, armazenamento escolhido e por quê, chave de partição se houver).
• Diagrama de alto nível usando ids de componentes da paleta (lb, apigw, app, cache, sql, kafka, …) e o percurso dos dois fluxos de requisição mais importantes.
• Pelo menos dois aprofundamentos nas partes mais difíceis do problema.
• Gargalos com 10× de escala, modos de falha com detecção e mitigação, segurança, observabilidade (SLIs/SLOs/alertas) e custo em ordem de grandeza.
• Seção Uso de IA (veja a política).

Entregáveis

No site da sua documentação (tag ex7): uma página design-doc com o design doc e uma página (ou seção) por ADR, numeradas ADR-001, ADR-002, …; diagramas em Mermaid ou imagens com o seu código-fonte; JSON opcional do playground em playground/design-doc.json. Traga a página aberta para a defesa oral.

Passo a passo

1. Esclareça (≈ 10% do esforço). Anote as perguntas que você faria a um entrevistador e responda-as você mesmo como premissas: quem são os usuários, quais os casos de uso centrais, que escala, o que importa mais — latência, consistência, custo?
2. Estime. Transforme a escala em QPS, armazenamento, banda e memória. Marque quais números obrigam uma decisão de design (por exemplo, "10 TB/dia de escritas → não cabe em um único primário SQL").
3. API e modelo de dados. Defina o contrato antes das caixas. Escolha o armazenamento de cada entidade pelo padrão de acesso, não por hábito.
4. Design de alto nível. Desenhe o design mais simples que atende aos requisitos funcionais e depois percorra as requisições principais através dele.
5. Aprofundamentos. Escolha as duas ou três partes em que o problema é realmente difícil (ordem, chaves quentes, fan-out, exactly-once, consistência, tempo real, custo das chamadas a LLM…) e vá fundo: alternativas, números, comportamento sob falhas.
6. Gargalos e falhas. O que quebra primeiro com 10×? O que acontece quando cada dependência está lenta ou fora do ar? Como você detecta isso?
7. Escreva as ADRs das decisões que você gostaria que alguém novo no time entendesse daqui a um ano.
8. Fechamento. Resuma o design em cinco linhas, liste as questões em aberto e os riscos que você aceita.
9. Ensaie a defesa. Explique o design em 5 minutos para um colega e deixe que ele mude um requisito.

Problemas

O professor faz o sorteio em aula (ou o publica no Blackboard). Dois alunos com o mesmo problema escrevem documentos independentes — eles serão comparados.

Defesa oral

A defesa dura 15 minutos, com o seu design doc na tela:

1. 5 minutos — apresentação. Requisitos e números, o diagrama, os dois fluxos principais, a decisão de que você mais se orgulha.
2. 10 minutos — perguntas. Incluindo uma pegadinha: uma mudança de requisito que você precisa tratar ao vivo, por exemplo:
   • o tráfego cresce 10× (ou uma chave/um usuário fica 1.000× mais quente);
   • o sistema precisa rodar em uma segunda região, tolerando a queda de uma região;
   • uma funcionalidade nova (por exemplo, busca, notificações, um assistente de IA) precisa ser acrescentada;
   • o orçamento é cortado pela metade;
   • um componente que você escolheu não é permitido (por exemplo, sem Kafka, sem NoSQL).

Exemplos de perguntas:

• "Qual número das suas estimativas guia a maior decisão? E se ele estiver errado por um fator de 10?"
• "Mostre o que acontece quando <dependência> leva 5 segundos para responder."
• "Por que este armazenamento e não <alternativa>? O que faria você mudar de ideia?"
• "Onde dados podem ser perdidos ou duplicados? Como você sabe que isso não aconteceu?"
• "Sobre o que você alerta? Quem é acordado, e o que essa pessoa olha primeiro?"
• "Qual ADR você revisaria primeiro, e por quê?"

O que se avalia é o entendimento: você pode dizer "não considerei isso" e então raciocinar a respeito. Ler o documento em voz alta não é uma defesa.

Templates

# Design doc — <system>

**Author:** <name> · **Status:** draft | in review | final · **Date:** <yyyy-mm-dd> · **Reviewers:** <names>

## 1. Context and goals
What problem, for whom, why now. Goals and non-goals.

## 2. Requirements
### Functional
1. ...
### Non-functional
| Attribute | Target |
|-|-|
| Latency | p99 < ... ms for ... |
| Availability | ...% per month |
| Durability | ... |
| Scale | ... DAU, ... req/s peak |
| Consistency | ... |
### Out of scope
- ...

## 3. Estimates
| Quantity | Formula | Result |
|-|-|-|
Numbers that force decisions: ...

## 4. API
| Method | Path / message | Request | Response | Notes (idempotency, auth) |
|-|-|-|-|-|

## 5. Data model
| Entity | Key | Main fields | Store | Why this store | Partition key |
|-|-|-|-|-|-|

## 6. High-level design
```mermaid
flowchart LR
    client --> lb --> app --> cache
    app --> sql
```
Walk-through of flow 1: ...
Walk-through of flow 2: ...

## 7. Deep dives
### 7.1 <hard part>
Options, numbers, decision (see ADR-00x), failure behaviour.
### 7.2 <hard part>

## 8. Scalability and bottlenecks
What breaks first at 10×, and the plan.

## 9. Reliability and failure modes
| Failure | Impact | Detection | Mitigation |
|-|-|-|-|

## 10. Security and privacy
Authentication, authorization, secrets, sensitive data, abuse.

## 11. Observability
| SLI | SLO | How measured | Alert |
|-|-|-|-|

## 12. Cost
Order of magnitude per month and the main cost drivers.

## 13. Alternatives considered
| Alternative | Why not |
|-|-|

## 14. Risks and open questions

## 15. Decisions
- ADR-001 — ...
- ADR-002 — ...
- ADR-003 — ...

## 16. AI usage

## 17. References

# Design doc — <sistema>

**Autor(a):** <nome> · **Status:** rascunho | em revisão | final · **Data:** <aaaa-mm-dd> · **Revisores:** <nomes>

## 1. Contexto e objetivos
Qual problema, para quem, por que agora. Objetivos e não objetivos.

## 2. Requisitos
### Funcionais
1. ...
### Não funcionais
| Atributo | Meta |
|-|-|
| Latência | p99 < ... ms para ... |
| Disponibilidade | ...% por mês |
| Durabilidade | ... |
| Escala | ... DAU, ... req/s no pico |
| Consistência | ... |
### Fora do escopo
- ...

## 3. Estimativas
| Grandeza | Fórmula | Resultado |
|-|-|-|
Números que obrigam decisões: ...

## 4. API
| Método | Caminho / mensagem | Requisição | Resposta | Observações (idempotência, autenticação) |
|-|-|-|-|-|

## 5. Modelo de dados
| Entidade | Chave | Campos principais | Armazenamento | Por que este armazenamento | Chave de partição |
|-|-|-|-|-|-|

## 6. Design de alto nível
```mermaid
flowchart LR
    client --> lb --> app --> cache
    app --> sql
```
Percurso do fluxo 1: ...
Percurso do fluxo 2: ...

## 7. Aprofundamentos
### 7.1 <parte difícil>
Opções, números, decisão (veja ADR-00x), comportamento sob falhas.
### 7.2 <parte difícil>

## 8. Escalabilidade e gargalos
O que quebra primeiro com 10×, e o plano.

## 9. Confiabilidade e modos de falha
| Falha | Impacto | Detecção | Mitigação |
|-|-|-|-|

## 10. Segurança e privacidade
Autenticação, autorização, segredos, dados sensíveis, abuso.

## 11. Observabilidade
| SLI | SLO | Como é medido | Alerta |
|-|-|-|-|

## 12. Custo
Ordem de grandeza por mês e os principais fatores de custo.

## 13. Alternativas consideradas
| Alternativa | Por que não |
|-|-|

## 14. Riscos e questões em aberto

## 15. Decisões
- ADR-001 — ...
- ADR-002 — ...
- ADR-003 — ...

## 16. Uso de IA

## 17. Referências

Template de ADR

Cada ADR é curta (uma página) e imutável depois de aceita: se a decisão mudar, escreva uma ADR nova que substitui a antiga².

# ADR-00x — <decision in a few words>

**Status:** proposed | accepted | superseded by ADR-00y · **Date:** <yyyy-mm-dd> · **Deciders:** <names>

## Context
The situation and the forces at play (requirements, numbers, constraints).

## Decision drivers
- <driver 1, e.g. p99 < 200 ms on reads>
- <driver 2, e.g. team knows PostgreSQL>

## Considered options
1. <option A>
2. <option B>
3. <option C>

## Decision
We choose <option>, because <reasons tied to the drivers>.

## Consequences
- Positive: ...
- Negative: ... (and how we live with them)

## Confirmation
How we will know the decision works (a test, a metric, a review date).

## Links
Design doc section, related ADRs, references.

# ADR-00x — <decisão em poucas palavras>

**Status:** proposta | aceita | substituída pela ADR-00y · **Data:** <aaaa-mm-dd> · **Decisores:** <nomes>

## Contexto
A situação e as forças em jogo (requisitos, números, restrições).

## Fatores de decisão
- <fator 1, por exemplo p99 < 200 ms nas leituras>
- <fator 2, por exemplo o time conhece PostgreSQL>

## Opções consideradas
1. <opção A>
2. <opção B>
3. <opção C>

## Decisão
Escolhemos <opção>, porque <motivos ligados aos fatores>.

## Consequências
- Positivas: ...
- Negativas: ... (e como convivemos com elas)

## Confirmação
Como saberemos que a decisão funciona (um teste, uma métrica, uma data de revisão).

## Links
Seção do design doc, ADRs relacionadas, referências.

Rubrica

Níveis conforme definidos em Como os exercícios são avaliados. O documento escrito e a defesa oral são avaliados juntos; a defesa pesa tanto quanto todos os critérios escritos somados.

FAQ