Construtor Core

Construtor que gera projetos Next.js 15 com arquitetura profissional: camadas separadas (repositories, use-cases, actions), auth via Better Auth, design tokens, testes e CI/CD — tudo pronto pra desenvolver com Claude Code.

Pré-requisitos

• Node.js 22+
• Docker Desktop — necessário para o banco local (PostgreSQL via Docker Compose)
• Claude Code — CLI (npm install -g @anthropic-ai/claude-code) ou extensão na IDE

Início rápido

1. Criar um projeto

npx construtor-core new meu-sistema

Sem instalar nada antes. O npx baixa e executa automaticamente.

Isso cria o projeto com:

• Estrutura completa de pastas (app, components, repositories, use-cases, actions, stores, db, lib, types)
• Configuração pronta (TypeScript, Tailwind CSS 4, Radix UI, Zustand, Drizzle ORM, Vitest, ESLint)
• Drizzle ORM configurado (schema, client, config, scripts npm) para queries ao banco
• Better Auth configurado (server, client, Drizzle adapter, admin plugin)
• Separação auth/perfil: users (Better Auth) + usuarios (app) com FK
• Middleware com proteção de rotas (validação via fetch, Edge-compatible)
• API route catch-all para Better Auth (/api/auth/[...all])
• Repository + use-case de exemplo (users)
• Error boundaries (error, global-error, not-found)
• Vitest configurado para testes unitários
• Skills do Claude Code copiadas para o projeto
• CLAUDE.md com instruções de arquitetura para os agentes
• Dependências instaladas via npm install

2. Configurar e iniciar

1. Abra a pasta meu-sistema na sua IDE
2. Rode npm run db:start para subir o PostgreSQL local (Docker Compose)
3. Gere o secret: openssl rand -base64 32 e cole no BETTER_AUTH_SECRET do .env
4. Rode npm run db:generate para gerar a migration inicial
5. Rode npm run db:migrate para aplicar a migration no banco
6. No terminal da IDE execute claude e depois:

/init-projeto

3. Desenvolver

/dev

Comandos do banco

| Comando | O que faz | |---|---| | db:start | Sobe PostgreSQL local via Docker Compose | | db:stop | Para o PostgreSQL local | | db:reset | Apaga volume e recria container (banco limpo) | | db:generate | Gera migration SQL do schema Drizzle | | db:migrate | Aplica migrations no banco | | db:seed | Insere dados de dev (rodar apos migrate) | | db:studio | Interface visual do Drizzle Studio |

Comandos do CLI

| Comando | O que faz | |---|---| | npx construtor-core new <nome> | Cria um novo projeto Next.js com estrutura completa | | npx construtor-core new <nome> <dir> | Cria o projeto num diretório específico | | npx construtor-core@latest update | Atualiza skills no projeto atual (rodar na raiz do projeto) | | npx construtor-core version | Mostra a versão instalada |

Skills disponíveis

Após a instalação, estes comandos ficam disponíveis dentro do Claude Code:

| Skill | O que faz | |---|---| | /dev | Orquestrador principal: entrevista, plano e implementação | | /init-projeto [nome] | Finaliza setup: componentes base, auth, layout | | /frontend --criar [nome] | Cria novo componente seguindo boas práticas | | /frontend [caminho] | Revisa componentes existentes | | /estrutura | Revisa separação de responsabilidades | | /estrutura --fix | Revisa e corrige automaticamente | | /auditoria | Auditoria completa: segurança, tipos, performance | | /auditoria --seguranca | Apenas variáveis de ambiente e autenticação | | /testes [caminho] | Gera testes unitários com Vitest |

Stack dos projetos gerados

| Tecnologia | Papel | |---|---| | Next.js 15 (App Router) | Framework fullstack | | TypeScript 5 (strict) | Tipagem | | Tailwind CSS 4 | Estilização | | Radix UI | Primitivos acessíveis (Dialog, Dropdown, etc.) | | Drizzle ORM + postgres.js | Queries ao banco (schema como código) | | Better Auth | Autenticação (Drizzle adapter, tabelas no public schema) | | Zustand | Estado client-side | | Zod | Validação de input | | Vitest | Testes unitários |

Arquitetura de camadas

O core segue uma separação rígida de responsabilidades:

| Camada | Onde | Faz | NÃO faz | |--------|------|-----|---------| | Models | src/db/models/ | Define tabelas (Drizzle) | Lógica de app | | Schema | src/db/schema.ts | Re-exporta todos os models | Definir tabelas direto | | Migrations | drizzle/ | SQL gerado pelo Drizzle Kit | Editar manualmente | | Repositories | src/repositories/ | Operações de banco (Drizzle) | Lógica de negócio | | Use-cases | src/use-cases/ | Lógica de negócio (classes) | Acesso direto ao banco, UI | | Validations | src/lib/validations/ | Valida input (Zod) | Acesso a banco | | Types | src/types/ | Tipos de domínio (joins, DTOs) | Redeclarar tipos do schema | | Actions | src/actions/ | Server Actions (chamam use-cases) | Lógica de negócio direto | | API Routes | src/app/api/ | Adaptador HTTP fino (auth + Zod + chamar use-case) | Lógica de negócio, chamar repository direto | | Pages | src/app/ | Busca via use-cases + renderiza | Lógica de negócio | | Components | src/components/ | Renderiza UI | Fetch de dados | | Stores | src/stores/ | Estado client-side compartilhado (Zustand) | Fetch de dados, lógica de negócio | | Hooks | src/hooks/ | Lógica reativa client-side | Acesso ao banco |

Fluxo da API

API routes são adaptadores HTTP finos. A lógica de negócio é a mesma dos Server Actions — ambos chamam use-cases.

[Browser]  → Server Action (actions/) → useCase.executar() → repository → banco
[Externo]  → API Route (app/api/)     → useCase.executar() → repository → banco

Estrutura de uma API route

src/
├── app/api/clientes/
│   └── route.ts              # 1. Porta de entrada HTTP
├── lib/validations/
│   └── cliente.ts            # 2. Schema Zod (input/output)
├── use-cases/clientes/
│   └── criar-cliente.ts      # 3. Lógica de negócio pura
├── repositories/
│   └── clientes.repository.ts # 4. Acesso ao banco (Drizzle)
├── types/
│   └── cliente.ts            # 5. Tipos de domínio (DTOs)

O que cada arquivo faz

| Arquivo | Responsabilidade | Tamanho esperado | |---|---|---| | route.ts | Auth + validação Zod + chamar use-case + retornar JSON | ~20-30 linhas por método | | validations/*.ts | Schemas Zod de entrada e saída | ~10-20 linhas | | use-cases/*.ts | Regra de negócio pura | varia | | repositories/*.ts | Queries SQL via Drizzle | varia | | types/*.ts | DTOs, tipos de joins | ~5-10 linhas |

Regras

• O route.ts pode chamar mais de um use-case para compor a resposta
• Se a composição envolve lógica de negócio, criar um use-case orquestrador
• NUNCA colocar no route.ts: filtros de negócio, cálculos, transformações, decisões condicionais
• Use-cases são agnósticos — não sabem se foram chamados por Server Action ou API route
• Isso evita duplicação: se a regra muda, altera em um lugar só

Estrutura gerada pelo novo-projeto

meu-sistema/
├── src/
│   ├── app/
│   │   ├── (auth)/login/page.tsx
│   │   ├── (dashboard)/layout.tsx    ← verifica sessão
│   │   ├── (dashboard)/page.tsx
│   │   ├── api/auth/[...all]/route.ts ← catch-all Better Auth
│   │   ├── error.tsx                 ← error boundary
│   │   ├── global-error.tsx          ← error boundary (root)
│   │   ├── not-found.tsx             ← página 404
│   │   ├── globals.css
│   │   ├── layout.tsx
│   │   └── page.tsx
│   ├── components/
│   │   ├── ui/                       ← Radix UI + Tailwind (via /init-projeto)
│   │   ├── forms/fields/
│   │   ├── layout/
│   │   └── shared/
│   ├── actions/                      ← server actions (chamam use-cases)
│   ├── use-cases/usuarios/            ← lógica de negócio (classes)
│   ├── repositories/                 ← operações de banco via Drizzle
│   ├── stores/                       ← Zustand stores (estado client-side)
│   ├── hooks/                        ← custom hooks
│   ├── db/
│   │   ├── models/user.ts            ← definição de tabela
│   │   ├── schema.ts                 ← re-exporta todos os models
│   │   └── index.ts                  ← client Drizzle
│   ├── lib/
│   │   ├── auth/
│   │   │   ├── server.ts             ← config Better Auth (Drizzle adapter)
│   │   │   ├── client.ts             ← cliente browser
│   │   │   ├── index.ts              ← API pública (getAuthUser, signIn, etc.)
│   │   │   ├── provider.ts           ← re-export
│   │   │   └── middleware.ts         ← proteção de rotas (Edge-compatible)
│   │   ├── validations/usuario.ts    ← schema Zod
│   │   ├── constants.ts
│   │   └── utils.ts                  ← cn(), formatDate(), formatCurrency(), SENHA_REGEX
│   ├── types/
│   │   └── index.ts                  ← tipos de domínio + ActionResult
│   └── middleware.ts                 ← proteção de rotas
├── drizzle/                          ← migrations geradas (npm run db:generate)
├── drizzle.config.ts
├── vitest.config.ts
├── scripts/
│   └── seed.ts                       ← seed de dev (Better Auth + perfil)
├── docker-compose.yml                ← PostgreSQL local (produção usa Supabase)
├── .claude/skills/                   ← skills do Claude Code
├── .env.example
├── .env
├── CLAUDE.md
├── next.config.ts
├── package.json
├── postcss.config.mjs
└── tsconfig.json

Estrutura deste repositório

construtor-core/
├── bin/
│   └── cli.js                        ← CLI principal (construtor-core new/update/version)
├── package.json                      ← pacote npm
├── scripts/
│   ├── novo-projeto.js               ← orquestrador do construtor
│   └── templates/                    ← módulos de geração de arquivos
│       ├── drizzle.js                ← models, schema, db client, drizzle config
│       ├── repositories.js           ← repository + use-case templates
│       ├── auth.js                    ← Better Auth config, clients, seeds, docker
│       ├── config-files.js           ← package.json, tsconfig, env, gitignore
│       ├── lib-code.js               ← utils, stores, types, validations
│       ├── app-pages.js              ← pages, middleware, error boundaries, vitest
│       └── claude-md.js              ← CLAUDE.md gerado para o projeto
├── skills/
│   ├── dev/
│   │   ├── SKILL.md                  → /dev (orquestrador)
│   │   └── references/
│   │       ├── code-templates.md
│   │       └── component-rules.md
│   ├── init-projeto/SKILL.md         → /init-projeto
│   ├── frontend/
│   │   ├── SKILL.md                  → /frontend
│   │   └── references/
│   │       └── creation-templates.md
│   ├── estrutura/SKILL.md            → /estrutura
│   ├── auditoria/SKILL.md            → /auditoria
│   └── testes/
│       ├── SKILL.md                  → /testes
│       └── references/
│           └── test-templates.md
├── CLAUDE.md                         ← instruções para o Claude neste repo
├── README.md
└── .env                              ← API keys (LINEAR_API_KEY) — nunca commitar

Publicar nova versão

Antes de abrir PR pra main, atualizar a versão:

npm version patch    # 1.1.0 → 1.1.1  (correção de bug)
npm version minor    # 1.1.0 → 1.2.0  (feature nova)
npm version major    # 1.1.0 → 2.0.0  (mudança que quebra compatibilidade)