Quickstart para Engenharia

Objetivo

Subir e validar o ambiente completo com os checks de qualidade mais relevantes para evitar regressão arquitetural.

Pré-requisitos

• Go 1.25+
• Node 20+
• pnpm
• Python + Pipenv (para docs)
• PostgreSQL local

Fluxo recomendado (primeiro dia)

1. Instalar dependências dos três apps.
2. Configurar arquivos de ambiente (backend/web/mobile) a partir dos .env.example.
3. Subir backend e web.
4. Validar checks do web e build da documentação.
5. Navegar pelos fluxos críticos: auth, ciclos, observações, chat, cursos.

Comandos base

# raiz do mono-repo
make setup

# backend: criar arquivo de ambiente (escolha um)
cp billings-ease-backend/.env.example billings-ease-backend/.env.local
# ou
cp billings-ease-backend/.env.example billings-ease-backend/.env.docker
# ou
cp billings-ease-backend/.env.example billings-ease-backend/.env.test

# backend
make run-backend

# web
cd billings-ease-web
pnpm install
pnpm check:deps:modules
pnpm check:deps:modules:strict
pnpm lint
pnpm build

# mobile
cd ../billings-ease-mobile
pnpm install
pnpm lint
pnpm type-check
pnpm start

# documentação
cd ../billings-ease-documentation
pipenv install -r requirements.txt
pipenv run mkdocs build

Pontos de validação obrigatórios

• Backend responde GET /health.
• Login web funciona e carrega /dashboard.
• Rotas protegidas respeitam requiredRole e requiredModule.
• Mobile autentica e resolve usuário com GET /users/me.
• Documentação compila sem warnings de navegação/link.

Regras de mudança

• Mudança de contrato de API: registrar ADR e atualizar docs no mesmo PR.
• Regra de negócio crítica: manter no backend.
• Alteração de arquitetura de módulo web: manter fluxo page -> hook -> service.