nexus-core-v3 3.0.0

package/knowledge/architecture/system-design-tradeoffs.md

@@ -0,0 +1,231 @@
+---
+id: system-design-tradeoffs
+domain: architecture
+agents: [architect]
+when: "ao desenhar a arquitetura de um sistema e precisar pesar trade-offs de escala, latência e consistência"
+---
+
+# System Design Trade-offs — pesando escala, latência e consistência
+
+## O problema
+
+Arquitetura medíocre escolhe componentes por reflexo: "vamos usar cache", "vamos shardar o banco",
+"coloca um load balancer". Sem nomear o trade-off, sem estimar a ordem de grandeza, sem dizer **por
+que esse e não o default**. O resultado é um diagrama bonito que desmorona na primeira pergunta de
+"e quando dobrar a carga?".
+
+O tell do desenho genérico:
+
+- Decisão de consistência implícita ("o banco resolve") — quando *forte vs eventual* muda toda a UX.
+- Cache jogado em cima sem definir a **estratégia de escrita** nem a **invalidação** (a parte difícil).
+- "Vamos escalar horizontalmente" sem back-of-the-envelope: nenhum número de RPS, storage, banda.
+- Replicação master-slave assumida sem citar o custo (lag de replicação, promoção manual de slave).
+- L4 vs L7 no load balancer tratados como detalhe, quando definem o que você consegue rotear.
+
+A régua deste pack: **toda escolha de componente carrega um trade-off nomeado e uma estimativa de
+ordem de grandeza.** Se você não consegue dizer o que perdeu ao ganhar, não escolheu — chutou.
+Fonte canônica das tabelas abaixo: *System Design Primer* (donnemartin).
+
+## Os princípios / o conhecimento
+
+### 1. Números de latência que ancoram qualquer estimativa
+
+Decoreba útil: as ordens de grandeza relativas. Memória é ~100 ns, datacenter round-trip é ~500 us
+(5000x), disco HDD seek é ~10 ms (20x o datacenter), e ir da Califórnia à Holanda e voltar é ~150 ms.
+
+| Operação | Latência | Relativo |
+|---|---|---|
+| L1 cache reference | 0.5 ns | — |
+| Branch mispredict | 5 ns | 10x L1 |
+| L2 cache reference | 7 ns | 14x L1 |
+| Mutex lock/unlock | 25 ns | — |
+| Main memory reference (RAM) | 100 ns | 20x L2, 200x L1 |
+| Compress 1 KB com Zippy/Snappy | 10.000 ns (10 us) | — |
+| Send 1 KB sobre rede 1 Gbps | 10.000 ns (10 us) | — |
+| Read 4 KB random de SSD | 150.000 ns (150 us) | ~1 GB/s |
+| Read 1 MB sequencial da memória | 250.000 ns (250 us) | — |
+| Round trip dentro do mesmo datacenter | 500.000 ns (500 us) | — |
+| Read 1 MB sequencial de SSD | 1.000.000 ns (1 ms) | ~1 GB/s, 4x memória |
+| HDD seek | 10.000.000 ns (10 ms) | 20x datacenter |
+| Read 1 MB sequencial sobre rede 1 Gbps | 10.000.000 ns (10 ms) | 40x memória |
+| Read 1 MB sequencial de HDD | 30.000.000 ns (30 ms) | 120x memória, 3x SSD |
+| Round trip CA → Holanda → CA | 150.000.000 ns (150 ms) | — |
+
+**Métricas de mão (throughput sequencial):**
+
+| Mídia | Leitura sequencial |
+|---|---|
+| HDD | ~30 MB/s |
+| Ethernet 1 Gbps | ~100 MB/s |
+| SSD | ~1 GB/s |
+| Memória principal | ~4 GB/s |
+
+Conclusões operacionais: SSD é ~4x a banda do disco e ~6x a banda da rede 1 Gbps; round trips
+mundiais cabem ~6–7 por segundo, contra ~2.000 round trips/s dentro do datacenter. **Evite o disco
+quando puder; mantenha dados quentes na memória; minimize round trips cross-region.**
+
+### 2. Estimativa back-of-the-envelope (potências de 2 e RPS)
+
+| Potência | Valor exato | Aprox. | Bytes |
+|---|---|---|---|
+| 2^10 | 1.024 | mil | 1 KB |
+| 2^20 | 1.048.576 | milhão | 1 MB |
+| 2^30 | 1.073.741.824 | bilhão | 1 GB |
+| 2^40 | 1.099.511.627.776 | trilhão | 1 TB |
+
+**Regra de RPS:** divida as requisições por dia por **86.400 segundos**. Ex.: 2,5 milhões de
+requisições/dia ÷ 86.400 ≈ **~29 req/s**. Sempre traduza "X por dia" em "Y por segundo" antes de
+dimensionar load balancer, fila ou banco.
+
+### 3. Modelos de consistência (a escolha que muda a UX)
+
+| Modelo | Garantia após write | Replicação | Use quando | Exemplos reais |
+|---|---|---|---|---|
+| **Fraca (weak)** | reads podem ou não ver o write; best-effort | — | latência > exatidão; perda tolerável | memcached; VoIP, vídeo-chat, jogos multiplayer em tempo real |
+| **Eventual** | reads *eventualmente* veem (tipicamente ms); async | assíncrona | alta disponibilidade vale mais que ler-na-hora | DNS, e-mail |
+| **Forte (strong)** | reads sempre veem o write | síncrona | transações, dinheiro, integridade | sistemas de arquivo, RDBMS |
+
+Trade-off central: **consistência forte custa latência e disponibilidade** (write síncrono, espera
+confirmação). Eventual ganha disponibilidade e throughput, mas exige UX que tolere janela de
+desatualização. *Read-after-write* (ler o próprio write) é a expectativa que mais quebra com
+eventual — trate explicitamente quando a tela mostra o que o usuário acabou de gravar.
+
+### 4. Disponibilidade em números (os "noves") e como compõem
+
+| Disponibilidade | Downtime/ano | Downtime/dia |
+|---|---|---|
+| 99,9% (três 9s) | 8h 45min 57s | 1min 26,4s |
+| 99,99% (quatro 9s) | 52min 35,7s | 8,6s |
+
+**Composição** — dois componentes mudam o número total conforme a topologia:
+
+| Topologia | Fórmula | Efeito |
+|---|---|---|
+| Em **sequência** | `A_total = A_foo * A_bar` | **derruba** (90% * 90% = 81%) |
+| Em **paralelo** | `A_total = 1 - (1 - A_foo) * (1 - A_bar)` | **eleva** (90% ∥ 90% = 99%) |
+
+Lição: caminho crítico com muitos componentes em série degrada a disponibilidade; redundância em
+paralelo a recupera. Conte os componentes em série antes de prometer SLA.
+
+### 5. Padrões de disponibilidade: fail-over e replicação
+
+| Padrão | Como funciona | Custo / risco |
+|---|---|---|
+| **Active-passive** | heartbeat entre ativo e standby; se o heartbeat cai, o passivo assume o IP | capacidade ociosa; janela até o standby assumir |
+| **Active-active** | ambos servem tráfego, dividindo carga | exige lidar com estado/sessão em ambos |
+| **Master-slave** | master serve read+write, replica para slaves (read) | promover slave a master exige lógica extra; risco de perda se o master cai antes de replicar |
+| **Master-master** | ambos servem read+write | precisa de LB ou lógica na app; quase sempre *loosely consistent* (viola ACID) ou aumenta latência de write; conflitos de escrita |
+
+Custo geral de replicação: **writes são replayados nas réplicas de leitura**. Muitos writes
+afogam as réplicas; quanto mais read slaves, maior o **replication lag**.
+
+### 6. Escalar o banco: federation, sharding, denormalização, SQL tuning
+
+| Técnica | O que faz | Ganho | Custo |
+|---|---|---|---|
+| **Federation** | divide o banco por **função** (ex.: users / products / forums) | menos replication lag, menos tráfego por banco, mais cache locality | inútil se o schema exige funções/tabelas enormes que cruzam domínios; joins cross-DB na app |
+| **Sharding** | distribui dados entre bancos por chave (ex.: por usuário) | menos read/write por shard, menos replicação, mais cache hits | distribuição pode ficar desbalanceada (hot shard); rebalancear adiciona complexidade; joins cross-shard difíceis |
+| **Denormalização** | duplica dados para evitar joins caros | melhora **leitura** | piora a **escrita**; sob carga pesada de write pode ficar pior que normalizado; manter cópias em sincronia |
+| **SQL tuning** | índices nas colunas consultadas; `CHAR` p/ tamanho fixo, `VARCHAR` p/ variável; particionar tabelas | leitura rápida sem trocar de paradigma | índice custa escrita e storage; é o primeiro passo, não o último |
+
+Ordem de ataque recomendada: **otimize o que tem (SQL tuning) → federation → sharding → denormalização**.
+Não pule direto pro sharding: ele é o mais caro de operar.
+
+### 7. Cache: onde cachear e a estratégia de escrita
+
+**Camadas de cache** (do cliente ao banco): client caching (browser/SO) · CDN · web server (reverse
+proxy) · database caching · application caching (Memcached/Redis em memória).
+
+A parte difícil não é cachear — é **escrever e invalidar**. As quatro estratégias:
+
+| Estratégia | Como funciona | Vantagem | Custo / risco |
+|---|---|---|---|
+| **Cache-aside** (lazy loading) | app lê cache; no miss, lê o banco e popula o cache | só cacheia o que é pedido; resiliente a falha do cache | cada miss = **3 trips** (cache → banco → cache), latência no miss; dados podem ficar stale após write no banco |
+| **Write-through** | app escreve no cache, que escreve **síncrono** no banco | leitura sempre consistente com o write | latência de write maior; nó novo não tem entradas até serem atualizadas (cache frio) |
+| **Write-behind** (write-back) | app escreve no cache; cache escreve no banco **async** | write rápido, absorve picos | **perda de dados** se o cache cai antes de persistir; complexidade |
+| **Refresh-ahead** | cache recarrega proativamente entradas quentes antes de expirar | esconde latência em dados previsíveis | previsão errada = recarga desperdiçada, pior que não fazer |
+
+Regra: **cache-aside** é o default seguro para a maioria; **write-through** quando read-after-write
+importa; **write-behind** quando o write é o gargalo e você tolera perda; **refresh-ahead** só com
+padrão de acesso previsível.
+
+### 8. CDN: push vs pull
+
+| Tipo | Como funciona | Bom para | Custo |
+|---|---|---|---|
+| **Pull CDN** | busca o conteúdo da sua origem no **primeiro request** do usuário, depois cacheia | sites de **tráfego alto** (cache se mantém quente) | primeiro request é mais lento; conteúdo pode ficar stale antes do TTL |
+| **Push CDN** | **você** sobe o conteúdo direto pro CDN e gerencia o que existe lá | sites de **tráfego baixo** ou conteúdo que muda raramente | você assume a responsabilidade de subir/expirar; storage de conteúdo pouco acessado |
+
+### 9. Load balancer e reverse proxy
+
+**L4 vs L7:**
+
+| Camada | Inspeciona | Custo | Quando |
+|---|---|---|---|
+| **Layer 4** (transporte) | IP origem/destino e portas | menos tempo e recursos | roteamento simples, throughput máximo, sem precisar olhar o conteúdo |
+| **Layer 7** (aplicação) | headers, mensagem, cookies | mais caro que L4 | roteamento por conteúdo (ex.: `/video` → cluster de vídeo, `/api` → cluster de API) |
+
+**Benefícios do load balancer:** SSL termination (descarrega cripto dos backends) · session
+persistence via cookie (mesma instância) · evita mandar request para servidor não-saudável · remove
+ponto único de falha (em par active-active/active-passive) · evita sobrecarga de recursos.
+
+**Reverse proxy vs load balancer:** o LB roteia para um **conjunto de servidores com a mesma função**;
+o reverse proxy **centraliza serviços internos atrás de uma interface pública unificada** e faz sentido
+**mesmo com um único web server**. Ambos oferecem SSL termination, compressão, cache e serviço de
+estático. Use LB quando o motivo é distribuir carga; reverse proxy quando é unificar/proteger.
+
+### 10. Assincronismo: tirar trabalho do caminho crítico
+
+| Componente | Faz | Quando |
+|---|---|---|
+| **Message queue** | recebe, segura e entrega mensagens; app publica job, worker processa async | desacoplar produtor de consumidor; absorver pico |
+| **Task queue** | recebe tarefas, executa e entrega resultado; suporta agendamento | trabalho pesado/agendado fora do request |
+| **Back pressure** | limita o tamanho da fila; retorna **HTTP 503** quando cheia | proteger memória e dar feedback de degradação ao cliente |
+
+Princípio: se a operação não precisa do resultado **na resposta**, tire-a do caminho síncrono. Fila
+custa complexidade operacional e consistência eventual — só vale quando o pico/latência justifica.
+
+## Checklist — o método (requisitos → estimativa → desenho → deep dive → gargalos)
+
+Antes de fechar um desenho, percorra as quatro etapas. Pular a 1 ou a 2 é o erro mais comum.
+
+- [ ] **1. Requisitos e escopo.** Levantei os casos de uso e as restrições? Perguntei quem usa, qual
+      volume, o que é leitura vs escrita, qual a tolerância a inconsistência?
+- [ ] **2. Estimativa back-of-the-envelope.** Traduzi requisições/dia em **req/s** (÷ 86.400)? Estimei
+      storage (potências de 2), banda e QPS de leitura vs escrita? Os números cabem nas ordens de
+      grandeza de latência (memória vs disco vs rede)?
+- [ ] **3. Desenho high-level.** Esbocei os componentes principais e as conexões, e **justifiquei**
+      cada um? Defini o modelo de consistência de cada caminho (forte vs eventual)?
+- [ ] **4. Deep dive nos componentes core.** Para cada parte crítica detalhei: estratégia de cache
+      (aside/through/behind/refresh-ahead) **e** invalidação? Estratégia de banco (tuning → federation
+      → sharding → denorm)? Replicação (master-slave vs master-master) com o custo nomeado?
+- [ ] **5. Gargalos.** Identifiquei e tratei o gargalo dado as restrições? Preciso de LB (L4 ou L7),
+      escala horizontal, cache, sharding? Calculei a disponibilidade composta (série derruba, paralelo
+      eleva)?
+- [ ] Cada componente carrega um **trade-off nomeado** — eu sei o que perdi ao ganhar?
+
+## Tabela de decisão "use X quando Y"
+
+| Use X | Quando Y |
+|---|---|
+| **Consistência forte** | dinheiro, transações, read-after-write obrigatório; tolera latência de write síncrono |
+| **Consistência eventual** | alta disponibilidade e throughput valem mais que ler-na-hora; UX tolera janela de ms |
+| **Consistência fraca** | tempo real (voz/vídeo/jogo); perder um update é melhor que esperar |
+| **Master-slave** | leitura domina; escrita centralizada num nó é aceitável; tolera promoção manual no fail |
+| **Master-master** | precisa de write em mais de um nó/região; aceita loose consistency ou conflito a resolver |
+| **Federation** | o banco divide por função natural (users/products/...); funções não cruzam domínios |
+| **Sharding** | uma tabela/dataset não cabe nem escala num nó; existe chave de partição balanceável |
+| **Denormalização** | leitura é o gargalo e os joins são caros; carga de write é moderada |
+| **SQL tuning primeiro** | sempre — antes de federar/shardar; é o passo mais barato |
+| **Cache-aside** | default; tolera staleness pós-write e o custo do miss (3 trips) |
+| **Write-through** | leitura precisa refletir o write na hora; aceita write mais lento |
+| **Write-behind** | write é o gargalo, picos altos; tolera risco de perda se o cache cair |
+| **Refresh-ahead** | padrão de acesso previsível em dados quentes; vale o custo de recarga proativa |
+| **Pull CDN** | tráfego alto; conteúdo dinâmico/atualizado; quer simplicidade de operação |
+| **Push CDN** | tráfego baixo ou conteúdo raramente atualizado; quer controle do que está no edge |
+| **Load balancer L4** | roteamento simples, throughput máximo, sem decisão por conteúdo |
+| **Load balancer L7** | roteamento por path/header/cookie; precisa inspecionar a aplicação |
+| **Reverse proxy** | unificar/proteger serviços internos; faz sentido mesmo com 1 web server |
+| **Active-passive** | redundância onde standby ocioso é aceitável; fail-over com janela tolerável |
+| **Active-active** | precisa usar toda a capacidade; resolveu estado/sessão compartilhado |
+| **Message/Task queue + back pressure** | trabalho fora do caminho síncrono; absorver pico; degradar com 503 em vez de cair |

package/knowledge/architecture/t3-fullstack-typesafe-stack.md

@@ -0,0 +1,273 @@
+---
+id: t3-fullstack-typesafe-stack
+domain: architecture
+agents: [architect]
+when: "ao montar um app full-stack type-safe do zero (especialmente para quem não é programador experiente)"
+---
+
+# T3 Stack — full-stack type-safe do tipo na ponta, sem escrever tipo
+
+A T3 stack (`create-t3-app`) é o scaffolder que entrega o tipo fluindo do banco até o
+`onClick` do botão **sem você declarar nenhuma interface compartilhada**. Você muda a coluna
+de uma tabela; o front-end quebra no `tsc` na hora, no campo certo. Esse é o produto: não é um
+"template bonito", é uma **arquitetura de boundaries tipados** que deixa um não-programador
+montar algo sólido porque o compilador vira o revisor.
+
+## O problema
+
+Quem está montando um app full-stack do zero cai em três armadilhas que a T3 resolve por
+construção:
+
+1. **O contrato API duplicado e dessincronizado.** O back-end retorna `{ userId }`, o front
+   espera `{ user_id }`, e ninguém percebe até dar `undefined` em produção. A solução ingênua
+   (escrever tipos à mão em dois lugares, ou um OpenAPI/GraphQL gigante) é trabalho que
+   apodrece. A T3 elimina o contrato escrito: o tipo da API **é inferido** do código do
+   servidor.
+2. **O env var que falta só aparece em produção.** `process.env.STRIPE_KEY` é `string |
+   undefined` em todo lugar, e o deploy sobe sem a chave. A T3 valida env no build e te dá
+   tipos.
+3. **A escolha de stack que trava você.** "Uso Prisma ou Drizzle? Pages ou App Router? Que
+   banco?" Sem critério, você escolhe por hype. A T3 expõe **uma flag por decisão**, com
+   default seguro, e te força a entender o trade-off de cada peça em vez de copiar um boilerplate
+   opaco.
+
+A filosofia oficial é dura e vale citar porque ela explica *por que* a stack é montada assim:
+**"Typesafety isn't optional. Any decision that compromises the typesafe nature of Create T3
+App is a decision that should be made in a different project."** A consequência prática: a T3
+**não** vem com gerenciador de estado, biblioteca de componentes, ou solução de deploy. **"We
+expect you to bring your own libraries that solve the needs of YOUR application."** Cada peça
+que está lá resolve um problema específico das tecnologias-core — nada de bloat.
+
+## O conhecimento
+
+### As peças e o que CADA uma resolve
+
+| Peça | Resolve | Por que está na T3 (e não outra) |
+|---|---|---|
+| **Next.js (App Router)** | Roteamento + Server/Client Components + bundling | Base; Server Components deixam chamar a API no servidor sem round-trip HTTP |
+| **TypeScript** | A linguagem do contrato | É o eixo: tudo existe pra preservar a inferência ponta a ponta |
+| **tRPC** | API type-safe sem schema escrito | Tipo flui por inferência (`typeof appRouter`), sem codegen, sem OpenAPI. Switching cost baixo = "bleed responsibly" |
+| **Zod** | Validação no boundary (input da API + env) | Schema único que **é** runtime-validator **e** fonte do tipo TS |
+| **Prisma** *ou* **Drizzle** | ORM type-safe (escolha uma) | Prisma = DX mais alta, schema próprio. Drizzle = mais perto do SQL, sem engine binário |
+| **NextAuth.js** | Auth (sessão, OAuth, adapter de banco) | "When you need flexible, secure, scalable auth" — integra no banco que você já tem |
+| **Tailwind CSS** | Estilo utility-first | Opt-in; não impõe design system |
+| **@t3-oss/env-nextjs** | Env vars validadas com Zod no build | Build não passa sem as env vars necessárias |
+
+> Filosofia "**Bleed responsibly**": tecnologia mais nova só entra onde o custo de troca é
+> baixo (tRPC, sim; banco experimental, não).
+
+### As flags do `create-t3-app` — uma decisão por flag
+
+Modo interativo (recomendado pra aprender): `npm create t3-app@latest`. Cada prompt é uma
+decisão arquitetural explícita. Para automação existe o modo CI.
+
+**Flags gerais (sempre valem):**
+
+| Flag | O que faz |
+|---|---|
+| `[dir]` | Nome/diretório do projeto |
+| `-y`, `--default` | Bootstrap com **todas** as opções selecionadas, pula os prompts |
+| `--noGit` | Não inicializa repositório git |
+| `--noInstall` | Gera o projeto **sem** rodar o install de dependências |
+
+**Flags experimentais de CI (só funcionam junto com `--CI`):**
+
+| Flag | O que ativa |
+|---|---|
+| `--CI` | Liga o modo não-interativo; **sem ela, as flags abaixo não têm efeito** |
+| `--trpc` | Inclui tRPC (API type-safe) |
+| `--prisma` | Inclui Prisma como ORM |
+| `--drizzle` | Inclui Drizzle como ORM (alternativa ao Prisma — escolha **uma**) |
+| `--nextAuth` | Inclui NextAuth.js |
+| `--tailwind` | Inclui Tailwind CSS |
+| `--appRouter` | Usa o App Router do Next.js (em vez do Pages Router) |
+| `--dbProvider [provider]` | Configura o banco. Valores: `mysql`, `postgres`, `planetscale`, `sqlite`. **Default: `sqlite`** |
+
+Exemplos reais da doc:
+```bash
+pnpm dlx create-t3-app@latest --CI --trpc --tailwind
+pnpm dlx create-t3-app@latest --CI --nextAuth --tailwind --drizzle --dbProvider postgres
+```
+
+> Regra: você **não** precisa opt-out do que não quer — basta não passar a flag. Se quiser ser
+> explícito, passe `false` (ex.: `--nextAuth false`).
+
+### A organização de pastas (App Router) — `src/server` é a parede
+
+O eixo da arquitetura é **uma fronteira física entre o que roda no servidor e o que vai pro
+browser**. Isso não é estético: é o que garante que código de servidor (e segredos) nunca
+vaze pro bundle do cliente.
+
+```
+prisma/ (ou drizzle.config.ts)
+  schema.prisma          # conexão + schema do banco, migrations, seed
+public/
+  favicon.ico            # assets estáticos
+src/
+  env.js                 # validação e tipos das env vars (Zod)
+  app/                   # TODAS as rotas do Next (page.tsx, layout.tsx com providers)
+    _components/         # componentes da app
+  server/                # código que SÓ roda no servidor (a "parede")
+    api/
+      trpc.ts            # config principal do back-end tRPC (context + helpers de procedure)
+      root.ts            # faz merge dos routers e exporta o router + o TIPO dele
+      routers/           # sub-routers (post.ts, user.ts, ...)
+    auth/                # config do NextAuth (config.ts)
+    db/                  # cliente Drizzle/Prisma (index.ts) + schema (schema.ts)
+  trpc/                  # ponte pra CHAMAR tRPC do cliente e dos server components
+    server.ts            # entrypoint pra usar tRPC em Server Components
+    react.tsx            # entrypoint front-end do tRPC (tipos de input/output do router)
+    query-client.ts      # cria o Query Client (cache + dedupe nos client components)
+  styles/
+postcss.config.js        # Tailwind via PostCSS
+```
+
+Regra de ouro: **nada em `src/app` importa de `src/server`**. O cliente importa só o **tipo**
+`AppRouter` — nunca a implementação. É isso que mantém o type-safety sem mandar o servidor pro
+browser.
+
+### tRPC — o tipo flui por inferência, não por contrato escrito
+
+**1. Um sub-router define procedures. Input validado com Zod:**
+```typescript
+const userRouter = createTRPCRouter({
+  getById: publicProcedure.input(z.string()).query(({ ctx, input }) => {
+    return ctx.prisma.user.findFirst({
+      where: { id: input },
+    });
+  }),
+});
+```
+
+**2. `root.ts` junta os sub-routers e exporta SÓ o tipo:**
+```typescript
+const appRouter = createTRPCRouter({
+  users: userRouter,
+  posts: postRouter,
+  messages: messageRouter,
+});
+
+export type AppRouter = typeof appRouter;   // <- isto, e só isto, vai pro cliente
+```
+
+**3. O cliente chama com type-safety total (input e output inferidos):**
+```typescript
+const userQuery = api.users.getById.useQuery(query.id);
+```
+Erre o nome do campo, ou mude o retorno no servidor, e o `tsc` acusa **aqui**. Sem codegen,
+sem step de build, sem schema duplicado.
+
+**O context (`trpc.ts`) tem duas camadas:**
+- `createInnerTRPCContext` — o que **não** depende da request (ex.: conexão de banco). Útil pra
+  testes.
+- `createTRPCContext` — o que **depende** da request (ex.: a sessão do usuário).
+
+### `publicProcedure` vs `protectedProcedure` — auth é um middleware
+
+`protectedProcedure` é só um `publicProcedure` com um middleware que checa a sessão (que veio
+do context). Se não há usuário, dispara `UNAUTHORIZED` **antes** do seu resolver rodar:
+```typescript
+export const protectedProcedure = t.procedure.use(({ ctx, next }) => {
+  if (!ctx.session?.user) {
+    throw new TRPCError({ code: "UNAUTHORIZED" });
+  }
+  return next({ /* ctx com session garantida não-nula */ });
+});
+```
+Dentro de uma `protectedProcedure`, `ctx.session.user` é tipado como existente. Você não
+escreve `if (!user) return 401` em cada handler — a parede já é o tipo.
+
+### NextAuth — sessão no servidor e no cliente
+
+| Onde | Como pega a sessão |
+|---|---|
+| Server Component (App Router) | `const session = await auth();` (de `~/server/auth`) |
+| Client Component | `const { data: session } = useSession();` (de `next-auth/react`, precisa `SessionProvider` no topo) |
+| Dentro de uma procedure tRPC | `ctx.session` (injetada via `createTRPCContext`) |
+
+- **Adapter de banco:** ao escolher Prisma **+** NextAuth (ou Drizzle + NextAuth), você ganha um
+  sistema de auth funcional com **todos os models pré-configurados** (User/Account/Session).
+- **Provider padrão:** Discord OAuth. Você só preenche `DISCORD_CLIENT_ID` /
+  `DISCORD_CLIENT_SECRET` no `.env` e registra o callback `<app url>/api/auth/callback/discord`.
+- **Adicionar campo na sessão** (ex.: `role`): use module augmentation em
+  `server/auth/config.ts` e inclua o campo no callback de sessão:
+  ```typescript
+  declare module "next-auth" {
+    interface Session extends DefaultSession {
+      user: { id: string } & DefaultSession["user"];
+    }
+  }
+  ```
+  Se adicionar coluna nova no model do adapter, **dê um default** (ex.: `role Role
+  @default(USER)`) — o adapter não conhece o campo extra.
+
+### Env vars — o Zod também guarda a fronteira do ambiente
+
+`src/env.js` define server, client e o mapeamento `runtimeEnv`:
+```javascript
+export const env = createEnv({
+  server: {
+    NODE_ENV: z.enum(["development", "test", "production"]),
+  },
+  client: {
+    // NEXT_PUBLIC_CLIENTVAR: z.string(),
+  },
+  runtimeEnv: {
+    NODE_ENV: process.env.NODE_ENV,
+  },
+});
+```
+Regras:
+- Variável de servidor vai em `server`; variável que o browser pode ver **precisa** do prefixo
+  `NEXT_PUBLIC_` e vai em `client`.
+- Acessar variável de servidor no cliente dispara erro de runtime — a fronteira é tipada.
+- **O build não completa** sem as env vars validadas (validação no build *e* runtime).
+- Para cada nova var: (1) põe no `.env`, (2) define o validador Zod, (3) destrutura em
+  `runtimeEnv` como `KEY: process.env.KEY`. "By destructuring it manually, you ensure that the
+  variable will never be stripped out from the bundle."
+- Conversão de tipo: `z.coerce.number()`, `z.coerce.boolean()` (env é sempre string crua).
+
+## Checklist
+
+Antes de considerar o scaffold "pronto pra construir em cima":
+
+- [ ] Sei justificar **cada flag** que liguei (não rodei `--default` no automático sem
+      entender)?
+- [ ] O cliente importa **só o tipo** `AppRouter` — nenhum import de `src/server` em `src/app`?
+- [ ] Todo input de procedure tem `.input(z.…)` — nenhum `query`/`mutation` recebe dado cru não
+      validado?
+- [ ] Rotas que exigem login usam `protectedProcedure`, não `publicProcedure` + check manual?
+- [ ] Toda env var que uso está declarada nos três lugares (`.env`, schema Zod, `runtimeEnv`)?
+- [ ] Variável sensível **não** está com prefixo `NEXT_PUBLIC_` (senão vaza pro bundle)?
+- [ ] Escolhi **um** ORM (Prisma OU Drizzle), não os dois?
+- [ ] O `dbProvider` está coerente com o banco real do deploy (não ficou em `sqlite` default por
+      esquecimento)?
+- [ ] Defini default para qualquer coluna nova que adicionei nos models do adapter NextAuth?
+
+## Tabela de decisão
+
+| Sua necessidade | A peça / flag | Observação |
+|---|---|---|
+| API type-safe sem escrever contrato | `--trpc` | O retorno do servidor vira o tipo do cliente por inferência |
+| Validar input da API e env vars | Zod (vem junto) | Mesmo schema = validação runtime + tipo TS |
+| ORM com DX máxima, schema declarativo | `--prisma` | Engine própria; ótimo pra quem está aprendendo |
+| ORM perto do SQL, sem binário, edge-friendly | `--drizzle` | Mais controle; `drizzle.config.ts` + `db/schema.ts` |
+| Banco de dev rápido, zero setup | `--dbProvider sqlite` | Default; troque para `postgres`/`mysql` no deploy |
+| Postgres / MySQL / PlanetScale em prod | `--dbProvider postgres\|mysql\|planetscale` | Defina **antes** de gerar migrations |
+| Login, OAuth, sessão | `--nextAuth` | Combine com `--prisma`/`--drizzle` → models de auth prontos |
+| Proteger uma rota de API | `protectedProcedure` | Middleware de sessão, não check manual por handler |
+| Buscar dados no servidor sem HTTP | `src/trpc/server.ts` em Server Component | Chama a procedure direto, sem round-trip |
+| Buscar/mutar dados no cliente com cache | `api.x.y.useQuery/useMutation` (`trpc/react.tsx`) | Cache + dedupe via `query-client.ts` |
+| Estilo utility-first | `--tailwind` | Opt-in; sem design system imposto |
+| Gerenciador de estado / UI lib / deploy | **nenhuma flag** | Filosofia: "bring your own" — adicione você |
+| Automatizar a geração (CI/script) | `--CI` + flags | Sem `--CI`, as flags de pacote são ignoradas |
+
+---
+
+**Fontes (verificadas na doc oficial):** create.t3.gg —
+[Introduction](https://create.t3.gg/en/introduction),
+[Installation](https://create.t3.gg/en/installation),
+[Folder Structure (App)](https://create.t3.gg/en/folder-structure-app),
+[tRPC](https://create.t3.gg/en/usage/trpc),
+[NextAuth.js](https://create.t3.gg/en/usage/next-auth),
+[Environment Variables](https://create.t3.gg/en/usage/env-variables).