Aller au contenu

Architecture Dependencies

Status

Normative Architecture Contract

Purpose

This document defines the authorized dependency directions between the architectural layers of CMonChoix Platform.

Its purpose is to prevent:

  • circular dependencies;
  • uncontrolled coupling;
  • technical details leaking into business layers;
  • duplicated business truth;
  • direct writes that bypass certified application boundaries.

Core rule

A dependency may point only toward a more fundamental layer or toward an explicitly authorized peer contract.

A layer must never depend on a more specialized layer.

Business truth
    ↓
Domain / Contracts
    ↓
Application / Vertical Modules
    ↓
Read Services / Write Services / Pipeline
    ↓
Infrastructure / Adapters / Runtime / Frontend

The diagram expresses dependency direction, not deployment topology.

Layer responsibilities

Domain

Owns generic business concepts, invariants and deterministic decision logic.

May depend on:

  • PHP standard library;
  • internal pure helpers;
  • Contracts.

Must not depend on:

  • Application;
  • Infrastructure;
  • Adapters;
  • Runtime;
  • Frontend;
  • Pipeline;
  • Vertical Modules;
  • WordPress;
  • SQL implementations.

Contracts

Owns stable interfaces, neutral DTOs, result structures, reason codes and cross-layer conventions.

Contracts must remain implementation-neutral and free of vertical-specific business logic.

They must not import concrete classes from Infrastructure, Adapters, Runtime, Frontend or legacy implementation namespaces.

Knowledge

Owns reusable business knowledge that enriches Domain meaning without owning orchestration or technical execution.

May depend on:

  • Domain;
  • Contracts.

Application

Owns use-case orchestration and coordinates domain decisions through explicit contracts.

May depend on:

  • Domain;
  • Knowledge;
  • Contracts.

Application must not depend directly on concrete infrastructure implementations. Transitional compatibility wrappers are acceptable only when documented, isolated and covered by a migration plan.

Vertical Modules

Own vertical-specific attributes, normalization rules, conflict policies, scoring rules and evidence interpretation.

May depend on:

  • Domain;
  • Contracts.

A Vertical Module must never depend on another Vertical Module.

A vertical may enrich generic behavior but must never redefine Domain truth or bypass shared contracts.

Read Services

Own audits, simulations, comparisons, diagnostics and validation reports.

May depend on:

  • Domain;
  • Contracts;
  • Vertical Modules;
  • read-only repository contracts.

Read Services must remain strictly read-only.

They must not:

  • execute INSERT, UPDATE or DELETE;
  • call a Write Service;
  • import concrete adapters;
  • mutate runtime state;
  • silently repair data.

Media Quality belongs to this rule by default: evaluation is audit-first, deterministic and non-destructive unless an explicit certified write path is invoked separately.

Write Services

Own explicit, validated and auditable business mutations.

May depend on:

  • Domain;
  • Contracts;
  • Vertical Modules;
  • repository or persistence ports.

Only Write Services may modify business data.

Entrypoints, rebuild orchestrators and adapters must call a Write Service rather than a legacy SQL writer directly.

Pipeline

Owns ingestion, normalization, enrichment and preparation of data for downstream services.

May depend on:

  • Domain;
  • Contracts;
  • Vertical Modules;
  • explicit application services.

The Pipeline must never depend on Frontend code or use UI behavior as business truth.

Infrastructure

Owns technical implementations such as persistence, queues, locks, state stores and external integrations.

May depend on:

  • Contracts;
  • technical libraries.

Infrastructure implements ports. It must not define business truth or orchestrate use cases.

Adapters

Translate external interactions into Platform operations.

May depend on:

  • Contracts;
  • Application services;
  • Infrastructure implementations where composition is required.

Adapters must not decide business outcomes.

WordPress adapters must remain isolated by execution context: frontend, admin, CLI, HTTP and worker adapters must not import one another. Shared behavior belongs in transport-neutral application services.

Runtime

Owns process orchestration, scheduling, bootstrapping and composition.

May depend on:

  • Application;
  • Infrastructure;
  • Adapters;
  • Contracts.

Runtime must not create new business rules or business truth.

Apps

Own executable entrypoints.

May depend on:

  • Application;
  • Adapters.

Apps orchestrate execution only. They do not own business logic.

Frontend

Consumes prepared projections.

May depend on:

  • projection contracts;
  • read models intended for display.

Frontend must never depend directly on feeds, Domain internals, Pipeline, Runtime or Write Services.

Authorized dependency matrix

Layer Authorized dependencies
Domain Contracts, pure helpers
Contracts neutral shared types only
Knowledge Domain, Contracts
Application Domain, Knowledge, Contracts
Vertical Modules Domain, Contracts
Read Services Domain, Contracts, Vertical Modules, read ports
Write Services Domain, Contracts, Vertical Modules, write ports
Pipeline Domain, Contracts, Vertical Modules, application services
Infrastructure Contracts, technical libraries
Adapters Contracts, Application, Infrastructure
Runtime Application, Infrastructure, Adapters, Contracts
Apps Application, Adapters
Frontend projection/read-model contracts

Prohibited dependencies

The following directions are forbidden:

  • Domain → Application / Infrastructure / Adapters / Runtime / Frontend / Vertical Modules;
  • Contracts → concrete implementation namespaces;
  • Vertical Module → another Vertical Module;
  • Read Service → Write Service or SQL mutation;
  • Application → concrete Infrastructure implementation;
  • Pipeline → Frontend;
  • Frontend → feeds, Domain internals, Runtime or Write Services;
  • Adapter → another context-specific adapter;
  • Runtime → new business rule definition;
  • any entrypoint → legacy business writer when a certified Write Service exists.

Decision and result boundaries

Cross-layer decisions must use stable contracts.

A result should expose, when relevant:

  • status;
  • normalized value or selected identity;
  • confidence;
  • evidence;
  • reason codes;
  • conflicts;
  • audit metadata;
  • contract or rule version.

Canonical status vocabularies must remain stable across layers. Typical decision states include:

  • resolved;
  • unknown;
  • ambiguous;
  • conflict.

Specialized services may expose additional operational states, but they must not reinterpret these canonical meanings.

Projection and persistence boundary

Projection construction and projection persistence are separate responsibilities.

Canonical inputs
    ↓
Projection Builder
    ↓
Projection DTO
    ↓
Projection Write Service
    ↓
Persistence adapter

The Builder remains deterministic and side-effect free.

The Write Service owns validation, mutation, retries, idempotency and auditability.

Legacy projection DTO names or wrappers may remain temporarily for compatibility, but canonical ownership must stay under neutral Contracts namespaces.

Transitional compatibility debt

Compatibility wrappers are permitted only when all of the following are true:

  • the canonical dependency direction is already established;
  • the wrapper contains no new business logic;
  • active consumers are known;
  • the debt is documented and bounded;
  • removal can occur without changing business behavior.

Dormant orchestration shells, historical namespaces and non-autoloaded prototypes must not be treated as active architecture merely because files still exist.

Current certification notes should distinguish:

  • active runtime dependencies;
  • compatibility-only wrappers;
  • dormant reference code;
  • accepted P2 cleanup debt.

BA-AL-001 — Legacy Application namespace island

The residual CMonChoix\\Application\\... namespace is an accepted legacy island only.

It is not part of Composer PSR-4 authority, must not gain new runtime consumers, and must not become a source of new business truth. Residual files remain bounded compatibility/reference debt until their certified removal. Canonical runtime code continues to use the CMonChoix\\Platform\\... namespace.

Enforcement

Dependency rules must be enforced through a combination of:

  • namespace and import scans;
  • architecture tests;
  • contract tests;
  • read-only SQL guards;
  • adapter isolation tests;
  • direct-writer detection;
  • deterministic replay tests;
  • runtime entrypoint audits.

A documentation claim is not sufficient by itself. Active runtime paths must be proven from code, bootstraps and entrypoints.

Invariants

The following invariants must always remain true:

  • Domain remains independent from technical execution;
  • Contracts remain neutral and stable;
  • Application owns use-case orchestration;
  • Infrastructure implements technical details through contracts;
  • Vertical Modules remain isolated;
  • Read Services never write;
  • Write Services are explicit and auditable;
  • Projection builders remain side-effect free;
  • Runtime orchestrates without creating business truth;
  • Frontend consumes projections and does not own business truth;
  • Adapters translate and do not decide;
  • Media Quality remains audit-first and non-destructive by default;
  • legacy compatibility code never becomes the new canonical boundary.

Valid examples

Photo Vertical
    ↓
Domain + Contracts

Read Service
    ↓
Vertical Module + read contracts

Runtime
    ↓
Application

Frontend
    ↓
Projection contract

Invalid examples

Domain
    ↓
Smartphone Vertical

Read Service
    ↓
Legacy SQL writer

Pipeline
    ↓
Frontend component

Frontend adapter
    ↓
CLI adapter

Future evolution

A new layer or dependency direction may be introduced only when:

  • its responsibility is unique and explicit;
  • its dependency direction is documented;
  • it preserves existing invariants;
  • it is validated by architecture tests;
  • it does not reintroduce a previously removed coupling.