Skip to content

ADR-23: Convenção de file layout em domínios e subdomínios

ADR-23: Convenção de file layout em domínios e subdomínios

Status: Aceito Data: 2026-05-28 Autor: Gabriel Sousa

Contexto

O plugin local_helico organiza código por domínio em classes/extensions/<domain>/<subdomain>/. Após a refatoração DDD do domínio product (2026-04-30) e a especificação dos domínios engine, metrics, activity, platform e admin, o codebase consolidou um padrão de file layout em 6 de 7 domínios: arquivos são agrupados por kind (responsabilidade arquitetural) em subdiretórios dedicados — contract/, service/, entity/, dto/, vo/, enums/, signal/, support/, listener/, repository/, exception/.

O domínio content é o outlier. Por razões históricas (foi o primeiro domínio especificado, em 2026-04-23, antes do padrão estar estabilizado), os arquivos de content ficam flat dentro do subdomain, agrupados apenas por prefixo de nome (discipline.php, discipline_dto.php, discipline_service.php, discipline_service_interface.php).

Sintomas do desalinhamento

  • Inconsistência cognitiva ao navegar entre domínios.
  • Subdomains de content com 15+ arquivos misturam entities, DTOs, services e interfaces sem separação visual.
  • Não é possível detectar gaps arquiteturais por listagem (ls contract/ evidencia ausência de contrato; grep por sufixo não).
  • O padrão flat conflita com a convenção PSR-4 idiomática usada em local_middag e na literatura DDD.
  • Refactors recentes (product, engine) já operaram no padrão tipado, criando débito de coerência.

ADRs relacionados

  • ADR-22 — Convenções de domínio e pertencimento de terms
  • ADR-30 — Domínio Content (arquitetura change_record, conflitos, mapa de materialização)
  • ADR-50, 60, 70, 80, 90 — Domínios product, engine, metrics, activity, platform

Decisões

1. Padrão canônico: typed dirs por kind

Todo domínio organiza arquivos PHP dentro de cada subdomain agrupando por kind em subdiretório dedicado. O namespace PSR-4 reflete o path físico (local_helico\extensions\<domain>\<subdomain>\<kind>).

2. Kind dirs aceitos

Kind dir Conteúdo
contract/ Interfaces — service contracts, repository contracts, ports
service/ Casos de uso, application services, command handlers
entity/ Entities (aggregate roots, entity_child) — modelos com identidade
dto/ Data Transfer Objects — transporte entre camadas
vo/ Value Objects — imutáveis, sem identidade
enums/ PHP enums
signal/ Eventos de domínio — payloads disparados/escutados
listener/ Listeners de signals/hooks
repository/ Implementações concretas de persistência
exception/ Exception types específicos do subdomain
support/ Helpers internos (presenters, formatters) sem categoria arquitetural

Um kind dir é criado apenas quando há ao menos um arquivo do tipo. Subdomains pequenos não criam dirs vazios.

3. Nome de arquivo e classe

Nome do arquivo e nome da classe não mudam ao mover para kind dir. O sufixo no nome (_service, _dto, _interface) é informativo e permanece — não é redundante com o kind dir porque facilita disambiguação em uses cross-namespace e segue o estilo já adotado em engine/product/metrics.

Antes:

content/base/discipline/discipline_service.php
namespace local_helico\extensions\content\base\discipline;
class discipline_service { ... }

Depois:

content/base/discipline/service/discipline_service.php
namespace local_helico\extensions\content\base\discipline\service;
class discipline_service { ... }

4. Sub-subdomains

Quando um sub-subdomain existir (ex: content.base.bank_question), a hierarquia de kind dirs aplica dentro do sub-subdomain, não acima. Sub-subdomains são tratados como qualquer subdomain.

5. Preservação de estruturas internas legítimas

Subtrees que representam pipeline interno ou agrupamento técnico (não um kind arquitetural) são preservados dentro de service/. Exemplos:

  • content.management.file_word.processing/ — pipeline de processamento Word com context/, engine/, processor/, document_source/ — preserva estrutura interna após mover sob service/processing/.
  • content.management.integration/ — integrações externas (law_school/, sharepoint/) — preserva estrutura interna.

A regra: kind dirs no nível do subdomain; subtrees técnicas internas mantidas dentro do kind dir apropriado.

6. Eventos soltos no subdomain

Signals que não pertencem a um sub-subdomain específico ficam em <subdomain>/signal/. Exemplo: content/change/content_conflict_detected.php → content/change/signal/content_conflict_detected.php.

7. Files no root do domínio

Arquivos no root do domínio (não em subdomain), como <domain>_extension.php e <domain>_hooks.php, permanecem no root sem kind dir. São arquivos de wiring/registro do plugin, não componentes de domínio.


Justificativa

  1. Consistência: 6/7 domínios já operam neste padrão. Aplicar a content elimina o outlier.
  2. Enforcement por dir: listar contract/ evidencia gaps; sufixo no nome não evidencia.
  3. PSR-4 idiomático: namespace reflete intenção arquitetural, não apenas localização.
  4. Compatibilidade com refactors recentes: alinha com 2026-04-30 (product DDD refactor).
  5. Escalabilidade: subdomains crescem (content.base.bank_question é exemplo); typed dirs absorvem crescimento sem perda de discoverability.

Trade-offs aceitos

  • Custo de migração de content: ~143 arquivos PHP a mover. Mitigado por faseamento (change → base → management) e PSR-4 auto-resolve de namespaces.
  • Profundidade de path adicional: mais um nível de diretório. Aceitável pela legibilidade ganha.
  • Sufixo redundante no nome: service/discipline_service.php repete a palavra service. Mantido por simetria com domínios existentes e para evitar diff massivo de renomes de classe.

Consequências

Diretas

  • Migração de content em 4 fases (change → base → management → raiz), formalizada em plan separado.
  • Atualização de ddd-config.yaml para refletir o padrão tipado quando o codegen LinkML evoluir.
  • Nenhum impacto em runtime — apenas reorganização física + namespace shift resolvido por PSR-4.

Para novos domínios

Qualquer novo subdomain criado a partir desta data segue typed dirs. PRs que criam arquivos em layout flat dentro de domínio existente são revisados como débito.

Para o codegen LinkML

O generator deve emitir arquivos diretamente em kind dirs. ADR-20 (Pipeline terms→LinkML→PHP) é atualizado em PR separado para refletir.


Referências

  • ADR-22 — Convenções de domínio
  • ADR-20 — Pipeline terms→LinkML→PHP (a atualizar)
  • ADR-30 — Domínio Content (arquitetura)
  • Plan de migração: docs/_archive/plans/2026-05-28-content-typed-dirs-migration.md (a criar na Fase 2)
Navigation

Type to search…

↑↓ navigate↵ selectEsc close