ADR 0002 — Monorepo com pnpm workspaces e Turborepo

Status: canônico · Escopo: Ferramenta de monorepo, cache de tarefas e enforcement de boundaries · Atualizado em: 2026-07-28

Registra por que o monorepo usa pnpm workspaces com Turborepo, e por que Nx foi descartado. Existe porque a pergunta foi feita diretamente.

Contexto

O repositório tem quatro apps (apps/api-worker, apps/booking-web, apps/llm-service, apps/llm-edge-worker) e dois pacotes compartilhados (packages/contracts, packages/test-fixtures). Um deles é Python, não TypeScript. Precisávamos de resolução de dependências entre pacotes, cache de tarefas e alguma forma de impedir que as camadas se misturassem.

Decisão

pnpm workspaces para o grafo de pacotes, Turborepo para orquestração e cache de tarefas, e dependency-cruiser para enforcement de boundaries de arquitetura — com pnpm gates:selftest provando que cada regra de fato rejeita sua violação.

Consequências

Fica mais fácil: o conjunto é pequeno e cada peça é substituível isoladamente; apps/llm-service participa do monorepo pelos seus próprios scripts (uv, ruff, pytest) sem precisar de plugin; as regras de boundary vivem em um arquivo legível e versionado.

Fica mais difícil: não há geradores de scaffolding nem grafo de projeto pronto — tarefa nova é script novo no package.json. Não há visualização de dependências fora do que o dependency-cruiser gera.

Passa a ser proibido: adicionar camada de orquestração de monorepo que duplique o que Turborepo já faz.

Alternativas descartadas

Alternativa	Por que perdeu
Nx	Resolveria as mesmas três necessidades, mas o conjunto atual já as cobre — e Nx traria um grafo de projeto próprio, plugins e convenções sobre um repositório que tem um app Python fora do seu ecossistema. Custo de migração e de conceitos sem ganho correspondente para um fundador solo. Reavaliar se o número de apps crescer muito ou se o tempo de CI virar gargalo.

Onde continuar

• Regras de boundary e o self-test: ARCHITECTURE.md
• Decisão de runtime: ADR 0001