Padrões de arquitetura
que viram boilerplate.

Regras que valem em qualquer projeto, salvo override explícito.

Ports & Adapters. Domínio puro, mundo externo só atrás de interface, wiring em cmd/.

# layout canônico
backend/
├── cmd/server/main.go        # entrypoint chi — todo o DI aqui
│   ├── worker/main.go          # Temporal worker
│   └── migrate/main.go
├── domain/
│   ├── entity/                 # entidades puras — ZERO deps externas
│   └── service/                # lógica de negócio
├── ports/
│   ├── inbound/                # SessionManager, WebhookValidator...
│   └── outbound/               # XxxRepository, Transcriber, DBTX...
├── adapters/
│   ├── driven/                 # 1 pasta por serviço externo
│   │   ├── postgres/ temporal/ stripe/ groq/ openrouter/ email/ ...
│   └── driving/http/           # rotas chi + handlers + middleware
├── internal/config/          # env vars validadas no boot (fail fast)
│   └── observability/          # Sentry + slog middleware
└── go.mod                      # go 1.26

App Router, React 19, Tailwind 4, pnpm, vitest. Middleware agora é proxy.ts.

frontend/src/
├── app/
│   ├── (auth)/                 # login, register, update-password
│   ├── (dashboard)/            # protegido — layout force-dynamic
│   ├── api/                    # route handlers (callback, webhook)
│   ├── providers.tsx · globals.css · layout.tsx
│   └── proxy.ts                # middleware (rename do Next 16)
├── components/<feature>/ + ui/  # Radix + custom
├── hooks/ useAuth.ts ...
├── lib/
│   ├── api.ts                  # apiFetch() — NUNCA fetch() cru
│   └── supabase/ client·server·middleware
└── types/ · test/

Toda automação roda via Task (go-task) — cada projeto tem um Taskfile.yaml v3 e nada executa fora dele: nunca comando ad-hoc no shell. A lógica vive em scripts/*.sh (bash, set -euo pipefail), a task só embrulha o script e loga com tee. Task names são a API pública do projeto (task -l = documentação); scripts/ é a trilha de auditoria.

# vocabulário Taskfile — task names são contrato
dev  dev:api  dev:worker  web:dev
test  test:backend  test:frontend  test:coverage   # dependência de build/deploy
lint  build                                        # CGO_ENABLED=0, deps:[test]
supabase:start  supabase:reset  migrate  migrate:local
deploy  deploy:backend  deploy:frontend  deploy:worker
logs:fly  status:fly  health
plan  apply  dev:apply  prd:apply                  # repos IaC — prd sempre com prompt:
vpn:up  vpn:down  vpn:status                       # acesso a recursos privados

# anatomia Taskfile v3 — gates, args, idempotência
build:
  deps: [test]                                # teste falhou = não builda
  cmds: [./scripts/build.sh 2>&1 | tee /tmp/build.log]
apply:
  desc: 'Uso: task apply -- env/dev/vpc'
  cmds: [terragrunt apply --working-dir {{.CLI_ARGS}}]
prd:apply:
  prompt: "PRODUCAO: confirma apply em prd?"     # destrutivo/prod = prompt obrigatório
supabase:start:
  status: [supabase status > /dev/null 2>&1]    # skip se já rodando

# Docker multi-stage → chainguard (0 CVEs)
FROM golang:1.26-alpine AS builder
RUN CGO_ENABLED=0 go build -ldflags "-X main.Version=${VERSION}" -o server ./cmd/server

FROM chainguard/static:latest
COPY --from=builder /app/server /server
ENTRYPOINT ["/server"]

# IaC — Terragrunt Stacks (OpenTofu) — wrapper YAML é O padrão:
# cada componente é configurado por manifest YAML estilo CRD; HCL fica genérico
infra/
├── root.hcl                    # locals: project, modules_base + remote_state
├── _units/<comp>/terragrunt.hcl  # templates parametrizados (vpc, rds, alb, ecs...)
├── env/{dev,qas,prd}/          # env.hcl: environment, region, account_id, module_ref
└── manifests/{env}/<comp>.yaml # wrapper YAML: apiVersion/kind/metadata/spec → yamldecode

# unit: backend + provider GERADOS, módulo por git tag
generate "backend"  { contents = s3 key "{env}/{comp}/terraform.tfstate" + dynamodb lock }
generate "provider" { contents = default_tags Project/Environment/ManagedBy }
terraform { source = "${modules_base}/<module>?ref=${local.ref}" }  # repo separado, semver
inputs    = merge(yamldecode(file("manifests/${env}/<comp>.yaml")).spec, {...})

# Ansible — playbook em fases, inventário YAML, orquestração do CP[0]
- name: "Fase 1 — Preparar OS"      # role prepare: sysctl 30+, modprobe, UFW, swap off
  hosts: microk8s
  become: yes
  roles: [prepare]
- name: "Fase 3 — Join nodes"
  hosts: control_plane[0]            # orquestra do primeiro CP
  tasks:
    - command: microk8s kubectl cluster-info
      register: api  until: api.rc == 0  retries: 18  delay: 10
    - include_tasks: tasks/join-node.yaml
      loop: "{{ groups['control_plane'][1:] + groups['workers'] }}"

Specs antes de código. Paths exatos — nunca PRD.md, nunca docs/specs/.

docs/
├── prd.md                       # Goals · FR/NFR · Assumptions · Epics
├── architecture.md              # Tech Stack table · Data Models · DDL · Workflows
├── stories/
│   ├── {epic}.{story}.{slug}.md # Status · Executor · AC · Tasks · Dev Notes
│   └── DEPENDENCY-GRAPH.md
└── runbooks/<topic>.md

Escolhas default. Desviar exige justificativa na arquitetura.

Checklist na ordem. Specs primeiro, código depois.

Conteúdo integral de cada llms.txt, embutido na página. Copie direto ou abra o arquivo.