Bloco Arquitetura
O que o bloco Arquitetura define
O bloco Arquitetura é um bloco de Padrões de Engenharia (padroes.spell) e define as decisões arquiteturais que se aplicam a todo o projeto: padrão de organização do código, estratégia de erros, logging e outras diretrizes transversais.
Sem o bloco Arquitetura, a IA escolhe a arquitetura por conta própria baseada no stack declarado em Tecnologia. Com o bloco declarado, o arquiteto técnico estabelece as restrições que a IA deve seguir.
Arquitetura {
padrao: Clean Architecture
organizacao-de-pastas: por feature
tratamento-de-erros: exceções tipadas + middleware global
logging: structured logging com correlationId
- Todas as respostas de erro seguem o formato {code, message, details}
- Controllers são finos — lógica vai nos Use Cases
- Repositórios não retornam IQueryable — só entidades materializadas
}Campos estruturados
| Campo | Descrição | Exemplos de valor |
|---|---|---|
padrao | Padrão arquitetural principal | Clean Architecture, Hexagonal, MVC, Layered |
organizacao-de-pastas | Como o código é organizado em pastas | por feature, por camada, por tipo |
tratamento-de-erros | Estratégia de tratamento de exceções | exceções tipadas + middleware global |
logging | Estratégia de logging | structured logging, console simples |
Instruções livres de arquitetura
A maioria das decisões arquiteturais não cabe em campos estruturados. Use instruções livres para qualquer diretriz que a IA deve seguir:
Arquitetura {
padrao: Hexagonal (Ports and Adapters)
organizacao-de-pastas: por domínio
tratamento-de-erros: Result pattern — sem exceções não tratadas
logging: OpenTelemetry + Jaeger
/// Arquitetura hexagonal foi escolhida para facilitar troca de banco de dados
/// sem impacto no domínio. Adapters de banco ficam na camada Infrastructure.
- Domain Layer não conhece infraestrutura — zero dependências externas
- Application Layer orquestra use cases — sem lógica de negócio própria
- Infrastructure Layer implementa os ports: banco, e-mail, storage
- Nenhuma entidade de domínio depende de atributos de ORM
- Testes unitários de domínio não precisam de banco de dados
}Padrões de resposta e contratos de API
O bloco Arquitetura é o lugar certo para declarar o formato de respostas da API e outros contratos transversais:
Arquitetura {
padrao: Vertical Slice Architecture
- Todas as respostas de erro seguem {code: string, message: string, details: object}
- Respostas paginadas seguem {items: [], total: int, skip: int, take: int}
- Endpoints de criação retornam o objeto completo com ID gerado
- Endpoints de atualização retornam o objeto completo atualizado
- Endpoints de exclusão retornam 204 sem corpo
- Datas sempre em ISO 8601 com timezone UTC
}Notas do arquiteto para decisões importantes
Use notas /// para registrar o motivo de decisões arquiteturais relevantes. Isso preserva o contexto para futuros desenvolvedores — e para a própria IA, caso precise revisitar a arquitetura:
Arquitetura {
padrao: Clean Architecture
/// Clean Architecture foi escolhida por decisão da diretoria de engenharia
/// em 2024. Não simplificar sem aprovação do arquiteto principal.
/// Referência: ADR-001 no Confluence.
organizacao-de-pastas: por feature
/// Organização por feature facilita onboarding de novos devs
/// e reduz conflitos de merge em features paralelas.
}