Stack universal

Stack universal

Esta é a stack obrigatória de todo projeto. Não é recomendação — é regra. Stacks adicionais específicas de um projeto são registradas em .specs/stack/ daquele projeto, nunca substituindo as bases aqui.

A stack

Camada	Tecnologia
Framework	Next.js (App Router)
Linguagem	TypeScript
Monorepo	Turborepo + pnpm workspaces (apps/*, packages/*)
Estilo	Tailwind CSS
Componentes	shadcn/ui (em packages/ui)
Notificações	Sonner (toasts)
Estado (frontend)	Zustand (padrão store + sync)
Validação	Zod
Testes	Vitest (+ Testing Library)
Banco	PostgreSQL (em Docker — ver orquestração)
ORM	Prisma
Contrato de API	OpenAPI (derivado do Zod) + Scalar para testes — ver OpenAPI e Scalar
Cliente tipado da API	openapi-typescript + openapi-fetch (tipos gerados do spec)
Gráficos	Recharts
Gerador de PDF	md-to-pdf (Puppeteer) para relatórios de ADR
Gerenciador de pacotes	pnpm

O projeto é um monorepo Turborepo: frontend, API e pacotes compartilhados no mesmo repositório (apps/web, packages/ui, …).

Proibições duras

• Sem any. Tipagem total, do banco ao componente — sem exceções.
• Zod em todo input de API. Nenhum dado de entrada é processado sem validação.
• Toda notificação ao usuário passa pelo Sonner (toast(...)). Nada de alert() nativo.
• Todo endpoint publica contrato OpenAPI e tem tipos gerados (openapi-typescript) para o cliente — o front nunca consome a API com tipos escritos à mão.

Validações obrigatórias antes de toda entrega

pnpm lint
pnpm typecheck   # ou: pnpm tsc --noEmit
pnpm build

Nenhuma entrega é considerada pronta sem passar pelas três.

O que é recomendação (não regra)

• A estrutura de pastas de código (src/modules, src/components, src/lib, …) é recomendada, não imposta. Ver Frontend e Backend para os pontos que são obrigatórios.
• Atomic Design para componentes: recomendado.
• Versões de Node e TypeScript não são fixadas pelo manifesto — cada projeto decide (via ADR de infraestrutura, se quiser travar).