---
id: architecture-tmpl
kind: template
agent: architect
produces: docs/architecture/{slug}-architecture.md
---

# Arquitetura: {nome do sistema/feature}

**Status:** Draft
**Classe de complexidade:** {SIMPLE / STANDARD / COMPLEX}
**Camada:** {fullstack / backend / frontend / brownfield}
**Rastreio:** {FRs/NFRs/CONs e achados de pesquisa que esta arquitetura serve}

## Contexto e Objetivo

> O quadro completo antes do desenho. Necessidade do usuário, restrição de negócio, capacidade do time.
> Pensar do usuário pra trás. Sem invenção: cada linha rastreia a um FR/NFR/CON ou achado.

- **Problema:** {o que o sistema precisa resolver}
- **Usuário/jornada:** {quem usa e como — do usuário pra trás}
- **Restrições de negócio:** {orçamento, prazo, conformidade}
- **Fonte:** {docs/prd/..., docs/specs/..., docs/research/...}

## Requisitos Não-Funcionais (NFRs)

> NFR não declarado é a causa nº 1 de arquitetura que parece certa e quebra em produção. Declarar números.

| NFR | Alvo | Fonte |
|---|---|---|
| Escala (RPS / usuários / volume) | {número} | {FR/NFR/CON} |
| Latência (p50 / p95 / p99) | {ms} | {...} |
| Disponibilidade (SLA) | {%} | {...} |
| Segurança / conformidade | {requisito} | {...} |
| Orçamento de infra | {custo-alvo} | {...} |

## Decisões de Arquitetura

> A decisão E o porquê. Decisão sem rastro vira mito de equipe em seis meses. Tecnologia chata por
> padrão; empolgante só por exceção justificada.

| # | Decisão | Alternativas descartadas | Trade-off (custo/risco) | Rastreio |
|---|---|---|---|---|
| AD-1 | {o que foi decidido} | {o que NÃO foi e por quê} | {o preço pago} | {FR/NFR/pesquisa} |
| AD-2 | {...} | {...} | {...} | {...} |

## Espinha Estrutural

> Fronteiras de serviço, fluxo de dados, pontos de integração. Complexidade tem que ser ganha:
> começar simples, projetar pra crescer.

- **Componentes/serviços:** {o que existe e a responsabilidade de cada um}
- **Fronteiras:** {onde uma parte termina e a outra começa — o contrato entre elas}
- **Fluxo de dados:** {como o dado atravessa o sistema, do request à persistência}
- **Diagrama:** {referência ou bloco — texto/mermaid}

## Stack Tecnológico

> Cada peça é um custo de operação, contratação e risco. Justificar o exótico.

| Camada | Tecnologia | Por quê (justificativa chata-por-padrão) |
|---|---|---|
| {frontend} | {tech} | {razão} |
| {backend} | {tech} | {razão} |
| {dados} | {tech — tecnologia decidida aqui; DDL delegado ao @data-engineer} | {razão} |
| {infra} | {tech} | {razão} |

## Contratos de API e Integração

> O contrato é a fronteira entre os donos das camadas. Definir aqui; implementação fica com o @dev.

- **Estilo:** {REST / GraphQL / tRPC / WebSocket}
- **Endpoints/operações principais:** {operação → entrada → saída}
- **Integrações externas:** {serviço → protocolo → modo de falha}

## Segurança e Custo

> Camadas do design, não apêndices. Defesa em profundidade; conta de infra dentro da decisão.

- **Defesa por camada:** {autenticação, autorização, validação, criptografia em trânsito/repouso}
- **Superfície de ataque e mitigação:** {ameaça → controle}
- **Modelo de custo:** {drivers de custo e estimativa por camada}

## Failure Modes ao Escalar (Teste do 10×)

> Toda fronteira passa pelo teste do 10×. Design sem o "o que quebra" é meio design.

| Componente/fronteira | O que quebra a 10× | Sinal de alerta | Mitigação |
|---|---|---|---|
| {ex.: query do feed} | {N+1, hot path, ponto único de falha} | {métrica que avisa} | {o que fazer} |
| {...} | {...} | {...} | {...} |

## Roteamento por Especialista

> Eu costuro o sistema; cada camada vai ao seu dono. Defino a fronteira e o contrato; o dono executa.

| Camada / artefato | Dono | O que é delegado |
|---|---|---|
| Schema / DDL / RLS / índices / migration | @data-engineer | {decisão de tecnologia feita aqui; implementação lá} |
| UX / fluxos / design system | @ux-design-expert | {fluxos a detalhar} |
| Código de implementação | @dev | {a partir desta arquitetura} |
| Quality gate | @qa | {após implementação} |
| git push / PR / release / CI/CD | @devops | {sempre — exclusivo} |

## Riscos e Pendências

> O que ainda não está resolvido e precisa de decisão, pesquisa ou validação.

- {risco / pergunta aberta — quem resolve e quando}

## Change Log

| Data | Mudança | Autor |
|---|---|---|
| {data} | {o quê} | @architect |