Projetos multi-módulo

Liberdade total de organização

O SPELL não impõe nenhuma estrutura de organização para os arquivos .spell. O arquiteto escolre a estratégia que faz mais sentido para o projeto. O compilador lê o conjunto completo de módulos e monta um AST único — independentemente de como estão organizados.

Três estratégias comuns:

Organização por módulo de negócio

Cada arquivo agrupa todos os blocos relacionados a um domínio: Dados + Regras + Endpoints + Telas do mesmo contexto. É a organização mais comum para times com múltiplos arquitetos de negócio, pois cada pessoa pode trabalhar no seu módulo de forma independente.

agendamedica.spell — por módulo de negócio

Projeto {
  nome: AgendaMedica
  versao: 2.0
  padroes: padroes.spell
}

Arquivos {
  - usuarios.spell        // Dados + Regras + Endpoints + Telas de usuários
  - medicos.spell         // Dados + Regras + Endpoints + Telas de médicos
  - pacientes.spell       // Dados + Regras + Endpoints + Telas de pacientes
  - consultas.spell       // Dados + Regras + Endpoints + Telas de consultas
  - notificacoes.spell    // Serviços de notificação
}

Organização por tipo de bloco

Cada arquivo contém um único tipo de bloco para todo o projeto. Facilita revisão quando o arquiteto quer auditar todas as regras juntas ou todos os endpoints de uma vez. Comum em projetos onde a modelagem de dados é feita por um DBA separado.

sistema.spell — por tipo de bloco

Projeto {
  nome: SistemaVendas
  versao: 1.0
}

Arquivos {
  - todas-as-tabelas.spell    // apenas Dados { }
  - todas-as-regras.spell     // apenas Regras { }
  - todos-os-endpoints.spell  // apenas Endpoints { }
  - todas-as-telas.spell      // apenas Telas { }
}

Organização por fase de entrega

Cada pasta representa uma fase ou sprint. Boa estratégia para projetos com entregas iterativas, pois o arquiteto vai adicionando módulos conforme o projeto evolui sem reorganizar o que já existe.

plataforma.spell — por fase

Projeto {
  nome: PlataformaEdu
  versao: 3.0
  padroes: padroes.spell
}

Arquivos {
  // Fase 1 — MVP
  - fase-1/autenticacao.spell
  - fase-1/cursos.spell
  - fase-1/matriculas.spell

  // Fase 2 — Engajamento
  - fase-2/progresso.spell
  - fase-2/certificados.spell
  - fase-2/forum.spell

  // Fase 3 — Monetização
  - fase-3/assinaturas.spell
  - fase-3/pagamentos.spell
  - fase-3/relatorios.spell
}

Como o compilador mescla os módulos

Independentemente da organização escolhida, o compilador sempre gera os arquivos de saída consolidados por tipo de bloco. Todos os blocos Dados de todos os módulos são combinados num único -dados.md. Todas as Regras vão para um único -regras.md.

O compilador monta um AST único com o conteúdo de todos os arquivos na ordem declarada em Arquivos { }. Se o mesmo nome de tabela aparecer em dois módulos diferentes, o compilador emite ❌ ERRO: tabela 'Usuario' declarada mais de uma vez.

Output consolidado — independe da organização dos .spell

plataformaedu/
├── CLAUDE.md
├── LEIAME.txt
├── plataformaedu-padroes.md   ← todos os padrões
├── plataformaedu-dados.md     ← todas as tabelas de todos os módulos
├── plataformaedu-regras.md    ← todas as regras de todos os módulos
├── plataformaedu-endpoints.md ← todos os endpoints de todos os módulos
└── plataformaedu-telas.md     ← todas as telas de todos os módulos

Adicionando e removendo módulos

O spellcomp tem comandos para gerenciar os módulos do projeto. Eles atualizam o bloco Arquivos { } automaticamente, mas o arquiteto pode editar o bloco à mão sem problema:

// Adicionar módulo ao projeto e registrar no arquivo-índice
spellcomp add agendamedica modulo-exames.spell

// Remover módulo (verifica dependências antes de remover)
spellcomp remove agendamedica modulo-exames.spell

O comando remove verifica se outros módulos referenciam entidades do módulo sendo removido. Se houver dependências, o compilador emite um aviso antes de confirmar a remoção.