---
type: rule
name: fronteiras-monorepo
description: Define a convenção de pacotes e regras de importação entre módulos do monorepo
scope: global
trigger: always_on
updatedAt: "2026-06-01"
---

# Regra: Fronteiras de Pacote no Monorepo

## Contexto

Cada módulo SaaS do ecossistema é organizado em até 4 pacotes dentro de um monorepo. O agente **deve** respeitar as fronteiras de importação entre pacotes para evitar acoplamento indevido.

## Convenção de Pacotes

Cada módulo segue a estrutura:

```
<modulo>-back       ← Servidor: rotas, serviços, filas, CRON
<modulo>-front      ← Interface: páginas Vue, componentes, composables
<modulo>-comuns     ← Compartilhado: tipos, schemas Zod, enums, utils puros
<modulo>-migracao   ← Banco de dados: migrations, seeds, scripts de carga
```

Nem todo módulo terá os 4 pacotes. O mínimo funcional é `back` + `front` + `comuns`.

## Regras de Importação

### Permitido ✅

```
<modulo>-front  → pode importar de → <modulo>-comuns
<modulo>-back   → pode importar de → <modulo>-comuns
<modulo>-migracao → pode importar de → <modulo>-comuns
```

### Proibido ❌

```
<modulo>-front  ✗ nunca importar de → <modulo>-back
<modulo>-back   ✗ nunca importar de → <modulo>-front
<modulo>-migracao ✗ nunca importar de → <modulo>-front
<modulo>-front  ✗ nunca importar de → <outro-modulo>-back
<outro-modulo>  ✗ nunca importar de → <modulo>-back (direto)
```

### Comunicação entre módulos

Módulos diferentes **nunca** importam código um do outro diretamente. Comunicação entre módulos deve ocorrer via:

- **API HTTP** (chamada de serviço entre backs)
- **Fila** (BullMQ, Redis) para processamento assíncrono
- **Banco compartilhado** com schemas/tabelas separados por módulo
- **Pacote `*-comuns` compartilhado** apenas para tipos e schemas de contrato

## O que vive em cada pacote

### `<modulo>-comuns`

O pacote comuns é a **única fonte de verdade** para tipos e schemas compartilhados:

```
<modulo>-comuns/src/
├── tabelas/            ← schemas Zod por entidade (zEntidadeCriar, etc.)
├── enums/              ← enums de domínio do módulo
├── tipos/              ← tipos derivados dos schemas
└── utils/              ← funções puras sem side-effect
```

**Proibido** no comuns:
- Componentes Vue ou React
- Código com `import` de Node.js (`fs`, `path`, `http`)
- Código com `import` de bibliotecas de frontend (`vue`, `vuetify`)
- Lógica de negócio que depende de banco ou serviço externo

### `<modulo>-back`

```
<modulo>-back/src/
├── rotas/              ← endpoints Express/Fastify
├── servicos/           ← lógica de negócio
├── banco/              ← queries (Knex, Prisma, etc.)
├── filas/              ← processadores de fila
├── cron/               ← tarefas agendadas
└── utils/              ← helpers exclusivos do back
```

### `<modulo>-front`

```
<modulo>-front/src/
├── paginas/            ← páginas/views por rota
├── componentes/        ← componentes reutilizáveis do módulo
├── composables/        ← lógica reutilizável (use*.ts)
└── utils/              ← helpers exclusivos do front
```

### `<modulo>-migracao`

```
<modulo>-migracao/src/
├── migrations/         ← criação/alteração de tabelas
├── seeds/              ← dados iniciais
└── scripts/            ← scripts de carga/transformação
```

## Impacto

Sem esta regra:
- Front importa serviço de back (quebra em build de produção)
- Módulo A acessa tabelas do Módulo B diretamente (acoplamento oculto)
- Schemas ficam duplicados entre back e front
- Mudança em um módulo quebra outro sem aviso

## Referências

- Rule: `global/rules/zod-validacao-padrao` (schemas no `*-comuns`)
- Skill: `global/skills/mapear-codigo-fonte/SKILL`