Arquitetura de stacks web da Hibex

• Stack = produto = repositório. Um repositório entrega um produto, com uma ou mais aplicações (cada uma com sua imagem Docker, endereço, client no Keycloak e família de cor).
• Um modelo zerado com lacunas. Tudo o que vale para qualquer tecnologia já vem decidido (regras, ORGs, estrutura, rotinas). O que depende da tecnologia vem marcado como {{LACUNA:<id>}}, para a stack preencher ao nascer.
• Nenhum código antes da stack definida. A ficha da stack (linguagem, framework, banco, testes, versões exatas) é preenchida e aceita primeiro. A CI fica vermelha enquanto houver lacuna.
• A mesma fundação para todas. Seis changes iguais em toda stack (esqueleto, identidade, E2E, observabilidade, aparência, implantação) antes da primeira funcionalidade de produto.
• Toda mudança por OpenSpec, todo código por TDD. Os testes fim a fim são hierárquicos (agrupamento → cenário → caso), e qualquer caso roda sozinho, com os setups dos níveis acima.
• Plataforma comum. Docker, Compose, Kamal, Bitwarden Secrets Manager, Keycloak, o contrato de observabilidade, backup testado e o design system da Hibex valem para todas as stacks.
• O humano publica, o agente prepara. Git, deploy, infraestrutura e segredos são do mantenedor; as regras dos agentes moram no AGENTS.md.

Uma stack construída enquanto as regras são descobertas paga caro pelo que chega tarde:

Este repositório transforma esse aprendizado num modelo, para toda stack começar do ponto em que uma stack madura chega. Como histórico: as regras foram concebidas a partir do estudo de uma primeira stack de produto da Hibex, construída antes deste modelo (19 · Aprendizados).

Toda decisão de uma stack mora numa de três camadas, e a de cima vence: o que falta em cima vira pedido, nunca exceção local.

Visão completa em 01 · Visão geral.

1. Decidir antes de construir: stack definida antes do código; decisão técnica vira ADR; comportamento vira change.
2. Tudo versionado, nada flutuante: ferramenta, biblioteca, imagem, action e CLI com versão exata.
3. O humano publica, o agente prepara: Git, deploy, infraestrutura e segredos só pelo mantenedor.
4. Teste primeiro: nenhum código sem um teste que falhou antes.
5. Uma mudança por vez, especificada: a change do OpenSpec é a unidade de trabalho.
6. Tudo reproduzível na máquina: o ambiente local sobe do zero, com um usuário por perfil.
7. Segurança por padrão: toda área restrita autenticada e autorizada por permissões finas; aplicação pública declarada como tal; nada de segredo em arquivo.
8. Operável desde o primeiro deploy: telemetria, sonda de vida e backup antes do produto.
9. A camada de cima vence: plataforma > arquitetura > stack.

Cada regra e como ela é garantida (hook, CI ou revisão): 02 · Princípios e regras.

Detalhe em 04 · Ciclo de vida.

O esqueleto que toda stack tem, seja qual for a tecnologia:

<plataforma>-stack-<produto>/
├── AGENTS.md · CLAUDE.md          regras dos agentes (CLAUDE.md só importa)
├── README.md · ARQUITETURA        porta de entrada · versão da arquitetura de origem
├── docs/
│   ├── ARCHITECTURE.md            a visão técnica viva
│   ├── stack.md                   a ficha da stack: tecnologia e versões
│   ├── produto/                   para quem e para quê
│   ├── decisoes/                  ADR-* da stack · organizacao/ORG-* (cópia, nunca editada)
│   ├── solucoes/ · guias/         detalhes de implementação · passo a passo
│   ├── acesso/<app>.md            permissões e perfis de cada aplicação
│   └── design-system/             famílias, estados, pedidos
├── openspec/                      specs (verdade viva) e changes
├── <módulos e aplicações>         o código (forma decidida na Fase 1)
├── e2e/groups/…                   testes fim a fim hierárquicos
├── deploy/<app>/                  Dockerfile · deploy.yml · .kamal/secrets
├── eng/                           scripts: ambiente local, auth, e2e, backup, verificações
├── vendor/hibex/                  cópia do design system, nunca editada
└── compose.yaml                   ambiente local descartável

As três idades do repositório (recém-nascido, fundação pronta, maduro): 05 · Anatomia.

Comece pela visão geral e aprofunde só no que interessa. Cada documento abre com um desenho que resume o assunto.

Por onde começar, conforme o seu papel

Todos os documentos

• Criar uma stack nova: hoje, enquanto o modelo zerado não existe, a referência é 04 + 06 + 07. Depois da validação, eng/new-stack.sh copiará o modelo.
• Adotar numa stack existente: cada assunto vira uma change do OpenSpec na própria stack, que decide a ordem e o ritmo; este repositório não acompanha quem adota.
• Mudar uma regra: ver Governança.

(Versões, CHANGELOG.md e arquivo ARQUITETURA são propostas desta visão, questão 3 de 20.)

stack-architecture/
├── README.md                     este documento
├── AGENTS.md · CLAUDE.md         regras para agentes de IA (CLAUDE.md só importa)
├── CHANGELOG.md                  as versões da arquitetura e o "Para as stacks" de cada uma
├── docs/
│   ├── 01…20-*.md                a arquitetura, um assunto por documento
│   ├── decisoes/                 ADRs deste repositório e, em organizacao/, as ORGs de toda stack
│   ├── imagens/desenhos/         os rabiscos (SVG gerado; não se edita à mão)
│   ├── imagens/banner-*.svg      o banner (README) e a capa (site), claro e escuro
│   └── design-system/            a família do site e os pedidos ao design system
├── modelo/                       o modelo zerado: os arquivos com que toda stack nasce, em lacunas
├── exemplos/e2e-atendimento/     o projeto de exemplo que prova o harness do E2E (prove.mjs)
├── eng/new-stack.sh              cria uma stack nova a partir do modelo (Fase 0)
├── eng/tests/                    os testes do new-stack.sh
├── eng/gap-catalog.sh   confere que cada lacuna do modelo está uma vez no catálogo
├── .github/workflows/ci.yml      testes dos scripts e hooks do modelo, catálogo, versões fixas, prova do E2E
├── eng/sketches/                 desenha os rabiscos e o banner (boards/ tem um arquivo por documento)
├── eng/atualizar-design-system.sh  traz a cópia do design system (do mantenedor: faz git clone)
├── vendor/hibex/                 cópia do design system 0.16.1, nunca editada à mão
├── site/                         gerador do site estático, nginx e as instruções de publicar
├── Dockerfile · docker-compose.yml  a imagem do site e o jeito de vê-la localmente
└── config/deploy.yml · .kamal/   o deploy em architecture.enterprise.hibex.net (do mantenedor)

O site

Os mesmos documentos como site estático, no design system da Hibex (família cobalt, três cantos, tema claro e escuro), com os rabiscos embutidos nas páginas. Tudo é gerado no build: o navegador não desenha nada, e o site funciona sem rede. Será publicado em architecture.enterprise.hibex.net, aberto, como o site do design system.

docker compose up --build             # a imagem de produção, em http://localhost:8080
node site/gerar.mjs --servir          # sem Docker, a mesma porta (antes: cd site && npm ci)

Pré-requisitos, publicação e como mudar um rabisco: site/README.md.

Convenções de escrita

• Português brasileiro; identificadores e nomes de ferramenta em inglês; termos técnicos consagrados sem tradução;
• Todo documento grande abre com um rabisco que resume o assunto, no estilo de rabisco do design system (a ADR-0037 dele): traço de lápis, Caveat, só as cores da marca, nos dois temas. O rabisco é desenhado por código em eng/sketches/boards/ e o texto ao redor sempre diz o mesmo que ele (o desenho não carrega informação sozinho). Nas stacks, o rabisco é a recomendação e o Mermaid é permitido (ORG-0005);
• Imagem que não é rabisco é, de preferência, SVG desenhado por código (como o banner, eng/sketches/banner.mjs). Quando precisa de um gerador de imagens, nasce como prompt num arquivo <imagem>.prompt.md ao lado do caminho dela (o banner tem os dele, para uma versão futura gerada por IA), e o mantenedor gera a imagem;
• Marca: o logotipo da Hibex é sempre o arquivo do design system, nunca texto redigitado nem desenho de imagem gerada.

Um projeto da Hibex Solutions.