Setup Local

Guia passo a passo para rodar o sistema do zero na máquina.

Pré-requisitos

Ferramenta	Versão mínima	Para quê
Docker	24+	Rodar todos os containers
Docker Compose	2.20+	Orquestração
Node.js	20+	Desenvolvimento local do frontend/backend
npm	9+	Gerenciamento de pacotes
Git	2.40+	Controle de versão

Contas necessárias:

• Acesso ao repositório Git
• Credenciais de acesso ao Azure Key Vault (ou .env.secrets manual)
• Conta Clerk (ambiente de desenvolvimento)

1. Clone o repositório

git clone <url-do-repo> app
cd app

2. Configure as variáveis de ambiente

Crie .env e .env.secrets na raiz:

cp .env.example .env
# Preencha as variáveis — veja /inicio-rapido/variaveis-de-ambiente

Atenção

.env.secrets nunca vai para o repositório. Contém credenciais reais de produção/dev.

3. Suba os containers de dependências

# Sobe apenas PostgreSQL, Redis e MinIO
docker compose -f docker-compose.yml -f docker-compose.local.yml up -d postgres redis minio

4. Instale as dependências e rode as migrations

# Backend
cd backend
npm install
npx prisma migrate dev
cd ..

# Frontend
cd frontend
npm install
cd ..

5. Inicie o backend e frontend

# Terminal 1 — Backend
cd backend
npm run start:dev

# Terminal 2 — Frontend
cd frontend
npm run dev

O backend sobe em http://localhost:3001 e o frontend em http://localhost:3000.

6. Verifique o health

curl http://localhost:3001/health
# Deve retornar: {"status":"ok"}

Estrutura de diretórios

app/
├── backend/           # API NestJS
│   ├── src/
│   │   ├── common/    # Guards, decorators, utils compartilhados
│   │   ├── modules/   # Módulos de negócio
│   │   └── prisma/    # Configuração do Prisma
│   ├── prisma/
│   │   └── schema.prisma
│   └── Dockerfile
├── frontend/          # Next.js
│   ├── app/           # Pages (App Router)
│   └── Dockerfile
├── docs/              # Documentação antiga / notas
├── docs-site/         # Esta documentação (VitePress)
├── memory/            # Memória persistente do assistente
├── deploy.sh          # Script de deploy OBRIGATÓRIO
├── docker-compose.yml
├── docker-compose.override.yml
├── docker-compose.labels.yml
└── .env.secrets       # NÃO commitado

Rodando testes

# Backend — unitários
cd backend && npm test

# Backend — com cobertura
cd backend && npm run test:cov

# Backend — e2e
cd backend && npm run test:e2e