Setup de Desenvolvimento

Guia completo para configurar seu ambiente de desenvolvimento local e começar a contribuir com a plataforma BITIO.

Pré-requisitos

Sistema Operacional

• macOS 10.15+ ou Ubuntu 18.04+ ou Windows 10 com WSL2
• Docker para desenvolvimento com banco local (opcional)

Software Necessário

Software	Versão	Instalação
Node.js	20.x LTS	nodejs.org
npm	10.x+	Incluído com Node.js
Git	2.40+	git-scm.com
VS Code	Latest	code.visualstudio.com

Verificação das Versões

# Verificar versões instaladas
node --version    # v20.x.x
npm --version     # 10.x.x
git --version     # 2.40.x

Setup do Projeto

1. Clone do Repositório

# Clone via SSH (recomendado)
git clone git@github.com:2biz/bitio.git
cd bitio

# Ou via HTTPS
git clone https://github.com/2biz/bitio.git
cd bitio

2. Instalação de Dependências

# Instalar todas as dependências do workspace
npm install

# Verificar se instalação foi bem-sucedida
npm run --workspaces list

Workspace Monorepo

O projeto usa npm workspaces para gerenciar dependências. Um único npm install na raiz instala tudo.

3. Configuração de Environment Variables

Frontend (.env.local)

apps/frontend/.env.local

# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:3333

# Analytics (desenvolvimento)
NEXT_PUBLIC_META_PIXEL_ID=
NEXT_PUBLIC_GOOGLE_GA_ID=

# Feature Flags
NEXT_PUBLIC_ENABLE_DEV_TOOLS=true
NEXT_PUBLIC_ENABLE_ANALYTICS=false

Backend (.env)

apps/backend/.env

# Database
DATABASE_URL="postgresql://postgres:password@localhost:5432/bitio_dev"

# AWS (desenvolvimento)
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=test
AWS_SECRET_ACCESS_KEY=test

# External APIs
META_PIXEL_ACCESS_TOKEN=
GOOGLE_ANALYTICS_MEASUREMENT_ID=

4. Setup do Banco de Dados

Opção A: PostgreSQL Local

# macOS (Homebrew)
brew install postgresql
brew services start postgresql

# Ubuntu
sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql

# Criar banco de desenvolvimento
createdb bitio_dev

Opção B: Docker (Recomendado)

docker-compose.yml (criar na raiz)

version: '3.8'
services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: bitio_dev
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

# Executar PostgreSQL via Docker
docker-compose up -d postgres

# Verificar se está rodando
docker-compose ps

5. Migração do Banco

# Ir para o diretório do backend
cd apps/backend

# Executar migrações do Prisma
npx prisma migrate dev

# Gerar o Prisma Client
npx prisma generate

# Seed com dados de exemplo (opcional)
npx prisma db seed

Executando o Projeto

Desenvolvimento Completo

# Na raiz do projeto - executa todos os apps
npm run dev

# URLs disponíveis:
# Frontend: http://localhost:3000
# Backend: http://localhost:3333 (serverless offline)
# Docs: http://localhost:3001

Executar Apps Individualmente

# Frontend Next.js
cd apps/frontend
npm run dev         # Port 3000

# Backend Serverless
cd apps/backend
npm run dev         # Port 3333

# Documentação
cd apps/docs
npm start           # Port 3001

# Design System (watch mode)
cd packages/design-system
npm run dev         # Watch + hot reload

VS Code Setup

Extensions Recomendadas

Instale as extensions via comando:

code --install-extension bradlc.vscode-tailwindcss
code --install-extension esbenp.prettier-vscode
code --install-extension dbaeumer.vscode-eslint
code --install-extension ms-vscode.vscode-typescript-next
code --install-extension prisma.prisma
code --install-extension ms-vscode.vscode-json

Settings.json

.vscode/settings.json

{
  "typescript.preferences.importModuleSpecifier": "relative",
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "tailwindCSS.includeLanguages": {
    "typescript": "javascript",
    "typescriptreact": "javascript"
  },
  "files.associations": {
    "*.css": "tailwindcss"
  },
  "emmet.includeLanguages": {
    "javascript": "javascriptreact",
    "typescript": "typescriptreact"
  }
}

Workspace Recommendations

.vscode/extensions.json

{
  "recommendations": [
    "bradlc.vscode-tailwindcss",
    "esbenp.prettier-vscode",
    "dbaeumer.vscode-eslint",
    "ms-vscode.vscode-typescript-next",
    "prisma.prisma"
  ]
}

Testando o Setup

Verificar Frontend

cd apps/frontend
npm run build       # Build deve passar sem erros
npm run lint        # Lint deve passar sem erros
npm run type-check  # TypeScript deve validar

Verificar Backend

cd apps/backend
npm run build       # Serverless package
npm test            # Testes unitários
npx prisma studio   # Abrir Prisma Studio (opcional)

Teste E2E Básico

# Com todos os apps rodando (npm run dev)

# 1. Acessar frontend
curl http://localhost:3000

# 2. Testar API de saúde
curl http://localhost:3333/health

# 3. Testar endpoint de menu
curl http://localhost:3333/menu/demo-restaurant

Troubleshooting

Problemas Comuns

1. Node.js Version Issues

# Verificar versão
node --version

# Se não for 20.x, instalar via nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

2. PostgreSQL Connection Error

# Verificar se PostgreSQL está rodando
sudo systemctl status postgresql  # Linux
brew services list | grep postgres  # macOS

# Verificar string de conexão
echo $DATABASE_URL

# Testar conexão
psql postgresql://postgres:password@localhost:5432/bitio_dev

3. Port Already in Use

# Ver que processo está usando a porta
lsof -ti:3000  # Frontend
lsof -ti:3333  # Backend

# Matar processo
kill -9 $(lsof -ti:3000)

# Ou usar portas alternativas
PORT=3001 npm run dev  # Frontend
PORT=3334 npm run dev  # Backend

4. Prisma Issues

# Reset completo do banco
npx prisma migrate reset

# Regenerar client
npx prisma generate

# Verificar schema
npx prisma validate

5. npm install Issues

# Limpar cache
npm cache clean --force

# Deletar node_modules e reinstalar
rm -rf node_modules package-lock.json
npm install

# Reset completo do workspace
npm run reset  # Script personalizado

Logs e Debug

Frontend Debug

# Habilitar debug do Next.js
DEBUG=* npm run dev

# Verificar build
npm run build 2>&1 | tee build.log

Backend Debug

# Serverless offline com debug
SLS_DEBUG=* npm run dev

# Logs do Lambda
tail -f .serverless/logs/*.log

Git Workflow

Configuração do Git

# Configurar usuário (se ainda não feito)
git config --global user.name "Seu Nome"
git config --global user.email "seu@email.com"

# Configurar hooks do projeto
npm run prepare  # Instala husky hooks

Primeiro Commit

# Criar branch de feature
git checkout -b setup/meu-ambiente

# Adicionar configurações locais (não commitadas)
echo "/.env.local" >> .git/info/exclude

# Fazer um commit teste
git add .
git commit -m "docs: add local development setup"

Validar Hooks

# Testar pre-commit hook
git add . && git commit -m "test: validate hooks"

# Deve executar:
# ✓ ESLint
# ✓ Prettier  
# ✓ TypeScript check
# ✓ Security check

Próximos Passos

1. Ler arquitetura: Architecture Overview
2. Explorar Integrations: Integration Guides
3. Git Workflow: Git Guidelines
4. Security Practices: Security Practices

Precisa de Ajuda?

• Issues técnicos: GitLab Issues
• Discussões: Slack #engenharia-bitio
• Documentação: Esta docs ou README dos apps
• Code review: PRs são sempre bem-vindos!

---

Setup completo! Agora você está pronto para contribuir com a plataforma BITIO.