20 · Questões em aberto e próximos passos

Quinze questões, todas decididas em 2026-10-18.

Sobre este repositório

1. Nome do repositório. Decidida: stack-architecture, transversal a todas as plataformas (sem o prefixo enterprise-), no par com os nomes das stacks (<plataforma>-stack-<produto>). A pasta local architecture/ segue até o repositório ser criado.
2. Onde mora o modelo zerado. Decidida: aqui, em modelo/, versionado junto com a documentação e copiado por eng/new-stack.sh: a regra e o modelo mudam juntos, numa só tag.
3. Versões da arquitetura. Decidida: tags arquitetura-vX.Y.Z, com CHANGELOG.md e a parte "Para as stacks", como o design system; cada stack guarda a sua versão no arquivo ARQUITETURA.
4. As ADRs deste repositório. Decidida: as decisões que valem para toda stack viram ORGs daqui e chegam às stacks como cópia; as que valem só para este repositório (o site, o kit de desenho) são ADRs daqui. A numeração é a questão 5.

Sobre as regras

5. Numeração das decisões. Decidida: duas famílias, cada uma com a sua sequência desde 0001, no lugar da faixa reservada: ORG (Organization Architecture Decision Record), em docs/decisoes/organizacao/ORG-NNNN-slug.md, nasce aqui e chega a cada stack como cópia nunca editada; ADR (Architecture Decision Record), em docs/decisoes/ADR-NNNN-slug.md, nasce na stack. As duas valem como decisão. "Uma ADR nunca contradiz uma ORG" é ela mesma uma ORG (ORG-0002): o que uma ORG não permite vira pedido para cá. O que antes eram sementes "com lacuna" vira ORG (a regra) + ADR pré-escrita no modelo (a escolha da stack). Detalhe em 07.
6. Banco padrão. Decidida: sem banco padrão. Banco e armazenamentos são lacuna da Fase 1, escolhidos com ADR. O modelo traz critérios de escolha (backup e restauração, imagem com versão exata, teste com o real em container, migrations ou equivalente) e cita o PostgreSQL como opção já provada para dados relacionais, sem impor; MongoDB, filas, armazenamento de arquivos e outros são igualmente válidos.
7. E2E na CI. Decidida: não na fundação; cada stack decide numa ADR própria (consequência da questão 12).
8. Correção de bug exige change? Decidida: sim, uma change pequena, a critério do mantenedor: um teste que reproduz o bug e a correção; a spec só muda se o comportamento esperado estava errado.
9. Hook de infraestrutura. Decidida: block-infra.py vem no modelo, ao lado do hook de Git, com teste próprio.
10. Permissões finas desde a fundação. Decidida: sim, para toda aplicação com área restrita: ela nasce com <app>:acessar e pelo menos um perfil composto, e o código confere permissões, nunca perfis. Com a observação do mantenedor: uma aplicação também pode ser pública, sem autenticação (site, landing, documentação); isso é declarado na ficha e no documento de acesso dela, e uma aplicação mista separa a parte pública da restrita por rota.
11. Preparar o ambiente do E2E por fora da interface. Decidida: só em três usos (tempo passou, volume, estado inalcançável), por preparadores com interface do modelo e implementação da stack. Com a observação do mantenedor: as stacks não usam todas SQL nem um banco só (MongoDB, filas, arquivos…) e precisam de simuladores de serviços externos; o ambiente do E2E é feito de pontos de encaixe, não de SQL (11).
12. Executor e ferramentas do E2E. Decidida: Playwright Test com a camada hierarchy/, TypeScript, o Chromium do Playwright, estação (CI por ADR da stack), um processo, sem retentativas, sem comparação visual, login pela tela do Keycloak, roteiro gerado de uma corrida, resultados em e2e/results/ (11).

Sobre a referência de estudo

13. O papel da stack-projetos. Decidida: ela é só referência de estudo para conceber esta arquitetura e não entra em nenhum fluxo, roteiro ou plano daqui. Se um dia adotar o modelo, aos poucos ou numa reescrita, a decisão é dela, tomada lá: este repositório não conhece as stacks que o usam, nem as futuras. A documentação vive por conta própria: fora do estudo (19), ela aparece só como histórico, e os exemplos usam um produto fictício (03).

Sobre os diagramas e o site

14. Diagramas nas stacks. Decidida: rabiscos como recomendação, Mermaid permitido. Rabisco para o que se lê muito e muda pouco (README, visão de produto, guias, a abertura dos documentos); Mermaid para o que muda em quase toda change ou precisa sair rápido (sequências, trechos do ARCHITECTURE.md). O kit de desenho vem no modelo.
15. O site da arquitetura. Decidida: aberto, como o site do design system: público e indexado pelos buscadores.

Assuntos que vão aparecer e que, quando aparecerem, entram aqui como versão nova:

• comunicação entre stacks além de "conta de serviço + API" (eventos, filas);
• uma aplicação sem interface (só API ou worker);
• ambientes além de local e produção (desenvolvimento implantado, homologação, demonstração). O toolbox já tem o realm hibex-enterprise-dev; falta o dos colaboradores, o host e os segredos (12);
• cópia externa dos backups (decisão do toolbox);
• guia de segurança de aplicação (SSRF, cabeçalhos, CSP);
• critérios de acessibilidade além do que o design system já cobre.