Decisões de StackENLer os ADRs

Um padrãopara cada camada.

As decisões full-stack da Visual Thinking, um ADR por camada: a opção que escolhemos, as que ficaram de fora e os compromissos que aceitámos.

Encontrar uma camada Como decidimos

36 decisões34 aceitesúltima decisão em 13 de novembro de 2026

A stack, de cima a baixo

36 camadas em três faixas. Passe o rato por uma camada para ler a decisão e destacar aquelas em que se apoia; abra-a para ver o raciocínio.

Construir a app22

  1. Framework de UIReactADR-0001
  2. Framework de aplicaçãoTanStack StartADR-0002
  3. Camada de APIHono em /api/*ADR-0004
  4. Validação de entradasZodADR-0005
  5. EstilosTailwind CSS v4 + shadcn/ui sobre Base UIADR-0011
  6. Obtenção de dados e estadoTanStack Query + loaders; URL + estado do ReactADR-0012
  7. FormuláriosTanStack Form + Zod + shadcn/ui FieldADR-0013
  8. TabelasTanStack Table v9 + shadcn/ui TableADR-0018
  9. Listas virtuaisTanStack VirtualADR-0019
  10. GráficosTanStack ChartsADR-0020
  11. MarkdownTanStack MarkdownADR-0021
  12. Realce de sintaxeTanStack HighlightADR-0022
  13. Debounce e throttleTanStack Pacer, fixadoADR-0023
  14. Atalhos de tecladoTanStack Hotkeys, fixadoADR-0024
  15. SDK de IATanStack AI, fixado; fornecedor por produtoADR-0025
  16. Estrutura do projetoWorkspace Bun; pastas por camada; src/server/ vedadoADR-0026
  17. Princípios de engenhariaKISS, YAGNI, SOLID, por esta ordemADR-0027
  18. Jobs em segundo plano e agendamentoBullMQ sobre ValkeyADR-0028
  19. Email transacionalReact Email + Nodemailer por SMTPADR-0029
  20. InternacionalizaçãoParaglide JSADR-0031
  21. Datas, fusos horários e dinheirodate-fns 4 + Intl; dinheiro em unidades menoresADR-0034
  22. Camada de APIServer routes do Start em /api/*ADR-0036

Guardar e proteger7

  1. Base de dadosPostgreSQLADR-0007
  2. ORM / camada de queriesDrizzle ORM v1 + Drizzle Kit sobre Bun SQLADR-0008
  3. AutenticaçãoBetter Auth 1.7ADR-0009
  4. Limitação de pedidosrate-limiter-flexible + ValkeyADR-0010
  5. Armazenamento de ficheiros e objetosAPI S3 sobre Ceph ou outro store compatível com S3ADR-0030
  6. Backup e restauro do PostgresDefinido por deploymentADR-0032
  7. AutorizaçãoControlo de acesso do Better AuthADR-0033

Entregar e operar7

  1. Destino de deployDocker, self-hosted, em BunADR-0003
  2. Runtime e toolchainNode LTS + pnpm + Vite+ADR-0006
  3. Testesbun test + Testcontainers; Playwright E2EADR-0014
  4. ObservabilidadeOpenTelemetry + GlitchTipADR-0015
  5. CI/CDUm workflow para GitHub + Forgejo; Nodus faz o deployADR-0016
  6. Reverse proxy e TLSTraefik 3.7, sem CDN por agoraADR-0017
  7. Runtime e toolchainBun, built-ins primeiroADR-0035
ADR-0001Aceite
Abrir ADR-0001

Como se toma uma decisão

  1. 1

    Um tema de cada vez

    As camadas são decididas pela ordem das dependências: primeiro o framework de UI, mais recentemente o SDK de IA.

  2. 2

    Opções, depois a decisão

    Os candidatos realistas são avaliados face às nossas restrições, com os prós e contras registados.

  3. 3

    Um ADR datado

    Contexto, opções consideradas, a decisão e as consequências: o que fica mais fácil, o que fica mais difícil, do que abdicamos.

  4. 4

    Substituído, nunca apagado

    Um ADR posterior pode substituir uma decisão. A página antiga continua publicada, marcada como Substituída.

Em discussão agora: nenhuma em aberto.O formato ADR

A forma de cada ADR, tal como o ADR-0036 a apresenta
ADR-0036: Camada de APIEstado AceiteData ContextoOpções consideradas1. Manter o Hono (ADR-0004)2. Server routes do Start3. tRPCDecisãoConsequências

Todas as decisões, por faixa

As três faixas do logótipo são as três camadas da stack: a app no topo, os dados por baixo e, na base, tudo o que a entrega e a mantém a correr.

Construir a app

Com o que se escreve cada ecrã, rota, formulário e handler de pedidos.

  1. ADR-0001Framework de UIReactBiblioteca de UI padrão da empresa para todas as apps web — React.
  2. ADR-0002Framework de aplicaçãoTanStack StartFramework de aplicação full-stack padrão da empresa — TanStack Start.
  3. ADR-0004Camada de APIHono em /api/*Camada de API HTTP padrão da empresa — Hono, montada em /api dentro da app TanStack Start.
  4. ADR-0005Validação de entradasZodBiblioteca de validação padrão da empresa — Zod, em todas as fronteiras do sistema.
  5. ADR-0011EstilosTailwind CSS v4 + shadcn/ui sobre Base UIEstilos padrão da empresa — Tailwind CSS v4, com componentes shadcn/ui sobre primitivas Base UI.
  6. ADR-0012Obtenção de dados e estadoTanStack Query + loaders; URL + estado do ReactObtenção de dados e estado padrão da empresa — TanStack Query por trás dos loaders do Router para o estado do servidor, o URL e o React para o estado do cliente, Zustand só quando necessário.
  7. ADR-0013FormuláriosTanStack Form + Zod + shadcn/ui FieldFormulários padrão da empresa — TanStack Form com schemas Zod partilhados, componentes Field do shadcn/ui e server functions POST; JavaScript obrigatório por predefinição.
  8. ADR-0018TabelasTanStack Table v9 + shadcn/ui TableTabelas padrão da empresa — TanStack Table v9, headless, renderizado com o markup de tabela do shadcn/ui; as listas que crescem são paginadas, ordenadas e filtradas no servidor através do URL e do Query.
  9. ADR-0019Listas virtuaisTanStack VirtualListas virtuais padrão da empresa — TanStack Virtual, headless, para listas longas, feeds e grids grandes quando a paginação e o CSS não chegam.
  10. ADR-0020GráficosTanStack ChartsGráficos padrão da empresa — TanStack Charts como SVG renderizado no servidor, por trás de wrappers finos nossos e não dos gráficos do shadcn/ui assentes em Recharts, com uma tabela equivalente para cada gráfico.
  11. ADR-0021MarkdownTanStack MarkdownRenderização de Markdown padrão da empresa — TanStack Markdown atrás de um componente partilhado por app, HTML em bruto desligado e uma só política de links e imagens para texto de modelos e de utilizadores.
  12. ADR-0022Realce de sintaxeTanStack HighlightRealce de sintaxe padrão da empresa — TanStack Highlight com uma lista explícita de linguagens, HTML escapado baseado em classes e cores vindas das nossas próprias variáveis CSS em claro e escuro.
  13. ADR-0023Debounce e throttleTanStack Pacer, fixadoDebounce e throttle padrão da empresa — os hooks React do TanStack Pacer, fixados em versões exatas enquanto for pré-1.0; os limites do lado do servidor ficam com o ADR-0010.
  14. ADR-0024Atalhos de tecladoTanStack Hotkeys, fixadoAtalhos de teclado padrão da empresa — TanStack Hotkeys, fixado em versões exatas enquanto for pré-1.0, com regras de WCAG 2.1.4 e de descoberta para cada atalho.
  15. ADR-0025SDK de IATanStack AI, fixado; fornecedor por produtoSDK de IA padrão da empresa — TanStack AI, fixado em versões exatas pré-1.0 e agnóstico do fornecedor; cada produto escolhe o seu fornecedor de modelos num ADR próprio.
  16. ADR-0026Estrutura do projetoWorkspace Bun; pastas por camada; src/server/ vedadoNorma da empresa para a estrutura dos repositórios — um workspace Bun com cada app em apps/, pastas por camada dentro de cada app, código só de servidor vedado em src/server/, variáveis de ambiente lidas com T3 Env, um só esquema de nomes de ficheiros e pull requests com squash, intitulados como Conventional Commits.
  17. ADR-0027Princípios de engenhariaKISS, YAGNI, SOLID, por esta ordemPadrão da empresa para a forma do código — KISS primeiro, YAGNI depois, SOLID onde o código tem uma razão real para mudar.
  18. ADR-0028Jobs em segundo plano e agendamentoBullMQ sobre ValkeyPadrão da empresa para trabalho fora do pedido — filas e job schedulers do BullMQ sobre o Valkey que já corremos, processados por um contentor worker da mesma imagem.
  19. ADR-0029Email transacionalReact Email + Nodemailer por SMTPPadrão da empresa para o email das apps — templates React Email enviados com Nodemailer por SMTP, a partir de um job em segundo plano; o fornecedor SMTP é escolhido por projeto.
  20. ADR-0031InternacionalizaçãoParaglide JSPadrão da empresa para i18n das apps — Paraglide JS, compilado para funções de mensagem tipadas, com o locale no URL e resolvido por pedido no servidor.
  21. ADR-0034Datas, fusos horários e dinheirodate-fns 4 + Intl; dinheiro em unidades menoresPadrão da empresa para tempo e dinheiro — date-fns 4 com @date-fns/tz para cálculos de datas, Intl para formatação, timestamptz no Postgres e dinheiro em unidades menores inteiras com um código de moeda.
  22. ADR-0036Camada de APIServer routes do Start em /api/*Camada de API HTTP padrão da empresa — server routes do TanStack Start em /api/*, com os handlers em src/server/api/ e autenticação só por token. Hono apenas quando um produto publica um contrato de API.

Guardar e proteger

Onde vivem os dados, quem lhes chega e quantos pedidos cada um pode fazer.

  1. ADR-0007Base de dadosPostgreSQLMotor de base de dados padrão da empresa — PostgreSQL.
  2. ADR-0008ORM / camada de queriesDrizzle ORM v1 + Drizzle Kit sobre Bun SQLPadrão da empresa para acesso à base de dados — Drizzle ORM v1 para queries, Drizzle Kit para migrações.
  3. ADR-0009AutenticaçãoBetter Auth 1.7Padrão da empresa para autenticação — Better Auth, autoalojado na app, com sessões no nosso Postgres.
  4. ADR-0010Limitação de pedidosrate-limiter-flexible + ValkeyLimitação de pedidos ao nível da app, padrão da empresa — rate-limiter-flexible no middleware global de pedidos do Start, contadores no Valkey.
  5. ADR-0030Armazenamento de ficheiros e objetosAPI S3 sobre Ceph ou outro store compatível com S3Padrão da empresa para ficheiros — a API S3 sobre um store compatível com S3 (Ceph RADOS Gateway por predefinição), buckets privados e URLs pré-assinados para uploads e downloads a partir do browser.
  6. ADR-0032Backup e restauro do PostgresDefinido por deploymentPadrão da empresa para backups da base de dados — definidos por deployment, nunca pela app, com um registo escrito e um restauro testado antes da entrada em produção.
  7. ADR-0033AutorizaçãoControlo de acesso do Better AuthPadrão da empresa para o que um utilizador autenticado pode fazer — o controlo de acesso do Better Auth para papéis e permissões, verificado no servidor em todos os pontos de entrada, com o âmbito das linhas na query.

Entregar e operar

Como o código é construído, testado, entregue, servido e observado em produção.

  1. ADR-0003Destino de deployDocker, self-hosted, em BunDestino de deploy padrão da empresa — contentores Docker com Bun, self-hosted.
  2. ADR-0006Runtime e toolchainNode LTS + pnpm + Vite+Padrão da empresa — runtime Node LTS, gestor de pacotes pnpm, toolchain unificada Vite+ (vp).
  3. ADR-0014Testesbun test + Testcontainers; Playwright E2ENorma da empresa para testes — bun test para testes unitários, de componentes (happy-dom) e de integração (Postgres e Valkey reais em Testcontainers); Playwright para interações e end-to-end.
  4. ADR-0015ObservabilidadeOpenTelemetry + GlitchTipNorma da empresa para observabilidade — OpenTelemetry em todas as apps, exportado por OTLP com os dados sensíveis filtrados antes de saírem do processo, e GlitchTip para erros no browser. Onde a telemetria é guardada, vista e alertada fica fora da app.
  5. ADR-0016CI/CDUm workflow para GitHub + Forgejo; Nodus faz o deployNorma da empresa para CI/CD — um workflow portável que corre em GitHub Actions e Forgejo Actions (uma microVM Firecracker efémera por job), uma imagem imutável por commit, implementada pelo Nodus.
  6. ADR-0017Reverse proxy e TLSTraefik 3.7, sem CDN por agoraNorma da empresa para o edge — o Traefik em cada host termina o TLS, define o IP de cliente de confiança, filtra por /readyz e limita floods; sem CDN por agora, com o risco de flood volumétrico aceite.
  7. ADR-0035Runtime e toolchainBun, built-ins primeiroPadrão da empresa para runtime e toolchain — o Bun como runtime, gestor de pacotes, workspaces e executor de testes, com preferência pelas APIs built-in do Bun em vez de pacotes; Oxlint, Oxfmt e Vite ficam para o que o Bun não faz.

Um padrão por camada.Tudo o resto precisa do seu próprio ADR.

Estas são as predefinições para cada novo projeto. Um produto pode desviar-se, mas escreve o seu próprio ADR a explicar porquê, para que a exceção fique registada ao lado da regra que quebra.

Regras do jogo

Comece pelo topoda stack.

Ler o ADR-0001 Como decidimos