Visão
01 · Visão geral
Uma página para entender o todo. Os outros documentos aprofundam cada parte.
A arquitetura em um mapa
Três camadas de decisão
Toda decisão de uma stack mora numa de três camadas. A camada diz quem decide e quando.
| Camada | Exemplos | Quem muda | Como muda |
|---|---|---|---|
| 1. Plataforma | Exemplos: o Keycloak em id.hibex.co, o Grafana, a política <app>.hibex.app | Quem muda: mantenedor, no toolbox / enterprise-stack-design | Como muda: ADR lá; as stacks consomem |
| 2. Arquitetura | Exemplos: "toda versão é fixa", "E2E em agrupamento → cenário → caso", "TDD" | Quem muda: mantenedor, aqui | Como muda: nova versão da arquitetura; as stacks adotam por change |
| 3. Stack | Exemplos: "Java 21 + Spring Boot 4.1", "PostgreSQL 16", "duas aplicações" | Quem muda: mantenedor + agente, na stack | Como muda: ADR na stack; comportamento por change do OpenSpec |
Regra de precedência: a camada de cima vence. Se uma stack precisa de algo que a arquitetura proíbe, ela não abre exceção local — leva o pedido para cá (mesmo mecanismo dos pedidos ao design system).
O que é fixo e o que é lacuna
| Assunto | Fixo (vem decidido) | Lacuna (a stack decide ao nascer) |
|---|---|---|
| Plataforma | Fixo (vem decidido): Linux; scripts em bash | Lacuna (a stack decide ao nascer): — |
| Versões | Fixo (vem decidido): toda ferramenta, biblioteca e imagem com versão exata; nunca latest | Lacuna (a stack decide ao nascer): os números de versão |
| Linguagem e framework | Fixo (vem decidido): — | Lacuna (a stack decide ao nascer): linguagem, runtime, framework web, abordagem de UI |
| Persistência | Fixo (vem decidido): armazenamentos descartáveis em container no dev e nos testes; evolução dos dados versionada; um dono de cada formato; sem banco padrão | Lacuna (a stack decide ao nascer): quais armazenamentos (relacional, MongoDB, fila, arquivos…), a ferramenta de evolução, o dono |
| Build | Fixo (vem decidido): um comando constrói e testa tudo; wrapper/lockfile versionado | Lacuna (a stack decide ao nascer): ferramenta de build, estrutura de módulos |
| Testes de unidade e integração | Fixo (vem decidido): TDD; dependências reais em container; sem banco em memória que finge ser outro | Lacuna (a stack decide ao nascer): frameworks e bibliotecas de teste |
| Testes fim a fim | Fixo (vem decidido): Playwright + Node; hierarquia agrupamento → cenário → caso; setups em cascata; capturas ligadas aos casos | Lacuna (a stack decide ao nascer): quais agrupamentos existem (nasce com "identidade") |
| Containers | Fixo (vem decidido): Docker na entrega (uma imagem por aplicação); Compose no desenvolvimento | Lacuna (a stack decide ao nascer): imagens base e versão |
| Implantação | Fixo (vem decidido): Kamal; imagens no ghcr.io; healthcheck em /up | Lacuna (a stack decide ao nascer): hosts, domínios, nomes de serviço |
| Segredos | Fixo (vem decidido): Bitwarden Secrets Manager; só referências no repositório | Lacuna (a stack decide ao nascer): prefixo e projeto no Bitwarden |
| Identidade | Fixo (vem decidido): aplicação com área restrita: Keycloak; OIDC Authorization Code + PKCE; realm por população; acesso por grupo, nunca papel direto no usuário; permissões e perfis documentados | Lacuna (a stack decide ao nascer): quais realms, clients, permissões, perfis |
| Observabilidade | Fixo (vem decidido): log JSON no stdout, métricas Prometheus em porta interna, traces OTLP, /up | Lacuna (a stack decide ao nascer): bibliotecas que implementam o contrato |
| Backup | Fixo (vem decidido): diário, retenção 7d/4s/6m, script de restauração testado | Lacuna (a stack decide ao nascer): ferramenta (depende do banco) |
| Interface | Fixo (vem decidido): design system da Hibex, cópia em vendor/hibex/, verificador no CI | Lacuna (a stack decide ao nascer): família de cor de cada aplicação |
| Mudança | Fixo (vem decidido): OpenSpec (propose → revisão → apply → archive); ADR para decisão técnica | Lacuna (a stack decide ao nascer): — |
| Agentes de IA | Fixo (vem decidido): AGENTS.md é a fonte; CLAUDE.md só o importa; Git e infraestrutura só pelo humano | Lacuna (a stack decide ao nascer): — |
| Documentação | Fixo (vem decidido): pt-BR; diagramas (rabisco recomendado, Mermaid permitido); ARCHITECTURE.md, decisoes/, solucoes/, guias/, acesso/ | Lacuna (a stack decide ao nascer): o conteúdo |
| Capturas de tela | Fixo (vem decidido): o mecanismo (ligado ao E2E) | Lacuna (a stack decide ao nascer): se a stack mantém um acervo versionado |
Como as peças se ligam
O diagrama abaixo é o "fio" de uma funcionalidade de ponta a ponta. Cada caixa é um documento ou ferramenta deste modelo.
A forma de uma stack implantada
Toda stack, seja qual for a tecnologia, fica com esta forma em produção. Muda o conteúdo das caixas, não o desenho.
De onde vêm as regras
As regras desta arquitetura valem por si: nenhuma depende de conhecer outra stack. Como histórico, elas foram concebidas a partir do estudo de uma primeira stack de produto da Hibex, construída antes deste modelo, enquanto as regras eram descobertas; esse estudo está em 19 · Aprendizados da stack-projetos.