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).
Hibex Solutions · arquitetura de stacks web
Toda stack nasce de onde a anterior chegou
O modelo com que toda stack web da Hibex nasce, cresce e é operada: o que vale para qualquer tecnologia já vem decidido, e o que depende dela vem marcado para cada produto preencher.
Documentos
20
ORGs
25
Changes de fundação
6
Fases da stack
5
Em 60 segundos
O que toda stack da Hibex tem em comum, seja qual for a tecnologia
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.
A arquitetura num relance
Visão geralToda decisão de uma stack mora numa de três camadas, e a de cima vence: a plataforma da Hibex sustenta esta arquitetura, que dá forma a cada stack. O que falta em cima vira pedido, nunca exceção local.
Do zero à operação
Ciclo de vidaCinco fases separadas por portões: nenhum código antes de a stack estar definida, e nenhuma funcionalidade de produto antes da fundação.
Por onde começar
Conforme o seu papel
Leia primeiro
Mantenedor validando esta visão
01 › 04 › 06 › 11 › 12 › 20
Leia primeiro
Quem vai criar uma stack nova
01 › 04 › 05 › 06 › 07
Leia primeiro
Quem desenvolve numa stack
02 › 09 › 10 › 11 › 18
Leia primeiro
Quem configura acesso no Keycloak
03 › 12
Leia primeiro
Quem opera (deploy, backup, telemetria)
13 › 14 › 15 › 18
Leia primeiro
Agente de IA
AGENTS.md › 02 › 17 › 09
Os documentos
Da visão geral às questões em aberto
Visão
01 · Visão geral
Uma página para entender o todo. Os outros documentos aprofundam cada parte.
Visão
02 · Princípios e regras
As regras que valem para toda stack, qualquer que seja a tecnologia. No modelo zerado, elas estão no AGENTS.md (para os agentes) e nas ORGs (para as pessoas), e as que…
Visão
03 · Conceitos e vocabulário
As palavras que usamos com sentido preciso. Quando um documento as usa, é este o sentido.
O modelo
04 · Ciclo de vida de uma stack
Uma stack passa por cinco fases. Entre elas há portões: condições verificáveis sem as quais a fase seguinte não começa. O mais importante é o portão 1: nenhum código…
O modelo
05 · Anatomia do repositório
Como o repositório de uma stack é em três momentos: recém-nascido (Fase 0), com a stack definida e a fundação pronta (fim da Fase 2), e maduro (Fase 3 em diante, com a…
O modelo
06 · Modelo zerado e lacunas
O modelo zerado é um repositório que sabe tudo sobre como trabalhamos e nada sobre a tecnologia do produto. Onde falta essa informação, há uma lacuna marcada. A primeira…
O modelo
07 · ORGs e ADRs
Uma stack registra decisões em dois níveis, cada um com a sua sequência. As ORGs (Organization Architecture Decision Records) são as decisões da organização: nascem aqui…
Como se trabalha
08 · Sistema de documentação
Cada tipo de conhecimento tem um lugar. Quem procura sabe onde olhar, e quem escreve sabe onde pôr. O agente segue o mesmo mapa.
Como se trabalha
09 · Mudanças com OpenSpec e TDD
Toda mudança de comportamento é uma change do OpenSpec. Toda linha de código de uma change nasce de um teste que falhou antes. As duas regras se encaixam: a spec diz o…
Como se trabalha
10 · Testes
Três camadas. As duas primeiras usam as ferramentas da linguagem da stack (lacuna); a terceira é igual em toda stack. O que é comum a todas: TDD, dependências reais em…
Como se trabalha
11 · Testes fim a fim hierárquicos
Os testes fim a fim (E2E) são organizados em três níveis — agrupamento → cenário → caso — e cada nível pode ter um setup que cria as condições de que os níveis abaixo…
Como se trabalha
17 · Agentes de IA
As stacks da Hibex são desenvolvidas com agentes de IA. As regras para eles moram no AGENTS.md — formato aberto, lido por qualquer agente. O CLAUDE.md só o importa. O que…
Como se trabalha
18 · Rotinas
O dia a dia de uma stack, rotina por rotina: quem faz, com que comando, e o que precisa estar verdadeiro no fim. Os comandos de tecnologia aparecem como <build>, <rodar…
A plataforma
12 · Identidade e acesso
Toda aplicação com área restrita é autenticada no Keycloak do toolbox e autoriza por permissões que ela mesma declara. Pessoas recebem acesso por perfis, atribuídos por…
A plataforma
13 · Containers, implantação e segredos
Docker empacota cada aplicação; Docker Compose monta o ambiente de desenvolvimento; Kamal implanta na VPS; Bitwarden Secrets Manager guarda os segredos. Deploy é sempre…
A plataforma
14 · Observabilidade
Toda aplicação nasce cumprindo um contrato de telemetria. A pilha que recebe os sinais é do toolbox; a aplicação só emite, do jeito combinado. A biblioteca que cumpre o…
A plataforma
15 · Backup e restauração
Todo dado tem backup. Toda restauração é testada. Um backup que nunca foi restaurado é uma suposição.
A plataforma
16 · Design system
A interface de toda stack segue o design system da Hibex (enterprise-stack-design). Ele está acima do produto: quando algo conflita, o produto se ajusta, e o que falta…
Origem e rumo
19 · Aprendizados da stack-projetos
A stack-projetos é a referência de estudo deste repositório: uma stack construída antes do modelo, enquanto as regras eram descobertas. Ela não segue o modelo nem faz…
Origem e rumo
20 · Questões em aberto e próximos passos
O que o mantenedor precisa decidir para esta visão virar regra, e o que construir depois. Cada questão traz opções e uma recomendação (a primeira).
Decisões
Decisões
As decisões deste repositório, em duas famílias (ORG-0001). As ORGs valem para toda stack da Hibex e chegam a cada uma como cópia da pasta organizacao/. As ADRs valem só…
Estado e roteiro
Questões em abertoA visão está escrita e validada, e as ORGs e as ADRs daqui estão aceitas. O modelo zerado está pronto, com os scripts, os hooks, a CI, o harness do E2E e o gerador de stacks. Agora vem uma stack piloto, da Fase 0 ao portão 2; depois, a primeira versão.