Status: Approved · v2.1 · SPEC-ARCH-BOUNDARIES-001

depends_on: SPEC-ARCH-MONOREPO-001

used_by: IS-ZERO-00.1, IS-ZERO-00.2

Package boundaries

Contrato de dependências que impede acoplamento silencioso e atalhos gerados por humanos ou IAs.

Matriz

Pacote	Pode importar	Não pode importar
contracts	arquivos internos	qualquer pacote interno/framework
mocks	contracts	shared, ui, apps, api
ui	contracts (tipos limitados)	shared, mocks, api, apps
ui-web	ui	contracts diretamente, shared, mocks, api, apps
ui-native	ui	contracts diretamente, shared, mocks, api, apps
shared	contracts, mocks	apps, api
web/mobile	contracts, shared, ui, ui-web (web)/ui-native (mobile)	api, fixtures/handlers de mocks
storybook	ui, ui-web	contracts, shared, mocks, api, web/mobile (nada de import direto de outro app)
api	contracts	shared, ui, mocks, apps

Regras operacionais

• Entre packages, usar package export; nunca ../../../packages/.../src.
• Type-only import também respeita boundary.
• UI recebe props e não chama hooks/services.
• Shared route builder não importa routers.
• API e apps comunicam por HTTP, nunca import.
• Runtime validation fica na API; form validation pode melhorar UX, mas backend revalida.
• Cálculo financeiro real e permission real pertencem ao backend.

Sinais de violação

• Screen importando @raizfc/mocks.
• UI importando @raizfc/shared.
• API importando hooks.
• Contracts importando decorators.
• Tipo duplicado no app.
• Endpoint string no componente.

Automação futura

• ESLint no-restricted-imports.
• dependency-cruiser/Madge quando necessário.
• CI de architecture compliance.

Critérios de aceite

• Grafo sem ciclos.
• Imports proibidos falham no lint futuro.
• Responsabilidade de cada pacote é clara.

Histórico

• 2.1 — adiciona ui-web e ui-native (adapters React DOM/React Native de packages/ui, ex.: RzButton) e storybook (app dedicado que só roda o Storybook, sem componente próprio). Nenhum app importa arquivo de outro app diretamente — web/mobile/storybook compartilham componentes só via ui-web/ui-native.
• 2.0 — versão anterior, preservada no histórico Git.