C4 (Context, Containers, Components, Code) foi formalizado por Simon Brown em 2018 e virou o padrão moderno mais acessível para diagramas de arquitetura. O Context Diagram (nível 1) é o ponto de entrada: mostra o sistema como caixa única, os usuários, e os sistemas externos com que interage. Idealmente o diagrama mais visto do projeto — o que aparece em pitch, onboarding, e revisão. Diferente de UML, C4 é deliberadamente simples: 4 níveis, vocabulário limitado, foco em comunicação entre humanos.
Template
# [Nome do sistema] — Context Diagram
## Diagrama (Mermaid syntax — renderiza em GitHub/GitLab/Notion)
```mermaid
graph TB
User[("👤 Usuário
(cliente final)")]
Admin[("👤 Admin
(operador interno)")]
System[("📦 [Seu Sistema]
Faz X, Y, Z para usuários finais")]
Auth[("🔐 IdP / Auth provider
OAuth 2.1 / OIDC")]
Payment[("💳 Gateway de pagamento
Stripe / Adyen")]
Notify[("📧 Provedor de email
SES / SendGrid")]
Analytics[("📊 Sistema analítico
BigQuery / Snowflake")]
User -->|"Usa via web/mobile"| System
Admin -->|"Administra via console"| System
System -->|"Autentica via OIDC"| Auth
System -->|"Cobra via API"| Payment
System -->|"Envia notificações"| Notify
System -->|"Exporta eventos"| Analytics
```
## Descrição
### Nosso sistema (caixa central)
**Propósito:** [1 frase]
**Usuários principais:** [quem usa]
**Volume típico:** [X RPS, Y usuários ativos]
### Atores externos
| Ator | Tipo | Interação |
|------|------|-----------|
| Usuário | Pessoa | Consome via web/mobile |
| Admin | Pessoa | Configura via console |
| IdP | Sistema | Autenticação e identidade |
| Gateway de pagamento | Sistema externo | Processa cobranças |
| Provedor de email | Sistema externo | Notificações transacionais |
| Sistema analítico | Sistema externo | Ingere eventos para análise |
### Decisões / restrições
- [Por que IdP externo e não auth próprio]
- [Por que gateway X — preço, cobertura, contrato]
- [Compliance: GDPR, LGPD, PCI — quais aplicam]
### Próximos níveis (não cobertos aqui)
- **Container diagram (C2):** detalha os containers/serviços DENTRO do sistema
- **Component diagram (C3):** detalha componentes dentro de cada container
- **Code (C4):** raramente vale formalizar; código é a melhor doc
### Como atualizar
[Periodicidade — ex: revisar a cada release maior, ou trimestralmente]
[Onde mora — ex: docs/architecture/c4-context.md no repo]
Se o diagrama de contexto precisa de explicação verbal para ser entendido por um stakeholder não-técnico, ele está com muita coisa. C4 é deliberadamente simples justamente para que um diretor leigo consiga "ler" sozinho. Comece simples; níveis mais profundos (containers, componentes) ficam para documentação interna do time.
Referências
- c4model.com — site oficial de Simon Brown
- Simon Brown, Software Architecture for Developers (Leanpub, 2018)
- Structurizr — ferramenta C4 oficial
- Mermaid — diagramas em texto que renderizam